Metadata-Version: 1.1
Name: tortilla
Version: 0.5.0
Summary: Wrapping web APIs made easy.
Home-page: https://github.com/tortilla/tortilla
Author: Hidde Bultsma
Author-email: me@redodo.io
License: MIT
Description: Tortilla
        ========
        
        
        |Build Status| |Coverage| |Docs| |Version| |License|
        
        .. |Build Status| image:: https://img.shields.io/travis/tortilla/tortilla.svg?style=flat
            :target: https://travis-ci.org/tortilla/tortilla
            :alt: Build Status
        .. |Coverage| image:: https://img.shields.io/coveralls/tortilla/tortilla.svg?style=flat
            :target: https://coveralls.io/r/tortilla/tortilla
            :alt: Coverage
        .. |Docs| image:: https://readthedocs.org/projects/tortilla/badge/?version=latest&style=flat
            :target: https://tortilla.readthedocs.org/en/latest/
            :alt: Docs
        .. |Version| image:: https://img.shields.io/pypi/v/tortilla.svg?style=flat
            :target: https://pypi.python.org/pypi/tortilla
            :alt: Version
        .. |License| image:: https://img.shields.io/pypi/l/tortilla.svg?style=flat
            :target: https://github.com/tortilla/tortilla/blob/master/LICENSE
            :alt: License
        
        
        *Wrapping web APIs made easy.*
        
        
        Installation via PIP:
        
        .. code-block:: text
        
            pip install tortilla
        
        
        Quick usage overview:
        
        .. code-block:: python
        
            >>> import tortilla
            >>> github = tortilla.wrap('https://api.github.com')
            >>> user = github.users.get('octocat')
            >>> user.location
            u'San Francisco'
        
        
        The Basics
        ~~~~~~~~~~
        
        Tortilla uses a bit of magic to wrap APIs. Whenever you get or call an
        attribute of a wrapper, the URL is appended by that attribute's name or
        method parameter. Let's say we have the following code:
        
        .. code-block:: python
        
            id, count = 71, 20
            api = tortilla.wrap('https://api.example.org')
            api.video(id).comments.get(count)
        
        Every attribute and method call represents a part of the URL:
        
        .. code-block:: text
        
            api         -> https://api.example.org
            .video      -> /video
            (id)        -> /71
            .comments   -> /comments
            .get(count) -> /20
            Final URL   -> https://api.example.org/video/71/comments/20
        
        The last part of the chain (``.get()``) executes the request. It also
        (optionally) appends one last part to the URL. Which allows you to do
        stuff like this:
        
        .. code-block:: python
        
            api.video.get(id)
            # instead of this
            api.video(id).get()
        
        So to summarize, getting attributes is used to define static parts of a
        URL and calling them is used to define dynamic parts of a URL.
        
        Once you've chained everything together, Tortilla will execute the
        request and parse the response for you.
        
        At the moment, Tortilla only accepts JSON-formatted responses.
        Supporting more formats is on the roadmap for future Tortilla versions.
        
        The parsed response will be *bunchified* which makes dictionary keys
        accessible through attributes. So, say we get the following JSON
        response for the user 'john':
        
        .. code-block:: json
        
            {"name": "John Doe"}
        
        If we request this with an already created wrapper, we can access the
        response data through attributes:
        
        .. code-block:: python
        
            >>> user = api.users.get('john')
            >>> user.name
            u'John Doe'
        
        
        Headers
        ~~~~~~~
        
        A common requirement for accessing APIs is providing authentication
        data. This usually has to be described in the headers of each request.
        Tortilla makes it very easy for you to describe those recurring headers:
        
        .. code-block:: python
        
            api.config.headers.token = 'secret authentication token'
        
        You can also define custom headers per request:
        
        .. code-block:: python
        
            api.endpoint.get(headers={'this': 'that'})
        
        These headers will be appended to the existing headers of the wrapper.
        
        
        Parameters
        ~~~~~~~~~~
        
        URL parameters can be defined per request in the ``params`` option:
        
        .. code-block:: python
        
            api.search.get(params={'q': 'search query'})
        
        
        Caching
        ~~~~~~~
        
        Some APIs have a limit on the amount of requests you can make. In these
        cases, caching can be very helpful. You can activate this with the
        ``cache_lifetime`` parameter:
        
        .. code-block:: python
        
            api = tortilla.wrap('https://api.example.org', cache_lifetime=100)
        
        All the requests made on this wrapper will now be cached for 100
        seconds. If you want to ignore the cache in a specific situation, you
        can use the ``ignore_cache`` parameter:
        
        .. code-block:: python
        
            api.special.request.get(ignore_cache=True)
        
        The response will now be reloaded.
        
        
        URL Extensions
        ~~~~~~~~~~~~~~
        
        APIs like Twitter's require an extension in the URL that specifies the
        response format. This can be defined in the ``extension`` parameter:
        
        .. code-block:: python
        
            api = tortilla.wrap('https://api.twitter.com/1.1', extension='json')
        
        This option can be overridden with every request or subwrap:
        
        .. code-block:: python
        
            api.special.endpoint.extension = 'xml'
            api.special.endpoint.get(extension='xml')
        
        
        URL Suffix
        ~~~~~~~~~~
        
        Some APIs uses a trailling slash at the end of URLs like in example below:
        
        .. code-block:: text
        
            https://api.example.org/resource/
        
        You can add the trailling slash with ``suffix="/"`` argument when wrapping
        the API or getting the URL with ``.url(suffix="/")`` method:
        
        .. code-block:: python
        
            api = tortilla.wrap('https://api.example.org', suffix="/")
            api.video(71).comments.url()
        
        Will return the following URL:
        
        .. code-block:: text
        
            api         -> https://api.example.org
            .video      -> /video
            (id)        -> /71/
            Final URL   -> https://api.example.org/video/71/
        
        
        Debugging
        ~~~~~~~~~
        
        Activating debug mode can be done with the ``debug`` parameter:
        
        .. code-block:: python
        
            api.debug = True
            # OR
            api = tortilla.wrap('https://api.example.org', debug=True)
        
        You can override the ``debug`` parameter per request:
        
        .. code-block:: python
        
            api.stuff.get(debug=False)
            api.other.stuff.get(debug=True)
        
        An example using the GitHub API:
        
        .. code-block:: python
        
            >>> user = github.users.get('octocat')
            Executing GET request:
                URL:     https://api.github.com/users/octocat
                headers: {}
                query:   None
                data:    None
        
            Got 200 OK:
                {u'public_repos': 5, u'site_admin': ...
        
        
        *Enjoy your data.*
        
Keywords: api wrapper
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
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.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet
