Metadata-Version: 2.0
Name: tortilla
Version: 0.1.0.dev3
Summary: A tiny library for creating wrappers around external APIs
Home-page: https://github.com/redodo/tortilla
Author: Hidde Bultsma
Author-email: dodo@gododo.co
License: MIT
Keywords: api wrapper
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Internet
Requires-Dist: lunch
Requires-Dist: colorclass
Requires-Dist: requests
Requires-Dist: httpretty

Tortilla
========

.. image:: https://travis-ci.org/redodo/tortilla.svg
:target: https://travis-ci.org/redodo/tortilla

Wrapping web APIs made easy.

Installation:

.. code:: bash

    pip install --pre tortilla

Quick usage:

.. code:: python

    >>> import tortilla
    >>> github = tortilla.wrap('https://api.github.com')
    >>> redodo = github.users.get('redodo')
    >>> redodo.id
    2227416

Intro
-----

In the following examples we can assume that the following code is
already executed:

.. code:: python

    import tortilla
    api = tortilla.wrap('https://api.example.org')

Tortilla 101
------------

A quick overview of Tortilla's flow:

1. You form a chain of URL parts
2. You invoke a ``get``, ``post``, ``patch``, ``put`` or ``delete``
   method at the end of the chain
3. Tortilla requests the URL
4. Tortilla tries to JSON decode to response and puts it in a ``Bunch``
   object (dictionary accessible via dots)
5. Tortilla returns the *bunched* object

Headers
-------

Most APIs require a authentication token before you can access its
endpoints.

Those can be set in the headers of a wrapped object:

.. code:: python

    api.headers.token = 'super secret token'

Or if you first need to login before getting a token:

.. code:: python

    auth = api.auth.post(data={'username': 'foo', 'password': 'bar'})
    api.headers.token = auth.token

If the header key contains a dot or is a reserved keyword you can use
the key instead of the attribute:

.. code:: python

    api.headers['from'] = 'stuff'
    api.headers['secret.key'] = 'more stuff'

Caching
-------

Caching stuff is easy:

.. code:: python

    api.cache_lifetime = 3600  # seconds
    # OR
    api = tortilla.wrap('https://api.example.org', cache_lifetime=3600)

If you want to ignore the cache and force a reload:

.. code:: python

    api.some.endpoint.get(ignore_cache=True)

URL Extensions
--------------

If the endpoints of your target API require an extension for the
response formatting you can set the ``extension`` parameter:

.. code:: python

    api.extension = 'json'
    # OR
    api = tortilla.wrap('https://api.example.org', extension='json')

This can be overwritten per request or URL part:

.. code:: python

    api.special.case.extension = 'json'
    api.special.case.stuff.get()
    # requests: https://api.example.org/special/case/stuff.json



