Metadata-Version: 1.1
Name: siren-client
Version: 1.0.0.dev1
Summary: Client for a Siren based Hypermedia API
Home-page: https://github.com/lonelyplanet/siren-client-python
Author: Will Wheatley
Author-email: will.wheatley@lonelyplanet.com.au
License: Apache 2.0
Description: Siren Client for Python
        =======================
        
        
        A generic client for consuming Hypermedia API's which utilise
        [Siren](https://github.com/kevinswiber/siren) for the entity schema.
        
        The client consumes the Siren and creates objects which represent the various
        Siren Objects. This library does not provide a transport mechanism to access the
        API but is designed to work with a
        [requests](http://docs.python-requests.org/en/latest/) session.
        
        Authentication is managed by the session manager provided to the the Siren
        client. Usage patterns below.
        
        
        ## Installing
        
        The library is available to install using pip:
        
            $ pip install siren-client
        
        Alternatively, you can clone this package and install it yourself.
        
        
        ## Getting Started
        
        The client is designed to allow you to traverse the data in the API, without
        having to worry about requests or URL construction. You simply need to provide
        the first object with a url:
        
        ```python
        import siren_client
        
        entity = siren_client.get('http://some.siren-api.com/')
        ```
        
        Each Siren Entity provided some introspection so that you can quickly see what
        the entity is.
        
        ```python
        print entity
        ```
        
        All of siren concepts are available as Python constructs.
        
        ### Basic Siren Attributes
        
        ```python
        print entity.uri
        print entity.class_
        print entity.rel  # Generally only if it is a sub-entity
        ```
        
        ### Siren Properties are available on the entity
        
        ```python
        print entity['Name']
        ```
        
        ### An Entity can be 'refreshed' from the server
        
        ```python
        entity.refresh()
        ```
        
        ### Following Siren links
        
        ```python
        print entity.links
        second_entity = entity.links['some-link']
        ```
        
        ### Using Siren Actions
        
        ```python
        print entity.actions
        print entity.actions['next']
        
        collection = entity.actions['next']()
        
        # You can pass any parameters to an action
        
        collection = entity.actions['next'](skip=3)
        
        # You can seed an action with the properties of some other entity
        
        new_entity_action = entity.actions['new-entity']
        new_entity_action.populate(entity)
        new_entity_action()  # This will call the action with the data set from `entity`
        new_entity_action(Name='Another Name')  # This will call the action as above
                                                # but override (or set) the name to be
                                                # 'Another Name'
        
        ```
        
        ## Config
        
        Configuration can be provided to the `get` function earlier.
        
        ```python
        import siren_client
        entity siren_client.get('http://my_url/', rel_base='https://my_api.com/rels/')
        ```
        
         - `rel_base` If set to a value, and this value is at the start of any rel
            that rel will have that value removed:
        
            Example:
            setting the rel_base to 'http://my.company/schema/' will convert any
            rel from the API (such as 'http://my.company/schema/my_link') to a
            shortened version (in this example: `my_link`)
        
         - `dumps` Provide your own function for serialising any requests. By default
            Siren Client will inspect the content type and automatically
            serialise into JSON as needed. The function will receive two
            parameters, the requested content type, and the data to serialise.
        
            ```python
            def my_dumps(content_type, data):
                # Convert data here
                return converted_data
            ```
        
         - `loads` Provide your own function for de-serialising any requests. By default
            Siren Client will inspect the content type and automatically
            de-serialise from JSON as needed. The function will receive two
            parameters, the requested content type, and the content to
            de-serialise.
        
            ```python
            def my_loads(content_type, data):
                # Convert data here
                return converted_data
            ```
        
         - `self_rel` By default the Siren Client will calculate the canonical 'URI' of
            an entity from the link containing a rel called `self`. This
            parameter lets you change the rel that the library will use to
            determine the canonical 'URI'.
        
        
        ## Authentication Setup
        
        The library expects a *requests* session (or similar) to manage the connection
        to the server. Whatever methods of authentication requests supports, the
        siren-client also supports. Any other transport configuration required (such as
        keep-alive, headers etc) can be utilised by configuring the Session or
        sub-classing the Session.
        
        ### Example Basic Authentication
        
        ```python
        import siren_client
        from requests import Session
        from requests.auth import HTTPBasicAuth
        
        session = Session()
        session.auth = HTTPBasicAuth('my_username', 'my_password')
        entity = siren_client.get('http://my.url.com/', session=session)
        ```
        
        ### Example Session Hook
        
        ```python
        def mutate_response_somehow(req, *args, **kwargs):
            # do something
            print r.url
        
        session = Session()
        session.hooks['response'] = mutate_response_somehow
        entity = siren_client.get('http://my.url.com/', session=session)
        ```
        
        ### Example Custom Header
        
        ```python
        session = Session()
        session.headers['X-Pizza'] = 'pepperoni'
        entity = siren_client.get('http://my.url.com/', session=session)
        ```
        
        ### Other plugins for Requests Session
        
         - https://github.com/requests/requests-oauthlib
        
        ## Replace Requests Session with your own transport
        
        The session simply provides a transport mechanism for the client. It could be
        completely replaced with an arbitrary object doing arbitrary things (such as
        communicating in some way other than HTTP). The only methods that are called on
        the Session object are the HTTP verbs, with the `get` being used for following
        links, etc. If your siren API provided a method of 'hyperspace' in an action
        definition, then the library would attempt to call the `hyperspace` method on
        the session transport.
        
        Regardless of which method is used to get the data from the server, the response
        is then required to have two attributes and one method:
        
          - `content` This can be whatever you want. By default it attempt to be
            de-serialized as JSON
          - `headers` A dictionary
          - `raise_for_status()` This allows the response to throw an exception if there
            is something wrong.
        
        
        ## Maintainers
        
        Lonely Planet maintains this code as a library that it actively uses.
        Contributions are welcome in the form of bug reports and pull requests.
        
        
        
        1.0.0.dev1
        ---
        
        -  Initial version for develoment use.
        
Keywords: siren hypermedia json
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries
Classifier: License :: OSI Approved :: Apache Software License
