bagofholding.bag module

The core user-facing object.

Full implementations of bags should guarantee the key features promised by the package: - Storage and retrieval of arbitrary pickleable python objects - Metadata preservation - Versioning verification - Browsing without loading - Partial reloading

class bagofholding.bag.Bag(filepath: str | Path, *args: object, _skip_load: bool = False, **kwargs: Any)

Bases: Packer, Mapping[str, Metadata | None], ABC

Bags are the user-facing object.

bag_info: BagInfo

browse()

filepath: Path

classmethod get_bag_info() → BagInfo

get_bespoke_content_class(obj: object) → type[BespokeItem[Any, Self]] | None

classmethod get_version() → str

join(*paths: str) → str

abstractmethod list_paths() → list[str]

A list of all available content paths.

load(path: str = 'object', version_validator: Literal['exact', 'semantic-minor', 'semantic-major', 'none'] | Callable[[str, str], bool] = 'exact', version_scraping: dict[str, Callable[[str], str | None]] | None = None) → Any

pack_metadata(metadata: Metadata, path: str) → None

static pickle_check(obj: Any, raise_exceptions: bool = True, print_message: bool = False) → str | None

A simple helper to check if an object can be pickled and unpickled. Useful if you run into trouble saving or loading and want to see whether the underlying object is compliant with pickle-ability requirements to begin with.

Parameters:

• obj – The object to test for pickling support.

• raise_exceptions – If True, re-raise any exception encountered.

• print_message – If True, print the exception message on failure.

Returns:

None if pickling is successful; otherwise, returns the exception message as a string.

classmethod save(obj: Any, filepath: str | Path, require_versions: bool = False, forbidden_modules: list[str] | tuple[str, ...] = (), version_scraping: dict[str, Callable[[str], str | None]] | None = None, _pickle_protocol: SupportsIndex = 4, overwrite_existing: bool = True) → None

Save a python object to file.

Parameters:

• obj (Any) – The (pickleble) python object to be saved.

• filepath (str|pathlib.Path) – The path to save the object to.

• require_versions (bool) – Whether to require a metadata for reduced and complex objects to contain a non-None version. (Default is False, objects can be stored from non-versioned packages/modules.)

• forbidden_modules (list[str] | tuple[str, ...] | None) – Do not allow saving objects whose root-most modules are listed here. (Default is an empty tuple, i.e. don’t disallow anything.) This is particularly useful to disallow “__main__” to improve the odds that objects will actually be loadable in the future.

• version_scraping (dict[str, Callable[[str], str]] | None) – An optional dictionary mapping module names to a callable that takes this name and returns a version (or None). The default callable imports the module string and looks for a __version__ attribute.

• overwrite_existing (bool) – Whether to overwrite an existing bag at the target location. (Default is True.)

storage_root: ClassVar[str] = 'object'

unpack_metadata(path: str) → Metadata

static validate_bag_info(bag_info: BagInfo, reference: BagInfo) → bool

widget()

class bagofholding.bag.BagInfo(qualname: 'str | None' = None, module: 'str | None' = None, version: 'str | None' = None)

Bases: HasVersionInfo, HasFieldIterator