Skip to content

livery.extensions.python

livery.extensions.python

The python extension's names another extension reads to stamp, build and test wheels.

The python extension builds, versions, publishes and tests a package whose set holds python. An extension that builds such a package's wheels with a tool of its own, as nanobind builds them with cibuildwheel, reads three of its functions. livery.extensions.python.stamp writes a release's version into the package's pyproject.toml and every __version__, and raises there the floors on the members released with it. livery.extensions.python.module_docs copies the package's docs/ into its source tree as the wheel's embedded _docs for one build, and removes the copy after it. livery.extensions.python.run_isolated_test installs a built wheel into a fresh venv and runs the package's tests against the installed copy.

Functions:

Name Description
module_docs

The wheel-embedded _docs, in the source tree for one build alone.

run_isolated_test

Install the built wheel into a fresh venv and test the installed copy.

stamp

Write version and raise package's floors in its manifests; the files changed.

Attributes:

Name Type Description
__version__

TYPE_CHECKING module-attribute

TYPE_CHECKING = False

__version__ module-attribute

__version__ = '0.0.0'

__all__ module-attribute

__all__ = ['__version__', 'module_docs', 'run_isolated_test', 'stamp']

module_docs

module_docs(package: Package) -> Generator[Path | None]

The wheel-embedded _docs, in the source tree for one build alone.

On entry the package's docs/ is copied whole to _docs in the shallowest of its module roots, the importable package its wheel ships, replacing any older copy. On exit the copy is removed, after a failed build too. A copy left behind puts the docs' example files under the package's source, where every checker that walks the tree judges them as the package's own code.

Yields:

Type Description
Generator[Path | None]

The copy's path; None when the package has no module to carry

Generator[Path | None]

it, or no docs/ to copy.

Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
@contextmanager
def module_docs(package: Package) -> Generator[Path | None]:
    """The wheel-embedded ``_docs``, in the source tree for one build alone.

    On entry the package's ``docs/`` is copied whole to ``_docs`` in
    the shallowest of its module roots, the importable package its
    wheel ships, replacing any older copy. On exit the copy is
    removed, after a failed build too. A copy left behind puts the
    docs' example files under the package's source, where every
    checker that walks the tree judges them as the package's own code.

    Yields:
        The copy's path; None when the package has no module to carry
        it, or no ``docs/`` to copy.
    """
    target = materialise_module_docs(package)
    try:
        yield target
    finally:
        if target is not None:
            shutil.rmtree(target, ignore_errors=True)

run_isolated_test

run_isolated_test(package: Package, root: Path, *, release_dirs: tuple[Path, ...] = (), resolution: str = 'latest', wheels_dir: Path | None = None) -> dict[str, str]

Install the built wheel into a fresh venv and test the installed copy.

One leg of the release's isolated test, at resolution: floor puts every direct dependency at its declared floor, so a floor lying about compatibility fails here; latest resolves the newest, the world a fresh consumer gets; head installs at the versions the workspace lock pins, read as it stands, and refuses in a workspace without a lock.

--find-links is limited to release_dirs, the co-released set's dist/ directories: a leftover wheel from a non-released package must never mask that the release needs an unpublished dependency version. Everything else resolves from the repo's configured indexes, like a real consumer. Each distribution those directories carry is refreshed in uv's cache, so a member rebuilt at the same version installs the wheel just built and never an earlier build of the same filename.

The toolchain installs after the wheel, at the lock's dev-group pins where a lock exists (bare pytest otherwise), and a probe then re-reads the package's own direct dependencies: the second install is pip-shaped and moves versions without erroring, so a toolchain pin that overlaps a floored dependency would silently undo the starvation. Movement is a taught refusal.

Parameters:

Name Type Description Default
package Package

The member whose wheel is installed and tested.

required
root Path

The workspace root, whose lock and indexes the install reads.

required
release_dirs tuple[Path, ...]

The co-released set's dist/ directories, the only places a wheel resolves from beside the indexes.

()
resolution str

floor, latest or head.

'latest'
wheels_dir Path | None

Where the wheel to install is, for a leg that built one outside the collected dist/; None takes the package's own dist/.

None

Returns:

Type Description
dict[str, str]

The resolved version per distribution, the report's raw

dict[str, str]

material ("floor leg: livery-forge 0.1.0").

Raises:

Type Description
Failed

