API¶
Simple Functions¶
- gntplib.publish(app_name, event_name, title, text='')¶
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
andNOTIFY
requests. They are sent byregister()
andpublish()
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 (ofstr
andbool
) orEvent
instance. It is converted to a list ofEvent
instance as follows:str
orunicode
item becomes value of the name attribute ofEvent
instance, whose other attributes are defaults. Double item is expanded to (name, enabled) tuple, and those values are passed toEvent
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='', 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, seeSocketCallback
.
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 andttl
is updated bySubscription-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='localhost', port=23053, timeout=10, password=None, key_hashing=<gntplib.keys._Algorithm object>, 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¶
Socket Callback Object¶
- class gntplib.SocketCallback(context='None', context_type='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.