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/pickle3': <class 'RestAuthCommon.handlers.Pickle3ContentHandler'>, 'application/x-www-form-urlencoded': <class 'RestAuthCommon.handlers.FormContentHandler'>, 'application/xml': <class 'RestAuthCommon.handlers.XMLContentHandler'>, 'application/pickle': <class 'RestAuthCommon.handlers.PickleContentHandler'>, 'application/json': <class 'RestAuthCommon.handlers.JSONContentHandler'>, 'application/yaml': <class 'RestAuthCommon.handlers.YAMLContentHandler'>}

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
application/json	handlers.JSONContentHandler
application/x-www-form-urlencoded	handlers.FormContentHandler
application/pickle	handlers.PickleContentHandler
application/pickle3	handlers.Pickle3ContentHandler
application/xml	handlers.XMLContentHandler
application/yaml	handlers.YAMLContentHandler

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

class RestAuthCommon.handlers.ContentHandler

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.

SUPPORT_NESTED_DICTS = True

Set to False if your content handler does not support nested dictionaries as used i.e. during user-creation.

library

Library configured with the librarypath class variable.

librarypath = None

Override librarypath to lazily load named library upon first use.

This may be a toplevel module (i.e. "json") or a submodule (i.e. "lxml.etree"). The named library is accessable via self.library.

Example:

class XMLContentHandler(ContentHandler):
    librarypath = 'lxml.etree'

    def unmarshal_str(self, data):
        tree = self.library.Element(data)
        # ...

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.

Parameters:obj (dict) – Data to marshal. Return type:bytes in python3, str in python2

marshal_list(obj)

Marshal a list.

Parameters:obj (list) – Data to marshal. Return type:bytes in python3, str in python2

marshal_str(obj)

Marshal a string.

Parameters:obj (str, bytes, unicode) – Data to marshal. Return type:bytes in python3, str in python2

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.

Parameters:data (bytes in python3, str in python2) – Data to unmarshal. Return type:str

unmarshal_dict(body)

Unmarshal a dictionary.

Parameters:data (bytes in python3, str in python2) – Data to unmarshal. Return type:dict

unmarshal_list(body)

Unmarshal a list.

Parameters:data (bytes in python3, str in python2) – Data to unmarshal. Return type:list

unmarshal_str(data)

Unmarshal a string.

Parameters:data (bytes in python3, str in python2) – Data to unmarshal. Return type:str in python3, unicode in python2

class RestAuthCommon.handlers.FormContentHandler

Handler for HTML Form urlencoded content.

Warning

Because of the limitations of urlencoded forms, this handler does not support nested dictionaries.

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

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

class RestAuthCommon.handlers.JSONContentHandler

Handler for JSON encoded content.

See also

Specification, WikiPedia

mime = 'application/json'

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

class RestAuthCommon.handlers.Pickle3ContentHandler

Handler for pickle-encoded content, protocol level version 3.

This version is only supported by the Python3 version the pickle module, this ContentHandler is only usable in Python3.

See also

module documentation, WikiPedia

mime = 'application/pickle3'

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

class RestAuthCommon.handlers.PickleContentHandler

Handler for pickle-encoded content.

See also

module documentation, WikiPedia

mime = 'application/pickle'

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

class RestAuthCommon.handlers.XMLContentHandler

Future location of the XML content handler.

Note

This ContentHandler requires the lxml library.

mime = 'application/xml'

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

class RestAuthCommon.handlers.YAMLContentHandler

Handler for YAML encoded content.

Note

This ContentHandler requires PyYAML library.

See also

Specification, WikiPedia

mime = 'application/yaml'

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

RestAuthCommon.handlers.YamlContentHandler

alias of YAMLContentHandler

RestAuthCommon.handlers.content_handler

alias of ContentHandler

RestAuthCommon.handlers.form

alias of FormContentHandler

RestAuthCommon.handlers.json

alias of JSONContentHandler

RestAuthCommon.handlers.xml

alias of XMLContentHandler