Skip to content

livery.workshop._pythons

livery.workshop._pythons

Python version facts, derived from the workspace, never asked.

The floor comes from the root pyproject.toml's requires-python bound; the newest supported minor is the workshop's own declaration. The CI matrix is the pair, so a new Python reaches every instance through a wheel bump, never an instance edit.

Functions:

Name Description
scripts_dir

Name venv's executables directory: Scripts on Windows, bin elsewhere.

venv_python

Name venv's interpreter on this platform.

runner_script

The console script in venv of the runner this process runs as.

python_floor

The workspace's Python floor.

declared_pythons

The contract's [ci] python-versions, or None when undeclared.

gate_pythons

The Pythons the gate point's check legs run: the newest of a derived matrix.

python_matrix

The CI matrix: the contract's declaration, else the floor and the newest minor.

Attributes:

Name Type Description
FLOOR_DEFAULT
NEWEST_SUPPORTED
PYTHONS_KEY

FLOOR_DEFAULT module-attribute

FLOOR_DEFAULT = '3.11'

NEWEST_SUPPORTED module-attribute

NEWEST_SUPPORTED = '3.14'

PYTHONS_KEY module-attribute

PYTHONS_KEY = 'python-versions'

scripts_dir

scripts_dir(venv: Path) -> Path

Name venv's executables directory: Scripts on Windows, bin elsewhere.

The running platform decides: a venv is used on the machine that made it. Nothing is read from the disk, so the venv may not exist yet.

Parameters:

Name Type Description Default
venv Path

The venv's directory.

required

Returns:

Type Description
Path

The directory its interpreter and its console scripts are in.

Source code in packages/workshop/src/livery/workshop/_pythons.py
def scripts_dir(venv: Path) -> Path:
    """Name *venv*'s executables directory: ``Scripts`` on Windows, ``bin`` elsewhere.

    The running platform decides: a venv is used on the machine that
    made it. Nothing is read from the disk, so the venv may not exist
    yet.

    Args:
        venv: The venv's directory.

    Returns:
        The directory its interpreter and its console scripts are in.
    """
    return venv / ("Scripts" if sys.platform == "win32" else "bin")

venv_python

venv_python(venv: Path) -> Path

Name venv's interpreter on this platform.

python.exe in livery.workshop.scripts_dir on Windows, and python there elsewhere. Nothing is read from the disk, so the venv may not exist yet.

Parameters:

Name Type Description Default
venv Path

The venv's directory.

required

Returns:

Type Description
Path

The interpreter's path.

Source code in packages/workshop/src/livery/workshop/_pythons.py
def venv_python(venv: Path) -> Path:
    """Name *venv*'s interpreter on this platform.

    ``python.exe`` in [livery.workshop.scripts_dir][] on Windows, and
    ``python`` there elsewhere. Nothing is read from the disk, so the
    venv may not exist yet.

    Args:
        venv: The venv's directory.

    Returns:
        The interpreter's path.
    """
    return scripts_dir(venv) / ("python.exe" if sys.platform == "win32" else "python")

runner_script

runner_script(venv: Path) -> Path

The console script in venv of the runner this process runs as.

Named as the running brand names its runner, with .exe on Windows, so a branded runner hands work to itself in another environment.

Source code in packages/workshop/src/livery/workshop/_pythons.py
def runner_script(venv: Path) -> Path:
    """The console script in *venv* of the runner this process runs as.

    Named as the running brand names its runner, with ``.exe`` on
    Windows, so a branded runner hands work to itself in another
    environment.
    """
    name = prog()
    return scripts_dir(venv) / (f"{name}.exe" if sys.platform == "win32" else name)

python_floor

python_floor(root: Path) -> str

The workspace's Python floor.

The lower bound of the root pyproject.toml's requires-python; livery.workshop._pythons.FLOOR_DEFAULT when the file or the bound is absent, which is what a workspace being born looks like.

Source code in packages/workshop/src/livery/workshop/_pythons.py
def python_floor(root: Path) -> str:
    """The workspace's Python floor.

    The lower bound of the root ``pyproject.toml``'s
    ``requires-python``;
    livery.workshop._pythons.FLOOR_DEFAULT when the file or the
    bound is absent, which is what a workspace being born looks
    like.
    """
    pyproject = root / "pyproject.toml"
    if not pyproject.is_file():
        return FLOOR_DEFAULT
    data = tomllib.loads(pyproject.read_text("utf-8"))
    spec = str(data.get("project", {}).get("requires-python", ""))
    match = re.search(r">=\s*(\d+\.\d+)", spec)
    return match.group(1) if match else FLOOR_DEFAULT

