Skip to main content

Comprehensive, yet easy-to-use, pythonic, ORM-like access to JSON API services

Project description

https://travis-ci.org/qvantel/jsonapi-client.svg?branch=master https://coveralls.io/repos/github/qvantel/jsonapi-client/badge.svg https://img.shields.io/pypi/v/jsonapi-client.svg https://img.shields.io/pypi/pyversions/jsonapi-client.svg https://img.shields.io/badge/licence-BSD%203--clause-blue.svg

JSON API client for Python

Introduction

Package repository: https://github.com/qvantel/jsonapi-client

This Python (3.6+) library provides easy-to-use, pythonic, ORM-like access to JSON API ( http://jsonapi.org )

  • Optional asyncio implementation

  • Optional model schema definition and validation (=> easy reads even without schema)

  • Resource caching within session

Installation

From Pypi:

pip install jsonapi-client

Or from sources:

./setup.py install

Usage

Client session

from jsonapi_client import Session, Filter, ResourceTuple

s = Session('http://localhost:8080/')
# To start session in async mode
s = Session('http://localhost:8080/', enable_async=True)

# You can also pass extra arguments that are passed directly to requests or aiohttp methods,
# such as authentication object
s = Session('http://localhost:8080/',
            request_kwargs=dict(auth=HTTPBasicAuth('user', 'password'))


# You can also use Session as a context manager. Changes are committed in the end
# and session is closed.
with Session(...) as s:
    your code

# Or with enable_async=True
async with Session(..., enable_async=True):
    your code

# If you are not using context manager, you need to close session manually
s.close()

# Again, don't forget to await in the AsyncIO mode
await s.close()

# Fetching documents
documents = s.get('resource_type')
# Or if you want only 1, then
documents = s.get('resource_type', 'id_of_document')

# AsyncIO the same but remember to await:
documents = await s.get('resource_type')

Filtering and including

# You need first to specify your filter instance.
# - filtering with two criteria (and)
filter = Filter(attribute='something', attribute2='something_else')
# - filtering some-dict.some-attr == 'something'
filter = Filter(some_dict__some_attr='something'))

# Same thing goes for including.
# - including two fields
include = Inclusion('related_field', 'other_related_field')

# Custom syntax for request parameters.
# If you have different URL schema for filtering or other GET parameters,
# you can implement your own Modifier class (derive it from Modifier and
# reimplement appended_query).
modifier = Modifier('filter[post]=1&filter[author]=2')

# All above classes subclass Modifier and can be added to concatenate
# parameters
modifier_sum = filter + include + modifier

# Now fetch your document
filtered = s.get('resource_type', modifier_sum) # AsyncIO with await

# To access resources included in document:
r1 = document.resources[0]  # first ResourceObject of document.
r2 = document.resource      # if there is only 1 resource we can use this

Pagination

# Pagination links can be accessed via Document object.
next_doc = document.links.next.fetch()
# AsyncIO
next_doc = await document.links.next.fetch()

# Iteration through results (uses pagination):
for r in s.iterate('resource_type'):
    print(r)

# AsyncIO:
async for r in s.iterate('resource_type'):
    print(r)

Resource attribute and relationship access

# - attribute access
attr1 = r1.some_attr
nested_attr = r1.some_dict.some_attr
#   Attributes can always also be accessed via __getitem__:
nested_attr = r1['some-dict']['some-attr']

# If there is namespace collision, you can also access attributes via .fields proxy
# (both attributes and relationships)
attr2 = r1.fields.some_attr

# - relationship access.
#   * Sync, this gives directly ResourceObject
rel = r1.some_relation
attr3 = r1.some_relation.some_attr  # Relationship attribute can be accessed directly

#   * AsyncIO, this gives Relationship object instead because we anyway need to
#     call asynchronous fetch function.
rel = r1.some_relation
#     To access ResourceObject you need to first fetch content
await r1.some_relation.fetch()
#     and then you can access associated resourceobject
res = r1.some_relation.resource
attr3 = res.some_attr  # Attribute access through ResourceObject

# If you need to access relatinoship object itself (with sync API), you can do it via
# .relationships proxy. For example, if you are interested in links or metadata
# provided within relationship, or intend to manipulate relationship.
rel_obj = r1.relationships.relation_name

Resource updating

# Updating / patching existing resources
r1.some_attr = 'something else'
# Patching element in nested json
r1.some_dict.some_dict.some_attr = 'something else'

# change relationships, to-many. Accepts also iterable of ResourceObjects/
# ResourceIdentifiers/ResourceTuples
r1.comments = ['1', '2']
# or if resource type is not known or can have multiple types of resources
r1.comments_or_people = [ResourceTuple('1', 'comments'), ResourceTuple('2', 'people')]
# or if you want to add some resources you can
r1.comments_or_people += [ResourceTuple('1', 'people')]
r1.commit()

# change to-one relationships
r1.author = '3'  # accepts also ResourceObjects/ResourceIdentifiers/ResourceTuple
# or resource type is not known (via schema etc.)
r1.author = ResourceTuple('3', 'people')

# Committing changes (PATCH request)
r1.commit(meta={'some_meta': 'data'})  # Resource committing supports optional meta data
# AsyncIO
await r1.commit(meta={'some_meta': 'data'})

Creating new resources

# Creating new resources. Schema must be given. Accepts dictionary of schema models
# (key is model name and value is schema as json-schema.org).

models_as_jsonschema = {
    'articles': {'properties': {
        'title': {'type': 'string'},
        'author': {'relation': 'to-one', 'resource': ['people']},
        'comments': {'relation': 'to-many', 'resource': ['comments']},
    }},
    'people': {'properties': {
        'first-name': {'type': 'string'},
        'last-name': {'type': 'string'},
        'twitter': {'type': ['null', 'string']},
    }},
    'comments': {'properties': {
        'body': {'type': 'string'},
     'author': {'relation': 'to-one', 'resource': ['people']}
 }}
}
# If you type schema by hand, it could be more convenient to type it as yml in a file
# instead

s = Session('http://localhost:8080/', schema=models_as_jsonschema)
a = s.create('articles') # Creates empty ResourceObject of 'articles' type
a.title = 'Test title'

# Validates and performs POST request, and finally updates resource based on server response
a.commit(meta={'some_meta': 'data'})
# Or with AsyncIO, remember to await
await a.commit(meta={'some_meta': 'data'})

# Commit metadata could be also saved in advance:
a.commit_metadata = {'some_meta': 'data'}
# You can also commit all changed resources in session by
s.commit()
# or with AsyncIO
await s.commit()

# Another example of resource creation, setting attributes and relationships & committing:
# If you have underscores in your field names, you can pass them in fields keyword argument as
# a dictionary:
cust1 = s.create_and_commit('articles',
                            attribute='1',
                            dict_object__attribute='2',
                            to_one_relationship='3',
                            to_many_relationship=['1', '2'],
                            fields={'some_field_with_underscore': '1'}
                            )

# Async:
cust1 = await s.create_and_commit('articles',
                                  attribute='1',
                                  dict_object__attribute='2',
                                  to_one_relationship='3',
                                  to_many_relationship=['1', '2'],
                                  fields={'some_field_with_underscore': '1'}
                                  )

Deleting resources

# Delete resource
cust1.delete() # Mark to be deleted
cust1.commit() # Actually delete

Credits

License

Copyright (c) 2017, Qvantel

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the Qvantel nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL QVANTEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

CHANGELOG

0.9.9 (2020-03-12)

  • Adapt to aiohttp>3.0

  • Workaround a weird bug

  • Fix deprecation warnings

  • Prevent AttributeDict() from modifying its input

  • #24: Fix error handling of server response

0.9.8 (2020-02-14)

  • #25: Fix for fetching resources without attributes

  • Stop following next when there are no more items

  • Fix build

  • Use custom_url logic for all request methods

  • #27: Await close on async sessions

  • Add apk libffi-dev dependency

  • Fix pytest.raise exception validation e.value

  • Added .venv, .vscode, .pytest_cache to .gitignore

  • Add support for extra headers as request_kwargs

0.9.7 (2019-02-01)

  • Support __getitem__ in Meta

  • Handle empty relationship data list

  • Allow returning link to relationship as an iterator

  • Fix handling null one-to-one-relationship

  • Don’t explicitly quote filter values

  • Include support

0.9.6 (2017-06-26)

  • When creating new resources, use default value specified in jsonschema, when available.

0.9.5 (2017-06-16)

  • Change Session.create_and_commit signature similarly as Session.create

0.9.4 (2017-06-16)

  • Remove ? from filenames (illegal in Windows)

  • Pass event loop aiohttp’s ClientSession

  • Return resource from .commit if return status is 202

  • Support underscores in field names in Session.create() through fields keyword argument.

  • Add support for extra arguments such as authentication object

  • AsyncIO support for context manager usage of Session

0.9.3 (2017-04-03)

  • Added aiohttp to install requirements

0.9.2 (2017-04-03)

  • Github release.

0.9.1 (2017-03-23)

  • Fix async content_type checking

  • Use Python 3’s new typing.NamedTuple instead of collections.NamedTuple

  • Make included resources available from Document

  • ResourceObject.json property

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonapi_client-0.9.9.tar.gz (40.9 kB view details)

Uploaded Source

Built Distribution

jsonapi_client-0.9.9-py3-none-any.whl (34.0 kB view details)

Uploaded Python 3

File details

Details for the file jsonapi_client-0.9.9.tar.gz.

File metadata

  • Download URL: jsonapi_client-0.9.9.tar.gz
  • Upload date:
  • Size: 40.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/46.0.0 requests-toolbelt/0.9.1 tqdm/4.42.1 CPython/3.6.2

File hashes

Hashes for jsonapi_client-0.9.9.tar.gz
Algorithm Hash digest
SHA256 348bb9efb5f98421f865f8258dae5aa781552a5910351ff578f084292e659cd1
MD5 be0a4f1b400a403b037146a304b291c5
BLAKE2b-256 8eb0c0ff1c3c9716c84bdf32e676ea836e8db9a3c137fbefb2cf228fb7c4de1c

See more details on using hashes here.

File details

Details for the file jsonapi_client-0.9.9-py3-none-any.whl.

File metadata

  • Download URL: jsonapi_client-0.9.9-py3-none-any.whl
  • Upload date:
  • Size: 34.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/46.0.0 requests-toolbelt/0.9.1 tqdm/4.42.1 CPython/3.6.2

File hashes

Hashes for jsonapi_client-0.9.9-py3-none-any.whl
Algorithm Hash digest
SHA256 6d9aa3d6f0146c03b2a169cec8554c6be268f750d89c32a0f43cf85a4105912f
MD5 4530b42eefcb04fc1ae88e08e8bcd885
BLAKE2b-256 55a58dc66076d41bad206914326dd18212e3815ceeed201cbd04b0f1244be037

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page