Usage

Flickr example

To use Durga in a project define a class that extends durga.Resource. This example uses the Flickr API flickr.photos.search with Python 3:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import pytest
from durga.element import Element

str = six.string_types[0]


class FlickrResource(durga.Resource):
    base_url = 'https://api.flickr.com/services'
    path = 'rest'
    objects_path = ('photos', 'photo')
    schema = durga.schema.Schema({
        'farm': durga.schema.Use(int, error='Invalid farm'),
        'id': durga.schema.Use(int, error='Invalid id'),
        'isfamily': durga.schema.Use(bool, error='Invalid isfamily'),
        'isfriend': durga.schema.Use(bool, error='Invalid isfriend'),
        'ispublic': durga.schema.Use(bool, error='Invalid ispublic'),
        'owner': durga.schema.And(str, len, error='Invalid owner'),
        'secret': durga.schema.And(str, len, error='Invalid secret'),
        'server': durga.schema.Use(int, error='Invalid server'),
        'title': durga.schema.And(str, len, error='Invalid title'),
    })
    query = {
        'method': 'flickr.photos.search',
        'api_key': 'a33076a7ae214c0d12931ae8e38e846d',
        'format': 'json',
        'nojsoncallback': 1,

Note

For convenience durga.Resource. and the schema library are available at the top module level.

Now you can search for the first 10 cat images:

cats = FlickrResource().collection.filter(text='Cat', per_page=10)

This will return a durga.Collection with a durga.Element for each result.

MusicBrainz example

Musicbrainz is an open music encyclopedia that collects music metadata and makes it available to the public. With Artist you get detailed entry for a single artist.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
from uuid import UUID

from dateutil import parser

import durga

class MusicBrainzResource(durga.Resource):
    base_url = 'http://musicbrainz.org/ws/2'
    id_attribute = 'id'
    path = 'artist'
    schema = durga.schema.Schema({
        'country': durga.schema.And(str, len, error='Invalid country'),
        'ipis': [durga.schema.Optional(str)],
        'area': {
            'disambiguation': durga.schema.Optional(str),
            'iso_3166_3_codes': [durga.schema.Optional(str)],
            'sort-name': str,
            'name': str,
            'id': durga.schema.And(str, len, lambda n: UUID(n, version=4)),
            'iso_3166_2_codes': [durga.schema.Optional(str)],
            'iso_3166_1_codes': [durga.schema.Optional(str)],
        },
        'sort-name': str,
        'name': str,
        'disambiguation': durga.schema.Optional(str),
        'life-span': {
            'ended': bool,
            'begin': durga.schema.And(str, len, parser.parse, error='Invalid begin'),
            'end': durga.schema.Or(
                None,
                durga.schema.And(str, len, parser.parse, error='Invalid end')),
        },
        'end_area': durga.schema.Or(None, {
            'disambiguation': durga.schema.Optional(str),
            'iso_3166_3_codes': [durga.schema.Optional(str)],
            'sort-name': str,
            'name': str,
            'id': durga.schema.And(str, len, lambda n: UUID(n, version=4)),
            'iso_3166_2_codes': [durga.schema.Optional(str)],
            'iso_3166_1_codes': [durga.schema.Optional(str)],
        }),
        'id': durga.schema.And(str, len, lambda n: UUID(n, version=4), error='Invalid id'),
        'type': str,
        'begin_area': {
            'disambiguation': durga.schema.Optional(str),
            'iso_3166_3_codes': [durga.schema.Optional(str)],
            'sort-name': str,
            'name': str,
            'id': durga.schema.And(str, len, lambda n: UUID(n, version=4)),
            'iso_3166_2_codes': [durga.schema.Optional(str)],
            'iso_3166_1_codes': [durga.schema.Optional(str)],
        },
        'gender': durga.schema.Or(None, str),
    })
    query = {
        'method': '',
        'fmt': 'json',
        'nojsoncallback': 1,
    }

Note

In the example above you can see a more complex usage of validation.

For example to validate UUIDs:

'id': durga.schema.And(str, len, lambda n: UUID(n, version=4)),

For example to validate date:

'begin': durga.schema.And(str, len, parser.parse, error='Invalid begin'),

Now let’s use the MusicBrainzResource:

MusicBrainzResource().collection.get(id='05cbaf37-6dc2-4f71-a0ce-d633447d90c3').name

That returns name of artist with given id:

'東方神起'