Content handlers

This module collects code related to marshalling and unmarshalling data. Marshalling objects transforms them to serializable strings that can be sent over the network while unmarshalling does the exact opposite: it transforms a string into a python object.

Both the RestAuth server and RestAuthClient use concrete implementations of the content_handler class to (un)marshal data. To use such a content handler, simply create an instance of the content handler:

import RestAuthCommon

# some example data:
data = {"foo": "bar"}

# lookup handler:
handler_class = RestAuthCommon.CONTENT_HANDLERS['application/json']
handler = handler_class()

# marshal some data (to send it)
marshalled = handler.marshal_dict( data )

# unmarshal some data (for received data):
unmarshalled = handler.unmarshal_dict( marshalled )

# this should always be the same:
print( unmarshalled == data )

You can also use this feature to implement your own content handlers. This is useful if your setup includes software that encodes or decodes data in a way not understood by the other side of the communication. Please see the respective documentation of the RestAuth server and of RestAuthClient for more information.

API documentation

Classes and methods related to content handling.

RestAuthCommon.handlers.CONTENT_HANDLERS = {'application/x-www-form-urlencoded': <class 'RestAuthCommon.handlers.form'>, 'application/json': <class 'RestAuthCommon.handlers.json'>, 'application/xml': <class 'RestAuthCommon.handlers.xml'>}

Mapping of MIME types to their respective handler implemenation. You can use this dictionary to dynamically look up a content handler if you do not know the requested content type in advance.

MIME type	handler	notes
application/json	handlers.json	default
application/x-www-form-urlencoded	handlers.form	Only use this for testing
application/xml	handlers.xml	not yet implemented

If you want to provide your own implementation of a content_handler, you can add it to this dictionary with the appropriate MIME type as the key.

class RestAuthCommon.handlers.content_handler

This class is a common base class for all content handlers. If you want to implement your own content handler, you must subclass this class and implement all marshal_* and unmarshal_* methods.

Never use this class directly. It does not marshal or unmarshal any content itself.

marshal(obj)

Shortcut for marshalling just any object.

Note: If you know the type of obj in advance, you should use the marshal_* methods directly for improved speed.

Parameters:obj – The object to marshall. Returns:The marshalled representation of the object. Return type:str Raises error.MarshalError:  If marshalling goes wrong in any way.

marshal_bool(obj)

Marshal a boolean.

marshal_dict(obj)

Marshal a dictionary.

marshal_list(obj)

Marshal a list.

marshal_str(obj)

Marshal a string.

mime = None

Override this with the MIME type handled by your handler.

unmarshal(raw_data, typ)

Shortcut for unmarshalling a string to an object of type typ.

Note: You may want to use the unmarshal_* methods directly for improved speed.

Parameters:

• raw_data (str) – The string to unmarshall.
• typ (type) – The typ of the unmarshalled object.

Returns:

The unmarshalled object.

Return type:

typ

Raises error.UnmarshalError:  

If unmarshalling goes wrong in any way.

unmarshal_bool(body)

Unmarshal a boolean.

unmarshal_dict(body)

Unmarshal a dictionary.

unmarshal_list(body)

Unmarshal a list.

unmarshal_str(data)

Unmarshal a string.

class RestAuthCommon.handlers.form

Concrete implementation of a content_handler that uses HTML forms. This content handler should not be used in any real world scenario, as it has many problems with unicode.

mime = 'application/x-www-form-urlencoded'

The mime-type used by this content handler is ‘application/x-www-form-urlencoded’.

class RestAuthCommon.handlers.json

Concrete implementation of a content_handler that uses JSON. This is the default content handler in both server and client library.

mime = 'application/json'

The mime-type used by this content handler is ‘application/json’.

class RestAuthCommon.handlers.xml

Future location of the XML content handler. This handler is not yet implemented!