declared_pythons

declared_pythons(root: Path) -> list[str] | None

The contract's [ci] python-versions, or None when undeclared.

Refuses a declaration that is not a non-empty list of version strings (3.14, or 3.14t for a free-threaded build), naming the key: an empty list would emit a matrix with no leg, and a stray value would reach the runner as a python it cannot find.

Source code in packages/workshop/src/livery/workshop/_pythons.py
def declared_pythons(root: Path) -> list[str] | None:
    """The contract's ``[ci] python-versions``, or ``None`` when undeclared.

    Refuses a declaration that is not a non-empty list of version
    strings (``3.14``, or ``3.14t`` for a free-threaded build), naming
    the key: an empty list would emit a matrix with no leg, and a
    stray value would reach the runner as a python it cannot find.
    """
    contract = root / "workshop.toml"
    if not contract.is_file():
        return None
    ci = load_contract(contract).get("ci") or {}
    if PYTHONS_KEY not in ci:
        return None
    declared = ci[PYTHONS_KEY]
    # The contract's judge holds it to a list of strings.
    if not declared:
        fail(f'[ci] {PYTHONS_KEY} must be a non-empty list of versions, like ["3.14"]')
    for value in declared:
        if not _VERSION_RE.match(value):
            fail(
                f"[ci] {PYTHONS_KEY} entry {value!r} is not a python version:"
                ' spell the minor, like "3.14", or "3.14t" for a free-threaded build'
            )
    return [str(value) for value in declared]

gate_pythons

gate_pythons(root: Path) -> list[str]

The Pythons the gate point's check legs run: the newest of a derived matrix.

The legs run in parallel, so a second Python adds runner minutes and no wall time; the floor's leg runs at the nightly point, where the whole matrix runs, and a floor-only failure reaches a person the next morning. A declared [ci] python-versions runs at the gate as declared: the contract chose.

Source code in packages/workshop/src/livery/workshop/_pythons.py
def gate_pythons(root: Path) -> list[str]:
    """The Pythons the gate point's check legs run: the newest of a derived matrix.

    The legs run in parallel, so a second Python adds runner minutes
    and no wall time; the floor's leg runs at the nightly point, where
    the whole matrix runs, and a floor-only failure reaches a person
    the next morning. A declared ``[ci] python-versions`` runs at the
    gate as declared: the contract chose.
    """
    declared = declared_pythons(root)
    if declared is not None:
        return declared
    return python_matrix(root)[-1:]

python_matrix

python_matrix(root: Path) -> list[str]

The CI matrix: the contract's declaration, else the floor and the newest minor.

[ci] python-versions in the root's workshop.toml wins where declared, so a development workspace runs one leg and a production contract keeps the full pair. Without it the pair derives: the lower bound of the root pyproject.toml's requires-python, and the newest minor the workshop tests against, so a new Python reaches every instance through a wheel bump. Each entry is a version such as 3.14, or 3.14t for a free-threaded build: in the declared order, or the floor first.

Raises:

Type Description
Failed

naming the key, when [ci] python-versions is not a non-empty list of such versions.

Source code in packages/workshop/src/livery/workshop/_pythons.py
def python_matrix(root: Path) -> list[str]:
    """The CI matrix: the contract's declaration, else the floor and the newest minor.

    ``[ci] python-versions`` in the root's ``workshop.toml`` wins where
    declared, so a development workspace runs one leg and a production
    contract keeps the full pair. Without it the pair derives: the
    lower bound of the root ``pyproject.toml``'s ``requires-python``,
    and the newest minor the workshop tests against, so a new Python
    reaches every instance through a wheel bump. Each entry is a
    version such as ``3.14``, or ``3.14t`` for a free-threaded build: in
    the declared order, or the floor first.

    Raises:
        Failed: naming the key, when ``[ci] python-versions`` is not a
            non-empty list of such versions.
    """
    declared = declared_pythons(root)
    if declared is not None:
        return declared
    floor = python_floor(root)
    if _minor(floor) >= _minor(NEWEST_SUPPORTED):
        return [floor]
    return [floor, NEWEST_SUPPORTED]