serialization

New in version 1.1.0.

Data serialization

Attributes

smisk.serialization.serializers

The serializer registry.

Type:Registry

Classes

class smisk.serialization.data(smisk.serialization.plistlib_.Data)

Represent arbitrary bytes.

data

Actual storage of the bytes.

Type:str
__init__(source):
source can be a str or a file-like object with a read method returning str.
encode()
Instance method to encode data into a printable, base-64 encoded, string.
decode(string)
Class method for creating a data object from a base-64 encoded string.
class smisk.serialization.Registry(object)

A serializers registry.

Can be accessed like a dictionary:

>>> reg = Registry()
>>> # (register some serializers here)
>>> reg[3]
<class MySerializer ...
>>> MySerializer in reg
True
>>> for serializer in reg:
...   print serializer
<class Serializer1 ...
<class Serializer2 ...
first_in

First registered serializer.

Type:Serializer
Value:None
media_types

Media type-to-Serializer map.

Type:dict
Value:{}
extensions

Filename extension-to-Serializer map.

Type:dict
Value:{}
serializers

List of available serializers.

Type:list
Value:[]
readers

Iterate serializers able to read, or unserialize, data.

for ser in reg.readers:
  print ser
Return type:generator
writers

Iterate serializers able to write, or serialize, data.

for ser in reg.writers:
  print ser
Return type:generator
register(serializer)

Register a new Serializer.

serializer should be the class of the serializer to register, not an instance.

unregister(serializer=None)
Unregister a previously registered Serializer or all registered serializers, if serializer is None.
find(media_type_or_extension)

Find a Serializer associated with a media type or an extension.

Return type:Serializer
Returns:None if not found.
associate(serializer, media_type=None, extension=None, override_existing=True)
Associate a Serializer with formats and/or extensions.
class smisk.serialization.Serializer(object)

Abstract baseclass for serializers.

All members described here are class members (serializers are never instantiated).

name

A human readable short and descriptive name of the serializer.

Type:str
Value:“Untitled serializer”
extensions

Filename extensions this serializer can handle.

Must contain at least one item. The first item will be used as the primary extension.

Type:collection
Value:tuple()
media_types

Media types this serializer can handle.

Must contain at least one item. The first item will be used as the primary media type.

Type:collection
Value:tuple()
charset

Preferred character encoding.

If the value is None the serializer is considered “binary”.

Type:str
Value:None
unicode_errors

How to handle unicode conversions.

Possible values: "strict", "ignore", "replace", "xmlcharrefreplace", "backslashreplace"

Type:str
Value:“strict”
handles_empty_response

If enabled, serialize() will be called even when leafs does not generate a response body. (i.e. params=None passed to serialize())

Some serialization formats does not allow empty responses (RPC-variants for instance) in which case this feature come in handy.

Type:bool
Value:False
can_serialize

Declares where there or not this serializer can write/encode/serialize data.

New in version 1.1.3.

Type:bool
Value:False
can_unserialize

Declares where there or not this serializer can read/decode/unserialize data.

New in version 1.1.3.

Type:bool
Value:False
serialize(params, charset) → tuple

Serialize the data structure params with the user/outside-prefered character encoding charset.

If the serializer is binary; the first item in the tuple returned should be None. If the serializer is textual; the character encoding actually used should be the first item of the tuple returned. It is constructed this way to allow serializers only to accept a few character encodings or to be able to enforce a specific one at the same time as some serializers strictly follow the charset requested by the user/outside.

Parameters:
  • params (dict) – Parameters
  • charset (str) – Destination charset. Might be discarded, so care about the returned charset.
Returns:

Tuple of (str charset, str data) where charset is the name of the actual charset used and might be None if binary or unknown. data must be a str.

Return type:

tuple

unserialize(file, length=-1, charset=None) → tuple

Unserialize bytes representing some kind of data structure.

Parameters:
  • file (object) – A file-like object implementing at least the read() method
  • length (int) – Number of bytes to read from file or -1 if unknown.
  • charset (str) – Character encoding of input if the serializer is textual. Might be None if unknown in which case the charset attribute should be considered.
Returns:

Tuple of (list args, dict params). args and params might be None.

Return type:

tuple

serialize_error(status, params, charset) → tuple

Encode an error.

Returning None indicates that someone else should handle the error encoding. (Normally this means that smisk.mvc.Application.error() serializes the error using best guess).

“params” will always contain:

  • code (int) — Error code (i.e. 123).
  • name (unicode) — Name of the error. i.e. “404 Not Found”
  • description (unicode) — Description of the error or the emtpy string.
  • server (unicode) — Short one line description of the server name, port and software.

“params” might contain:

  • traceback (list) — A list of strings.
Parameters:
  • status (smisk.mvc.http.Status) – HTTP status
  • params (dict) – Parameters
  • charset (str) – Destination charset. Might be discarded, so care about the returned charset.
Returns:

Tuple of (str charset, str data) where charset is the name of the actual charset used and might be None if binary or unknown.

Return type:

tuple

add_content_type_header(response, charset)
Sets "Content-Type" header if missing in response. This method is called by smisk.mvc.Application when completing a HTTP transaction and should not be overridden in subclasses (as it)
directions()

List of possible directions, or read/write capabilities.

Returns:["read", "write"], ["read"], ["write"] or []
Return type:list
did_register(registry)

Called when this serializer has been successfully registered in a Registry (the registry instance is passed as the registry argument).

Default implementation does nothing. This is meant to be overridden in subclasses to allow a kind of initialization routine, setting up the serializer if needed.

Parameters:
  • registry (Registry) – The registry in which this serializer was registered.
Return type:

None

did_unregister(registry)

Called when this serializer has been removed from a Registry.

Default implementation does nothing. This is meant to be overridden in subclasses to allow a kind of tear-down routine, finalizing the serializer if needed.

Parameters:
  • registry (Registry) – The registry in which this serializer was removed.
Return type:

None

exception smisk.serialization.SerializationError(Exception)
Indicates an encoding error (when converting an object to bytes).
exception smisk.serialization.UnserializationError(Exception)
Indicates an decoding error (when converting bytes to an object).