Package: siren-client
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 variousSiren Objects. This library does not provide a transport mechanism to access theAPI 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 Sirenclient. Usage patterns below.## InstallingThe library is available to install using pip:$ pip install siren-clientAlternatively, you can clone this package and install it yourself.## Getting StartedThe client is designed to allow you to traverse the data in the API, withouthaving to worry about requests or URL construction. You simply need to providethe first object with a url:```pythonimport siren_cliententity = siren_client.get('http://some.siren-api.com/')```Each Siren Entity provided some introspection so that you can quickly see whatthe entity is.```pythonprint entity```All of siren concepts are available as Python constructs.### Basic Siren Attributes```pythonprint entity.uriprint entity.class_print entity.rel  # Generally only if it is a sub-entity```### Siren Properties are available on the entity```pythonprint entity['Name']```### An Entity can be 'refreshed' from the server```pythonentity.refresh()```### Following Siren links```pythonprint entity.linkssecond_entity = entity.links['some-link']```### Using Siren Actions```pythonprint entity.actionsprint entity.actions['next']collection = entity.actions['next']()# You can pass any parameters to an actioncollection = entity.actions['next'](skip=3)# You can seed an action with the properties of some other entitynew_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'```## ConfigConfiguration can be provided to the `get` function earlier.```pythonimport siren_cliententity 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 relthat rel will have that value removed:Example:setting the rel_base to 'http://my.company/schema/' will convert anyrel from the API (such as 'http://my.company/schema/my_link') to ashortened version (in this example: `my_link`)- `dumps` Provide your own function for serialising any requests. By defaultSiren Client will inspect the content type and automaticallyserialise into JSON as needed. The function will receive twoparameters, the requested content type, and the data to serialise.```pythondef my_dumps(content_type, data):# Convert data herereturn converted_data```- `loads` Provide your own function for de-serialising any requests. By defaultSiren Client will inspect the content type and automaticallyde-serialise from JSON as needed. The function will receive twoparameters, the requested content type, and the content tode-serialise.```pythondef my_loads(content_type, data):# Convert data herereturn converted_data```- `self_rel` By default the Siren Client will calculate the canonical 'URI' ofan entity from the link containing a rel called `self`. Thisparameter lets you change the rel that the library will use todetermine the canonical 'URI'.## Authentication SetupThe library expects a *requests* session (or similar) to manage the connectionto the server. Whatever methods of authentication requests supports, thesiren-client also supports. Any other transport configuration required (such askeep-alive, headers etc) can be utilised by configuring the Session orsub-classing the Session.### Example Basic Authentication```pythonimport siren_clientfrom requests import Sessionfrom requests.auth import HTTPBasicAuthsession = Session()session.auth = HTTPBasicAuth('my_username', 'my_password')entity = siren_client.get('http://my.url.com/', session=session)```### Example Session Hook```pythondef mutate_response_somehow(req, *args, **kwargs):# do somethingprint r.urlsession = Session()session.hooks['response'] = mutate_response_somehowentity = siren_client.get('http://my.url.com/', session=session)```### Example Custom Header```pythonsession = 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 transportThe session simply provides a transport mechanism for the client. It could becompletely replaced with an arbitrary object doing arbitrary things (such ascommunicating in some way other than HTTP). The only methods that are called onthe Session object are the HTTP verbs, with the `get` being used for followinglinks, etc. If your siren API provided a method of 'hyperspace' in an actiondefinition, then the library would attempt to call the `hyperspace` method onthe session transport.Regardless of which method is used to get the data from the server, the responseis then required to have two attributes and one method:- `content` This can be whatever you want. By default it attempt to bede-serialized as JSON- `headers` A dictionary- `raise_for_status()` This allows the response to throw an exception if thereis something wrong.## MaintainersLonely 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.