Skip to main content

Superscriptions: A (super-)thin Python2.7 wrapper around the Superfeedr PubSubHubbub API.

Project description

===============================
Superscription
===============================

.. image:: https://badge.fury.io/py/superscription.png
:target: http://badge.fury.io/py/superscription

.. image:: https://travis-ci.org/shrikant-joshi/superscription.png?branch=master
:target: https://travis-ci.org/shrikant-joshi/superscription

.. image:: https://pypip.in/d/superscription/badge.png
:target: https://crate.io/packages/superscription?version=latest


Superscriptions: A (super-)thin Python2.7 wrapper around the Superfeedr PubSubHubbub API.

It uses the excellent ``requests`` module by Kenneth Reitz for
interacting with the Superfeedr API endpoints. As a result, all
responses are available in their entirely, should you choose to
introspect and/or work with them further.

- Free software: BSD license
- Documentation: http://superscription.rtfd.org.

Features
--------

1. The various ``hub.mode``\ s offered by Superfeedr are made available
as straightforward & intuitive methods.
2. An (almost) one-to-one mapping of allowed parameters to
keyword-arguments for these methods.
3. Each response is available in its entirety for inspection if needed,
thanks to Kenneth Reitz's excellent ``requests`` module.

Basic Usage
-----------

Basic usage is pretty straightforward and looks like this:

::

>>> import superscription
>>> ss = superscription.Superscription("Marvin", "PainInMyDiodes")

You can also, pass in a token, instead of a password. In fact, it is
recommended!

::

>>> ss = superscription.Superscription("Marvin", token="0123456789abcdef0123456789abcdef")

Don't worry, not passing either the password or the token will raise an
``AttributeError``!

::

>>> ss = superscription.Superscription("ArthurDent")
Traceback (most recent call last):
[...]
AttributeError: You must initialize the object with either a password or a token! We recommend the token for security purposes, as does Superfeedr!

Modes? Methods!
---------------

Each Superfeedr ``hub.mode`` (``subscribe``, ``unsubscribe``, ``list``,
``display``) is available as an object method of the Superscription
class. All parameters accepted by Superfeedr can be declared as keyword
arguments.

NOTE: The order of the parameters is the same as specified in the
`Superfeedr PuSH Webhooks
documentation <http://documentation.superfeedr.com/subscribers.html#webhooks>`__,
in case you want to pass them as ``args`` rather than ``kwargs``.
Using keyword arguments is always recommended, though. :)

Paramters? Kwargs!
------------------

Any optional parameters allowed by the Superfeedr PuSH API can simply be
passed as keyword arguments for each of the corresponding method calls.
To construct the keyword argument corresponding to a parameter, replace
the dot (**.**) in the parameter name, with an underscore (**\_**).

For instance, ``hub.secret`` corresponds to ``hub_secret``:

::

>>> result = ss.subscribe(hub_topic='http://push-pub.appspot.com/feed', hub_callback="http://my.callback.tld/callback/", hub_verify="sync", hub_secret="RandomHubSecretGoesHere")
>>> print result
True

Parameters without a '.' in their name correspond to keyword arguments
with the same name. for instance, ``page`` can be passed as ``page``
itself:

::

>>> result = ss.list(hub_callback="http://my.callback.tld/callback/", page="1")
>>> print result
True
>>> ss.response.status_code
202

...except for the parameter ``format`` which corrresponds to the keyword
argument ``fmt``. This has been done deliberately, to avoid any
potential confusion/problems with the ``str.format()`` method/call.

Available methods
-----------------

All methods return a boolean ``True`` or ``False`` depending on whether
the subscription was successfully performed using Superfeedr or ran into
problems.

Potential problems have been documented (to some extent) in the section
`Errors & Warnings <#errors>`__.

Subscribe
~~~~~~~~~

The ``.subscribe()`` method takes TWO mandatory arguments, ``hub_topic``
& ``hub_callback``:

::

>>> result = ss.subscribe('http://push-pub.appspot.com/feed', "http://my.domain.tld/callback/")
>>> print result
True
>>> ss.response.status_code
202

Unsubscribe
~~~~~~~~~~~

The ``.unsubscribe()`` method takes ONE mandatory argument,
``hub_topic``:

::

>>> result = ss.unsubscribe(hub_topic='http://push-pub.appspot.com/feed')
>>> print result
True
>>> ss.response.status_code
202

If you have multiple subscriptions for the same ``hub_topic`` but each
one is associated with a different ``hub_callback``, you will have to
call the method each time for each (of the) callback(s) for which you
want to unsubscribe.

List
~~~~

The ``.list()`` method takes ONE mandatory argument, ``hub_callback``:

::

>>> result = ss.list(hub_callback='http://my.domain.tld/callback')
>>> print result
True
>>> ss.response.status_code
200
>>> ss.response.json()
[{u'subscription': {u'feed': {u'url': u'http://push-pub.appspot.com/feed', u'title': u'Publisher example'}, u'secret': None, u'endpoint': u'http://my.domain.tld/callback', u'format': u'json'}}]

Retrieve
~~~~~~~~

The ``.retrieve()`` method takes ONE mandatory argument, ``hub_topic``:

::

>>> result = ss.retrieve(hub_topic='http://push-pub.appspot,com/feed')
>>> print result
True
>>> ss.response.status_code
200
>>> data = ss.response.json()
>>> data.keys()
[u'status', u'items', u'title']

Responses
---------

The response from Superfeedr is the standard ``Response`` object
returned by the \`\ ``requests`` module and is saved as an attribute on
the ``superscription`` object itself:

::

>>> result = ss.subscribe('http://push-pub.appspot.com/feed', "http://my.domain.tld/callback/")
>>> print ss.response
<Response [204]>

Do note that the 'response' attribute is available on ``ss`` & not
``result``.

::

>>> type(ss.response)
requests.models.Response
>>> ss.response.status_code
204
>>> ss.response.content
''
>>> ss.response.text
u''

Errors and Warnings
-------------------

If the Superfeedr request runs into problems, or is generally
unsuccessful for some reason, the execution is stopped by raising the
corresponding error.

Optional Arguments are, well, optional...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Arguments with ``None`` values are discarded and a ``RuntimeWarning`` is
displayed before the API endpoint request is made:

::

>>> result = ss.subscribe("http://push-pub.appspot.com/feed", "http://my.domain.tld/callback", hub_secret=None, hub_verify=None)
[...]
RuntimeWarning: Extra arguments passed in function call: hub_secret, hub_verify

Mandatory Arguments are MANDATORY!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Not passing in the mandatory arguments raises the standard
``TypeError``:

::

>>> result = ss.subscribe('http://push-pub.appspot.com/feed')
[...]
TypeError: subscribe() takes at least 3 arguments (2 given)

All URLs must be fully-qualified
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

URLs for ``hub_topic`` and ``hub_callback`` must be fully-qualified
URIs, with a minimum of ``scheme`` and ``hostname``, else you'll get an
``AttributeError`` on the first of them to be caught:

::

>>> ss.subscribe("http://google", "my.domain.tld/callback")
[...]
AttributeError: http://google - URL is not fully-qualified!

--------------

That's it! Please feel free to add to/modify the documentation and the
project buy forking and submitting a PR.



History
-------

0.1.0 (2014-03-22)
++++++++++++++++++

* First release on PyPI.

Project details


Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page