mafw.devtools.pyversions.manager

Pure Python version policy transformations.

This module defines VersionManager, the testable heart of the Python version management feature (GitLab issue #247). Each operation takes a PythonConfig and returns a new validated configuration (or raises DevtoolsError); none of the operations performs any file or network I/O. This separation keeps the business rules independent of both the TOML document and the CLI, which is what makes them straightforward to exercise with property-based tests.

The supported operations are:

Added in version 2.4.

author:

Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)

Classes

VersionManager()

Pure transformations over a PythonConfig.
class mafw.devtools.pyversions.manager.VersionManager[source]

Bases: object

Pure transformations over a PythonConfig.

Every method returns a freshly validated configuration; the input is never mutated. Guard conditions (malformed input, duplicates, constraint violations) raise DevtoolsError before any new configuration is produced, so a rejected operation leaves the caller’s configuration intact.

add_experimental(cfg: PythonConfig, version: str) → PythonConfig[source]

Register a version for experimental evaluation.

Stable minor targets and prerelease identifiers are both accepted; a prerelease is recorded as its minor-version target (3.16a1 → 3.16) so that Hatch/uv selectors can use it.

Parameters:

  • cfg – The current configuration.

  • version – A stable target or prerelease identifier.

Returns:

The updated, validated configuration.

Raises:

DevtoolsError – If version is malformed, already experimental, or already supported.

add_supported(cfg: PythonConfig, version: str) → PythonConfig[source]

Add a stable version to the supported list, promoting it if experimental.

Parameters:

  • cfg – The current configuration.

  • version – A stable major.minor target such as "3.15".

Returns:

The updated, validated configuration.

Raises:

DevtoolsError – If version is malformed, a prerelease, or already supported.

remove(cfg: PythonConfig, version: str) → PythonConfig[source]

Remove a version from whichever canonical list contains it.

Parameters:

  • cfg – The current configuration.

  • version – A stable major.minor version to retire.

Returns:

The updated, validated configuration.

Raises:

DevtoolsError – If version is malformed, is the current default, is the base version of the current free-threaded interpreter, or is not configured at all.

set_default(cfg: PythonConfig, version: str) → PythonConfig[source]

Change the default development interpreter.

Parameters:

  • cfg – The current configuration.

  • version – A supported stable version to become the new default.

Returns:

The updated configuration (identical if version is already the default).

Raises:

DevtoolsError – If version is malformed, not supported, or only experimental.

set_free_threaded(cfg: PythonConfig, version: str) → PythonConfig[source]

Change the free-threaded test interpreter.

Parameters:

  • cfg – The current configuration.

  • version – A free-threaded selector such as "3.15t" whose base version is officially supported.

Returns:

The updated, validated configuration.

Raises:

DevtoolsError – If version is not an X.Yt selector or its base version is not supported.

mafw.devtools.pyversions.manager._insert_sorted(versions: tuple[str, ...], version: str) → tuple[str, ...][source]

Return versions with version inserted, kept ascending and unique.

mafw.devtools.pyversions.manager._require_stable(version: str) → str[source]

Validate that version is a well-formed stable major.minor target.

The project supports only CPython 3.x, therefore the major component is constrained to 3 and the minor to the 0–99 range.

Parameters:

version (str) – The candidate version string.

Returns:

The validated version string (unchanged).

Return type:

str

Raises:

DevtoolsError – If version is not a stable 3.MINOR target.