docs/index.rst
.. turbasen.py documentation master file, created by
sphinx-quickstart on Fri Jan 29 07:26:30 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
turbasen.py
=============================
Python client for `Nasjonal Turbase <http://www.nasjonalturbase.no/>`_,
featuring:
- :ref:`Object model for all datatypes <datatypes>`
- :ref:`Container API on instances to access document fields (dict-like)
<document-fields>`
- :ref:`Exceptions abstract away HTTP status codes <exceptions>`
- :ref:`Automatic iteration over paginated list queries <static-methods>`
- :ref:`Handling partial documents returned from list queries
<partial-documents>`
- :ref:`ETag handling with refresh on expiry <settings>`
- :ref:`Client caching <settings>`
- :ref:`Event triggers <events>`
Installation
-----------------------------
.. code-block:: bash
pip install turbasen
.. _datatypes:
Datatypes
-----------------------------
.. py:class:: turbasen.Bilde
`Images <http://www.nasjonalturbase.no/data/bilder/>`_
.. py:class:: turbasen.Gruppe
`Groups <http://www.nasjonalturbase.no/data/grupper/>`_
.. py:class:: turbasen.Liste
`Lister <http://www.nasjonalturbase.no/data/lister/>`_
.. py:class:: turbasen.Område
`Areas <http://www.nasjonalturbase.no/data/omrader/>`_
.. py:class:: turbasen.Sted
`Places <http://www.nasjonalturbase.no/data/steder/>`_
.. py:class:: turbasen.Tur
`Trips <http://www.nasjonalturbase.no/data/turer/>`_
Environment variables
-----------------------------
``API_KEY``
Your API key. Can also be specified via the ``API_KEY`` setting.
``ENDPOINT_URL``
API endpoint. See the ``ENDPOINT_URL`` setting.
.. _settings:
Settings
-----------------------------
``ENDPOINT_URL = https://api.nasjonalturbase.no``
API endpoint. Set to ``https://dev.nasjonalturbase.no`` for development.
``LIMIT = 20``
Documents returned per page. API hard max limit is currently 50. Note that
setting this to a low number when the use case is to retrieve all documents is
inefficient.
``CACHE = DummyCache()``
Can be set to a cache engine implementing a small subset of the Django cache
API to enable caching.
``CACHE_LOOKUP_PERIOD = 60 * 60 * 24``
Number of seconds a *list* cache is retained
``CACHE_GET_PERIOD = 60 * 60 * 24 * 30``
Number of seconds an *object* cache is retained. Note that *ETag* may be
checked and used to expire the cache if applicable, so this value should
normally be high.
``ETAG_CACHE_PERIOD = 60 * 60``
Number of seconds to ignore ``ETag`` checks and use local cache blindly.
``API_KEY = os.environ.get('API_KEY', '')``
Get your API key at
`Nasjonal Turbase Developer <https://developer.nasjonalturbase.no/>`_.
Example usage
-----------------------------
Initialization:
.. code-block:: python
import turbasen
turbasen.configure(LIMIT=3, ENDPOINT='https://dev.nasjonalturbase.no')
List documents, with some parameter filters:
.. code-block:: python
turbasen.Sted.list(pages=1, params={
'tilbyder': 'DNT',
'status': 'Offentlig',
'tags': 'Hytte',
})
# [<Sted: 52407fb375049e561500027d (partial): Øvre Grue>,
# <Sted: 52407fb375049e561500035a (partial): Ravnastua fjellstue>,
# <Sted: 52407fb375049e5615000356 (partial): Lahpoluoppal>]
Get single document:
.. code-block:: python
sted = turbasen.Sted.get('546b36a511f41a9c00c0d4d9')
# <Sted: 546b36a511f41a9c00c0d4d9: En liten hytte>
sted['navn']
# En liten hytte
len(sted)
# 17
Create and delete document:
.. code-block:: python
sted = turbasen.Sted(
lisens='Privat',
status='Kladd',
navn='Testcabin',
beskrivelse='Testcabin',
tags=['Hytte'],
)
sted.save()
# API warning: {
# 'code': 'missing_field',
# 'field': 'navngiving',
# 'resource': 'Document'
# }
sted.delete()
API
-----------------------------
.. _static-methods:
Static methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. py:function:: list(pages=None, params=dict())
Return a list of documents. If ``pages`` is not ``None``, limits the results
to ``pages`` pages with ``LIMIT`` documents on each page.
Filter results with ``params``, or specify which ``fields`` should be
returned to increase performance, avoiding extra fetches for
:ref:`partial documents <partial-documents>`. See
`the API documentation <http://www.nasjonalturbase.no/api/>`_.
.. py:function:: get(object_id)
Retrieve a document of this datatype with the given object id.
.. _instance-methods:
Instance methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. py:function:: save()
Save this document. If the document doesn't have an ``_id`` field, it will be
assigned. Saving a :ref:`partial document <partial-documents>` will perform
a ``PATCH`` request, only overwriting fields that are defined locally.
.. py:function:: delete()
Delete this document. It must be saved (ie. have an ``_id`` field).
.. py:function:: get_field(key[, default])
See `dict.get <https://docs.python.org/3/library/stdtypes.html?#dict.get>`_
.. _document-fields:
Document fields
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Instances are
`collections <https://docs.python.org/3/library/collections.html>`_, so document
fields are accessed as keys on a regular ``dict``. All
`dict methods <https://docs.python.org/3/library/stdtypes.html?#dict>`_ are
implemented, except for
`dict.get <https://docs.python.org/3/library/stdtypes.html?#dict.get>`_ which is
renamed to ``get_field``, see :ref:`instance methods <instance-methods>`.
.. _exceptions:
Exceptions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. py:class:: turbasen.exceptions.DocumentNotFound
Thrown when a request references to a document with an object id that doesn't
exist.
.. py:class:: turbasen.exceptions.Unauthorized
Thrown when a request returns a HTTP 401 Unathorized or 403 Forbidden status
code.
.. py:class:: turbasen.exceptions.InvalidDocument
Thrown when updating or creating a document with invalid data.
.. py:class:: turbasen.exceptions.ServerError
Thrown when a request results in a 5xx server error response.
.. _partial-documents:
Partial documents
-----------------------------
Documents returned from calling ``list`` are not complete, but classified as
*partial*. When accessing a field on a partial document which does not exist,
a ``GET`` request is automatically performed under the hood to request the
entire document. If the accessed field now exists, it is returned as normal.
If you know you only need a few fields from a ``list`` call, it may be a good
idea to specify those in the params field like this:
``params={'fields': ['field1', 'field2']}`` to avoid performing a ``GET``
request for each of the documents in your list.
.. _events:
Events
-----------------------------
.. code-block:: python
def handle_get_request():
logger.debug("turbasen.py performed a GET request.")
turbasen.handle_event('api.get_object', handle_get_request)
``api.get_object``
GET request made for a single object
``api.get_objects``
GET request for a new page with list of objects - called once for each new
page
``api.post_object``
POST request made with a new object
``api.put_object``
PUT request made for an existing object
``api.delete_object``
DELETE request made for an existing object