Skip to content

livery.workshop._registries

livery.workshop._registries

Where each artifact kind's registry lives: the resolution ladder.

One resolution for every artifact kind the ecosystem publishes or probes, so no caller derives a registry address on its own. The ladder, per kind: the declaration wins (the env cascade's variables first, machine truth over committed; then the contract's [registries] table), else the forge's own hosted registry of that kind, else the ecosystem default where one exists (pypi.org for python), else a refusal naming the kind and the rungs it tried. A declaration may be a local folder or share: every kind publishes to a path, so a workspace can work with no registry server at all.

Classes:

Name Description
RegistryTarget

One resolved registry for one artifact kind.

Functions:

Name Description
target_table

target as the publish phase's registry-target: its fields by name.

registry

The registry the workspace at root reads and publishes kind artifacts at.

resolve_registry

The registry for kind, through the ladder; refusal teaches.

RegistryTarget dataclass

RegistryTarget(kind: str, url: str, publish_url: str = '', local: bool = False, token: str = '', releases: bool = False)

One resolved registry for one artifact kind.

Attributes:

Name Type Description
kind str

Which artifact registry this is.

url str

The registry's address: the read index for python (the publish endpoint is publish_url), the remote for conan, the reference prefix for container. A local path when the declaration was a folder.

publish_url str

Where python dists upload; empty means the publisher's own default resolution (uv publish and trusted publishing on pypi.org). Unused by other kinds.

local bool

True when the target is a folder or share rather than a server.

releases bool

True when the artifacts ride the forge's own releases, attached to each member's receipt tag. The route a conan package takes on a forge that hosts no conan registry; url is then the repository's page, for printing.

token str

The registry credential, for reads and uploads alike: the kind's credential variable when set, else the forge lane's token when the forge rung answered. Empty reads anonymously and lets the publisher's own resolution decide.

Methods:

Name Description
from_table

The target a registry-target table holds.

kind instance-attribute

kind: str

url instance-attribute

url: str

publish_url class-attribute instance-attribute

publish_url: str = ''

local class-attribute instance-attribute

local: bool = False

token class-attribute instance-attribute

token: str = ''

releases class-attribute instance-attribute

releases: bool = False

from_table classmethod

from_table(table: Mapping[str, object]) -> RegistryTarget

The target a registry-target table holds.

The engine gives each step of the publish phase the registry it resolved as the registry-target key: a table of this class's fields by name, which the step reads back with this constructor. The table holds kind and url, and a field it leaves out takes its default.

Parameters:

Name Type Description Default
table Mapping[str, object]

Each field of the target by its name.

required

Returns:

Type Description
RegistryTarget

The target the table holds.

Raises:

Type Description
ValueError

when the table is not a registry target: it has no kind or no url, a value has another type than its field, or a key names no field. The message names the field and what it takes, and never a value, since token is a credential.

Source code in packages/workshop/src/livery/workshop/_registries.py
@classmethod
def from_table(cls, table: Mapping[str, object]) -> RegistryTarget:
    """The target a ``registry-target`` table holds.

    The engine gives each step of the ``publish`` phase the registry
    it resolved as the ``registry-target`` key: a table of this
    class's fields by name, which the step reads back with this
    constructor. The table holds ``kind`` and ``url``, and a field
    it leaves out takes its default.

    Args:
        table: Each field of the target by its name.

    Returns:
        The target the table holds.

    Raises:
        ValueError: when the table is not a registry target: it has
            no ``kind`` or no ``url``, a value has another type than
            its field, or a key names no field. The message names
            the field and what it takes, and never a value, since
            ``token`` is a credential.
    """
    names = tuple(field.name for field in fields(cls))
    unknown = [name for name in table if name not in names]
    if unknown:
        raise ValueError(
            f"not a registry target: the table holds {', '.join(unknown)};"
            f" a registry target holds {', '.join(names)}"
        )
    for field in fields(cls):
        if field.default is MISSING and field.name not in table:
            raise ValueError(
                f"not a registry target: the table has no {field.name},"
                " which every registry target holds"
            )
    return cls(
        kind=_text(table, "kind"),
        url=_text(table, "url"),
        publish_url=_text(table, "publish_url"),
        local=_flag(table, "local"),
        token=_text(table, "token"),
        releases=_flag(table, "releases"),
    )

target_table

target_table(target: RegistryTarget) -> dict[str, object]

target as the publish phase's registry-target: its fields by name.

