Skip to content

livery.extensions.conan

livery.extensions.conan

The conan extension's names another extension reads to build against its packages.

The conan extension builds a member whose recipe, conanfile.py, names a reference into the conan cache, and releases it. An extension whose builds link such a member reads six of its names. The workspace's conan members resolve one another from their sources through the conan workspace file at the root, livery.extensions.conan.WORKSPACE_FILE, whose text livery.extensions.conan.workspace_file renders. livery.extensions.conan.workspace_aside hides that file for a block, so a build in it resolves each member from the conan cache. A release's build saves the package it created out of the cache with livery.extensions.conan.save_cache, one file per host, and livery.extensions.conan.restore_from_releases restores a released version from the member's release on the forge. A release's stamp raises the floors a recipe declares on the members released with it through livery.extensions.conan.raise_floors, a consumer's recipe among them.

Functions:

Name Description
raise_floors

Raise each requirement on a member released with package; the files changed.

restore_from_releases

Restore name at version from its release into the conan cache.

save_cache

Save this host's built package out of the conan cache; the file.

workspace_aside

Hide root's conan workspace for the block, so members resolve from the cache.

workspace_file

The conan workspace file for root: each conan member, from its source.

Attributes:

Name Type Description
WORKSPACE_FILE
__version__

TYPE_CHECKING module-attribute

TYPE_CHECKING = False

WORKSPACE_FILE module-attribute

WORKSPACE_FILE = 'conanws.yml'

__version__ module-attribute

__version__ = '0.0.0'

__all__ module-attribute

__all__ = ['WORKSPACE_FILE', '__version__', 'raise_floors', 'restore_from_releases', 'save_cache', 'workspace_aside', 'workspace_file']

raise_floors

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

Raise each requirement on a member released with package; the files changed.

floors names each such member by its path, to the version it releases at. A reference to that member in the recipe in the range form a requirement writer writes, "<name>/[>=<floor>]", takes that version, in a recipe that names a reference and in a consumer's alike. Empty for no floors, for a package with no recipe, and for a recipe that names none of them.

Source code in packages/extensions/conan/src/livery/extensions/conan/_package.py
def raise_floors(package: Package, floors: Mapping[str, str]) -> list[str]:
    """Raise each requirement on a member released with *package*; the files changed.

    *floors* names each such member by its path, to the version it
    releases at. A reference to that member in the recipe in the range
    form a requirement writer writes, ``"<name>/[>=<floor>]"``, takes
    that version, in a recipe that names a reference and in a
    consumer's alike. Empty for no floors, for a package with no
    recipe, and for a recipe that names none of them.
    """
    recipe = package.directory / RECIPE_FILE
    if not floors or not recipe.is_file():
        return []
    from livery.workshop import discover_packages

    names = {
        member.name: floors[member.path]
        for member in discover_packages(package.root)
        if member.path in floors and member.path != package.path
    }
    text = original = recipe.read_text("utf-8")
    for name, version in names.items():
        text = re.sub(
            rf'("{re.escape(name)}/\[>=)[^\]"]+(\]")',
            rf"\g<1>{version}\g<2>",
            text,
        )
    if text == original:
        return []
    recipe.write_text(text, encoding="utf-8")
    return [RECIPE_FILE]

restore_from_releases

restore_from_releases(root: Path, name: str, version: str, *, cwd: Path) -> None

Restore name at version from its release into the conan cache.

The consumer's half of the releases route: the member's release is read for this host's saved cache, the bytes are checked against the digest the forge reports, and conan cache restore puts the package where a build resolves it.

Raises:

Type Description
Failed

when the member is unknown here, the release carries no cache for this host, or the bytes do not match the digest.

Source code in packages/extensions/conan/src/livery/extensions/conan/_package.py
def restore_from_releases(root: Path, name: str, version: str, *, cwd: Path) -> None:
    """Restore *name* at *version* from its release into the conan cache.

    The consumer's half of the releases route: the member's release
    is read for this host's saved cache, the bytes are checked
    against the digest the forge reports, and ``conan cache
    restore`` puts the package where a build resolves it.

    Raises:
        Failed: when the member is unknown here, the release carries
            no cache for this host, or the bytes do not match the
            digest.
    """
    from livery.workshop import this_repository

    path = member_path(root, name)
    if not path:
        fail(
            f"{name} is not a member of this workspace, so its conan"
            " package has no release here; declare a conan remote that"
            " serves it"
        )
    tag = f"{path}/v{version}"
    wanted = cache_name(name, version)
    repository = this_repository(root)
    assets = repository.release.assets(tag)
    match = next((asset for asset in assets if asset.name == wanted), None)
    if match is None:
        carried = ", ".join(sorted(asset.name for asset in assets)) or "nothing"
        fail(
            f"release {tag} carries no conan cache for this host: wanted"
            f" {wanted}, it carries {carried}. Release {name} {version}"
            " from a wave that ran this host's wheel platform."
        )
    data = repository.release.download_asset(tag, wanted)
    verify_digest(wanted, data, match.digest)
    with tempfile.TemporaryDirectory() as scratch:
        archive = Path(scratch) / wanted
        archive.write_bytes(data)
        restore_cache(archive, cwd=cwd)
    print(f"  conan: {name}/{version} restored from {tag}")

save_cache

save_cache(package: Package, version: str, into: Path) -> Path

Save this host's built package out of the conan cache; the file.

The release matrix runs one leg per wheel platform: each leg creates the package for its own host and saves it here, the collection gathers every leg's file, and the wave attaches them all to the member's release. conan cache restore reads one back on any machine.

Raises:

Type Description
Failed

when conan refuses the save; the message carries its output.

