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/json': <class 'RestAuthCommon.handlers.JSONContentHandler'>, 'application/pickle': <class 'RestAuthCommon.handlers.PickleContentHandler'>, 'application/pickle3': <class 'RestAuthCommon.handlers.Pickle3ContentHandler'>, 'application/x-www-form-urlencoded': <class 'RestAuthCommon.handlers.FormContentHandler'>, 'application/xml': <class 'RestAuthCommon.handlers.XMLContentHandler'>, '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
[source]¶ 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 viaself.library
.Example:
class XMLContentHandler(ContentHandler): librarypath = 'lxml.etree' def unmarshal_str(self, data): tree = self.library.Element(data) # ...
-
marshal
(obj)[source]¶ 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_dict
(obj)[source]¶ Marshal a dictionary.
Parameters: obj (dict) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_list
(obj)[source]¶ Marshal a list.
Parameters: obj (list) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_str
(obj)[source]¶ 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)[source]¶ 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)[source]¶ Unmarshal a boolean.
Parameters: data (bytes in python3, str in python2) – Data to unmarshal. Return type: str
-
unmarshal_dict
(body)[source]¶ Unmarshal a dictionary.
Parameters: data (bytes in python3, str in python2) – Data to unmarshal. Return type: dict
-
-
class
RestAuthCommon.handlers.
FormContentHandler
[source]¶ Handler for HTML Form urlencoded content.
Warning
Because of the limitations of urlencoded forms, this handler does not support nested dictionaries.
-
marshal_dict
(obj)[source]¶ Marshal a dictionary.
Parameters: obj (dict) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_list
(obj)[source]¶ Marshal a list.
Parameters: obj (list) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_str
(obj)[source]¶ Marshal a string.
Parameters: obj (str, bytes, unicode) – Data to marshal. Return type: bytes in python3, str in python2
-
mime
= 'application/x-www-form-urlencoded'¶ The mime-type used by this content handler is ‘application/x-www-form-urlencoded’.
-
unmarshal_dict
(body)[source]¶ Unmarshal a dictionary.
Parameters: data (bytes in python3, str in python2) – Data to unmarshal. Return type: dict
-
-
class
RestAuthCommon.handlers.
JSONContentHandler
[source]¶ Handler for JSON encoded content.
See also
-
class
ByteDecoder
(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)[source]¶
-
class
ByteEncoder
(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]¶ -
default
(obj)[source]¶ Implement this method in a subclass such that it returns a serializable object for
o
, or calls the base implementation (to raise aTypeError
).For example, to support arbitrary iterators, you could implement default like this:
def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) # Let the base class default method raise the TypeError return JSONEncoder.default(self, o)
-
-
marshal_dict
(obj)[source]¶ Marshal a dictionary.
Parameters: obj (dict) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_list
(obj)[source]¶ Marshal a list.
Parameters: obj (list) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_str
(obj)[source]¶ Marshal a string.
Parameters: obj (str, bytes, unicode) – Data to marshal. Return type: bytes in python3, str in python2
-
mime
= 'application/json'¶ The mime-type used by this content handler is ‘application/json’.
-
unmarshal_bool
(body)[source]¶ Unmarshal a boolean.
Parameters: data (bytes in python3, str in python2) – Data to unmarshal. Return type: str
-
unmarshal_dict
(body)[source]¶ Unmarshal a dictionary.
Parameters: data (bytes in python3, str in python2) – Data to unmarshal. Return type: dict
-
class
-
class
RestAuthCommon.handlers.
Pickle3ContentHandler
[source]¶ 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
-
mime
= 'application/pickle3'¶ The mime-type used by this content handler is ‘application/pickle3’.
-
-
class
RestAuthCommon.handlers.
PickleContentHandler
[source]¶ Handler for pickle-encoded content.
See also
-
marshal_dict
(obj)[source]¶ Marshal a dictionary.
Parameters: obj (dict) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_list
(obj)[source]¶ Marshal a list.
Parameters: obj (list) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_str
(obj)[source]¶ Marshal a string.
Parameters: obj (str, bytes, unicode) – Data to marshal. Return type: bytes in python3, str in python2
-
mime
= 'application/pickle'¶ The mime-type used by this content handler is ‘application/pickle’.
-
unmarshal_dict
(data)[source]¶ Unmarshal a dictionary.
Parameters: data (bytes in python3, str in python2) – Data to unmarshal. Return type: dict
-
-
class
RestAuthCommon.handlers.
XMLContentHandler
[source]¶ Future location of the XML content handler.
Note
This ContentHandler requires the lxml library.
-
marshal_dict
(obj)[source]¶ Marshal a dictionary.
Parameters: obj (dict) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_list
(obj)[source]¶ Marshal a list.
Parameters: obj (list) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_str
(obj)[source]¶ Marshal a string.
Parameters: obj (str, bytes, unicode) – Data to marshal. Return type: bytes in python3, str in python2
-
mime
= 'application/xml'¶ The mime-type used by this content handler is ‘application/xml’.
-
unmarshal_dict
(body)[source]¶ Unmarshal a dictionary.
Parameters: data (bytes in python3, str in python2) – Data to unmarshal. Return type: dict
-
-
class
RestAuthCommon.handlers.
YAMLContentHandler
[source]¶ Handler for YAML encoded content.
Note
This ContentHandler requires PyYAML library.
See also
-
marshal_dict
(obj)[source]¶ Marshal a dictionary.
Parameters: obj (dict) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_list
(obj)[source]¶ Marshal a list.
Parameters: obj (list) – Data to marshal. Return type: bytes in python3, str in python2
-
marshal_str
(obj)[source]¶ Marshal a string.
Parameters: obj (str, bytes, unicode) – Data to marshal. Return type: bytes in python3, str in python2
-
mime
= 'application/yaml'¶ The mime-type used by this content handler is ‘application/yaml’.
-
unmarshal_dict
(data)[source]¶ Unmarshal a dictionary.
Parameters: data (bytes in python3, str in python2) – Data to unmarshal. Return type: dict
-
-
RestAuthCommon.handlers.
YamlContentHandler
¶
-
RestAuthCommon.handlers.
content_handler
¶
-
RestAuthCommon.handlers.
form
¶
-
RestAuthCommon.handlers.
json
¶
-
RestAuthCommon.handlers.
xml
¶