cmeta.packages module

Package Manager class

cMeta author and developer: (C) 2025-2026 Grigori Fursin

See the cMeta COPYRIGHT and LICENSE files in the project root for details.

Classes

class cmeta.packages.PackageResult(module: object, name: str, version: str, satisfies: bool, specifier: str, installed_now: bool)[source]

Bases: object

module: object
name: str
version: str
satisfies: bool
specifier: str
installed_now: bool
__init__(module: object, name: str, version: str, satisfies: bool, specifier: str, installed_now: bool) → None
class cmeta.packages.Packages(cfg=None, cache=None, logger=None, fail_on_error=False, allow_install=True, timeout: float = None, add_install_args: str = None)[source]

Bases: object

__init__(cfg=None, cache=None, logger=None, fail_on_error=False, allow_install=True, timeout: float = None, add_install_args: str = None)[source]

Initialize package manager state and install/runtime options.

Parameters:

  • cfg – Framework configuration dictionary.

  • cache – Cache dictionary used to store resolved data.

  • logger – Logger instance used for diagnostic messages.

  • fail_on_error – If True, raise exceptions instead of returning error dictionaries.

  • allow_install – If True, allow automatic package installation.

  • timeout (float) – Timeout value in seconds.

  • add_install_args (str) – Value for add install args.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

log(level, msg)[source]

Log a message using the configured logger.

Parameters:

  • level – Log level string (e.g., ‘debug’, ‘info’, ‘warning’, ‘error’).

  • msg – Message to log.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

get_version(module)[source]

Get version string from a Python module.

Parameters:

module – Python module object.

Returns:

Version string if available, None otherwise.

Return type:

str or None

Raises:

Exception – Propagated runtime errors, if any.

poetry_to_pep440(spec)[source]

Convert Poetry-style version specifier to PEP 440 format.

Parameters:

spec – Poetry version specifier (e.g., ‘^1.2.0’, ‘~1.2.0’, ‘1.*’).

Returns:

PEP 440 compatible version specifier.

Return type:

str

Raises:

Exception – Propagated runtime errors, if any.

build_spec(v, vmin, vmax, specifier)[source]

Build a version specifier string from version constraints.

Parameters:

  • v – Exact version string (e.g., ‘1.2.0’).

  • vmin – Minimum version string.

  • vmax – Maximum version string.

  • specifier – Poetry or PEP 440 version specifier.

Returns:

Combined version specifier, or None if no constraints provided.

Return type:

str or None

Raises:

Exception – Propagated runtime errors, if any.

build_pip_requirement(name, version, vmin, vmax, specifier)[source]

Build a pip-compatible requirement string like ‘numpy>=1.20,<2.0’

Parameters:

  • name – Name identifier.

  • version – Version string.

  • vmin – Minimum allowed version string.

  • vmax – Maximum allowed version string.

  • specifier – Version specifier string.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

kill_process_tree(pid)[source]

Kill a process tree (process and all its children).

Parameters:

pid – Process ID to kill.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

pip_install_sync(pkg, silent, install_args, timeout, con)[source]

Install a Python package using pip synchronously.

Parameters:

  • pkg – Package requirement string (e.g., ‘numpy>=1.20’).

  • silent – If True, suppress installation output.

  • install_args – Additional pip install arguments string.

  • timeout – Timeout in seconds (None for no timeout).

  • con – If True, print console messages.

Raises:

RuntimeError – If installation is disabled, times out, or fails.

Returns:

Operation result.

Return type:

dict

async pip_install_async(pkg, silent, install_args, timeout, con)[source]

Install a Python package asynchronously using pip with timeout support.

Parameters:

  • pkg – Package requirement name or specifier.

  • silent – If True, suppress installer output.

  • install_args – Additional arguments passed to package installer.

  • timeout – Timeout value in seconds.

  • con – If True, print output to console.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

try_import(name)[source]

Try to import a Python module by name.

Parameters:

name – Module name to import.

Returns:

Module object if import succeeds, None if not found.

Return type:

module or None

Raises:

Exception – Propagated runtime errors, if any.

build_cache_key(name, version, vmin, vmax, specifier, async_flag)[source]

Build a cache key for package lookup.

Parameters:

  • name – Package name.

  • version – Exact version string.

  • vmin – Minimum version string.

  • vmax – Maximum version string.

  • specifier – Version specifier string.

  • async_flag – True if async import, False otherwise.

Returns:

Cache key string.

Return type:

str

Raises:

Exception – Propagated runtime errors, if any.

get(name, version=None, version_min=None, version_max=None, specifier=None, *, silent=False, install_args='', timeout=None, use_cache=True, allow_install=None, con=False)[source]

Get or install a Python package synchronously.

Parameters:

  • name – Package name to import.

  • version – Exact version required.

  • version_min – Minimum version required.

  • version_max – Maximum version required.

  • specifier – Version specifier (Poetry or PEP 440 format).

  • silent – If True, suppress installation output.

  • install_args – Additional pip install arguments.

  • timeout – Installation timeout in seconds (overrides default).

  • use_cache – If True, use cached results.

  • allow_install – If True, allow package installation (overrides instance setting).

  • con – If True, print console messages.

Returns:

Object with module, name, version, satisfies, specifier, and installed_now fields.

Return type:

PackageResult

Raises:

Exception – Propagated runtime errors, if any.

async get_async(name, version=None, version_min=None, version_max=None, specifier=None, *, silent=False, install_args='', timeout=None, use_cache=True, allow_install=None, con=False)[source]

Asynchronously resolve, optionally install, and validate a Python package.

Parameters:

  • name – Name identifier.

  • version – Version string.

  • version_min – Minimum allowed version string.

  • version_max – Maximum allowed version string.

  • specifier – Version specifier string.

  • silent – If True, suppress installer output.

  • install_args – Additional arguments passed to package installer.

  • timeout – Timeout value in seconds.

  • use_cache – If True, reuse cached values when available.

  • allow_install – If True, allow automatic package installation.

  • con – If True, print output to console.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

get_all(pip_packages, con=False)[source]

Resolve a mapping of packages synchronously and return module handles.

Parameters:

  • pip_packages – Mapping of package names to resolution settings.

  • con – If True, print output to console.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

async get_async_all(pip_packages, con=False)[source]

Resolve a mapping of packages asynchronously and return module handles.

Parameters:

  • pip_packages – Mapping of package names to resolution settings.

  • con – If True, print output to console.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

normalize_detected_version(version_str)[source]

Normalize non-standard version strings to PEP 440 compatible format.

Parameters:

version_str – Version string that may contain platform identifiers,

Returns:

Normalized version string compatible with packaging library.

Return type:

str

Raises:

Exception – Propagated runtime errors, if any.

match_version(requested_version, detected_version)[source]

Check if a detected version matches a requested version specifier.

Parameters:

  • requested_version – Version requirement in Poetry or PyPI format

  • detected_version – Installed version string (e.g., ‘2.3.1’, ‘2.3.windows.1’,

Returns:

{‘return’: 0, ‘matched’: bool} on success,

{‘return’: 1, ‘error’: str} on error.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.