scistag.filestag.bundle.Bundle

class Bundle

Bases: object

The bundle class is able to store a list, a tuple or a dictionary in a zip file. In case of a dictionary only the “first” level can be used for the storage of “advanced” data types such as images, DataFrames, numpy arrays etc.

With help of the Bundle class function parameters can easily be passed between different processes, clients and servers without the need to pickle them and in consequence without being bound to fully compatible module versions by using common interchange formats such as parquet files or json files.

Methods

bundle	Stores a dictionary, a list or a tuple in a zip file in memory and returns its bytes string representation which can then for example be passed to another process, client or server and extracted there or just be dumped to a database or a disk.
from_bytes	Converts an object from it's byte representation back to its normal form.
register_bundler	Registers a new bundling helper function
register_unpacker	Registers a new unpacking helper function
to_bytes	Converts an element to its storable bytes representation
unpack	Unpacks a previously bundled data package to it's original form

Attributes

__annotations__
__dict__
__doc__
__module__
__weakref__	list of weak references to the object (if defined)
_access_lock	Configuration access lock
_base_types_registered	Defines if the base types were registered
_bundlers	Registered functions to convert an of type key to it's bytes representation
_unpackers	Registered functions to convert an object from a known type and it's bytes representation back to it's original form such as a dictionary, numpy array or pandas DataFrame

classmethod _ensure_base_types()

Ensures that all base types are registered

classmethod bundle(elements, compression=None)

Stores a dictionary, a list or a tuple in a zip file in memory and returns its bytes string representation which can then for example be passed to another process, client or server and extracted there or just be dumped to a database or a disk.

Parameters

elements (dict[str, Any] | list[Any] | tuple) – The elements to be stored. Supported data types are

(w/o extensions which may be registered) dictionaries, lists, tuples, strings, floats, booleans, Pandas DataFrames, DataSeries, numpy arrays and byte strings. :type compression: int | None :param compression: The compression level (from 0 to 99) (fast to small) :rtype: bytes :return: The bytes dump of the zip archive.

classmethod from_bytes(data_type, data, options)

Converts an object from it’s byte representation back to its normal form.

Parameters

• data_type (str) – The data type as returned from to_bytes

• data (bytes) – The data

• options (UnpackOptions) – Advanced unpacking options

Return type

Any

Returns

The reconstructed object

classmethod register_bundler(data_type, callback)

Registers a new bundling helper function

Parameters

• data_type (type) – The data type to look out for

• callback (Callable[[Any, BundlingOptions], tuple[str, bytes]]) – The function be called to bundle the data

classmethod register_unpacker(data_type, callback)

Registers a new unpacking helper function

Parameters

• data_type (str) – The data type as string to look out for (as stored in the dictionary of the bundled data and returned by the corresponding BundleToBytesCallback)

• callback (Callable[[bytes, UnpackOptions], Any]) – The function be called to unpack the data

classmethod to_bytes(element, options)

Converts an element to its storable bytes representation

Parameters

• element (Any) – The element to convert to bytes

• options (BundlingOptions) – Advanced bundling options

Return type

tuple[str, bytes]

Returns

The data type to be stored in the bundle and the bytes string

classmethod unpack(data)

Unpacks a previously bundled data package to it’s original form

Parameters

data (bytes) – The data to unpack (as returned by bundle())

Return type

dict[str, Any] | list[Any] | tuple

Returns

The dictionary, tuple or list containing the bundled objects

_access_lock = <scistag.common.mt.stag_lock.StagLock object>

Configuration access lock

_base_types_registered = False

Defines if the base types were registered

_bundlers: dict[type, Callable[[Any, scistag.filestag.bundle.BundlingOptions], tuple[str, bytes]]] = {}

Registered functions to convert an of type key to it’s bytes representation

_unpackers: dict[str, Callable[[bytes, scistag.filestag.bundle.UnpackOptions], Any]] = {}

Registered functions to convert an object from a known type and it’s bytes representation back to it’s original form such as a dictionary, numpy array or pandas DataFrame