mafw.devtools.dependencies.compile

Dependency compilation utilities for MAFw.

This module provides functions for compiling dependency lockfiles using uv, reading resolved dependency versions, and managing Python version metadata from the project configuration.

Module Attributes

`PYPROJECT_FILE`	Path to the TOML file containing the project dependencies.
`DEFAULT_FREEZE_EXTRAS`	Extras used when compiling dependency lockfiles for release freezing and compatibility checks.

Functions

`collect_compiled_dependency_versions`(...)	Compile dependency lockfiles and collect the resolved versions they report.
`compile_dependency_lockfile`(python_version, ...)	Compile a dependency lockfile for a specific CPython version.
`compile_python_selector`(python_version)	Build the Python selector used by `uv` for dependency compilation.
`ensure_mafw_project_root`()	Ensure the current working directory is the MAFw project root.
`load_pylock_packages`(pylock_path)	Parse a pylock TOML file into a dictionary keyed by lowercase package name.
`load_pyproject_doc`(toml_text)	Parse a `pyproject.toml` payload once and return the TOML document.
`parse_python_version`(version)	Parse a Python version string in `major.minor` form.
`project_python_versions`()	Read the supported CPython versions from `tool.mafw.supported-python` list in pyproject.toml.
`project_python_versions_from_doc`(doc)	Extract supported CPython versions from a parsed `pyproject.toml` document.
`python_versions_between`(min_python_ver, ...)	Build the inclusive list of Python versions between two bounds.
`read_compiled_dependency_versions`(pylock_text)	Read resolved dependency versions from a compiled lockfile payload.

mafw.devtools.dependencies.compile.collect_compiled_dependency_versions(python_versions: list[str]) → dict[str, Version][source]

Compile dependency lockfiles and collect the resolved versions they report.

The command mirrors the dependency verification workflow by invoking uv pip compile for each supported CPython version. A temporary lockfile is generated for each version and removed afterwards.

Parameters:: python_versions (list[str]) – Supported Python versions to compile.
Returns:: Mapping of package name to highest resolved version across the compiled lockfiles.
Return type:: dict[str, Version]

mafw.devtools.dependencies.compile.compile_dependency_lockfile(python_version: str, pylock_file: Path, extras: list[str], resolution: str | None = None, output_format: str | None = None, with_hashes: bool = False) → None[source]

Compile a dependency lockfile for a specific CPython version.

Parameters:

python_version (str) – CPython version used for the uv pip compile run.
pylock_file (Path) – Output path for the generated lockfile.
extras (list[str]) – Project extras requested during compilation.
resolution (str | None) – Optional UV resolution strategy (e.g. ‘lowest-direct’, ‘highest’).
output_format (str | None) – Optional output format (e.g. ‘requirements.txt’).
with_hashes (bool) – Whether to generate hashes for the compiled requirements.

mafw.devtools.dependencies.compile.compile_python_selector(python_version: str) → str[source]

Build the Python selector used by uv for dependency compilation.

For Python 3.14 and newer, request the GIL-enabled variant explicitly so free-threaded interpreters do not leak into dependency resolution.

This distinction is still needed because of the psycopg

Parameters:: python_version (str) – Base Python version in major.minor form.
Returns:: Python selector string passed to uv.
Return type:: str

mafw.devtools.dependencies.compile.ensure_mafw_project_root() → list[str][source]

Ensure the current working directory is the MAFw project root.

Returns:: Validated supported Python versions from tool.mafw.supported-python.
Return type:: list[str]
Raises:: DevtoolsError – If pyproject.toml is missing or does not identify MAFw.

mafw.devtools.dependencies.compile.load_pylock_packages(pylock_path: Path) → dict[str, dict[str, Any]][source]

Parse a pylock TOML file into a dictionary keyed by lowercase package name.

Each value in the returned dictionary contains at minimum the name, version, and optionally marker fields from the original TOML entry.

Parameters:

pylock_path (Path) – Path to the pylock TOML file.

Returns:

Dictionary mapping lowercase package names to their package metadata.

Return type:

dict[str, dict[str, Any]]

Raises:

FileNotFoundError – If pylock_path does not exist.
tomllib.TOMLDecodeError – If the file is not valid TOML.

mafw.devtools.dependencies.compile.load_pyproject_doc(toml_text: str) → TOMLDocument[source]

Parse a pyproject.toml payload once and return the TOML document.

Parameters:: toml_text (str) – Raw TOML payload.
Returns:: Parsed TOML document.
Return type:: tomlkit.TOMLDocument
Raises:: DevtoolsError – If the TOML payload cannot be parsed.

mafw.devtools.dependencies.compile.parse_python_version(version: str) → tuple[int, int][source]

Parse a Python version string in major.minor form.

Parameters:: version (str) – Python version string.
Returns:: Major/minor version tuple.
Return type:: tuple[int, int]
Raises:: DevtoolsError – If the version is invalid.

mafw.devtools.dependencies.compile.project_python_versions() → list[str][source]

Read the supported CPython versions from tool.mafw.supported-python list in pyproject.toml.

The field is expected to be a list of strings representing CPython major.minor versions. The helper validates each entry and returns a sorted, de-duplicated list so downstream callers have deterministic ordering.

Returns:: Sorted list of supported CPython versions.
Return type:: list[str]
Raises:: DevtoolsError – If pyproject.toml cannot be parsed or the field contains unsupported values.

mafw.devtools.dependencies.compile.project_python_versions_from_doc(doc: TOMLDocument) → list[str][source]

Extract supported CPython versions from a parsed pyproject.toml document.

Parameters:: doc (tomlkit.TOMLDocument) – Parsed TOML document.
Returns:: Sorted list of supported CPython versions.
Return type:: list[str]
Raises:: DevtoolsError – If the tool.mafw.supported-python field is invalid.

mafw.devtools.dependencies.compile.python_versions_between(min_python_ver: str, max_python_ver: str, supported_versions: list[str]) → list[str][source]

Build the inclusive list of Python versions between two bounds.

The returned versions must also be present in supported_versions.

Parameters:

min_python_ver (str) – Minimum Python version.
max_python_ver (str) – Maximum Python version.
supported_versions (list[str]) – List of supported Python versions from project metadata.

Returns:

Ordered list of version strings.

Return type:

list[str]

mafw.devtools.dependencies.compile.read_compiled_dependency_versions(pylock_text: str) → dict[str, Version][source]

Read resolved dependency versions from a compiled lockfile payload.

The returned mapping stores the highest resolved version seen for each dependency name, normalized to lowercase for stable lookups.

Parameters:: pylock_text (str) – Raw pylock.pyX.Y.toml content.
Returns:: Mapping of package name to highest resolved version.
Return type:: dict[str, Version]
Raises:: DevtoolsError – If the TOML payload cannot be parsed.

mafw.devtools.dependencies.compile.DEFAULT_FREEZE_EXTRAS: Final[tuple[str, ...]] = ('seaborn', 'all-db', 'steering-gui'): Extras used when compiling dependency lockfiles for release freezing and compatibility checks.

mafw.devtools.dependencies.compile.PYPROJECT_FILE: Final[Path] = PosixPath('pyproject.toml'): Path to the TOML file containing the project dependencies.