/docs/GNotifier Gawel's repository

Welcome to GNotifier’s documentation!

This Page

Welcome to GNotifier’s documentation!¶

GNotifier is a web service to send messages via GTalk and GMail

GNotifier is not secure. This mean that everybody can post notifications. BUT GNotifier is a wsgi application. If you need a secure service then write a small middleware for that !

Report bugs/patches at gael@gawel.org

GNotifier application¶

GNotifier is a WSGI application. You can launch it using Paste.

Here is a sample config file used to send notifications to recipients:

[server:main]
# GNotifier is a fast application so let's use gunicorn server
use=egg:gunicorn
port=5222

[app:main]
use=egg:GNotifier
# google id / password
gid = notif@gawel.org
passwd = xxx

# one or more adresses separated by spaces
recipients = gael@gawel.org

# debug mode. If false, send a notification on server startup
debug=false

Then run:

$ paster serve your_config.ini

GNotifier clients¶

There is two functions to use the web service

Example:

>>> import notifier
>>> notifier.notify('Hello world !', path='/gtalk') #doctest: +ELLIPSIS
{'status': 0, 'recipients': ['gael@gawel.org'], 'time': ...}

Command line¶

There is also a command line script:

$ gnotify -u http://localhost:5222 Hello world

Get help:

$ gnotify -h
Usage: gnotify [options] message

Options:
  -h, --help            show this help message and exit
  -u URL, --url=URL     HTTP Host
  -r RECIPIENTS, --recipient=RECIPIENTS
                        Recipients. You can have more than one -r
  -q, --quick           Use quick notifier
  -i, --im              Only send on IM
  -m MINUTES, --minutes=MINUTES
                        Wait X minutes before sending
  -s SECONDS, --seconds=SECONDS
                        Wait X seconds before sending
  -c INGREDIENT, --cook=INGREDIENT
                        Send notification for cooking. Valid ingredients are:
                        boiled_eggs (3m15s), hard_eggs (10m0s)
  -v, --verbose         More output

JSON API¶

You can use this API to build your own client.

Initialize test application:

>>> from webtest import TestApp
>>> from notifier.server import Notifier
>>> app = Notifier('notif@gawel.org', 'xxx', recipients='gael@gawel.org', debug=True)
>>> app = TestApp(app)

JSON helper:

>>> import simplejson
>>> def json(**kwargs): return simplejson.dumps(kwargs)

The index page is useless but assume it work:

>>> print app.get('/')
Response: 200 OK
Content-Type: text/html; charset=UTF-8
<html><body><h1>Welcome to GNotifier<h1></body></html>

Ok, let’s post a notification both on GTalk and GMail:

>>> resp = app.post('/', json(title='Yes!'))
>>> print resp #doctest: +ELLIPSIS
Response: 200 OK
Content-Type: application/json; charset=UTF-8
{"status": 0, "recipients": ["gael@gawel.org"], "time": ...}

Post on GTalk:

>>> resp = app.post('/gtalk', json(title='You got a message!'))
>>> print resp #doctest: +ELLIPSIS
Response: 200 OK
Content-Type: application/json; charset=UTF-8
{"status": 0, "recipients": ["gael@gawel.org"], "time": ...}

Post on GMail:

>>> resp = app.post('/gmail', json(title='You got a mail!', message='Youhou !'))
>>> print resp #doctest: +ELLIPSIS
Response: 200 OK
Content-Type: application/json; charset=UTF-8
{"status": 0, "recipients": ["gael@gawel.org"], "time": ...}

Sending notifications to others:

>>> resp = app.post('/', json(title='You got a mail!', message='Youhou !',
...                           recipients=['other@gawel.org']))
>>> print resp #doctest: +ELLIPSIS
Response: 200 OK
Content-Type: application/json; charset=UTF-8
{"status": 0, "recipients": ["other@gawel.org"], "time": ...}

If an error occurs you’ll get a status=1. Let’s ommit the title:

>>> resp = app.post('/', json(message='Youhou !', recipients=['other@gawel.org']))
>>> print resp #doctest: +ELLIPSIS
Response: 200 OK
Content-Type: application/json; charset=UTF-8
{"status": 1, "time": ..., "error": "No title found in JSON data"}