Adapters

Adapters are responsible for transforming a Resource instance into a request body string. For example, in the SirenAdapter, they would put the properties in a dictionary called “properties”, the related resource in a list called “entities”, and so on and so forth. All adapters instantiation requires at least a resource instance.

Finally, adapters are independent of web framework and database/managers used. This means that you can completely reuse adapters across all of your applications.

Building your own adapter

At some point or another, you will probably want to roll out your own adapter. Maybe you are using a front-end framework that is expecting a specific format or maybe you’re porting over from django-rest-framework and don’t want to have to change your front-end. Either way, you want some flexibility in how the resource gets formatted.

For an example of a basic adapter check out the built in JSON adapter.

Required pieces

formats

A tuple or list of available formats in unicode/str form. These are the formats that are used to match the requests accept-types with the appropriate adapter.

AdapterBase.formatted_body

This property is the fully qualified and formatted response. For example, you might return a Hypermedia formatted response body such as the SIREN hypermedia protocol or HAL. This must be overridden by any subclass. Additionally, it is a property and must be decorated as such.

Returns:The formatted response body.
Return type:unicode
AdapterBase.extra_headers

Headers that should be added to response. For example it might be the content-type etc... This must be overridden by any subclass since it raises a NotImplementedError. It can also be overridden as a class attribute if it will not be dynamic.

Returns:A dictionary of the headers to return.
Return type:dict

Optional pieces

These methods do not have to be implemented in the subclass but in some cases it may make more sense.

classmethod AdapterBase.format_exception(exc)[source]

Takes an exception and appropriately formats the response. By default it just returns a json dump of the status code and the exception message. Any exception that does not have a status_code attribute will have a status_code of 500.

Parameters:exc (Exception) – The exception to format.
Returns:A tuple containing: response body, format, http response code
Return type:tuple

Adapters API

Built in adapters

class ripozo.adapters.siren.SirenAdapter(resource, base_url=u'')[source]

An adapter that formats the response in the SIREN format. A description of a SIREN format can be found here: SIREN specification

classmethod format_exception(exc)[source]

Takes an exception and appropriately formats it in the siren format. Mostly. It doesn’t return a self in this circumstance.

Parameters:exc (Exception) – The exception to format.
Returns:A tuple containing: response body, format, http response code
Return type:tuple
classmethod format_request(request)[source]

Simply returns request

Parameters:request (RequestContainer) – The request to handler
Return type:RequestContainer
formatted_body

Gets the formatted body of the response in unicode form. If self.status_code == 204 then this will return an empty string.

Returns:The siren formatted response body
Return type:unicode
generate_entity(resource, name, embedded)[source]

A generator that yields entities

generate_fields_for_endpoint_funct(endpoint_func)[source]

Returns the action’s fields attribute in a SIREN appropriate format.

Parameters:endpoint_func (apimethod) –
Returns:A dictionary of action fields
Return type:dict

Generates the Siren links for the resource.

Returns:The list of Siren formatted links.
Return type:list
get_entities()[source]

Gets a list of related entities in an appropriate SIREN format

Returns:A list of entities
Return type:list
class ripozo.adapters.jsonapi.JSONAPIAdapter(resource, base_url=u'')[source]

An adapter for formatting and ResourceBase instance in an appropriate format. See the specification for more details on what format it will return.

classmethod format_exception(exc)[source]

Responsible for formatting the exception according to the error formatting specification

Parameters:exc (Exception) – The exception to format
Returns:The response body, content type and status code as a tuple in that order.
Return type:unicode, unicode, int
classmethod format_request(request)[source]

Unwraps a JSONAPI request according to the `specification .<http://jsonapi.org/format/#crud>`_ Basically, it reformats the attributes and relationships to be top level and dot formatted instead of an underlying dictionary.

Parameters:request (RequestContainer) – The request whose request body should be updated
Returns:The updated request ready for ripozo.
Return type:RequestContainer
formatted_body

Returns a string in the JSON API format.

Returns:The appropriately formatted string
Return type:unicode|str
class ripozo.adapters.hal.HalAdapter(resource, base_url=u'')[source]

