Serializables

Contains utilities for creating serializable types and to serialize and deserialize them into objects that can be encoded through json.

class dman.core.serializables.Config(validate: bool = False)

Configuration for serializables.

This class has a global instance that can be accessed as follows:

>>> dman.core.serializables.config.validate = True
>>> dman.params.serialize.validate = True  # equivalent

Parameters:

validate (bool, optional) – Cancel serialization when an invalid object is encountered. Defaults to False.

dman.core.serializables.compare_type(base: Type, check: Sequence[Type])

Compare two types, supporting generic types.

The signature operates similarly to isinstance.

dman.core.serializables.get_type_name(ser_type)

Get the class name of an instance or type.

dman.core.serializables.ser_type2str(obj)

Returns the serialize type string of an object or class.

dman.core.serializables.ser_str2type(ser)

Returns the class represented by a serialize type string.

dman.core.serializables.is_serializable(ser)

Check if an object is a serializable type.

dman.core.serializables.is_serializable_type_str(ser: str)

Check if a string is the name of a registered serializable type.

dman.core.serializables.is_deserializable(serialized: Any)

Check if an object has been produced through serialization.

If the serialized object is a dictionary, then it should include the serializable type string.

dman.core.serializables.register_serializable(name: str, cls: Type[Any], serialize: Optional[Callable[[Any, Optional[BaseContext]], Any]] = None, deserialize: Optional[Callable[[Any, Optional[BaseContext]], Any]] = None)

Register a class as a serializable type with a given name.

If the serialize and deserialize methods are not provided then the class should have a __serialize__ and __deserialize__ method defined. In this case however you should prefer using the :func:serializable decorator instead.

Parameters:

• name (str) – Name of the serializable

• cls (Type[Any]) – Class to register

• serialize (Callable[[Any, Optional[BaseContext]], Any], optional) – Serialize method. Defaults to None.

• deserialize (Callable[[Any, Optional[BaseContext]], Any], optional) – Deserialize method. Defaults to None.

Example

>>> class Base: ...
>>> register_serializable('base', Base, lambda obj: '<base>', lambda ser: Base())

dman.core.serializables.serializable_types()

Return the serializable types dictionary.

dman.core.serializables.get_custom_serializable(cls: Type[Any], default=None)

Get the signature of a custom serializable object.

dman.core.serializables.serialize(obj, context: Optional[BaseContext] = None, content_only: bool = False)

Serialize a serializable object.

The context can be used to store the current directory, logging and custom serialization behavior. Serializable objects are created using serializable() or alternatively using register_serializable().

By default, any object that can be handled by json is serializable. That is str, int, float, None, list, tuple and dict.

Parameters:

• obj – The object to serialize

• context (BaseContext, optional) – The serialization context. Defaults to None.

• content_only (bool, optional) – Do not include type information when true. Results in more compact serialization. Defaults to False.

Example

>>> @serializable
>>> @dataclass
>>> class Base:
>>>     value: str
>>> ser = serialize([Base('content'), 'message'])
>>> print(sjson.dumps(ser, indent=4))
[
    {
        "_ser__type": "Base",
        "_ser__content": {
            "value": "content"
        }
    },
    "message"
]
>>> ser = serialize(Base('content'), content_only=True)
>>> print(sjson.dumps(ser, indent=4))
{
    "value": "content"
}

dman.core.serializables.deserialize(serialized, context: Optional[BaseContext] = None, expected=None)

Deserialize an object produced through serialization.

The context can be used to store the current directory, logging and custom serialization behavior. Deserializable objects are created using serializable() or alternatively using register_serializable().

By default, any object that can be handled by json is deserializable. That is str, int, float, None, list, tuple and dict.

Parameters:

• serialized – The object to deserialize.

• context (BaseContext, optional) – _description_. Defaults to None.

• expected (_type_, optional) – Class or string representing the expected type. If set to None the type is received from the dictionary. Defaults to None.

Example

>>> @serializable(name='_base')
>>> @dataclass
>>> class Base:
>>>     value: str
>>> ser = serialize(Base('content'))
>>> print(deserialize(ser).value)
content
>>> ser = serialize(Base('content'), content_only=True)
>>> print(deserialize(ser, expected=Base).value)
content
>>> print(deserialize(ser, expected='_base').value)
content

