使い方

gntplib は通知の送信のために Publisher を提供します。購読リクエストの送信のために Subscriber を提供します。

Publish

一般的な使い方は次の通りです。

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

これは以下の 3 つの部分から構成されています。

1. publisher インスタンスの生成
2. GNTP サーバへの publisher インスタンスの登録
3. GNTP サーバへの通知の送信

Publisher インスタンスの生成

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

第一引数はアプリケーション名です。これは登録する GNTP サーバの GNTP クライアントの中でユニークな名前です。

第二引数はこの publisher が送信する通知タイプのリストです。リストの要素は文字列、文字列と真偽値のタプルまたは Event インスタンスです。

タプルを使えば無効化した通知タイプを簡単に定義することができます。

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

これで有効化した通知タイプ Event A と無効化した通知タイプ Event B が登録されます。

通知タイプのプロパティを完全に定義するには Event を使ってください。

さらにキーワード引数を使えば、GNTP サーバのアドレスとタイムアウトを指定することができます。

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

初期値は host=’localhost’、port=23053、timeout=10 です。

Publisher インスタンスの登録

>>> publisher.register()

register() メソッドを使います。

一度 publisher を登録すると、それと同じアプリケーション名と通知タイプの publisher を再登録する必要はありません。

通知の送信

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

publish() メソッドを使います。

第一引数は通知タイプ名です。これは Publisher のコンストラクタの第二引数で定義した通知タイプ名のうちのひとつです。

第二引数は通知タイトルで、第三引数は通知テキストです。

Subscribe

一般的な使い方は次の通りです。

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

Subscriber は 4 つの位置指定引数を必要とします。id_ は subscriber ID、name は subscriber 名、hub は非購読マシンのアドレス、password はパスワードです。

subscriber と非購読マシンのポート番号はデフォルトポート番号の 23053 が使われます。subscriber のポート番号を変更するには、port キーワード引数に希望のポート番号をセットします。非購読マシンのポート番号を変更するには、hub キーワード引数にホスト名の文字列ではなくてホスト名-ポートのタプルをセットします。

SUBSCRIBE リクエストは subscribe() で送信されます。subscribe() は gntplib.Publisher のメソッドと同様に callback キーワード引数を受け取ります。もし callback キーワード引数をセットしなければ、store_ttl() がコールバックとして使われ、gntplib.Subscriber の ttl 属性は非購読マシンからのレスポンスの 'Subscription-TTL' ヘッダの値で更新されます。

また便宜関数 subscribe() を使うこともできます。

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

アイコン

GNTP では、以下の状況でアイコンを使うことができます。

• アプリケーションのアイコンとして。Publisher の icon キーワード引数で指定します。
• 通知のデフォルトアイコンとして。Event の icon キーワード引数で指定します。
• 個々の通知のアイコンとして。publish() の icon キーワード引数で指定します。

アイコンのデータタイプは <url> または <uniqueid> です。gntplib はどちらのデータタイプも同じようにサポートします。

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

<url> データタイプを使うには icon キーワード引数に url 文字列を渡します。<uniqueid> データタイプを使うには icon キーワード引数に Resource インスタンスを渡します。上記の例では icon1 が <url> データタイプのアイコンで icon2 が <uniqueid> データタイプのアイコンです。

コールバック

GNTP では、通知ウィンドウのコールバックを指定することができます。URL コールバックはクリック時のコールバックで、GNTP サーバがそのイベントを処理します。ソケットコールバックはクリック、クローズ、タイムアウト時のコールバックで、GNTP クライアントがそれらのイベントを処理します。

gntplib はどちらのコールバックも同じようにサポートします。

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

または

>>> 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'))

url コールバックを使うには url 文字列を gntp_callback キーワード引数に渡します。ソケットコールバックを使うには SocketCallback インスタンスを gntp_callback キーワード引数に渡します。

ソケットコールバック用として、gntplib はより使い易いキーワード引数も提供します。context、context_type、on_click、on_close、on_timeout です。以下は上記の例と同じ内容です。

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

gntp_callback キーワード引数を他のソケットコールバック用の引数といっしょに使うことはできません。

ノート

ユーザが通知ウィンドウを閉じるまで、ソケットコールバックはクライアントのスレッドをブロックします。そのため、通常、ソケットコールバックはスレッドプールなどといっしょに使われます。または gntplib.async モジュールを使ってください。これは Tornado を使った非同期処理をサポートしています。

セキュリティ

パスワード

Publisher の password キーワード引数にパスワード文字列を指定することができます。

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

gntplib はデフォルトのハッシュアルゴリズムとして SHA256 を使います。ハッシュアルゴリズムを変更するには、key_hashing キーワード引数に keys.MD5、keys.SHA1、、keys.SHA512 のいずれかを指定します。

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

上で述べたように password は Subscriber の必須の位置指定引数です。Subscriber も key_hashing キーワード引数を受け取ることができます。

暗号化

Publisher と Subscriber の encryption キーワード引数に暗号化アルゴリズムを指定することができます。利用可能な暗号化アルゴリズムは ciphers.AES、ciphers.DES、ciphers.DES3 です。暗号化を有効にするには password 引数を指定する必要があります。password 引数が None の場合 encryption キーワード引数は無視されます。

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

key_hashing のキーサイズは少なくとも encryption のキーサイズ以上でなければなりません。つまり keys.MD5 と keys.SHA1 は ciphers.AES または ciphers.DES3 で使うことができません。

ノート

Growl 1.3.3 ではメッセージの暗号化は実装されていません。

拡張ヘッダ

custom headers または app-specific headers を含めるには、Publisher や Subscriber の custom_headers または app_specific_headers キーワード引数にキー-値タプルを渡します。

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

リクエストごとにそれらを変更するには、リクエストを送出する前に直接それらの属性を変更します。

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

Resource を使ってバイナリデータを渡すこともできます。

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