An adapter that formats the response in the HAL format. A description of the HAL format can be found here: HAL Specification

classmethod format_exception(exc)[source]

Takes an exception and appropriately formats the response. By default it just returns a json dump of the status code and the exception message. Any exception that does not have a status_code attribute will have a status_code of 500.

Parameters:exc (Exception) – The exception to format.
Returns:A tuple containing: response body, format, http response code
Return type:tuple
classmethod format_request(request)[source]

Simply returns request

Parameters:request (RequestContainer) – The request to handler
Return type:RequestContainer
formatted_body
Returns:The response body for the resource.
Return type:unicode
generate_relationship(relationship_list)[source]

Generates an appropriately formated embedded relationship in the HAL format.

Parameters:relationship (ripozo.viewsets.relationships.relationship.BaseRelationship) – The relationship that an embedded version is being created for.
Returns:If it is a ListRelationship it will return a list/collection of the embedded resources. Otherwise it returns a dictionary as specified by the HAL specification.
Return type:list|dict
class ripozo.adapters.basic_json.BasicJSONAdapter(resource, base_url=u'')[source]

Just a plain old JSON dump of the properties. Nothing exciting.

Format:

<resource_name>: {
    field1: "value"
    field2: "value"
    relationship: {
        relationship_field: "value"
    }
    list_relationship: [
        {
            relationship_field: "value"
        }
        {
            relationship_field: "value"
        }
    ]
}
classmethod format_exception(exc)[source]

Takes an exception and appropriately formats the response. By default it just returns a json dump of the status code and the exception message. Any exception that does not have a status_code attribute will have a status_code of 500.

Parameters:exc (Exception) – The exception to format.
Returns:A tuple containing: response body, format, http response code
Return type:tuple
classmethod format_request(request)[source]

Simply returns request

Parameters:request (RequestContainer) – The request to handler
Return type:RequestContainer
formatted_body
Returns:The formatted body that should be returned. It’s just a json.dumps of the properties and relationships
Return type:unicode

Base Adapter

class ripozo.adapters.base.AdapterBase(resource, base_url=u'')[source]

The adapter base is responsible for specifying how a resource should be translated for the client. For example, you may want to specify a specific hypermedia protocol or format it in a manner that is specific to your client (though you should probably avoid that)

Parameters:formats (list) – A list of strings that indicate which Content-Types will match with this adapter. For example, you might include ‘application/vnd.siren+json’ in the formats for a SIREN adapter. This means that any request with that content type will be responded to in the appropriate manner. Any of the strings in the list will be considered the appropriate format for the adapter on which they are specified.
combine_base_url_with_resource_url(resource_url)[source]

Does exactly what it says it does. Uses join_url_parts with the self.base_url and resource_url argument together.

Parameters:resource_url (unicode) – The part to join with the self.base_url
Returns:The joined url
Return type:unicode
extra_headers

Headers that should be added to response. For example it might be the content-type etc... This must be overridden by any subclass since it raises a NotImplementedError. It can also be overridden as a class attribute if it will not be dynamic.

Returns:A dictionary of the headers to return.
Return type:dict
classmethod format_exception(exc)[source]

Takes an exception and appropriately formats the response. By default it just returns a json dump of the status code and the exception message. Any exception that does not have a status_code attribute will have a status_code of 500.

Parameters:exc (Exception) – The exception to format.
Returns:A tuple containing: response body, format, http response code
Return type:tuple
classmethod format_request(request)[source]

Takes a request and appropriately reformats the request. For example, jsonAPI requires a specific request format that must be transformed to work with ripozo. For this base implementation it simply returns the request without any additional formating.

Parameters:request (RequestContainer) – The request to reformat.
Returns:The formatted request.
Return type:RequestContainer
formatted_body

This property is the fully qualified and formatted response. For example, you might return a Hypermedia formatted response body such as the SIREN hypermedia protocol or HAL. This must be overridden by any subclass. Additionally, it is a property and must be decorated as such.

Returns:The formatted response body.
Return type:unicode
status_code
Returns:Returns the status code of the resource if it is available. If it is not it assumes a 200.
Return type:int