Usage — gntplib 0.5 documentation

# Usage

gntplib provides `Publisher` to send notifications and `Subscriber` to send subscription requests.

## Publish

Here is a general usage:

    >>> publisher = Publisher('App', ['Event'])
    >>> publisher.register()
    >>> publisher.publish('Event', 'Title', 'Text')

This is constructed from the following 3 steps:

1. Create a publisher instance

2. Register the publisher instance to the GNTP server

3. Send a notification to the GNTP server

### Create a Publisher Instance

    >>> publisher = Publisher('App', ['Event'])

First argument is the name of the application. This name should be unique among the GNTP clients registered to the GNTP server.

Second argument is the list of the notification types which this publisher will sent. The item of the list is a string, a string-bool tuple or a `Event` instance.

The tuple is to define disabled notification type easily:

    >>> Publisher('App', ['Event A', ('Event B', False)])

Then enabled notification type `Event A` and disabled notification type `Event B` are registered.

To fully define the properties of the notification type, use `Event` instance.

Moreover, you can specify the address of the GNTP server and the timeout in seconds with keyword arguments:

    >>> Publisher('App', ['Event'],
                  host='remote.example.org', port=30000, timeout=20)

The defaults are host=’localhost’, port=23053 and timeout=10.

### Register the Publisher Instance

    >>> publisher.register()

Use `register()` method.

Once the publisher is registered, you don’t need to re-register the same application name and notification types of it.

### Send a Notification

    >>> publisher.publish('Event', 'Title', 'Text')

Use `publish()` method.

First argument is the name of the notification. This is one of the names of the notification types which is defined at `Publisher` constructor’s second argument.

Second argument is the title of the notification, and third argument is the text of the notification.

## Subscribe

Here is a general usage:

    >>> id = uuid.uuid4().hex
    >>> subscriber = Subscriber(id, 'Subscriber', 'hub.example.org', 'secret')
    >>> subscriber.subscribe()

`Subscriber` requires four positional arguments: id_ as a subscriber id, name as a subscriber name, hub as a subscribed-to machine address, password as a password.

The port numbers of the subscriber and subscribed-to machine are used default port number: 23053. To change the port number of the subscriber, set port keyword argument to the desired port number. To change the port number of the subscribed-to machine, set hub to host-port tuple instead of host string.

`SUBSCRIBE` request is sent by `subscribe()`. `subscribe()` accepts callback keyword argument as a final callback like the methods of `gntplib.Publisher`. If you don’t set callback keyword argument, `store_ttl()` is used as a final callback, and `gntplib.Subscriber`'s `ttl` attribute is updated by the value of `'Subscription-TTL'` header of the response from the subscribed-to machine.

And you can also use convenience function `subscribe()`:

    >>> ttl = subscribe(id, 'Subscriber', 'hub.example.org', 'secret')

## Icon

In GNTP, you can use icons in the following scenes.

- as icon of the application - `icon` keyword argument of `Publisher`

- as default icon of the notification - `icon` keyword argument of `Event`

- as icon of the notification - `icon` keyword argument of `publish()`

The data type of the icon is <url> or <uniqueid>. gntplib supports both data types in the same way:

    >>> icon1 = 'http://growl.googlecode.com/hg/Core/Resources/About.png'
    >>> icon2 = Resource(open('notification.png', 'rb').read())
    >>> publisher = Publisher('App', ['Icon Event'], icon=icon1)
    >>> publisher.register()
    >>> publisher.publish('Icon Event', 'Title', icon=icon2)

To use <url> data type, pass url string to `icon` keyword argument. To use <uniqueid> data type, pass a `Resource` instance to `icon` keyword argument. In the above example, `icon1` is of <url> data type, and `icon2` is of <uniqueid> data type.

## Callback

In GNTP, you can define the notification window’s callback. URL callbacks are on click callbacks, which the GNTP server handles their events. Socket callbacks are on click, on close and/or on timeout callbacks, which the GNTP client handles their events.

gntplib supports both callbacks in the same way:

    >>> publisher.publish('Callback Event', 'Click me!',
    ...                   gntp_callback='http://google.com')

or

    >>> import webbrowser
    >>> class MyCallback(SocketCallback):
    ...     def __init__(self, url):
    ...         SocketCallback.__init__(self, url)
    ...     def on_click(self, response):
    ...         webbrowser.open_new_tab(self.context)
    >>> publisher.publish('Callback Event', 'Click me!',
    ...                   gntp_callback=MyCallback('http://google.com'))

To use url callback, pass url string to `gntp_callback` keyword argument. To use socket callback, pass `SocketCallback` instance to `gntp_callback` keyword argument.

For socket callback, gntplib provides more ease-of-use keyword arguments: `context`, `context_type`, `on_click`, `on_close` and `on_timeout`. And the following is same as above:

    >>> def on_click(response):
    ...     webbrowser.open_new_tab('http://google.com')
    >>> publisher.publish('Callback Event', 'Click me!', on_click=on_click)

You cannot use `gntp_callback` keyword argument with other socket callback’s keyword arguments.

Note

Socket callback blocks the client thread until the notification window is dismissed by the user, so it is usually used on thread pool, and so on. Or use `gntplib.async` module, which supports asynchronous proccessing built on Tornado.

## Security

### Password

You can set password keyword argument of `Publisher` to password string:

    >>> Publisher('App', ['Event'], password='secret')

gntplib use SHA256 as default hashing algorithm. To change the hashing algorithm, set key_hashing keyword argument to keys.MD5, keys.SHA1 or keys.SHA512:

    >>> Publisher('App', ['Event'], password='secret', key_hashing=keys.MD5)

password is a required positional argument for `Subscriber` as described above. `Subscriber` can also accepts key_hashing keyword argument.

### Encryption

You can set encryption keyword argument of `Publisher` and `Subscriber` to encryption algorithm. Available encryption algorithms are ciphers.AES, ciphers.DES and ciphers.DES3. To enable encryption, setting password argument is required. If password argument is set to None, encryption keyword argument will be ignored:

    >>> Publisher('App', ['Event'], password='secret', encryption=ciphers.AES)

The key size of key_hashing must be at least the key size of encryption. So keys.MD5 and keys.SHA1 cannot be used with ciphers.AES or ciphers.DES3.

Note

The encryption of messages is not implemented in Growl 1.3.3.

## Additional Headers

To include custom headers or app-specific headers, pass the list of key-value tuples to custom_headers or app_specific_headers keyword arguments of `Publisher` and `Subscriber`:

    >>> publisher = Publisher('App', ['Event'],
    ...                       custom_headers=[('Sender', 'gntplib')],
    ...                       app_specific_headers=[('Filename', 'file.txt')])

If you want to change them each request, modify their attributes directly before dispatching requests:

    >>> publisher.app_specific_headers = [('Filename', 'foo.txt')]
    >>> publisher.register()
    >>> publisher.app_specific_headers = [('Filename', 'bar.txt')]
    >>> publisher.publish('Event', 'Title')

You can also pass binary contents with `Resource`:

    >>> resource = Resource(open('manual.pdf', 'rb').read())
    >>> publisher.app_specific_headers = [('resource', resource)]