XMPP notifications for psychology experiments
Project description
eXpMPP
======
XMPP notifications for psychology experiments
Installation
======
##With pip (recommended)
The latest stable binaries are available via pip. Simply run `pip install expmpp --user`
##From github
1. `git clone https://github.com/louist87/expmpp.git`
2. `cd expmpp`
3. `python setup.py develop --user`
Usage
======
##Setting up a client
In order to begin receiving notifications, we must first initialize a client.
This should be done **exactly once** in your application and the resultant `Client` instance can then be imported by various submodules.
```python
from expmpp.client import Client
my_listeners = ['mylistener@domain.com'] # ID of the account being notified
client = Client('myuser@domain.com', 'mypassword', listeners=my_listeners)
```
##Sending notifications
Once you've initialized your client, you can begin sending arbitrary notifications.
```python
client.notify('This is a test.')
```
##Monitoring functions
Sometimes it is useful to be notified when a specific function returns. A common use-case is to send a notificaiton to the experimentor when the function responsible for running an experimental block has completed. This use-case motivates the following example:
```python
@client.monitor("Block Complete")
def run_block():
# logic to run the block
```
When the function `run_block` returns, eXpMPP will send a notification containing the text `Block Complete`.
It is often desirable to provide information about the return value of the monitored function. By default, `Client.monitor` attempts to fill a [python-formatted string](https://docs.python.org/2/library/stdtypes.html#str.format) with the return value of the monitored function. Thus,
```python
@client.monitor("Block {0} Complete")
def run_block():
# logic to run block
return block_num
```
is expected to return a string such as `Block 1 Complete`, assuming `run_block` returns an integer.
For functions that return multiple values (or iterable containers), the `unpack` flag, when set to `True`, will attempt to map each variable in the returned container to its respective placeholder. For instance:
```python
@client.monitor("Subject {0}, Block {1} Complete", unpack=True)
def run_block():
# logic to run block
return sub_num, block_num
```
The above example is expected to return a string such as `Subject 1, Block 3 Complete`.
If the function returns a dictionary, setting `unpack=True` will map the the values of the dictionary to named placeholders as follows:
```python
@client.monitor("Subject {sub}, Block {block} Complete")
def run_block():
# logic to run block
return {'sub': sub_num, 'block': block_num}
```
The above example is expected to return a string similar to the one in the preceding example.
###Transforming output for notification
On occasion, a function will return a value that is either non-human-readable or whose default formatting is sinfully ugly. For these cases, a function can be passed to the `transformer` keyword argument, which allows a developer to transform the output before notification. Note that the `transformer` parameter does **not** change the function's final return value; it only changes what gets sent over the wire.
```python
def check_err(ret_val):
if ret_val is None:
return "Block complete. No errors."
else:
return "Error: {0}".format(ret_val)
@client.monitor('{0}', transformer=check_err)
def run_block():
# logic to run block
return ret_val
```
======
XMPP notifications for psychology experiments
Installation
======
##With pip (recommended)
The latest stable binaries are available via pip. Simply run `pip install expmpp --user`
##From github
1. `git clone https://github.com/louist87/expmpp.git`
2. `cd expmpp`
3. `python setup.py develop --user`
Usage
======
##Setting up a client
In order to begin receiving notifications, we must first initialize a client.
This should be done **exactly once** in your application and the resultant `Client` instance can then be imported by various submodules.
```python
from expmpp.client import Client
my_listeners = ['mylistener@domain.com'] # ID of the account being notified
client = Client('myuser@domain.com', 'mypassword', listeners=my_listeners)
```
##Sending notifications
Once you've initialized your client, you can begin sending arbitrary notifications.
```python
client.notify('This is a test.')
```
##Monitoring functions
Sometimes it is useful to be notified when a specific function returns. A common use-case is to send a notificaiton to the experimentor when the function responsible for running an experimental block has completed. This use-case motivates the following example:
```python
@client.monitor("Block Complete")
def run_block():
# logic to run the block
```
When the function `run_block` returns, eXpMPP will send a notification containing the text `Block Complete`.
It is often desirable to provide information about the return value of the monitored function. By default, `Client.monitor` attempts to fill a [python-formatted string](https://docs.python.org/2/library/stdtypes.html#str.format) with the return value of the monitored function. Thus,
```python
@client.monitor("Block {0} Complete")
def run_block():
# logic to run block
return block_num
```
is expected to return a string such as `Block 1 Complete`, assuming `run_block` returns an integer.
For functions that return multiple values (or iterable containers), the `unpack` flag, when set to `True`, will attempt to map each variable in the returned container to its respective placeholder. For instance:
```python
@client.monitor("Subject {0}, Block {1} Complete", unpack=True)
def run_block():
# logic to run block
return sub_num, block_num
```
The above example is expected to return a string such as `Subject 1, Block 3 Complete`.
If the function returns a dictionary, setting `unpack=True` will map the the values of the dictionary to named placeholders as follows:
```python
@client.monitor("Subject {sub}, Block {block} Complete")
def run_block():
# logic to run block
return {'sub': sub_num, 'block': block_num}
```
The above example is expected to return a string similar to the one in the preceding example.
###Transforming output for notification
On occasion, a function will return a value that is either non-human-readable or whose default formatting is sinfully ugly. For these cases, a function can be passed to the `transformer` keyword argument, which allows a developer to transform the output before notification. Note that the `transformer` parameter does **not** change the function's final return value; it only changes what gets sent over the wire.
```python
def check_err(ret_val):
if ret_val is None:
return "Block complete. No errors."
else:
return "Error: {0}".format(ret_val)
@client.monitor('{0}', transformer=check_err)
def run_block():
# logic to run block
return ret_val
```
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
eXpMPP-1.0.3.tar.gz
(3.7 kB
view details)
Built Distribution
File details
Details for the file eXpMPP-1.0.3.tar.gz
.
File metadata
- Download URL: eXpMPP-1.0.3.tar.gz
- Upload date:
- Size: 3.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 450db20eaa9a89fa68be51f1b510fdaa671dc0d85068aed2f8a1ccc2f9422f01 |
|
MD5 | 2bd150050c1a39c8b0aae66e76746fe0 |
|
BLAKE2b-256 | 1dbb033623e0d256358e88a658e21d0bc026aea4ef2eacbdcd147c075be26899 |
File details
Details for the file eXpMPP-1.0.3.linux-x86_64.tar.gz
.
File metadata
- Download URL: eXpMPP-1.0.3.linux-x86_64.tar.gz
- Upload date:
- Size: 5.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0829fb33ce3bfbcea06e05930dff8b43750c162662d5c2a5a687180417029cdf |
|
MD5 | a785f13559089c21416048a73bbc5ae9 |
|
BLAKE2b-256 | b6ae2294434f3fc792ec9130d604cad7b892c00e05d0fd97d7ad425d4ba7445c |