Metadata-Version: 1.0
Name: gntplib
Version: 0.2
Summary: A Growl Notification Transport Protocol (GNTP) client library in Python
Home-page: http://github.com/papaeye/gntplib
Author: papaeye
Author-email: papaeye@gmail.com
License: BSD License
Description: gntplib
        =======
        
        gntplib is a Growl Notification Transport Protocol (GNTP_) client library in
        Python.
        
        .. _GNTP: http://www.growlforwindows.com/gfw/help/gntp.aspx
        
        Prerequisites
        -------------
        
        There are the following **optional** prerequisites.
        
        * tornado - to use ``gntplib.async`` module or to run test suite of gntplib.
        * nose - to run test suite of gntplib.
        
        Usage
        -----
        
        Simple usage::
        
            >>> import gntplib
            >>> gntplib.notify('Simple', 'Simple Event', 'Simple Title', 'Simple Text')
        
        General usage::
        
            >>> notifier = gntplib.Notifier('Basic', ['Basic Event'])
            >>> notifier.register()
            >>> notifier.notify('Basic Event', 'Basic Title', 'Basic Text')
        
        ``gntplib.Event`` class has a bit more attributes::
        
            >>> events = [gntplib.Event('foo', display_name='This is displayed',
            ...                         enabled=False)]
            >>> notifier = gntplib.Notifier('Event Sample 1', events)
            >>> notifier.register()
        
        And here is a convenient way::
        
            >>> notifier = gntplib.Notifier('Event Sample 2',
            ...                             ['Event A', ('Event B', False)])
            >>> notifier.register()
        
        Then enabled event ``Event A`` and disabled event ``Event B`` are registered.
        
        Icon
        ~~~~
        
        You can use icons of <url> and <uniqueid> data type in the same way::
        
            >>> icon1 = 'http://growl.googlecode.com/hg/Core/Resources/About.png'
            >>> icon2 = gntplib.RawIcon(open('notification.png', 'rb').read())
            >>> notifier = gntplib.Notifier('Icon', ['Icon Event'], icon=icon1)
            >>> notifier.register()
            >>> notifier.notify('Icon Event', 'Icon Title', icon=icon2)
        
        Callback
        ~~~~~~~~
        
        You can use either url callback or socket callback at one notification.
        Here is a url callback example::
        
            >>> notifier = gntplib.Notifier('Callback', ['Callback Event'])
            >>> notifier.register()
            >>> notifier.notify('Callback Event', 'Click me!',
            ...                 'but nothing happens in Growl 1.3.3',
            ...                 gntp_callback='http://google.com')
        
        Here is a socket callback example::
        
            >>> import webbrowser
            >>> def on_click(response):
            ...     webbrowser.open_new_tab('http://google.com')
            >>> notifier = gntplib.Notifier('Callback', ['Callback Event'])
            >>> notifier.register()
            >>> notifier.notify('Callback Event', 'Click me!', on_click=on_click)
        
        Asynchronous Notifier and Icon
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        You can use asynchronous notifier and icon if tornado is intalled::
        
            >>> try:
            ...     from gntplib import async
            ...     from tornado import gen, ioloop
            ... except ImportError:
            ...     pass
            ... else:
            ...     icon = async.AsyncIcon(
            ...         'http://growl.googlecode.com/hg/Core/Resources/About.png')
            ...     @gen.engine
            ...     def main():
            ...         notifier = async.AsyncNotifier('Async', ['Async Event'],
            ...                                        icon=icon)
            ...         yield gen.Task(notifier.register)
            ...         notifier.notify('Async Event', 'Async Icon')
            ...     try:
            ...         main()
            ...         ioloop.IOLoop.instance().start()
            ...     except KeyboardInterrupt:
            ...         ioloop.IOLoop.instance().stop()
        
        Note
        ----
        
        * Because ``Application-Icon: <url>`` is not implemented in Growl 1.3.3,
          Passing string value as ``icon`` parameter of ``Notifier`` constructor
          does not work.  Use ``Icon`` instance as above.
        
        * Because ``Notification-Icon`` at REGISTER request is not implemented in
          Growl 1.3.3, ``Event`` constructor's ``icon`` parameter does not work.
        
        * Because ``Notification-Icon: <url>`` at NOTIFY request is not implemented in
          Growl 1.3.3, Passing string value as ``icon`` parameter of
          ``Notify.nofity()`` method does not work.  Use ``Icon`` instance as above.
        
        * Because ``Notification-Callback-Target`` is not implemented in Growl 1.3.3,
          Passing string value as ``callback`` parameter of ``Notify.notify()`` method
          does not work.  Use socket callback as above.
        
        
        History
        -------
        
        0.2 (2012-03-18)
        ~~~~~~~~~~~~~~~~
        
        * Add support for asynchronous processing built on Tornado.
        
          - Add ``gntplib.async.AsyncNotifier`` and ``gntplib.async.AsyncIcon``.
        
        * Imporve usability of callback.
        
          - ``SocketCallback``:  Now ``SocketCallback`` is not a abstract class, but
            represents a socket callback.  Its ``if_clicked``, ``if_closed`` and
            ``if_timedout`` methods are replaced with ``on_click``, ``on_close`` and
            ``on_timeout`` methods respectively, which can be set at the constructor.
        
          - ``Notifier.notify()``:  Redefine ``callback`` argument as for the callback
            to run after closing the connection with the GNTP server.
            Add ``gntp_callback`` argument for url callback (as string) and socket
            callback (as ``SocketCallback`` instance).
            Add ``context``, ``context_type``, ``on_click``, ``on_close`` and
            ``on_timeout`` arguments to define a socket callback easily.
        
        * Remove ``callback`` argument from ``gntplib.notify()``.
        
        * Rename ``gntplib.Icon`` to ``gntplib.RawIcon``.
        
        0.1 (2012-03-12)
        ~~~~~~~~~~~~~~~~
        
        * Initial release.
        
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
