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='')[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

property 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='')[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

property 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='')[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

property 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='')[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

property 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='')[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

abstract property 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

abstract property 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

property 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