Dedun
*****

Dedun is a Python client for the RESTful API of `API.Leipzig
<http://www.apileipzig.de/>`_. This API gives access to the public data of the
city of Leipzig. At the moment Dedun can only be used to read from the API.

Dedun was a Nubian god worshipped during ancient times and was depicted as a
lion. The lion is also part of the coat of arms of the city of Leipzig.

Installation
============

Use `pip` or `easy_install` to install the package::

    $ pip install dedun

Or install from the sources::

    $ tar xzf dedun-0.2.tar.gz
    $ cd dedun-0.2
    $ python setup.py install

Usage
=====

You need a personal API key to use Dedun. You can request an API key at the
`API.Leipzig website <http://www.apileipzig.de/>`_.

Create a Result object
----------------------

First create an instance of a Result class using your API key::

>>> import dedun
>>> comp = dedun.MediahandbookCompanies(api_key='XXXXXXXXXXXXXXXXXXXX')

Fetch all items
---------------

Now you can fetch all mediahandbook companies using the all() method::

    >>> companies = comp.all()
    >>> print companies
    1039 mediahandbook/companies items

You can also use the count() method to get the total number of results::

    >>> companies.count()
    1039

The Result object is a list consisting of MediahandbookCompaniesResult objects::

    >>> companies[0]
    MediahandbookCompaniesResult: Leipziger Universitätsverlag GmbH und Akademische Verlagsanstalt AVA
    >>> print companies[0].get_attributes()
    [u'phone_primary', u'people', u'past_customers', u'updated_at', u'street', u'postcode', u'id', u'city', u'email_secondary', u'fax_secondary', u'mobile_secondary', u'housenumber_additional', u'housenumber', u'fax_primary', u'resources', u'main_activity', u'old_id', u'sub_branches', u'sub_market_id', u'mobile_primary', u'url_primary', u'url_secondary', u'name', u'created_at', u'phone_secondary', u'products', u'email_primary', u'main_branch_id']
    >>> print companies[0].name
    Leipziger Universitätsverlag GmbH und Akademische Verlagsanstalt AVA
    >>> print companies[0].id
    1
    >>> print companies[0].email_primary
    info@univerlag-leipzig.de

You can also use slicing and iteration to get a part of the results::

    >>> companies[:10]
    [MediahandbookCompaniesResult: Leipziger Universitätsverlag GmbH und Akademische Verlagsanstalt AVA, MediahandbookCompaniesResult: Sittauer Mediendesign, MediahandbookCompaniesResult: Realdesign GmbH, MediahandbookCompaniesResult: Frauenkultur e.V. Leipzig, MediahandbookCompaniesResult: Jürgen Auge Atelier für Gebrauchs- und Werbegrafik, MediahandbookCompaniesResult: Leipziger Städtische Bibliotheken, MediahandbookCompaniesResult: Foto Pampel, MediahandbookCompaniesResult: AECom VERTRIEB,  Fachgroßhandel für Computerzubehör, MediahandbookCompaniesResult: Gesellschaft für Nachrichtenerfassung und Nachrichtenverbreitung, MediahandbookCompaniesResult: OCR Systeme GmbH]
    >>> for c in companies[:10]:
    ...     print c.name
    ...
    Leipziger Universitätsverlag GmbH und Akademische Verlagsanstalt AVA
    Sittauer Mediendesign
    Realdesign GmbH
    Frauenkultur e.V. Leipzig
    Jürgen Auge Atelier für Gebrauchs- und Werbegrafik
    Leipziger Städtische Bibliotheken
    Foto Pampel
    AECom VERTRIEB,  Fachgroßhandel für Computerzubehör
    Gesellschaft für Nachrichtenerfassung und Nachrichtenverbreitung
    OCR Systeme GmbH

Search for items
----------------

Search for items using the search() method::

    >>> augen = comp.search(name='Auge')
    >>> augen
    2 mediahandbook/companies items
    >>> for a in augen:
    ...     print a.name
    ...
    Jürgen Auge Atelier für Gebrauchs- und Werbegrafik
    Leipziger Wohnungs- und Baugesellschaft mbH
    >>> leipzig_10 = comp.search(city='Leipzig', limit=10)
    >>> print leipzig_10
    10 mediahandbook/companies items

Get a single item
-----------------

Fetch a single item using the get() method::

    >>> auge = comp.get(name='Auge')
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "dedun.py", line 167, in get
        raise MultipleResults()
    dedun.MultipleResults: Your query had multiple results.
    >>> auge = comp.get(name='Auge Atelier')
    >>> print auge
    MediahandbookCompaniesResult: Jürgen Auge Atelier für Gebrauchs- und Werbegrafik
    >>> comp.get(id=232323)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "dedun.py", line 168, in get
        item = result[0]
      File "dedun.py", line 110, in __getitem__
        raise ObjectNotFound('Item not found.')
    dedun.ObjectNotFound: Item not found.

Activate debugging
------------------

Create a new instance to activate debugging::

    >>> comp_debug = dedun.MediahandbookCompanies(api_key='XXXXXXXXXXXXXXXXXXXX', debug=True)
    >>> comp_debug.all()
    http://www.apileipzig.de/api/v1/mediahandbook/companies?api_key=XXXXXXXXXXXXXXXXXXXX&format=json
    1039 mediahandbook/companies items
    >>> comp_debug.get(id=23)
    http://www.apileipzig.de/api/v1/mediahandbook/companies/search?api_key=XXXXXXXXXXXXXXXXXXXX&id=23&format=json
    MediahandbookCompaniesResult: Kleines Werbeteam

Available Resource classes
--------------------------

- CalendarEvents
- CalendarHosts
- CalendarVenues
- DistrictDistricts
- DistrictIhkcompanies
- DistrictStatistics
- DistrictStreets
- MediahandbookBranches
- MediahandbookCompanies
- MediahandbookPeople
