superscription 0.1.0

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

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