versioned_pickle API reference

Main module of versioned-pickle.

The main API consists of these functions:

dump()

load()

These can be used as a nearly drop-in replacement for the corresponding functions from the stdlib pickle module. Only these are needed for normal use. Additional public objects (including EnvironmentMetadata and PackageMismatchWarning) are exposed only for introspecting or potentially customizing the treatment of environment metadata and handling of mismatches.

class versioned_pickle.EnvironmentMetadata(packages: dict[str, str], py_ver: tuple[int, int, int], package_scope: Literal['object', 'loaded', 'installed'])

Class for managing metadata about the environment used when creating or loading a versioned pickle.

Typically not needed when using the main dump/load API. If one does need to construct instances, from_scope can calculate the needed data from high-level intent.

packages

dict of distribution names to version strings

Type:

dict[str, str]

py_ver

the python interpreter version

Type:

tuple[int, int, int]

package_scope

the type of scope that was used for which packages to include.

Type:

{“object”, “loaded”, “installed”}

classmethod from_header_dict(metadata: dict[str, Any]) → EnvironmentMetadata

Inverse of to_header_dict - create an instance from a native dict in the pickle-header format.

classmethod from_scope(package_scope: Literal['object', 'loaded', 'installed'] = 'object', object_modules: Iterable[str] | None = None) → EnvironmentMetadata

Construct an EnvironmentMetadata based on the type of scope for which packages to include.

This is the typical way to construct instances, not calling the class name directly.

Parameters:

  • package_scope ({"object", "loaded", "installed"}) – can be “object” meaning the specific modules needed for an object, in which case module names must be specified in object_modules, or “loaded”, or “installed”.

  • object_modules (optional Iterable[str],) – module names needed to pickle an object and for which to record pkg versions. Only used if package_scope is ‘object’. Needed modules can be determined automatically using _IntrospectionPickler.

to_header_dict() → dict[str, dict[str, Any]]

Get a representation of the metadata as a Python-native dict.

Used when one doesn’t want to have import versioned_pickle itself, such as in the header created for pickle files.

validate_against(loaded_env: EnvironmentMetadata) → PackageMismatchWarning | None

Validate the environment metadata instance against the one for the loading environment.

Typically this would not be called by users, but should be handled by the dump/load API. The validation logic compares only the packages dict, and ignores extra packages in the loading env.

exception versioned_pickle.PackageMismatchWarning(msg: str, mismatches: dict[str, tuple[str, Optional[str]]])

Warning class used when loading pickled data whose metadata doesn’t validate against the loading env.

versioned_pickle.dump(obj: object, file: IO[bytes], package_scope: Literal['object', 'loaded', 'installed'] = 'object') → None

Pickle an object’s data to a file with environment metadata.

Parameters:

  • obj (any object to pickle) –

  • file (file-like obj (writable, binary mode)) –

  • package_scope (optional str {'object', 'loaded', 'installed'},) – How to determine which packages to include in metadata. “object”: the specific modules needed to pickle the object, or “loaded”: any module that has currently been imported (regardless of where), or “installed”: all installed distributions.

versioned_pickle.dumps(obj: object, package_scope: Literal['object', 'loaded', 'installed'] = 'object') → bytes

Like dump, but returns an in-memory bytes object instead of using a file.

versioned_pickle.load(file: IO[bytes], return_meta: bool = False) → object

Load an object from a pickle file saved by ‘dump’, and validate the environment metadata.

The saved EnvironmentMetadata from the environment that dumped the file is checked against the current EnvironmentMetadata. Extra packages in the load env are ignored as is python version. If they do not match, a PackageMismatchWarning is warned with details of the mismatches.

Parameters:

  • file (file-like obj (readable, binary mode)) –

  • return_meta (optional bool) – if True return a tuple of the object and its metadata

versioned_pickle.loads(data: bytes, return_meta: bool = False) → object

Like load, but takes a bytes-like object.