API

Simple Functions

gntplib.publish(app_name, event_name, title, text=u'')

Register a publisher and send a notification at a time.

Parameters:

• app_name – the name of the application.
• event_name – the name of the notification.
• title – the title of the notification.
• text – the text of the notification. Defaults to ''.

gntplib.subscribe(id_, name, hub, password, port=23053)

Send a subscription request and return ttl.

Parameters:

• id – the unique id of the subscriber.
• name – the name of the subscriber.
• hub – the subscribed-to machine. If a string is given, it is used as a host of the hub and default port number 23053 is used. If host-port tuple is given, it is used directly.
• password – the password of the subscribed-to machine.
• port – the port number of the subscriber. Defaults to 23053.

Application Objects

class gntplib.Publisher(name, event_defs, icon=None, custom_headers=None, app_specific_headers=None, gntp_client_class=None, **kwargs)

Publisher of Growl Notification Transport Protocol (GNTP).

This class supports REGISTER and NOTIFY requests. They are sent by register() and publish() methods respectively. These methods can accept the optional final callback as callback keyword argument, which run after closing the connection with the GNTP server.

event_defs is a list of str, unicode, double (of str and bool) or Event instance. It is converted to a list of Event instance as follows: str or unicode item becomes value of the name attribute of Event instance, whose other attributes are defaults. Double item is expanded to (name, enabled) tuple, and those values are passed to Event constructor. Event instance item is used directly.

Optional keyword arguments are passed to the gntp_client_class constructor.

Parameters:

• name – the name of the application.
• event_defs – the definitions of the notifications.
• icon – url string or an instance of Resource for the icon of the application. Defaults to None.
• custom_headers – the list of key-value tuples for Custom Headers.
• app_specific_headers – the list of key-value tuples for App-Specific Headers.
• gntp_client_class – GNTP client class. If it is None, GNTPClient is used. Defaults to None.

Note

In Growl 1.3.3, icon of url string does not work.

publish(name, title, text=u'', id_=None, sticky=False, priority=0, icon=None, coalescing_id=None, callback=None, gntp_callback=None, **socket_callback_options)

Send a notification to the GNTP server.

Parameters:

• name – the name of the notification.
• title – the title of the notification.
• text – the text of the notification. Defaults to ‘’.
• id – the unique ID for the notification. If set, this should be unique for every request. Defaults to None.
• sticky – if set to True, the notification remains displayed until dismissed by the user. Defaults to False.
• priority – the display hint for the receiver which may be ignored. A higher number indicates a higher priority. Valid values are between -2 and 2, defaults to 0.
• icon – url string or an instance of Resource to display with the notification. Defaults to None.
• coalescing_id – if set, should contain the value of the id_ of a previously-sent notification. This serves as a hint to the notification system that this notification should replace/update the matching previous notification. The notification system may ignore this hint. Defaults to None.
• callback – the callback run after closing the connection with the GNTP server. Defaults to None.
• gntp_callback – url string for url callback or SocketCallback instance for socket callback. Defaults to None.
• socket_callback_options – the keyword arguments to be used to instantiating SocketCallback for socket callback. About acceptable keyword arguments, see SocketCallback.

Note

In Growl 1.3.3, icon of url string does not work.

Note

Growl for Windows v2.0+ and Growl v1.3+ require coalescing_id to be the same on both the original and updated notifcation, ignoring the value of id_.

register(callback=None)

Register this publisher to the GNTP server.

Parameters:callback – the callback run after closing the connection with the GNTP server. Defaults to None.

class gntplib.Subscriber(id_, name, hub, password, port=23053, custom_headers=None, app_specific_headers=None, gntp_client_class=None, **kwargs)

Subscriber of Growl Notification Transport Protocol (GNTP).

This class supports SUBSCRIBE request.

Parameters:

• id – the unique id of the subscriber.
• name – the name of the subscriber.
• hub – the subscribed-to machine. If a string is given, it is used as a host of the hub and default port number 23053 is used. If host-port tuple is given, it is used directly.
• password – the password of the subscribed-to machine.
• port – the port number of the subscriber. Defaults to 23053.
• custom_headers – the list of key-value tuples for Custom Headers.
• app_specific_headers – the list of key-value tuples for App-Specific Headers.
• gntp_client_class – GNTP client class. If it is None, GNTPClient is used. Defaults to None.

store_ttl(response)

Update ttl attribute.

subscribe(callback=None)

Send a subscription request.

If callback is None, store_ttl() is used and ttl is updated by Subscription-TTL value of the response.

Parameters:callback – the callback run after closing the connection with the GNTP server. Defaults to None.

class gntplib.async.AsyncPublisher(name, event_defs, icon=None, io_loop=None, **kwargs)

Asynchronous Publisher of Growl Notification Transport Protocol (GNTP).

Same as Publisher except the following:

• uses AsyncGNTPClient as gntp_client_class.
• accepts tornado.ioloop.IOLoop instance by additional io_loop keyword argument.

Parameters:

• name – the name of the application.
• event_defs – the definitions of the notifications.
• icon – url string or an instance of Resource for the icon of the application. Defaults to None.
• io_loop – tornado.ioloop.IOLoop instance.
• custom_headers – the list of key-value tuples for Custom Headers.
• app_specific_headers – the list of key-value tuples for App-Specific Headers.

