communication.packers.serialization module

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

class communication.packers.serialization.DeserializerOpts(fallback_pickle=False, ormsgpack_option=None)

Bases: _Opts

Options to change the behaviour of deserialization.

ormsgpack_option: int | None = None

Option passed to ormsgpack.unpackb.

class communication.packers.serialization.Serializer

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

classmethod 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

classmethod deserialize(obj, opts=DeserializerOpts(fallback_pickle=False, ormsgpack_option=None))

Function that turns the bytes object into a python object

Parameters:

• obj (bytes) – Bytes object to unpack.

• opts (DeserializerOpts) – Options to change the behaviour of the serialization.

Raises:

TypeError – Failed to deserialize the provided object

Return type:

Any

Returns:

Unpacked object.

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

Register serialization and deserialization functions.

Parameters:

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

• deserializer (Callable[[Any, DeserializerOpts], 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

classmethod 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

classmethod serialize(obj, opts=SerializerOpts(fallback_pickle=False, ormsgpack_option=408))

Function that serializes the object for transmission.

Parameters:

• obj (Any) – Object to pack.

• opts (SerializerOpts) – Options to change the behaviour of the serialization

Raises:

TypeError – Failed to serialize the provided object.

Return type:

bytes

Returns:

Packed object (serialized and annotated).

classmethod transform_into_native(obj, opts)

Given an object with non-native types (that is: not supported by ormsgpack), this function transforms the non-native types into native types. For example, the ormsgpack does not serialize tuples so we transform them into dictionaries and lists.

>>> Serializer.transform_into_native((1, 2, 3))
{"type": "tuple", "data": [1, 2, 3]}

This function is usually called by serializer plugins to transform (nested,) non-native objects into native types.

Parameters:

• obj (Any) – Object to transform.

• opts (SerializerOpts) – Options to change the behaviour of the serialization.

Raises:

Exception – Raised when object cannot be serialized.

Return type:

bytes | dict[str, bytes]

Returns:

Transformed object.

classmethod transform_into_nonnative(obj, opts)

Given an object that is deserialized into native types (that is: supported by ormsgpack), this function transforms the native types back into non-native types in a depth-first manner. For example, the ormsgpack does not serialize tuples so we conjugate them from dictionaries and lists.

>>> Serializer.transform_into_nonnative({"numbers": {"type": "tuple", "data": [1, 2, 3]}, "myname": "beth"})
{"numbers": (1, 2, 3), "myname": "beth"}

This function is usually called by serializer plugins to transform nested objects back into their expected, non-native types.

Parameters:

• obj (Any) – object to transform

• opts (DeserializerOpts) – options to change the behaviour of the serialization

Return type:

Any

Returns:

transformed object

class communication.packers.serialization.SerializerOpts(fallback_pickle=False, ormsgpack_option=408)

Bases: _Opts

Options to change the behaviour of serialization.

ormsgpack_option: int | None = 408

Option passed to ormsgpack.packb.

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

Bases: Protocol

Type placeholder for classes supporting custom serialization.

static deserialize(obj, opts)

Deserialize the given object into an object of this class.

Parameters:

• obj (Any) – Object to be deserialized.

• opts (DeserializerOpts) – Options to change the behaviour of the deserialization.

Return type:

SupportsSerialization

Returns:

Deserialized object.

serialize(opts)

Serialize this object into bytes.

Parameters:

opts (SerializerOpts) – Options to change the behaviour of the serialization.

Return type:

Any

Returns:

Serialization of this instance to Dict with bytes.