PopIt-Python 0.1.2

Python bindings to connect to the PopIt API

popit-python
============

Python bindings to connect to the `PopIt <https://github.com/mysociety/popit>`_ API. You can *create*, *read*, *update* and *delete* any items from PopIt through this Binding. Actually, this is only a convenient wrapper around `PopIt's <https://github.com/mysociety/popit>`_ RESTful API.

Installation
------------
PopIt-Python is available as a module on PyPi, to install, simply run::

pip install PopIt-Python

Alternatively, clone this repo and install as you see fit.

How do I use this when I want to...
-----------------------------------

First, you'll need to get the PopIt binding object. Make sure PopIt as running and that you have all the information you need. Then get the object use the `PopIt` constructor. ::

from popit import PopIt

api = PopIt(instance = 'professors', \
hostname = '127-0-0-1.org.uk', port = 3000, api_version = 'v1', \
user = '[e-mail]', password = 'tJo1zBum')

* ``instance`` Name of the instance you created. There can be more than one for one installation.
* ``hostname`` The Hostname of the PopIt server.
* ``api_version`` The version of the PopIt API. Since there may be changes in the way you access the data in PopIt you want to have a stable API version. We recommend that you use the latest version, if possible.
* ``port`` The port, PopIt is accessible through. This probably is ``80`` or ``3000``. ``80`` is the default.
* ``user`` Your username. You will not be able to write anything if you haven't provided your username and password.
* ``password`` The password for the user.

…create something?
~~~~~~~~~~~~~~~~~~

This PopitWrapper lets you easily create a new item by name. This can be a ``person``, ``organisation`` or ``position``. There may be other options that you can find in the `PopIt API documentation <https://github.com/mysociety/popit/wiki/API-Overview>`_. ::

new = api.person.post({'name': 'Albert Keinstein'})
print(new)

# get the id of the newly created item
id = new['result']['_id']


…read something
~~~~~~~~~~~~~~~~

If you want to get a single item from PopIt, use ``name(id)``. ::

# you need a valid ID for example from the create process.
result = api.person(id).get()
print(result)

To get all Items from a kind, use `name`. ::

results = api.person.get()
print(results)

…update something?
~~~~~~~~~~~~~~~~~~

::

result = api.person(id).put({"name": "Albert Einstein"})
print(result)

…delete something?
~~~~~~~~~~~~~~~~~~

::

successful = api.person(id).delete()

…get an error?
~~~~~~~~~~~~~~

This is easy. This wrapper helps you with various error messages that help you get the wrapper working. Here are some explanations for error messages.

**HttpClientError: Client Error 404**
You are looking for an item that does not exist. Please provide a valid id. This Error can happen when you ty to *create*, *read*, *update* or *delete* an item.

**HttpClientError: Client Error 401**
You wanted to *create*, *update* or *delete* an item but provided a wrong username or password.

*Note*: You won't see this error before you actually try to modify any data.

**SchemaError: 'foo does not exist. Try one of these schemas: organisation, position, person.'**
This happens when you try to get data from a schema that does not exist (in this case ``foo``). The available schemas are determined when you first create the api object.

…get more information about what's going on internally?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enable logging. ::

logging.basicConfig(level = logging.WARN, format=FORMAT)

Requirements
------------

If you don't use pip to install the module, you'll also need:

* slumber (``pip install slumber``)
* requests (``pip install requests``)

How to run the tests
--------------------

* Copy the config_example.py to config_test.py
* Change the entries in the testconfig.py to you local test server
* Install `oktest <http://www.kuwata-lab.com/oktest/>`_ (``pip install oktest``)
* Make sure PopIt is running. You cannot test this Wrapper without a running PopIt instance.
* run ``python test.py``