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:
Create a publisher instance
Register the publisher instance to the GNTP server
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 ofPublisher
as default icon of the notification -
icon
keyword argument ofEvent
as icon of the notification -
icon
keyword argument ofpublish()
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)]