dedun 0.3.2

Dedun is a Python client for the RESTful API of API.Leipzig. This API gives access to the public data of the city of Leipzig.

Dedun

Dedun is a Python client for the RESTful API of API.Leipzig. 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:

$ wget http://pypi.python.org/packages/source/d/dedun/dedun-0.3.tar.gz
$ tar xzf dedun-0.3.tar.gz
$ cd dedun-0.3
$ python setup.py install

If you install from the sources or want to run the test suite you have to install the requirements manually:

$ pip install anyjson>=0.3.1

Quick overview

You need a personal API key to use Dedun. You can request an API key at the API.Leipzig website.

Create a Result object

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

>>> from dedun.resources import MediahandbookCompanies
>>> comp = 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
[e-mail]

Each object can be retrieved in JSON:

>>> companies[0].get_json()
'{"phone_primary": "[phone]", "people": [1, 2], "past_customers": null, "updated_at": "2011-03-14T17:47:47+01:00", "street": "Oststra\\u00dfe", "postcode": "04317", "id": 1, "city": "Leipzig", "email_secondary": null, "fax_secondary": null, "mobile_secondary": null, "housenumber_additional": null, "housenumber": 41, "fax_primary": null, "resources": null, "main_activity": null, "old_id": 3, "sub_branches": [23], "sub_market_id": 3, "mobile_primary": null, "url_primary": "http://www.univerlag-leipzig.de", "url_secondary": "http://www.univerlag-leipzig.de", "name": "Leipziger Universit\\u00e4tsverlag GmbH und Akademische Verlagsanstalt AVA", "created_at": "2011-02-23T03:06:15+01:00", "phone_secondary": null, "products": null, "email_primary": "[e-mail]", "main_branch_id": 17}'

Result objects can be sorted and reverted:

>>> companies[0]
MediahandbookCompaniesResult: Leipziger Universitätsverlag GmbH und Akademische Verlagsanstalt AVA
>>> companies.reverse()
>>> companies[0]
MediahandbookCompaniesResult: Helden wider Willen e.V.
>>> companies.order_by('name')
1039 mediahandbook/companies items
>>> companies[0]
MediahandbookCompaniesResult: (type:g)publishing
>>> companies[-1]
MediahandbookCompaniesResult: Übersetzungsdienst Annett Koch

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/resources.py", line 59, in get
    raise exceptions.MultipleResults()
dedun.exceptions.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/resources.py", line 60, in get
    return result[0]
  File "dedun/results.py", line 103, in __getitem__
    raise exceptions.ObjectNotFound('Item not found.')
dedun.exceptions.ObjectNotFound: Item not found.

Activate debugging

Create a new instance to activate debugging:

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

Running the test suite

To run the test suite you need the Dedun source code. There are two ways to obtain it.

1. Clone the Mercurial repository from BitBucket:

   $ hg clone https://bitbucket.org/keimlink/dedun

1. Download the package from PyPI and unpack it:

   $ wget http://pypi.python.org/packages/source/d/dedun/dedun-0.3.tar.gz
   $ tar xzvf dedun-0.3.tar.gz

All test are written using py.test. You can execute them without having py.test installed. The only prerequisite is the installation of the previously mentioned requirements:

$ pip install anyjson>=0.3.1

Run the test suite using python setup.py test (no py.test installation required). The tests requiring the local HTTP server will automatically be skipped:

$ python setup.py test
================================================= test session starts ==================================================
platform darwin -- Python 2.6.1 -- pytest-2.1.2
collected 37 items

tests/test_resources.py ..sss...sss.
tests/test_results.py .........................

========================================= 31 passed, 6 skipped in 0.40 seconds =========================================

To run the tests which mock HTTP requests using a local test server you need additional packages:

$ pip install pytest pytest-localserver

After installing the packages you can run all tests:

$ python setup.py test
================================================= test session starts ==================================================
platform darwin -- Python 2.6.1 -- pytest-2.1.2
collected 37 items

tests/test_resources.py ............
tests/test_results.py .........................

============================================== 37 passed in 3.47 seconds ===============================================

If you want to skip the tests using the local HTTP server on purpose you can do it this way:

$ py.test --no-localserver
================================================= test session starts ==================================================
platform darwin -- Python 2.6.1 -- pytest-2.1.3
collected 37 items

tests/test_resources.py ..sss...sss.
tests/test_results.py .........................

========================================= 31 passed, 6 skipped in 0.41 seconds =========================================

Reporting bugs

If you find bugs or have ideas for new features please use the issue tracker.

Contributing

Development happens at BitBucket. You are highly encouraged to participate in the development.

License

This software is licensed under the New BSD License. See the LICENSE file in the top distribution directory for the full license text.

Changelog

0.3.2

• Removed deprecated __getslice__ method from dedun.results.

• Added commands for coverage and pylint to setup.py.

• Better solution for deprecated import:

  from dedun import MediahandbookCompanies

• Removed runtests.py from py_modules.

0.3.1

• Added versiontools >= 1.8 setup requirement.

0.3.0

• Fixed issue #1: Slicing does not respect reverse() method.

• Added new method ResultBase.get_json.

• Added test suite (using py.test).

• Reorganized code as a Python package.

• Using BSD license now.

• Requires now anyjson >= 0.3.1.

0.2.5

• Added new Results methods order_by and reverse.

0.2.4

• Fixed installation instructions.

0.2.3

• Fixed setup.py encodings (again).

0.2.2

• Fixed setup.py encodings.

0.2.1

• Minor fixes.

0.2.0

• New Resource and Result classes.

• Added debug argument to Resource classes.

• New ObjectNotFound, ImproperlyConfigured and MultipleResults exceptions.

0.1.0

• Initial release. Supports only JSON. Documentation and tests will come with future releases.