bagofholding.metadata module

Tools for extracting and logging information about python objects.

class bagofholding.metadata.HasContentType(content_type: 'str')

Bases: object

content_type: str

class bagofholding.metadata.HasFieldIterator

Bases: object

A simple helper mixin for dataclasses

field_items() → ItemsView[str, str | None]

class bagofholding.metadata.HasVersionInfo(qualname: 'str | None' = None, module: 'str | None' = None, version: 'str | None' = None)

Bases: object

module: str | None = None

qualname: str | None = None

version: str | None = None

class bagofholding.metadata.Metadata(content_type: 'str', qualname: 'str | None' = None, module: 'str | None' = None, version: 'str | None' = None, meta: 'str | None' = None)

Bases: HasVersionInfo, HasContentType, HasFieldIterator

meta: str | None = None

bagofholding.metadata.get_module(obj: Any) → str

bagofholding.metadata.get_qualname(obj: Any) → str

bagofholding.metadata.get_version(module_name: str, version_scraping: dict[str, Callable[[str], str | None]] | None = None) → str | None

Given a module name, get its associated version (if any). By default, this simply looks for the __version__ attribute on the imported module.

For builtins this is just the python interpreter version.

Parameters:

• module_name (str) – The module to examine.

• version_scraping (VersionScrapingMap | None) – Since some modules may store their version in other ways, this provides an optional map between module names and callables to leverage for extracting that module’s version.

Returns:

The module’s version as a string, if any can be found.

Return type:

(str | None)

bagofholding.metadata.validate_version(metadata: Metadata, validator: Literal['exact', 'semantic-minor', 'semantic-major', 'none'] | Callable[[str, str], bool] = 'exact', version_scraping: dict[str, Callable[[str], str | None]] | None = None) → None

Check whether versioning information in a piece of metadata matches the current environment.

Parameters:

• metadata (Metadata) – The metadata to validate.

• validator ("exact" | Callable[[str, str], bool]) – A recognized keyword or a callable that takes the current and metadata versions as strings and returns a boolean to indicate whether the current version matches the metadata reference. Keywords are “exact” (versions must be identical), “semantic-minor” (semantic versions (X.Y.Z where all are integers) match in the first two digits; all non-semantic versions must match exactly), “semantic-major” (semantic versions match in the first digit), and “none” (don’t compare the versions at all).

• 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.

Raises:

EnvironmentMismatch – If the module in the metadata cannot be found, or if the current and metadata versions do not pass validation.