Skip to main content

UNKNOWN

Project description

=============
genericclient
=============

A generic client for RESTful APIs

::

$ pip install genericclient


Quickstart
==========

::

from genericclient import GenericClient

myclient = GenericClient(api_url)

myresource = myclient.resources.get(id=1)

actives = myclient.posts.filter(active=True)


Usage
=====

Instantiation
-------------

::

myclient = GenericClient(url, auth=None, adapter=None, trailing_slash=False)


Arguments:

* ``url``: The root URL of your API
* ``auth``: The auth for your API. You can pass anything that ``requests`` can accept as auth.
* ``adapter``: optional session adapter for ``requests``.
* ``trailing_slash``: You can set this to ``True`` if your API's URLs end with a ``/``

Endpoints
---------

Endpoints are available as properties on the main instance.

``.all()``
~~~~~~~~~~

Retrieves all resources (essentially a simple ``GET`` on the endpoint)::

myclient.posts.all() # GET /posts/

``.filter(**kwargs)`` calls a ``GET`` with ``kwargs`` as querystring values::

myclient.posts.filter(blog=12, status=1) # GET /posts/?blog=12&status=1

``.get(**kwargs)``
~~~~~~~~~~~~~~~~~~

A special case of ``.filter()``.

If ``kwargs`` contains ``id``, ``pk``, ``slug`` or ``username``, that value will
be used in the URL path, in that order.

Otherwise, it calls a ``GET`` with ``kwargs`` as querystring values.

If the returned list is empty, will raise ``ResourceNotFound``.

If the returned list contains more than 1 resource, will raise ``MultipleResourcesFound``

Note that ``.get()`` will return a ``Resource``, not a list of ``Resource``s

::

myclient.posts.filter(blog=12, status=1) # GET /posts/?blog=12&status=1
myclient.posts.filter(id=12) # GET /posts/12/
myclient.posts.filter(slug='12-ways-clickbait') # GET /posts/12-ways-clickbait/

``.create(payload)``
~~~~~~~~~~~~~~~~~~~~

Will result in a ``POST``, with ``payload`` (a ``dict``) as the request's body,
returning a new ``Resource``::

post = myclient.posts.create({'blog': 12, 'status': 1}) # POST /posts/

``.create_or_update(payload)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If ``payload`` contains a key called ``'id'``, will issue a ``PUT``, otherwise
it will call ``.create``::

post = myclient.posts.create_or_update({'id': 1234, 'status': 1}) # PUT /posts/1234/


``.delete(pk)``
~~~~~~~~~~~~~~~

Will issue a ``DELETE``, and will use ``pk`` as part of the URL::

myclient.posts.delete(24) # DELETE /posts/24/

Resources
---------

All endpoints methods (with the exception of ``.delete()``) return either a
``Resource`` or a list of ``Resource``s.

A ``Resource`` is just a wrapping class for a ``dict``, where keys can be accessed
as properties.

Additionally, ``Resource`` s have a special property called ``.payload``, which
contains the original payload received from the server.

``Resource``s have the following methods:

``Resource.delete()`` will result in a ``DELETE``, with ``Resource.id`` as
par of the URL::

blog = myclient.posts.create({'blog': 12, 'status': 1}) # POST /posts/
blog.delete() # DELETE /blog/345/ -- the ID 345 was returned by the server in the previous response

``Resource.save()`` will result in a ``PUT``, with ``Resource.id`` as
par of the URL::

post = myclient.posts.create({'blog': 12, 'status': 1}) # POST /posts/
post.status = 2
post.save() # PUT /posts/345/

License
-------

Licensed under the MIT License.

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

genericclient-0.0.5.tar.gz (4.2 kB view details)

Uploaded Source

Built Distribution

genericclient-0.0.5-py2.py3-none-any.whl (6.6 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file genericclient-0.0.5.tar.gz.

File metadata

File hashes

Hashes for genericclient-0.0.5.tar.gz
Algorithm Hash digest
SHA256 b94cb7bfb210eb431614bf9636959ca839c55beeb851820c69f41cfd38be8efa
MD5 b3d3113ac91d6012d77899b8d6270359
BLAKE2b-256 0b15c6f4c26fd02c47f797d1f44b962a89deb3c76d75a0936bffe3f2fbd64485

See more details on using hashes here.

Provenance

File details

Details for the file genericclient-0.0.5-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for genericclient-0.0.5-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 09fcbd3f114a4f7b4235fbe2a0c553daaec766ef018bd9b910ba47bb6ec2b95f
MD5 8946eb2f24f8fa64a2f4d4876985a826
BLAKE2b-256 e47db183dfcf169e7024b98c3e5ab12e318e7dee367371b2214e04b9cc890906

See more details on using hashes here.

Provenance

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