jsonhome package¶

Subpackages¶

Module contents¶

class jsonhome.Document¶

Bases: dict

A model of a JSON Home document that can be manipulated.

add_resource(relation, **kwargs)¶

Create a new resource on this document.

Create a new resource with prefilled attributes and add it to the current document.

Parameters:	relation (str) – The string relationship to this resource that will be used to identity resources. href (str) – A direct URI link to a resource. href_template (str) – A template from which a URI is determined. href_vars (dict) – The raw href variables that should be set. uri (str) – A templatable URI, of the form expected by `set_uri()`. uri_vars (dict) – The URI variables that are interpolated in the form expected by `set_uri()`. docs (str) – location for human-readable documentation. allow_delete (bool) – allow the DELETE method on resource. allow_get (bool) – allow the GET method on resource. allow_head (bool) – allow the HEAD method on resource. allow_options (bool) – allow the OPTIONS method on resource. allow_patch (bool) – allow the PATCH method on resource. allow_post (bool) – allow the POST method on resource. allow_put (bool) – allow the PUT method on resource. accept_patch (list(str)) – Hints the PATCH [RFC5789] request formats accepted by the resource for this client; equivalent to the Accept-Patch HTTP response header. accept_post (list(str)) – Hints the POST request formats accepted by the resource for this client. accept_prefer (list(str)) – Hints the preferences supported by the resource. Note that, as per that specifications, a preference can be ignored by the server. accept_ranges (list(str)) – Hints the range-specifiers available to the client for this resource; equivalent to the Accept-Ranges HTTP response header
Raises:	jsonhome.ResourceAlreadyExists – If there is already a relation with the requested name available on the document.
Returns:	The new resource. This is the same resource that was added to the document so a user may perform additional manipulation.
Return type:	`Resource`.

classmethod from_dict(data)¶

Create a json-home document from de-serialized data.

Convert a dict that may have been received from an external site into a json-home document that can be manipulated and queried.

Parameters:	data (dict) – The data to be converted.
Return type:	`Document`

classmethod from_json(data)¶

Create a JSON home document from a JSON string.

Take a string that was received from a remote service and load the JSON home document that describes its resources.

Return type:	`Document`

get_uri(relation, **kwargs)¶

Get an absolute URI for this resource.

Fetch the absolute URI. If there is an absolute URI set on this resource that will be returned.

If there is a templated URI then the variables in the template will be evaluated against the values passed in through keyword arguments.

Parameters:	relation (str) – The relation to the resource you wish to get the URI for.

resource_class¶

The class of resource that should be created.

alias of Resource

to_dict()¶

Convert the document into a serializable format.

Convert the current document into a valid json-home format so that it can be serialized into JSON.

Return type:	dict

to_json(**kwargs)¶

Convert the Document into JSON format.

Serialize the json-home document into valid JSON so that it can be sent to users.

Return type:	str

class jsonhome.Resource¶

Bases: dict

One resource that exists within a JSON home document.

accept_patch¶

Hints the PATCH request formats accepted by the resource.

This is equivalent to the Accept-Patch HTTP response header.

accept_post¶: Hints the POST request formats accepted by the resource.

accept_prefer¶

Hints the preferences supported by the resource.

Note that, as per that specifications, a preference can be ignored by the server.

accept_ranges¶

Hints the range-specifiers available to the client.

This is equivalent to the Accept-Ranges HTTP response header.

allow¶

HTTP Allow Methods for this resource.

Hints the HTTP methods that the current client will be able to use to interact with the resource; equivalent to the Allow HTTP response header.

allow_delete¶: Allow the DELETE method on this resource

allow_get¶: Allow the GET method on this resource

allow_head¶: Allow the HEAD method on this resource

allow_options¶: Allow the OPTIONS method on this resource

allow_patch¶: Allow the PATCH method on this resource

allow_post¶: Allow the POST method on this resource

allow_put¶: Allow the PUT method on this resource

