serdio.serde module

The Serdio serialization and deserialization implementation.

The serdio.serde spec is an extension of MessagePack that can handle some extra Python types, while also allowing users to supply their own hooks for seamless encoding/decoding of user-defined types.

Usage

xyb_bytes = serdio.serialize(2, 3.0, b=2.0)

x, y = serdio.deserialize(xyb_bytes)
print(f"{x}, {y}")
# 2, 3.0

args, kwargs = serdio.deserialize(xyb_bytes, as_signature=True)
print(f"{args[0]}, {args[1]}, b={kwargs["b"]}")
# 2, 3.0, b=2.0

class serdio.serde.SerdeHookBundle(encoder_hook, decoder_hook)

Bases: object

An encoder-decoder hook pair for user-defined types.

The encoder_hook and decoder_hook specify how to convert from a user-defined type into an equivalent collection of Python-native values and back. Thus for any object X of user-defined type T, the following relationship should hold:

hook_bundle = SerdioHookBundle(f, g)
native_X = hook_bundle.encoder_hook(X)  # f(X)
Y = hook_bundle.decoder_hook(native_X)  # g(native_X)
assert X == Y

Note that native_X above needs to be some collection of native Python values, e.g. a simple dataclass can be represented as a dictionary of attributes mapping to values.

Parameters:

• encoder_hook (Callable) – An encoder function specifying how serdio.serde.serialize() should break down any custom types into Python native types.

• decoder_hook (Callable) – The inverse of encoder_hook, specifying how serdio.serde.deserialize() should re-assemble the encoder_hook output into user-defined types.

decoder_hook: Callable

encoder_hook: Callable

to_dict()

Return the encoder-decoder hook pair as a dictionary.

Return type:

Dict

unbundle()

Return the encoder-decoder hook pair as a tuple.

Return type:

Tuple

serdio.serde.bundle_serde_hooks(hook_bundle)

Helper to lift an encoder-decoder hook pair into a SerdeHookBundle.

Parameters:

hook_bundle – A tuple, list, dict or SerdeHookBundle containing an encoder-decoder hook pair. If a tuple or list, the encoder_hook must come first. If a dictionary, must have exactly two keys "encoder_hook" and "decoder_hook".

Returns:

A SerdeHookBundle encapsulating the encoder-decoder hook pair.

Raises:

ValueError – if the hook_bundle dictionary is malformed.

serdio.serde.deserialize(serdio_bytes, decoder=None, as_signature=False)

Unpacks serdio-serialized bytes to an object

Parameters:

• serdio_bytes (bytes) – Byte array to deserialize.

• decoder (Optional[Callable]) – Optional callable specifying Messagepack decoder for user-defined types. See SerdeHookBundle for details.

• as_signature (bool) – Optional boolean determining return format. If True, unpack the serialized byte array into an args tuple and a kwargs dictionary. This argument is most useful when the user is trying to serialize the inputs to a function of unknown arity.

Return type:

Any

Returns:

The deserialized object. If as_signature=True, assumes the resulting object is a dictionary with an args tuple and kwargs dict for values, and returns these two instead of the full dictionary.

serdio.serde.serialize(*args, encoder=None, **kwargs)

Serializes a set of args` and ``kwargs into bytes with MessagePack.

Parameters:

• *args (Any) – Positional arguments to include in the serialized bytes

• encoder (Optional[Callable]) – Optional callable specifying MessagePack encoder for user-defined types. See SerdeHookBundle for details.

• kwargs (Any) – Keyword arguments to include in the serialized bytes

Return type:

bytes

Returns:

Dictionary of args and kwargs, serialized with MessagePack and optional custom encoder.

Raises:

TypeError – if encoder is not callable. Other errors can be raised by MessagePack during packing.