dman.core.serializables.serializable(cls=None, /, *, name: Optional[str] = None, template: Optional[Any] = None)

Make a class serializable.

Returns the same class as was passed in and the class is registered as a serializable type. Serialization and Deserialization methods are added automatically if cls is a dataclass or an Enum. Otherwise a __serialize__ and __deserialize__ method should be provided for serialization. If these are not provided conversion will fail.

See Defining Serializables for detailed examples on how to create serializable types.

Parameters:

• cls (Any) – The class to process.

• name (str, optional) – The name of the serializable type. Defaults to None.

• template (Any, optional) – Template class to use during serialization. Defaults to None.

dman.core.serializables.register_instance(inst: ~typing.Optional[~typing.Any] = None, /, *, name: str = <dataclasses._MISSING_TYPE object>)

Register instance for serialization

Parameters:

• inst (Any) – Instance to serialize. Defaults to None.

• name (str) – Name of instances.

Example

>>> @dman.register_instance(name='ell1')
>>> def ell1(x, y):
>>>     return abs(x) + abs(y)

>>> dman.register_instance(ell1, name='ell1')

class dman.core.serializables.Unserializable(type: str, info: str)

Represents an object that could not be serialized.

class dman.core.serializables.ExcUnserializable(type: str, info: str, trace: Trace)

Represents an object that could not be serialized due to an exception.

class dman.core.serializables.Undeserializable(type: str, info: str, serialized: Optional[dict] = None, expected: Optional[str] = None)

Represents an object that could not be deserialized.

serialized: dict = None

The serialized object.

expected: str = None

The expected serializable type of the object.

format()

Generator producing the description of the invalid object.

class dman.core.serializables.ExcUndeserializable(type: str, info: str, trace: Trace, serialized: dict, expected: str)

Represents an object that could not be deserialized due to an exception.

format()

Generator producing the description of the invalid object.

dman.core.serializables.isvalid(obj)

Check if an object is valid

exception dman.core.serializables.SerializationError

Serialization Error raised when an object could not be serialized.

exception dman.core.serializables.ValidationError

Validation Error raised when an object could not be validated.

dman.core.serializables.validate(obj, msg: str = 'Could not validate object')

Check if the object is valid, raise a ValidationError otherwise.

Parameters:

• obj – The object to validate

• msg (str, optional) – An optional message set in the Validation Error. Defaults to ‘Could not validate object’.

Raises:

ValidationError – The object is not valid.

class dman.core.serializables.BaseContext

The basic interface for serialization contexts.

It is passed hierarchically through the hierarchy of objects that are being serialized and describes how the serialization should be completed. For dman.model.record.Context for more information.

serialize(obj, content_only: bool = False)

Serialize a serializable object.

The context can be used to store the current directory, logging and custom serialization behavior. Serializable objects are created using serializable() or alternatively using register_serializable().

By default, any object that can be handled by json is serializable. That is str, int, float, None, list, tuple and dict.

Parameters:

• obj – The object to serialize

• context (BaseContext, optional) – The serialization context. Defaults to None.

• content_only (bool, optional) – Do not include type information when true. Results in more compact serialization. Defaults to False.

See also: serialize().

serialize_object(obj)

Serialize a generic serializable object.

serialize_list(obj: list)

Serialize a list.

serialize_dict(obj: dict)

Serialize a dictionary.

deserialize(serialized, ser_type=None)

Deserialize an object produced through serialization.

The context can be used to store the current directory, logging and custom serialization behavior. Deserializable objects are created using serializable() or alternatively using register_serializable().

By default, any object that can be handled by json is deserializable. That is str, int, float, None, list, tuple and dict.

Parameters:

• serialized – The object to deserialize.

• context (BaseContext, optional) – _description_. Defaults to None.

• expected (_type_, optional) – Class or string representing the expected type. If set to None the type is received from the dictionary. Defaults to None.

• also (See) – deserialize().

deserialize_object(serialized, expected)

Deserialize an object of an expected type.

deserialize_atomic(serialized, expected)

Deserialize an atomic object of an expected type