classmethod create(**kwargs)¶

Create a new resource with specified values.

A factory function that allows you to create a new Resource object with a number of attributes in one method.

Parameters:

href (str) – A direct URI link to a resource.
href_template (str) – A template from which a URI is determined.
href_vars (dict) – The raw href variables that should be set.
uri (str) – A templatable URI, of the form expected by set_uri().
uri_vars (dict) – The URI variables that are interpolated in the form expected by set_uri().
docs (str) – location for human-readable documentation.
allow_delete (bool) – allow the DELETE method on resource.
allow_get (bool) – allow the GET method on resource.
allow_head (bool) – allow the HEAD method on resource.
allow_options (bool) – allow the OPTIONS method on resource.
allow_patch (bool) – allow the PATCH method on resource.
allow_post (bool) – allow the POST method on resource.
allow_put (bool) – allow the PUT method on resource.
accept_patch (list(str)) – Hints the PATCH [RFC5789] request formats accepted by the resource for this client; equivalent to the Accept-Patch HTTP response header.
accept_post (list(str)) – Hints the POST request formats accepted by the resource for this client.
accept_prefer (list(str)) – Hints the preferences supported by the resource. Note that, as per that specifications, a preference can be ignored by the server.
accept_ranges (list(str)) – Hints the range-specifiers available to the client for this resource; equivalent to the Accept-Ranges HTTP response header

Return type:

Resource.

docs¶: The location for human-readable documentation for the resource.

get_uri(**kwargs)¶

Get an absolute URI for this resource.

Fetch the absolute URI. If there is an absolute URI set on this resource that will be returned.

If there is a templated URI then the variables in the template will be evaluated against the values passed in through keyword arguments.

hints¶

Additional hint information defined by the resource.

Resource hints allow clients to find relevant information about interacting with a resource beforehand, as a means of optimising communications, as well as advertising available behaviours (e.g., to aid in laying out a user interface for consuming the API).

Hints are just that - they are not a “contract”, and are to only be taken as advisory. The runtime behaviour of the resource always overrides hinted information.

For example, a resource might hint that the PUT method is allowed on all “widget” resources. This means that generally, the user has the ability to PUT to a particular resource, but a specific resource might reject a PUT based upon access control or other considerations. More fine-grained information might be gathered by interacting with the resource (e.g., via a GET), or by another resource “containing” it (such as a “widgets” collection) or describing it (e.g., one linked to it with a “describedby” link relation).

href¶: A Direct URI Link to a resource.

href_template¶: A templated URI link to a resource.

href_vars¶: A indication for variables in the template to construct a URI.

is_allowed(method)¶

Test if a HTTP method can be used with this resource.

Parameters:	method (str) – a HTTP method string to find.
Returns:	bool or None if no hints are defined by the resource.

set_uri(uri, **kwargs)¶

Set the URI on this resource based on its format.

Selective set the href or href-template and href-vars depending on if the URI contains a templated form or not. If there are variables set in the URI then a relation name be passed as a kwarg as well.

Passing an absolute URI:

res.set_uri('/path/to/resource')

Passing a templated URI:

res.set_uri('/path/to/resource{/param}',
            param='http://description/rel/param')

Parameters:	uri (str) – The URI you want to set. This may contain variables.
Raises:	jsonhome.MissingValues – If a templated URI is passed and there is not a relation passed as a keyword argument that matches the variable.

exception jsonhome.JsonHomeException¶

Bases: exceptions.Exception

Base Exception class that all JSONHome exceptions inherit from.

exception jsonhome.MissingValues¶

Bases: jsonhome.JsonHomeException

There is not enough information in the JSONHome document to finish.

exception jsonhome.UnknownResource¶

Bases: jsonhome.JsonHomeException

There is no resource available with the specified relation.

exception jsonhome.ResourceAlreadyExists¶

Bases: jsonhome.JsonHomeException

A resource with the specified relation already exists.