pyiron_snippets.versions module

Tools for reliably and robustly extracting versioning info from python objects.

class pyiron_snippets.versions.VersionInfo(module: str, qualname: str | None, version: str | None)

Bases: object

Immutable record of an object’s module, qualified name, and module version.

This is useful for capturing provenance metadata about classes and instances, e.g. for serialization or reproducibility tracking.

module

The dotted module path where the object’s type is defined.

Type:

str

qualname

The qualified name of the object’s type within its module. A None qualname indicates that the object is itself a module.

Type:

str | None

version

The version string of the top-level package, or None if no version could be determined.

Type:

str | None

Example

>>> from pyiron_snippets import versions
>>>
>>> versions.VersionInfo.of(42)
VersionInfo(module='builtins', qualname='int', version=...)

Note

For object instances, this is version info about that object’s _type_, not information about where the instance itself is living.

property findable_at: str

property fully_qualified_name: str

property has_version: bool

property in_main: bool

property is_lambda: bool

property is_local: bool

module: str

classmethod of(obj: object, version_scraping: dict[str, Callable[[str], str | None]] | None = None, forbid_main: bool = False, forbid_locals: bool = False, forbid_lambda: bool = False, require_version: bool = False, strict: bool = False) → VersionInfo

Construct a VersionInfo by introspecting obj.

If a __module__ or __qualname__ is immediately available, they are used, otherwise the same fields are sought on the object’s type.

Parameters:

• obj – The object to introspect.

• version_scraping – Optional mapping from top-level package names to callables that return a version string (or None). Used to handle packages that don’t expose __version__.

• forbid_main – If True, raise ValueError when the module is __main__.

• forbid_locals – If True, raise ValueError when the qualname contains <locals> (i.e. the type was defined inside a function).

• forbid_lambda – If True, raise ValueError when the qualname contains <lambda>.

• require_version – If True, raise ValueError when no version can be determined for the module.

• strict – A shortcut to turn on all the other forbid and require flags.

Returns:

A new VersionInfo instance.

Raises:

ValueError – If any of the forbid_* / require_* constraints are violated.

qualname: str | None

validate_constraints(forbid_main: bool = False, forbid_locals: bool = False, forbid_lambda: bool = False, require_version: bool = False, strict: bool = False) → Self

version: str | None

class pyiron_snippets.versions.VersionInfoFactory(version_scraping: dict[str, Callable[[str], str | None]] | None = None, forbid_main: bool = False, forbid_locals: bool = False, require_version: bool = False)

Bases: object

A simple stateful wrapper for VersionInfo that is useful when getting info from multiple objects with the same settings.

forbid_locals: bool = False

forbid_main: bool = False

of(obj: object) → VersionInfo

require_version: bool = False

validate_constraints(info: VersionInfo) → VersionInfo

version_scraping: dict[str, Callable[[str], str | None]] | None = None

pyiron_snippets.versions.get_module(obj: Any) → str

Get module information for an arbitrary object.

Note

For object instances, this is version info about that object’s _type_, not information about where the instance itself is living.

pyiron_snippets.versions.get_qualname(obj: Any) → str | None

Get module information for an arbitrary object.

Note

For object instances, this is version info about that object’s _type_, not information about where the instance itself is living.

pyiron_snippets.versions.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 iteratively checking each module level for an available version. By default, this simply looks for the __version__ attribute on the imported module, but searching behaviour can be customized with the :arg:`version_scraping` argument.

The first found version walking up the module path takes precedence over higher versions, and the version scraping map entries take precedence over the default __version__ check at each step while walking.

For builtins, the python interpreter version is given.

Parameters:

• module_name (str) – The module to recursively 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)

Warning

This imports the module in the process, so it is not “safe”.