when resolution is none of the three, when no wheel is there to install, when the head leg finds no lock, when an install fails, when the toolchain install moves a direct dependency the leg resolved, and when the tests fail.

Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
def run_isolated_test(
    package: Package,
    root: Path,
    *,
    release_dirs: tuple[Path, ...] = (),
    resolution: str = "latest",
    wheels_dir: Path | None = None,
) -> dict[str, str]:
    """Install the built wheel into a fresh venv and test the installed copy.

    One leg of the release's isolated test, at *resolution*: ``floor``
    puts every direct dependency at its declared floor, so a floor
    lying about compatibility fails here; ``latest`` resolves the
    newest, the world a fresh consumer gets; ``head`` installs at the
    versions the workspace lock pins, read as it stands, and refuses
    in a workspace without a lock.

    ``--find-links`` is limited to *release_dirs*, the co-released
    set's ``dist/`` directories: a leftover wheel from a non-released
    package must never mask that the release needs an unpublished
    dependency version. Everything else resolves from the repo's
    configured indexes, like a real consumer.
    Each distribution those directories carry is refreshed in uv's
    cache, so a member rebuilt at the same version installs the wheel
    just built and never an earlier build of the same filename.

    The toolchain installs after the wheel, at the lock's dev-group
    pins where a lock exists (bare pytest otherwise), and a probe
    then re-reads the package's own direct dependencies: the second
    install is pip-shaped and moves versions without erroring, so a
    toolchain pin that overlaps a floored dependency would silently
    undo the starvation. Movement is a taught refusal.

    Args:
        package: The member whose wheel is installed and tested.
        root: The workspace root, whose lock and indexes the install
            reads.
        release_dirs: The co-released set's ``dist/`` directories, the
            only places a wheel resolves from beside the indexes.
        resolution: ``floor``, ``latest`` or ``head``.
        wheels_dir: Where the wheel to install is, for a leg that built
            one outside the collected ``dist/``; None takes the
            package's own ``dist/``.

    Returns:
        The resolved version per distribution, the report's raw
        material ("floor leg: livery-forge 0.1.0").

    Raises:
        Failed: when *resolution* is none of the three, when no wheel
            is there to install, when the head leg finds no lock, when
            an install fails, when the toolchain install moves a direct
            dependency the leg resolved, and when the tests fail.
    """
    import json
    import tempfile

    if resolution not in RESOLUTIONS:
        fail(
            f"{package.name}: the isolated test resolves at"
            f" {', '.join(RESOLUTIONS)}, not {resolution!r}"
        )
    strategy, locked = RESOLUTIONS[resolution]

    # Sorted for determinism: with several wheels in dist a glob's
    # filesystem order once handed the leg a musllinux wheel the
    # venv could not install.
    built = wheels_dir if wheels_dir is not None else package.directory / "dist"
    wheels = sorted(built.glob("*.whl"))
    if not wheels:
        fail(f"{package.name}: no wheel in {built} to validate; build first")
    with tempfile.TemporaryDirectory() as scratch:
        from livery.workshop import venv_python

        venv = Path(scratch) / "venv"
        python = venv_python(venv)

        def _run_install(*args: str) -> None:
            result = tools.uv.opts(cwd=scratch, nofail=True, recorded=False)(*args)
            if result.code != 0:
                fail(
                    f"{package.name} isolated install ({resolution}) exited"
                    f" {result.code}:\n{result.stdout}{result.stderr}"
                )

        def _listing() -> dict[str, str]:
            listing = tools.uv.opts(cwd=scratch, nofail=True, recorded=False)(
                "pip", "list", "--python", str(python), "--format", "json"
            )
            versions: dict[str, str] = {}
            if listing.code == 0:
                for row in json.loads(listing.stdout or "[]"):
                    versions[str(row.get("name", ""))] = str(row.get("version", ""))
            return versions

        constraints: tuple[str, ...] = ()
        if locked:
            pins = _lock_pins(root, Path(scratch))
            if pins is None:
                fail(
                    f"{package.name}: the head leg installs at the versions the"
                    f" workspace lock pins, and uv export read no lock in {root};"
                    " lock the workspace, or list floor or latest in"
                    " [release] prove"
                )
            constraints = ("--constraint", str(pins))
        # The leg's own interpreter version, explicitly: bare `uv
        # venv` takes uv's default python, and a platform wheel
        # built for the running interpreter (cp311) cannot install
        # into a venv of another (cp314). Pure wheels never noticed.
        _run_install(
            "venv",
            "--python",
            f"{sys.version_info.major}.{sys.version_info.minor}",
            str(venv),
        )
        _run_install(
            "pip",
            "install",
            "--python",
            str(python),
            f"--resolution={strategy}",
            *[f"--find-links={d}" for d in release_dirs],
            *_refresh_args(release_dirs),
            *_index_args(root),
            *constraints,
            _install_target(package, wheels[0]),
            # The declared dependencies ride the command line so
            # the resolution strategy treats them as direct; see
            # _direct_requirements.
            *_direct_requirements(package),
        )
        resolved = _listing()
        before = _direct_versions(package, resolved)
        # The toolchain never rides the starved install: lowest-direct
        # aimed at it once dragged pytest back a decade. Locked pins
        # where the workspace has them, minus what the leg resolved,
        # so the leg keeps its floor or its latest; pytest is a no-op
        # re-request when the pins already hold it.
        # The toolchain resolves from the same indexes as the wheel:
        # the lock's pins name whatever versions the workspace's own
        # index serves, and a bare-PyPI install cannot see those.
        pins = _dev_pins(root, Path(scratch))
        if pins is not None:
            pins = _pins_without(pins, resolved)
            _run_install(
                "pip",
                "install",
                "--python",
                str(python),
                *_index_args(root),
                "-r",
                str(pins),
            )
        _run_install(
            "pip", "install", "--python", str(python), *_index_args(root), "pytest"
        )
        after = _direct_versions(package, _listing())
        moved = {
            name: (before[name], version)
            for name, version in after.items()
            if name in before and before[name] != version
        }
        if moved:
            listed = ", ".join(
                f"{name} {was} -> {now}" for name, (was, now) in sorted(moved.items())
            )
            fail(
                f"{package.name}: the toolchain install moved direct"
                f" dependencies the {resolution} leg had resolved: {listed}."
                " The starvation must stay honest: a toolchain tool needs"
                " another version of a dependency the member declares, so"
                " pin that tool where the two agree, or widen the member's"
                " floor."
            )
        tests = package.directory / "tests"
        if tests.is_dir():
            result = footman.run(
                [
                    str(python),
                    "-m",
                    "pytest",
                    str(tests),
                    "-q",
                    "-p",
                    "no:cacheprovider",
                    # pytest derives its rootdir from the test paths and
                    # finds the workspace's configuration, whose addopts
                    # would hand the leg xdist workers and coverage flags;
                    # the leg is serial and unmetered by design.
                    "-o",
                    "addopts=",
                ],
                cwd=scratch,
                env=_leg_env(root, venv),
                nofail=True,
                recorded=False,
            )
            if result.code != 0:
                fail(
                    f"{package.name} isolated tests ({resolution}) failed:\n"
                    f"{result.stdout[-4000:]}{result.stderr[-2000:]}"
                )
        return _listing()