Source code in packages/workshop/src/livery/workshop/_registries.py
def target_table(target: RegistryTarget) -> dict[str, object]:
    """*target* as the ``publish`` phase's ``registry-target``: its fields by name."""
    return {
        "kind": target.kind,
        "url": target.url,
        "publish_url": target.publish_url,
        "local": target.local,
        "token": target.token,
        "releases": target.releases,
    }

registry

registry(root: Path, kind: str) -> RegistryTarget

The registry the workspace at root reads and publishes kind artifacts at.

kind is python, conan or container. The first rung that names one wins: the environment's variables for the kind, the contract's [registries] table, the forge's own registry of the kind, then the ecosystem's default.

Raises:

Type Description
Failed

when kind is not an artifact registry kind, naming the three.

Source code in packages/workshop/src/livery/workshop/_registries.py
def registry(root: Path, kind: str) -> RegistryTarget:
    """The registry the workspace at *root* reads and publishes *kind* artifacts at.

    *kind* is ``python``, ``conan`` or ``container``. The first rung
    that names one wins: the environment's variables for the kind, the
    contract's ``[registries]`` table, the forge's own registry of the
    kind, then the ecosystem's default.

    Raises:
        Failed: when *kind* is not an artifact registry kind, naming
            the three.
    """
    return resolve_registry(root, kind)

resolve_registry

resolve_registry(root: Path, kind: str) -> RegistryTarget

The registry for kind, through the ladder; refusal teaches.

The rungs, in order: the env cascade's variables (machine truth over committed declarations), the contract's [registries] table, the forge's own registry of the kind, the ecosystem default. A python declaration may split read and publish addresses; the other kinds carry one.

Source code in packages/workshop/src/livery/workshop/_registries.py
def resolve_registry(root: Path, kind: str) -> RegistryTarget:
    """The registry for *kind*, through the ladder; refusal teaches.

    The rungs, in order: the env cascade's variables (machine truth
    over committed declarations), the contract's ``[registries]``
    table, the forge's own registry of the kind, the ecosystem
    default. A python declaration may split read and publish
    addresses; the other kinds carry one.
    """
    env_vars = _ENV_VARS.get(kind)
    if env_vars is None:
        fail(f"{kind!r} is not an artifact registry kind: python, conan, container")
    token = os.environ.get(_CREDENTIAL_VARS.get(kind, ""), "")
    declared_read = os.environ.get(env_vars[0], "")
    declared_publish = os.environ.get(env_vars[1], "") if len(env_vars) > 1 else ""
    if not declared_read and not declared_publish:
        contract = load_contract(root / "workshop.toml")
        table = contract.get("registries") or {}
        entry = table.get(kind) if isinstance(table, dict) else None
        if isinstance(entry, str):
            declared_read = entry
        elif isinstance(entry, dict):
            declared_read = str(entry.get("url", ""))
            declared_publish = str(entry.get("publish", ""))
    if declared_read or declared_publish:
        read = declared_read or declared_publish
        if not token:
            # A declaration naming the forge's own registry keeps the
            # forge lane token: committing the address must not lose
            # the credential the forge rung would have carried. A
            # foreign address never inherits it.
            resolved = _forge_registry(root, kind)
            if resolved is not None:
                forge_url, lane_token = resolved
                if forge_url and (
                    read.startswith(forge_url) or declared_publish.startswith(forge_url)
                ):
                    token = lane_token
        return RegistryTarget(
            kind=kind,
            url=_normalise(read),
            publish_url=_normalise(declared_publish),
            local=_is_local(read),
            token=token,
        )
    resolved = _forge_registry(root, kind)
    if resolved is None and kind == "conan":
        # A forge with no conan registry still has releases, and a
        # conan package is a file: each member's caches ride its own
        # receipt tag. The consumer reads them back through the same
        # forge, so nothing outside the repository is involved.
        return _forge_releases(root)
    if resolved is not None:
        forge_url, lane_token = resolved
        if kind == "python":
            # The forge-registry shape: the base takes uploads and
            # serves the simple index under /simple.
            return RegistryTarget(
                kind=kind,
                url=f"{forge_url}/simple",
                publish_url=forge_url,
                token=token or lane_token,
            )
        return RegistryTarget(kind=kind, url=forge_url, token=token or lane_token)
    default = _ECOSYSTEM.get(kind)
    if default is not None:
        return RegistryTarget(
            kind=kind, url=default[0], publish_url=default[1], token=token
        )
    fail(
        f"no {kind} registry resolves: nothing declared (env or the"
        " [registries] table), this forge hosts none, and the kind has"
        " no ecosystem default. Declare one, a local folder included."
    )