API — gntplib 0.5 documentation

# 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` 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='', 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.

## 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

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.

## 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.