jangada.serialization.Serializable#

class jangada.serialization.Serializable(*args, **kwargs)#

Bases: object

Base class for objects that can be serialized to/from dictionaries.

Serializable provides a framework for converting Python objects to dictionary structures suitable for persistence in HDF5 files or other storage backends. It handles nested objects, collections, primitive types, and special dataset types like NumPy arrays and Pandas timestamps.

Parameters:

*argstuple: Variable positional arguments. Supports: - No args: Initialize from kwargs - One Serializable instance: Copy constructor
**kwargsdict: Keyword arguments mapping property names to values.

Raises:

ValueError: If args don’t match any supported initialization signature, or if kwargs contain unknown property names.

See also

SerializableProperty: Descriptor for serializable properties
SerializableMetatype: Metaclass that enables serialization

Notes

All Serializable properties must be SerializableProperty descriptors. Regular attributes are not included in serialization.

The serialization format uses dictionaries with a special ‘__class__’ key to store the fully qualified class name. This allows accurate reconstruction of the original object type.

When using is_copy=True in serialize(), only properties with copiable=True are included. This is useful for persistence - you can mark cached or temporary properties as non-copiable.

Examples

Define a Serializable class:

>>> class Experiment(Serializable):
...     name = SerializableProperty(default="")
...     temperature = SerializableProperty(default=293.15)
...     data = SerializableProperty(default=None)
...
>>> exp = Experiment(name="Test", temperature=373.15)
>>> exp.name
'Test'

Serialize to a dictionary:

>>> data = Serializable.serialize(exp)
>>> data['__class__']
'__main__.Experiment'
>>> data['name']
'Test'

Deserialize back to an object:

>>> restored = Serializable.deserialize(data)
>>> restored.name
'Test'
>>> restored.temperature
373.15

Copy an object:

>>> copy = exp.copy()
>>> copy is exp
False
>>> copy == exp
True

Nested objects work automatically:

>>> class Trial(Serializable):
...     trial_num = SerializableProperty(default=0)
...     experiment = SerializableProperty(default=None)
...
>>> trial = Trial(trial_num=1, experiment=exp)
>>> data = Serializable.serialize(trial)
>>> restored = Serializable.deserialize(data)
>>> restored.experiment.name
'Test'

Collections are handled recursively:

>>> exp_list = [Experiment(name=f"Exp{i}") for i in range(3)]
>>> serialized = Serializable.serialize(exp_list)
>>> restored = Serializable.deserialize(serialized)
>>> len(restored)
3

jangada.serialization.Serializable#

This Page