publish(name, title, text=u'', id_=None, sticky=False, priority=0, icon=None, coalescing_id=None, callback=None, gntp_callback=None, **socket_callback_options)

Send a notification to the GNTP server.

Parameters:

• name – the name of the notification.
• title – the title of the notification.
• text – the text of the notification. Defaults to ‘’.
• id – the unique ID for the notification. If set, this should be unique for every request. Defaults to None.
• sticky – if set to True, the notification remains displayed until dismissed by the user. Defaults to False.
• priority – the display hint for the receiver which may be ignored. A higher number indicates a higher priority. Valid values are between -2 and 2, defaults to 0.
• icon – url string or an instance of Resource to display with the notification. Defaults to None.
• coalescing_id – if set, should contain the value of the id_ of a previously-sent notification. This serves as a hint to the notification system that this notification should replace/update the matching previous notification. The notification system may ignore this hint. Defaults to None.
• callback – the callback run after closing the connection with the GNTP server. Defaults to None.
• gntp_callback – url string for url callback or SocketCallback instance for socket callback. Defaults to None.
• socket_callback_options – the keyword arguments to be used to instantiating SocketCallback for socket callback. About acceptable keyword arguments, see SocketCallback.

Note

In Growl 1.3.3, icon of url string does not work.

Note

Growl for Windows v2.0+ and Growl v1.3+ require coalescing_id to be the same on both the original and updated notifcation, ignoring the value of id_.

register(callback=None)

Register this publisher to the GNTP server.

Parameters:callback – the callback run after closing the connection with the GNTP server. Defaults to None.

class gntplib.async.AsyncSubscriber(id_, name, hub, password, port=23053, io_loop=None, **kwargs)

Asynchronous Subscriber of Growl Notification Transport Protocol (GNTP).

Same as Subscriber except the following:

• uses AsyncGNTPClient as gntp_client_class.
• accepts tornado.ioloop.IOLoop instance by additional io_loop keyword argument.

Parameters:

• name – the name of the subscriber.
• hub – the subscribed-to machine. If a string is given, it is used as a host of the hub and default port number 23053 is used. If host-port tuple is given, it is used directly.
• password – the password of the subscribed-to machine.
• id – the unique id of the subscriber. If not set, randomly generated UUID is used.
• port – the port number of the subscriber. Defaults to 23053.
• io_loop – tornado.ioloop.IOLoop instance.
• custom_headers – the list of key-value tuples for Custom Headers.
• app_specific_headers – the list of key-value tuples for App-Specific Headers.

store_ttl(response)

Update ttl attribute.

subscribe(callback=None)

Send a subscription request.

If callback is None, store_ttl() is used and ttl is updated by Subscription-TTL value of the response.

Parameters:callback – the callback run after closing the connection with the GNTP server. Defaults to None.

GNTP Client Object

class gntplib.GNTPClient(host=u'localhost', port=23053, timeout=10, password=None, key_hashing=<gntplib.keys._Algorithm object at 0x101ddc650>, encryption=None, connection_class=None)

GNTP client.

Parameters:

• host – host of GNTP server. Defaults to ‘localhost’.
• port – port of GNTP server. Defaults to 23053.
• timeout – timeout in seconds. Defaults to 10.
• password – the password used in creating the key.
• key_hashing – the type of hash algorithm used in creating the key. It is keys.MD5, keys.SHA1, keys.SHA256 or keys.SHA512. Defaults to keys.SHA256.
• encryption – the tyep of encryption algorithm used. It is None, ciphers.AES, ciphers.DES or ciphers.3DES. None means no encryption. Defaults to None.
• connection_class – GNTP connection class. If it is None, GNTPConnection is used. Defaults to None.

Notification Type Object

class gntplib.Event(name, display_name=None, enabled=True, icon=None)

Represent notification type.

Parameters:

• name – the name of the notification.
• display_name – the display name of the notification, which is appeared at the Applications tab of the Growl Preferences. Defaults to None.
• enabled – indicates if the notification should be enabled by default. Defaults to True.
• icon – url string or an instance of Resource for the default icon to display with the notifications of this notification type. Defaults to None.

Note

In Growl 1.3.3, icon does not work.

Resource Objects

class gntplib.Resource(data)

Class for <uniqueid> data types.

Parameters:data – the binary content.

unique_id()

Return the <uniqueid> value.

unique_value()

Return the <uniquevalue> value.

class gntplib.async.AsyncResource(url)

Class for asynchronous resource.

Parameters:url – url string of the resource.

Socket Callback Object

class gntplib.SocketCallback(context=u'None', context_type=u'None', on_click=None, on_close=None, on_timeout=None)

Base class for socket callback.

Each of the callbacks takes one positional argument, which is Response instance.

Parameters:

• context – value of Notification-Callback-Context. Defaults to 'None'.
• context-type – value of Notification-Callback-Context-Type. Defaults to 'None'.
• on_click – the callback run at CLICKED callback result.
• on_close – the callback run at CLOSED callback result.
• on_timeout – the callback run at TIMEDOUT callback result.

Note

TIMEDOUT callback does not occur in my Growl 1.3.3.

on_click(response)

Run CLICKED event callback.

on_close(response)

Run CLOSED event callback.

on_timeout(response)

Run TIMEDOUT event callback.