Packing

register_packable(cls, pack_fn, create_fn, unpack_fn, name=None)[source]

Register a type to be packable. Requires a pack_fn, create_fn, and unpack_fn to store and restore object state.

Parameters
  • cls (ClassVar) – type to be registered

  • pack_fn (Callable) – callable input is an instance of the type, and packs all data necessary to recover the state

  • create_fn (Callable) – callable input is the expected type and the packed data, creates a new instance of the type,

without unpacking any packed data (to avoid reference loops) :type unpack_fn: Callable :param unpack_fn: callable input is the instance of packed data and then restores that instance to the original state using the packed data by unpacking any values therein. :type name: Optional[str] :param name: (optional) name of the class used for storing :rtype: NoReturn :return: A SavableClassCollisionError if the name is already registered

class Packable[source]

Bases: object

Any subclass of this mixin can be serialized using pack

All subclasses must implement __create__, __pack__, and __unpack__ to register the type. By passing a type to use_cls the type for which these methods are used can be overridden from the subclass.

classmethod __init_subclass__(use_cls=None, name=None)[source]

This method automatically registers any subclass that is declared.

Parameters

use_cls – The class to register (if it is different than cls)

Returns

None

__deepcopy__(memodict=None)[source]

Produces a deep copy of the data by packing and repacking.

Parameters

memodict (Optional[Dict[Any, Any]]) – Unused

Return type

Any

Returns

A deep copy of self

classmethod __create__(data)[source]

Create the object without loading the state from data. You can use the data to inform how to initialize the object, however no stored objects should be unpacked (to avoid reference loops)

Parameters

data (Dict[str, NewType()(PACKED, object)]) – packed data to restore object state, should NOT be unpacked here

Return type

Packable

Returns

A fresh instance of the class registered with this create_fn

__pack__()[source]

Collect all data in self necessary to store the state.

Warning

All data must be “packed” storing it. This is done by passing the data into

Packable._pack_obj and using what is returned.

Return type

Dict[str, NewType()(PACKED, object)]

Returns

A dict of packed data necessary to recover the state of self

__unpack__(data)[source]

Using data, recover the packed state. Must be overridden by all subclasses.

Warning

All data must be “unpacked” before using it. This is done by passing the data into

Packable._unpack_obj and using what is returned.

Parameters

data (Dict[str, NewType()(PACKED, object)]) – The information that is returned by __pack__.

Return type

NoReturn

Returns

Nothing. Once returned, the object should be in the same state as when it was packed

PRIMITIVE = typing.Union[str, int, float, bool, NoneType]

Valid primitives

SERIALIZABLE(x)
JSONABLE(x)
pack_member(obj, force_str=False)[source]

Store the object state by packing it, possibly returning a reference.

This function should be called inside implemented __pack__ on all data in an object necessary to restore the object state.

Note: this function should not be called on the top level (use pack instead).

Parameters
  • obj (NewType()(SERIALIZABLE, object)) – serializable data that should be packed

  • force_str (bool) – if the data is a key for a dict, set this to true to ensure the key is a str

Return type

NewType()(PACKED, object)

Returns

packed data

unpack_member(data)[source]

Restore the object data by unpacking it.

This function should be called inside implemented __unpack__ on all data in an object necessary to restore the object state from the packed data.

Note: this function should not be called on the top level (use unpack instead).

Parameters

data (NewType()(PACKED, object)) – packed data that should be unpacked

Return type

NewType()(SERIALIZABLE, object)

Returns

unpacked data to restore the state

pack(obj, meta=None, include_timestamp=False)[source]

Serializes any object, returning a json object that can be converted to a json string.

Parameters
  • obj (NewType()(SERIALIZABLE, object)) – Object to be serialized

  • meta (Optional[Dict[str, NewType()(PACKED, object)]]) – Meta information, must be jsonable

  • include_timestamp (bool) – include a timestamp in the meta information

Return type

NewType()(JSONABLE, object)

Returns

packed data, which can be converted to a json string using json.dumps

unpack(data, return_meta=False)[source]

Deserialize a packed object to recover the original state.

Parameters
  • data (NewType()(PACKED, object)) – serialized (packed) state of an object

  • return_meta (bool) – return any meta information from the serialized data

Return type

NewType()(SERIALIZABLE, object)

Returns

the unpacked (restored) object

save_pack(obj, fp, meta=None, include_timestamp=False)[source]

Pack (serialize) the object and store it as a json file

Parameters
  • obj (NewType()(SERIALIZABLE, object)) – object to be packed

  • fp (TextIO) – writable file-like object where the packed object is stored

  • include_timestamp (bool) – include timestamp in meta information

Return type

NoReturn

Returns

None

load_pack(fp, return_meta=False)[source]

Loads json file of packed object and unpacks the object

Parameters
  • fp (TextIO) – writable file-like object

  • return_meta (bool) – return the meta information stored

Return type

NewType()(SERIALIZABLE, object)

Returns

unpacked object from json file

json_pack(obj, meta=None, include_timestamp=False)[source]

Pack object and return a json string of the serialized object

Parameters
  • obj (NewType()(SERIALIZABLE, object)) – to be packed

  • meta (Optional[Dict[str, NewType()(JSONABLE, object)]]) – any meta information to include

  • include_timestamp (bool) – include timestamp in meta information

Return type

str

Returns

json string of the serialized data

json_unpack(data, return_meta=False)[source]

Unpack json string of a packed object.

Parameters
  • data (str) – json string of a packed object

  • return_meta (bool) – return meta information

Return type

NewType()(SERIALIZABLE, object)

Returns

unpacked object