communication.serialization module

This module contains the serialization logic used in sending and receiving arbitrary objects.

class communication.serialization.Serialization

Bases: object

Virtual class that provides packing and unpacking functions used for communications. The outline is as follows: - serialization functions for different classes - packing function that handles metadata and determines which serialization needs to happen

• deserialization functions for different classes

• unpacking function that handles metadata and determines which deserialization needs to happen

static clear_serialization_logic(reload_defaults=True)

Clear all custom serialization (and deserialization) logic that was added to this class.

Parameters:

reload_defaults (bool) – After clearing, reload the (de)serialization logic that is provided by the package.

Return type:

None

static collection_deserialize(collection_obj, **kwargs)

Function for deserializing collections

Parameters:

• collection_obj (list[Any] | dict[str, Any]) – object to deserialize

• **kwargs (Any) – optional extra keyword arguments

Raises:

ValueError – raised when (nested) value cannot be deserialized

Return type:

dict[str, Any] | list[Any]

Returns:

deserialized collection

static default_deserialize(obj, use_pickle=False, **_kwargs)

Fall-back function is case no specific deserialization function is available. This function uses the pickle library

Parameters:

• obj (bytes) – object to deserialize

• use_pickle (bool) – set to true if one wishes to use pickle as a fallback deserializer

• **_kwargs (Any) – optional extra keyword arguments

Raises:

NotImplementedError – Default serialization not possible for the provided object and arguments

Return type:

Any

Returns:

deserialized object

static default_serialize(obj, use_pickle, **_kwargs)

Fall-back function is case no specific serialization function is available. This function uses the pickle library

Parameters:

• obj (Any) – object to serialize

• use_pickle (bool) – set to true if one wishes to use pickle as a fallback serializer

• **_kwargs (Any) – optional extra keyword arguments

Raises:

NotImplementedError – raised when no serialization function is defined for object

Return type:

bytes

Returns:

serialized object

static deserialize(obj, use_pickle=False, **kwargs)

Function that detects which deserialization function should be run and calls it

Parameters:

• obj (Any) – object to deserialize

• use_pickle (bool) – set to true if one wishes to use pickle as a fallback deserializer

• **kwargs (Any) – optional extra keyword arguments

Return type:

Any

Returns:

deserialized object

static pack(obj, msg_id, use_pickle, option=408, **kwargs)

Function that adds metadata and serializes the object for transmission.

Parameters:

• obj (Any) – object to pack

• msg_id (str | int) – message identifier associated to the message

• use_pickle (bool) – set to true if one wishes to use pickle as a fallback packer

• option (int | None) – ormsgpack options can be specified through this parameter

• **kwargs (Any) – optional extra keyword arguments

Raises:

TypeError – Failed to serialize the provided object

Return type:

bytes

Returns:

packed object (serialized and annotated)

static register(serializer, deserializer, *types, check_annotations=True, overwrite=False)

Register serialization and deserialization functions.

Parameters:

• serializer (Union[Callable[[Any, Any], Any], Callable[[Any, bool, Any], Any]]) – Serializer function.

• deserializer (Union[Callable[[Any, Any], Any], Callable[[Any, bool, Any], Any]]) – Deserializer function.

• types (str) – Object types that the serializer can serialize.

• check_annotations (bool) – Verify annotations of the (de)serializer conform to the protocol.

• overwrite (bool) – Allow (silent) overwrite of currently registered serializers.

Raises:

• RepetitionError – Attempted overwrite of registered serialization function.

• TypeError – Annotations do not conform to the protocol.

Return type:

None

static register_class(obj_class, check_annotations=True, overwrite=False)

Register (de)serialization logic associated to SupportsSerialization objects.

Parameters:

• obj_class (type[SupportsSerialization]) – object class to set serialization logic for.

• check_annotations (bool) – validate return annotation of the serialization logic.

• overwrite (bool) – Allow (silent) overwrite of currently registered serializers.

Raises:

• RepetitionError – raised when serialization function is already defined for object class.

• TypeError – raised when provided object class has no (de)serialization function.

• AnnotationError – raised when the return annotation is inconsistent.

Return type:

None

static serialize(obj, use_pickle, **kwargs)

Function that detects with serialization function should be used and applies it

Parameters:

• obj (Any) – object to serialize

• use_pickle (bool) – set to true if one wishes to use pickle as a fallback serializer

• **kwargs (Any) – optional extra keyword arguments

Return type:

bytes | dict[str, bytes]

Returns:

serialized object

static unpack(obj, use_pickle=False, option=None, **kwargs)

Function that handles metadata and turns the bytes object into a python object

Parameters:

• obj (bytes) – bytes object to unpack

• use_pickle (bool) – set to true if one wishes to use pickle as a fallback deserializer

• option (int | None) – ormsgpack options can be specified through this parameter

• **kwargs (Any) – optional extra keyword arguments

Raises:

TypeError – Failed to deserialize the provided object

Return type:

tuple[str, Any]

Returns:

unpacked object

class communication.serialization.SupportsSerialization(*args, **kwargs)

Bases: Protocol

Type placeholder for classes supporting custom serialization.

static deserialize(obj, **kwargs)

Deserialize the given object into an object of this class.

Parameters:

• obj (Any) – object to be deserialized.

• **kwargs (Any) – Optional extra keyword arguments.

Return type:

SupportsSerialization

Returns:

Deserialized object.

serialize(**kwargs)

Serialize this object into bytes.

Parameters:

**kwargs (Any) – Optional extra keyword arguments.

Return type:

Any

Returns:

Serialization of this instance to Dict with bytes.