Source code in packages/extensions/conan/src/livery/extensions/conan/_package.py
def save_cache(package: Package, version: str, into: Path) -> Path:
    """Save this host's built package out of the conan cache; the file.

    The release matrix runs one leg per wheel platform: each leg
    creates the package for its own host and saves it here, the
    collection gathers every leg's file, and the wave attaches them
    all to the member's release. ``conan cache restore`` reads one
    back on any machine.

    Raises:
        Failed: when conan refuses the save; the message carries its
            output.
    """
    into.mkdir(parents=True, exist_ok=True)
    archive = into / cache_name(package.name, version)
    result = _conan(
        package.directory,
        "cache",
        "save",
        f"{package.name}/{version}:*",
        "--file",
        str(archive),
    )
    if result.code != 0:
        fail(
            f"conan cache save ({package.name}/{version}) exited"
            f" {result.code}:\n{result.stdout[-3000:]}{result.stderr[-2000:]}"
        )
    return archive

workspace_aside

workspace_aside(root: Path) -> Generator[None]

Hide root's conan workspace for the block, so members resolve from the cache.

A release leg builds what the release ships: a member's conan create and an extension's wheel resolve a sibling to the package the leg created, never to its source tree. Conan finds the workspace from the directory a command runs in and has no switch to ignore it, so the file moves aside for the block and comes back after it, a failure included. A leg killed inside the block leaves the file aside, and the next sync writes it again.

Source code in packages/extensions/conan/src/livery/extensions/conan/_package.py
@contextmanager
def workspace_aside(root: Path) -> Generator[None]:
    """Hide *root*'s conan workspace for the block, so members resolve from the cache.

    A release leg builds what the release ships: a member's
    ``conan create`` and an extension's wheel resolve a sibling to the
    package the leg created, never to its source tree. Conan finds the
    workspace from the directory a command runs in and has no switch
    to ignore it, so the file moves aside for the block and comes back
    after it, a failure included. A leg killed inside the block leaves
    the file aside, and the next ``sync`` writes it again.
    """
    path = root / WORKSPACE_FILE
    if not path.is_file():
        yield
        return
    aside = path.with_name(f"{WORKSPACE_FILE}.aside")
    os.replace(path, aside)
    try:
        yield
    finally:
        os.replace(aside, path)

workspace_file

workspace_file(root: Path, *, absolute: bool = False) -> str

The conan workspace file for root: each conan member, from its source.

The fragment this extension declares: the workshop writes it at the root while a package's set holds conan and withdraws it with the last package that did. A package that lists conan, or an extension that requires it, holds it (livery.workshop.extension_set). The members are listed in path order.

Conan finds the file by walking up from the directory a command runs in, so a command inside the workspace resolves each member from its source tree, and one outside resolves it from the cache or a remote. Nothing is registered in the conan home, so a workspace leaves nothing behind, and each checkout of a repository resolves to its own sources. An entry names its member by path alone: conan reads the reference from the recipe's name and version, so the file stays right when a release stamps the version.

A member whose recipe names no reference is left out: conan deduces a workspace package's reference from the recipe's name and version, and a consumer's recipe, requirements alone, is what conan installs for, never a workspace package.

Parameters:

Name Type Description Default
root Path

The workspace root, whose members the file lists.

required
absolute bool

Whether each entry is the member's absolute POSIX path, for a copy placed outside the root: a Linux build container mounts the root at its host path and reads such a copy beside the package it builds. False writes the paths relative to the root, for the file the root holds.

False
Source code in packages/extensions/conan/src/livery/extensions/conan/_package.py
def workspace_file(root: Path, *, absolute: bool = False) -> str:
    """The conan workspace file for *root*: each conan member, from its source.

    The fragment this extension declares: the workshop writes it at
    the root while a package's set holds conan and withdraws it with
    the last package that did. A package that lists conan, or an
    extension that requires it, holds it
    ([livery.workshop.extension_set][]). The members are
    listed in path order.

    Conan finds the file by walking up from the directory a command
    runs in, so a command inside the workspace resolves each member
    from its source tree, and one outside resolves it from the cache
    or a remote. Nothing is registered in the conan home, so a
    workspace leaves nothing behind, and each checkout of a repository
    resolves to its own sources. An entry names its member by path
    alone: conan reads the reference from the recipe's ``name`` and
    ``version``, so the file stays right when a release stamps the
    version.

    A member whose recipe names no reference is left out: conan
    deduces a workspace package's reference from the recipe's ``name``
    and ``version``, and a consumer's recipe, requirements alone, is
    what conan installs for, never a workspace package.

    Args:
        root: The workspace root, whose members the file lists.
        absolute: Whether each entry is the member's absolute POSIX
            path, for a copy placed outside the root: a Linux build
            container mounts the root at its host path and reads such
            a copy beside the package it builds. False writes the
            paths relative to the root, for the file the root holds.
    """
    from livery.workshop import discover_packages

    entries = [
        f"  - path: {(root / member.path).as_posix()}"
        if absolute
        else f"  - path: {member.path}"
        for member in discover_packages(root)
        if is_conan_package(member)
    ]
    # An empty list, spelled: a bare key reads as nothing, and conan's
    # loader fails iterating it, while a workspace of consumers alone
    # is a workspace with no package.
    lines = [
        "# The conan workspace: a conan command run inside this folder",
        "# resolves each package below from its source tree. Rendered from",
        "# the members packaged with conan; the gate keeps it matching.",
        *(["packages:", *entries] if entries else ["packages: []"]),
    ]
    return "\n".join(lines) + "\n"

__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/conan/src/livery/extensions/conan/__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.conan' has no attribute {name!r}"
        )
    return getattr(importlib.import_module(module), name)