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
Testing
-------
Running tests is pretty simple. Just install the requirements and use nose.
pip install -r requirements-testing.txt
Once installed, test unit tests:
nosetests -A integration!=1
Otherwise, you'll want to include a GAPI Application Key so the integration
tests can successfully hit the API.
export GAPI_APPLICATION_KEY=MY_SECRET_KEY; nosetests
Thanks for helping!
History
-------
0.1.41 (2015-04-14)
------------------
* Added `DepartureComponent` resource. See the [official G API documentation for details](https://developers.gadventures.com/docs/departure_component.html)
0.1.40 (2015-04-06)
-------------------
* Added `deposit` to `DepartureService` model
0.1.39 (2015-03-31)
-------------------
* Refactor ``APIRequestor._request``. While this should not change existing functionality, it is now possible to override specific methods on ``APIRequestor`` if needed.
0.1.38 (2015-03-23)
-------------------
* Fixed: Due to inconsistencies in the G API with regards to nested resources, the `fetch` function was modified to use the raw data from the API, rather than a specific set of allowed fields.
0.1.37 (2015-03-23)
-------------------
* Fixed: Iterating over ``products`` within the ``promotions`` object now works as expected. Previously, accessing the ``products`` attribute would result in a Query object with incorrect parameters.
0.1.36 (2015-03-17)
-------------------
* Support free to amount price range formatting (e.g. Free-10CAD)
0.1.35 (2015-03-12)
-------------------
* Added `duration_min` & `duration_max` to `ActivityDossier` model
0.1.34 (2015-03-11)
-------------------
* Added `OptionalActivity` model
* All Dossiers with `details`:
* Now represented as list of `DossierDetail` models
* Added convenience methods for retrieving specific details
* `ItineraryComponent` and `ActivityDossier` use new `Duration` model
for their `duration` field/property
* Added `duration_label` and `location_label` to `ItineraryComponent`
* Added `duration_label`, `price_per_person_label`, and `price_per_group_label`
to `ActivityDossier`
0.1.33 (2015-03-02)
-------------------
* Added `name` field to the Itinerary resource.
0.1.32 (2015-02-18)
-------------------
* Changed cache key creation to account for `GAPI_LANGUAGE` when the environment variable is set.
0.1.31 (2015-02-18)
-------------------
* Fixed a bug when setting _resource_fields in ``DepartureService`` resource
0.1.30 (2015-02-11)
-------------------
* ``TourDossier.structured_itineraries`` now refers to a list of Itinerary
resources
0.1.29 (2015-02-10)
-------------------
* Added ``TransportDossier`` and ``Itinerary`` resources.
* The reference to the itinerary in a ``DepartureService`` is now a
full-fledged ``Itinerary`` resource.
0.1.28 (2015-01-22)
-------------------
* Bug fix to correctly send ``Content-Type: application/json`` in POST, PUT, or PATCH.
0.1.27 (2015-01-19)
-------------------
* Update ``DepartureService`` object to contain a reference to its ``Itinerary``
0.1.26 (2015-01-14)
-------------------
* Normalize API request headers, to promote caching.
0.1.25 (2015-01-09)
-------------------
* Added ``ActivityDossier`` and ``AccommodationDossier`` resources, as well as references to it from ``Activity`` and ``Accommodation``.
0.1.24 (2015-01-07)
-------------------
* Added ``PlaceDossier`` resource, as well as reference to it from ``Place``
0.1.22 (2014-12-12)
-------------------
* Added ``advertised_departures`` to ``TourDossier``
0.1.21 (2014-11-26)
-------------------
* Fixed a bug with promotions on a Price object. When promotions were accessed, gapipy would query for all promotions, rather than returning the inline list.
0.1.20 (2014-11-20)
-------------------
* Departure resource is now listable via filters.
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
Testing
-------
Running tests is pretty simple. Just install the requirements and use nose.
pip install -r requirements-testing.txt
Once installed, test unit tests:
nosetests -A integration!=1
Otherwise, you'll want to include a GAPI Application Key so the integration
tests can successfully hit the API.
export GAPI_APPLICATION_KEY=MY_SECRET_KEY; nosetests
Thanks for helping!
History
-------
0.1.41 (2015-04-14)
------------------
* Added `DepartureComponent` resource. See the [official G API documentation for details](https://developers.gadventures.com/docs/departure_component.html)
0.1.40 (2015-04-06)
-------------------
* Added `deposit` to `DepartureService` model
0.1.39 (2015-03-31)
-------------------
* Refactor ``APIRequestor._request``. While this should not change existing functionality, it is now possible to override specific methods on ``APIRequestor`` if needed.
0.1.38 (2015-03-23)
-------------------
* Fixed: Due to inconsistencies in the G API with regards to nested resources, the `fetch` function was modified to use the raw data from the API, rather than a specific set of allowed fields.
0.1.37 (2015-03-23)
-------------------
* Fixed: Iterating over ``products`` within the ``promotions`` object now works as expected. Previously, accessing the ``products`` attribute would result in a Query object with incorrect parameters.
0.1.36 (2015-03-17)
-------------------
* Support free to amount price range formatting (e.g. Free-10CAD)
0.1.35 (2015-03-12)
-------------------
* Added `duration_min` & `duration_max` to `ActivityDossier` model
0.1.34 (2015-03-11)
-------------------
* Added `OptionalActivity` model
* All Dossiers with `details`:
* Now represented as list of `DossierDetail` models
* Added convenience methods for retrieving specific details
* `ItineraryComponent` and `ActivityDossier` use new `Duration` model
for their `duration` field/property
* Added `duration_label` and `location_label` to `ItineraryComponent`
* Added `duration_label`, `price_per_person_label`, and `price_per_group_label`
to `ActivityDossier`
0.1.33 (2015-03-02)
-------------------
* Added `name` field to the Itinerary resource.
0.1.32 (2015-02-18)
-------------------
* Changed cache key creation to account for `GAPI_LANGUAGE` when the environment variable is set.
0.1.31 (2015-02-18)
-------------------
* Fixed a bug when setting _resource_fields in ``DepartureService`` resource
0.1.30 (2015-02-11)
-------------------
* ``TourDossier.structured_itineraries`` now refers to a list of Itinerary
resources
0.1.29 (2015-02-10)
-------------------
* Added ``TransportDossier`` and ``Itinerary`` resources.
* The reference to the itinerary in a ``DepartureService`` is now a
full-fledged ``Itinerary`` resource.
0.1.28 (2015-01-22)
-------------------
* Bug fix to correctly send ``Content-Type: application/json`` in POST, PUT, or PATCH.
0.1.27 (2015-01-19)
-------------------
* Update ``DepartureService`` object to contain a reference to its ``Itinerary``
0.1.26 (2015-01-14)
-------------------
* Normalize API request headers, to promote caching.
0.1.25 (2015-01-09)
-------------------
* Added ``ActivityDossier`` and ``AccommodationDossier`` resources, as well as references to it from ``Activity`` and ``Accommodation``.
0.1.24 (2015-01-07)
-------------------
* Added ``PlaceDossier`` resource, as well as reference to it from ``Place``
0.1.22 (2014-12-12)
-------------------
* Added ``advertised_departures`` to ``TourDossier``
0.1.21 (2014-11-26)
-------------------
* Fixed a bug with promotions on a Price object. When promotions were accessed, gapipy would query for all promotions, rather than returning the inline list.
0.1.20 (2014-11-20)
-------------------
* Departure resource is now listable via filters.
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.41.tar.gz
(40.3 kB
view hashes)