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 registeredpack_fn (
Callable
) – callable input is an instance of the type, and packs all data necessary to recover the statecreate_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
- 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
-
classmethod
-
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 packedforce_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 serializedmeta (
Optional
[Dict
[str
,NewType()
(PACKED
,object
)]]) – Meta information, must be jsonableinclude_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 objectreturn_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 packedfp (
TextIO
) – writable file-like object where the packed object is storedinclude_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 objectreturn_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 packedmeta (
Optional
[Dict
[str
,NewType()
(JSONABLE
,object
)]]) – any meta information to includeinclude_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 objectreturn_meta (
bool
) – return meta information
- Return type
NewType()
(SERIALIZABLE
,object
)- Returns
unpacked object