Metadata-Version: 2.0
Name: pushjack
Version: 0.2.2
Summary: Push notifications for APNS (iOS) and GCM (Android).
Home-page: https://github.com/dgilland/pushjack
Author: Derrick Gilland
Author-email: dgilland@gmail.com
License: MIT License
Keywords: apns ios gcm android push notifications
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Requires-Dist: requests

********
pushjack
********

|version| |travis| |coveralls| |license|

Push notifications for APNS (iOS) and GCM (Android).


Links
=====

- Project: https://github.com/dgilland/pushjack
- Documentation: http://pushjack.readthedocs.org
- PyPi: https://pypi.python.org/pypi/pushjack/
- TravisCI: https://travis-ci.org/dgilland/pushjack


Quickstart
==========

Whether using ``APNS`` or ``GCM``, pushjack provides a common API interface for each.


APNS
----

Using the ``APNSClient`` class:


.. code-block:: python

    from pushjack import APNSClient, create_apns_config

    config = create_apns_config({
        'APNS_CERTIFICATE': '<path/to/certificate.pem>'
    })

    client = APNSClient(config)

    token = '<device token>'
    alert = 'Hello world.'

    # Send to single device.
    # Keyword arguments are optional.
    client.send(token,
                alert,
                badge='badge count',
                sound='sound to play',
                category='category',
                content_available=True,
                title='Title',
                title_loc_key='t_loc_key',
                title_loc_args='loc_args',
                action_loc_key='a_loc_key',
                loc_key='loc_key',
                launch_image='path/to/image.jpg',
                extra={'custom': 'data'})

    # Send to multiple devices.
    # Accepts the same keyword arguments as send().
    client.send_bulk(tokens, alert, **options)

    # Get expired tokens.
    expired = client.get_expired_tokens()


Using the APNS module directly:


.. code-block:: python

    from pushjack import apns

    # Call signature is the same as APNSClient.
    apns.send(token, alert, **options)
    apns.send_bulk(token, alert, **options)


GCM
---

Using the ``GCMClient`` class:


.. code-block:: python

    from pushjack import GCMClient, create_gcm_config

    config = create_gcm_config({
        'GCM_API_KEY': '<api key>'
    })

    client = GCMClient(config)

    registration_id = '<registration id>'
    data = {'message': 'Hello world.'}

    # Send to single device.
    # Keyword arguments are optional.
    client.send(registration_id,
                data,
                collapse_key='collapse_key',
                delay_while_idle=True,
                time_to_live=100)

    # Send to multiple devices.
    # Accepts the same keyword arguments as send().
    client.send_bulk(tokens, data, **options)


Using the GCM module directly:


.. code-block:: python

    from pushjack import gcm

    # Call signature is the same as GCMClient.
    gcm.send(token, alert, **options)
    gcm.send_bulk(token, alert, **options)


Config
------

The config object for configuring a client is expected to be a ``dict`` or subclass of ``dict``:


.. code-block:: python

    gcm_config = {
        'GCM_API_KEY': '<api key>',
        'GCM_URL': 'https://android.googleapis.com/gcm/send',
        'GCM_MAX_RECIPIENTS': 1000
    }

    apns_config = {
        'APNS_CERTIFICATE': '<path/to/certificate.pem>',
        'APNS_HOST': 'gateway.push.apple.com',
        'APNS_PORT': 2195,
        'APNS_FEEDBACK_HOST': 'feedback.push.apple.com',
        'APNS_FEEDBACK_PORT': 2196,
        'APNS_ERROR_TIMEOUT': 0.5,
        'APNS_DEFAULT_EXPIRATION_OFFSET': 60 * 60 * 24 * 30
        'APNS_MAX_NOTIFICATION_SIZE': 2048
    }


For a class based approached, configuration classes are provided for subclassing which can be passed to each client class. By default, both ``GCMConfig``, ``APNSConfig``, and ``APNSSandboxConfig`` will set default values for the settings that shouldn't change. You will need to set ``GCM_API_KEY`` or ``APNS_CERTIFICATE`` appropriately though:


.. code-block:: python

    from pushjack import GCMClient, GCMConfig, APNSConfig, APNSSandboxConfig

    class MyGCMConfig(GCMConfig):
        GCM_API_KEY = '<api key>'

    class MyAPNSConfig(APNSConfig):
        APNS_CERTIFICATE = '<path/to/certificate.pem>'

    class MyAPNSSandboxConfig(APNSConfig):
        APNS_CERTIFICATE = '<path/to/certificate.pem>'


    client = GCMClient(MyGCMConfig)


**NOTE:** You can only pass in a class to the client initializer if it is a subclass of one of the provided ``*Config`` classes.



For more details, please see the full documentation at http://pushjack.readthedocs.org.


.. |version| image:: http://img.shields.io/pypi/v/pushjack.svg?style=flat-square
    :target: https://pypi.python.org/pypi/pushjack/

.. |travis| image:: http://img.shields.io/travis/dgilland/pushjack/master.svg?style=flat-square
    :target: https://travis-ci.org/dgilland/pushjack

.. |coveralls| image:: http://img.shields.io/coveralls/dgilland/pushjack/master.svg?style=flat-square
    :target: https://coveralls.io/r/dgilland/pushjack

.. |license| image:: http://img.shields.io/pypi/l/pushjack.svg?style=flat-square
    :target: https://pypi.python.org/pypi/pushjack/


