Python client for the G Adventures REST API
Project description
===============================
G API Python Client
===============================
.. image:: https://badge.fury.io/py/gapipy.svg
:target: http://badge.fury.io/py/gapipy
.. image:: https://travis-ci.org/gadventures/gapipy.svg?branch=master
:target: https://travis-ci.org/gadventures/gapipy
A client for the G Adventures REST API (https://developers.gadventures.com)
* GitHub Repository: https://github.com/gadventures/gapipy/
* Documentation: http://gapipy.readthedocs.org.
* Free software: MIT license
Quick Start
-----------
>>> from gapipy import Client
>>> api = Client(application_key='MY_SECRET_KEY')
>>> tour = api.tours.get(21346)
>>> tour.product_line
u'PPP'
>>> tour.departures.count()
105
>>> dossier = tour.tour_dossier
>>> dossier.name
u'Peru Panorama'
>>> tour.get_brief_itinerary()[:2]
[{'body': u'Arrive at any time.', 'label': u'Day 1 Lima'},
{'body': u'Fly to Juliaca and transfer to Puno. Visit the floating Islands of Uros and take a guided tour of Lake Titicaca with a homestay in a small village. Optional visit to Sillustani burial site.',
'label': u'Days 2-4 Puno/Lake Titicaca (1B,1L,1D)'}]
Resources
---------
Resource objects are instantiated from python dictionaries created from JSON
data. The fields are parsed and converted to python objects as specified in the
resource class.
A nested resource will only be instantiated when its corresponding attribute is
accessed in the parent resource.
A field pointing to the URL for a collection of a child resources will hold a
``Query`` object for that resource. As for nested resources, it will only be
instantiated when it is first accessed.
Queries
-------
A Query for a resource can be used to fetch resources of that type (either a
single instance or an iterator over them, possibly filtered according to some
conditions). Queries are roughly analogous to Django's QuerySets.
An API client instance has a query object for each available resource
(accessible by an attribute named after the resource name)
Methods on Query objects
========================
All queries support the ``get`` method. The other methods are only supported
for queries whose resources are listable.
``get(resource_id)``
Get a single resource.
``all([limit=n])``
Generator over all resources in the current query. If ``limit`` is a
positive integer ``n``, then only the first ``n`` results will be returned.
``filter(field1=value1, [field2=value2, ...])``
Filter resources on the provided fields and values. Calls to ``filter`` can
be chained.
``count()``
Return the number of resources in the current query (by reading the
``count`` field on the response returned by requesting the list of
resources in the current query).
Caching
-------
A handful of cache backends are available for your use. The cache backend is
configurable by adjusting the ``GAPI_CACHE_BACKEND`` environment variable.
* Use ``cache_options`` when instantiating the Client to override default
cache client settings.
* Use ``cached=False`` when retrieving a resource to get a fresh copy and
add it to the cache.
* Use ``Query.is_cached`` to check if a resource is cached
e.g. ``api.query(resource_name).is_cached(resource_id)``
* Use ``Query.purge_cached`` to purge a resource from the cache.
e.g. ``api.query(resource_name).purge_cached(resource_id)``
``gapipy.cache.SimpleCache``
A simple in-memory cache for single process environments and is not
thread safe.
``gapipy.cache.RedisCache``
A key-value cache store using Redis as a backend.
``gapipy.cache.NullCache``
A cache that doesn't cache.
Since the cache backend is defined by a python module path, you are free to use
a cache backend outside of this project.
Dependencies
------------
The only dependency needed to use the client is requests_.
.. _requests: http://python-requests.org
History
-------
0.1.19 (2014-11-17)
-------------------
* Fixed a bug with `RedisCache.is_cached` where it would not use the set `key_prefix` when checking for existence in cache. Effectively, it would always return False
0.1.18 (2014-11-12)
-------------------
* When setting a date_field, initiate it as a `datetime.date` type.
0.1.17 (2014-11-07)
------------------
* Deprecated `RedisHashCache` from cache backends available by default. Was not well tested or reliable.
0.1.16 (2014-10-28)
---------------------
* Fixed a bug where if a model field received `null` as a value, it would fail. Now,
if the result is `null`, the model field will have an appropriate `None` value.
0.1.15 (2014-10-23)
---------------------
* Fix a bug in the DepartureRoom model. The `price_bands` attribute is now
properly set.
0.1.14 (2014-10-22)
---------------------
* Fixed a bug where AgencyDocument was not included in the code base.
0.1.13 (2014-10-21)
---------------------
* Add ``latitude``, ``longitude``, and ``documents`` to the ``Agency`` resource.
0.1.12 (2014-10-20)
---------------------
* ``date_created`` on the ``Agency`` resource is correctly parsed as a local time.
0.1.11 (2014-10-15)
---------------------
* Improve the performance of ``Resource.fetch`` by handling cache get/set.
0.1.10 (2014-10-09)
---------------------
* Fix a bug in AccommodationRoom price bands. The `season_dates` and
`blackout_dates` attributes are now properly set.
0.1.9 (2014-09-23)
---------------------
* Add `iso_639_3` and `iso_639_1` to `Language`
0.1.8 (2014-09-17)
---------------------
* Remove the `add_ons` field in `Departure`, and add `addons`.
0.1.7 (2014-08-22)
---------------------
* Fix a bug when initializing AccommodationRoom from cached data.
0.1.6 (2014-08-19)
---------------------
* Add Query.purge_cached
0.1.5 (2014-07-29)
---------------------
* Add `details` field to the list of `incomplete_requirements` in a `DepartureService`.
0.1.4 (2014-07-21)
---------------------
* Removed sending of header `X-HTTP-Method-Override: PATCH` when the update
command is called. Now, when `.save(partial=True)` is called, the
correct PATCH HTTP method will be sent with the request.
0.1.3 (2014-07-18)
------------------
* Return ``None`` instead of raising a HTTPError 404 exception when fetching a
non-existing resource by id.
* Added ability to create resources from the Query objects on the client
instance (for example, ``api.customers.create({'name': {'legal_first_name': 'Pat', ...}, ...})``)
0.1.2 (2014-07-14)
------------------
* Added Query.is_cached
* Added cache options
0.1.1 (2014-06-27)
------------------
* Use setuptools find_packages
0.1.0 (2014-06-20)
------------------
* First release on PyPI.
G API Python Client
===============================
.. image:: https://badge.fury.io/py/gapipy.svg
:target: http://badge.fury.io/py/gapipy
.. image:: https://travis-ci.org/gadventures/gapipy.svg?branch=master
:target: https://travis-ci.org/gadventures/gapipy
A client for the G Adventures REST API (https://developers.gadventures.com)
* GitHub Repository: https://github.com/gadventures/gapipy/
* Documentation: http://gapipy.readthedocs.org.
* Free software: MIT license
Quick Start
-----------
>>> from gapipy import Client
>>> api = Client(application_key='MY_SECRET_KEY')
>>> tour = api.tours.get(21346)
>>> tour.product_line
u'PPP'
>>> tour.departures.count()
105
>>> dossier = tour.tour_dossier
>>> dossier.name
u'Peru Panorama'
>>> tour.get_brief_itinerary()[:2]
[{'body': u'Arrive at any time.', 'label': u'Day 1 Lima'},
{'body': u'Fly to Juliaca and transfer to Puno. Visit the floating Islands of Uros and take a guided tour of Lake Titicaca with a homestay in a small village. Optional visit to Sillustani burial site.',
'label': u'Days 2-4 Puno/Lake Titicaca (1B,1L,1D)'}]
Resources
---------
Resource objects are instantiated from python dictionaries created from JSON
data. The fields are parsed and converted to python objects as specified in the
resource class.
A nested resource will only be instantiated when its corresponding attribute is
accessed in the parent resource.
A field pointing to the URL for a collection of a child resources will hold a
``Query`` object for that resource. As for nested resources, it will only be
instantiated when it is first accessed.
Queries
-------
A Query for a resource can be used to fetch resources of that type (either a
single instance or an iterator over them, possibly filtered according to some
conditions). Queries are roughly analogous to Django's QuerySets.
An API client instance has a query object for each available resource
(accessible by an attribute named after the resource name)
Methods on Query objects
========================
All queries support the ``get`` method. The other methods are only supported
for queries whose resources are listable.
``get(resource_id)``
Get a single resource.
``all([limit=n])``
Generator over all resources in the current query. If ``limit`` is a
positive integer ``n``, then only the first ``n`` results will be returned.
``filter(field1=value1, [field2=value2, ...])``
Filter resources on the provided fields and values. Calls to ``filter`` can
be chained.
``count()``
Return the number of resources in the current query (by reading the
``count`` field on the response returned by requesting the list of
resources in the current query).
Caching
-------
A handful of cache backends are available for your use. The cache backend is
configurable by adjusting the ``GAPI_CACHE_BACKEND`` environment variable.
* Use ``cache_options`` when instantiating the Client to override default
cache client settings.
* Use ``cached=False`` when retrieving a resource to get a fresh copy and
add it to the cache.
* Use ``Query.is_cached`` to check if a resource is cached
e.g. ``api.query(resource_name).is_cached(resource_id)``
* Use ``Query.purge_cached`` to purge a resource from the cache.
e.g. ``api.query(resource_name).purge_cached(resource_id)``
``gapipy.cache.SimpleCache``
A simple in-memory cache for single process environments and is not
thread safe.
``gapipy.cache.RedisCache``
A key-value cache store using Redis as a backend.
``gapipy.cache.NullCache``
A cache that doesn't cache.
Since the cache backend is defined by a python module path, you are free to use
a cache backend outside of this project.
Dependencies
------------
The only dependency needed to use the client is requests_.
.. _requests: http://python-requests.org
History
-------
0.1.19 (2014-11-17)
-------------------
* Fixed a bug with `RedisCache.is_cached` where it would not use the set `key_prefix` when checking for existence in cache. Effectively, it would always return False
0.1.18 (2014-11-12)
-------------------
* When setting a date_field, initiate it as a `datetime.date` type.
0.1.17 (2014-11-07)
------------------
* Deprecated `RedisHashCache` from cache backends available by default. Was not well tested or reliable.
0.1.16 (2014-10-28)
---------------------
* Fixed a bug where if a model field received `null` as a value, it would fail. Now,
if the result is `null`, the model field will have an appropriate `None` value.
0.1.15 (2014-10-23)
---------------------
* Fix a bug in the DepartureRoom model. The `price_bands` attribute is now
properly set.
0.1.14 (2014-10-22)
---------------------
* Fixed a bug where AgencyDocument was not included in the code base.
0.1.13 (2014-10-21)
---------------------
* Add ``latitude``, ``longitude``, and ``documents`` to the ``Agency`` resource.
0.1.12 (2014-10-20)
---------------------
* ``date_created`` on the ``Agency`` resource is correctly parsed as a local time.
0.1.11 (2014-10-15)
---------------------
* Improve the performance of ``Resource.fetch`` by handling cache get/set.
0.1.10 (2014-10-09)
---------------------
* Fix a bug in AccommodationRoom price bands. The `season_dates` and
`blackout_dates` attributes are now properly set.
0.1.9 (2014-09-23)
---------------------
* Add `iso_639_3` and `iso_639_1` to `Language`
0.1.8 (2014-09-17)
---------------------
* Remove the `add_ons` field in `Departure`, and add `addons`.
0.1.7 (2014-08-22)
---------------------
* Fix a bug when initializing AccommodationRoom from cached data.
0.1.6 (2014-08-19)
---------------------
* Add Query.purge_cached
0.1.5 (2014-07-29)
---------------------
* Add `details` field to the list of `incomplete_requirements` in a `DepartureService`.
0.1.4 (2014-07-21)
---------------------
* Removed sending of header `X-HTTP-Method-Override: PATCH` when the update
command is called. Now, when `.save(partial=True)` is called, the
correct PATCH HTTP method will be sent with the request.
0.1.3 (2014-07-18)
------------------
* Return ``None`` instead of raising a HTTPError 404 exception when fetching a
non-existing resource by id.
* Added ability to create resources from the Query objects on the client
instance (for example, ``api.customers.create({'name': {'legal_first_name': 'Pat', ...}, ...})``)
0.1.2 (2014-07-14)
------------------
* Added Query.is_cached
* Added cache options
0.1.1 (2014-06-27)
------------------
* Use setuptools find_packages
0.1.0 (2014-06-20)
------------------
* First release on PyPI.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
gapipy-0.1.19.tar.gz
(34.4 kB
view hashes)