gapipy 0.1.21

Python client for the G Adventures REST API

===============================
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.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.