stamp

stamp(package: Package, version: str, floors: Mapping[str, str]) -> list[str]

Write version and raise package's floors in its manifests; the files changed.

The version goes into pyproject.toml and every __version__ (stamp_version), and each requirement on one of floors, the members released with package, takes that member's version (raise_floors). Each file once, relative to the package's directory.

Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
def stamp(package: Package, version: str, floors: Mapping[str, str]) -> list[str]:
    """Write *version* and raise *package*'s floors in its manifests; the files changed.

    The version goes into ``pyproject.toml`` and every ``__version__``
    (`stamp_version`), and each requirement on one of *floors*, the
    members released with *package*, takes that member's version
    (`raise_floors`). Each file once, relative to the package's
    directory.
    """
    changed = stamp_version(package).stamp(version)
    changed += raise_floors(package, floors)
    return list(dict.fromkeys(changed))

__getattr__

__getattr__(name: str) -> object

Serve a public name from its module, each time it is read.

The value is never kept here, so a test that patches the name in its module is read through.

Source code in packages/extensions/python/src/livery/extensions/python/__init__.py
def __getattr__(name: str) -> object:
    """Serve a public name from its module, each time it is read.

    The value is never kept here, so a test that patches the name in
    its module is read through.
    """
    import importlib

    module = _EXPORTS.get(name)
    if module is None:
        raise AttributeError(
            f"module 'livery.extensions.python' has no attribute {name!r}"
        )
    return getattr(importlib.import_module(module), name)