Skip to content

livery.workshop._extensions

livery.workshop._extensions

The extension walk: the lists in the contracts, every channel.

Every extension is one kind, and two lists name them: the root workshop.toml's [workspace] extensions and each package's workshop.toml, the extensions it is composed of. The root's list takes any extension, and a package's list one whose declarations show it composes something in a package. A list's set is the list and every extension it requires. The installed set is the root's set and every package's set: a sync installs it, and mounting reads it, the base first, then the installed set in composition order: each extension after the ones it requires, ties alphabetical. No list's order decides anything: each list is written in its canonical form, the minimal one in composition order. So a package installed by accident never changes a repository: discovery is the lists and nothing else.

Functions:

Name Description
workspace_root

The nearest ancestor carrying the workspace's contract, or None.

installed_extensions

The names installed distributions declare extensions under, sorted.

shipping_distribution

The installed distribution whose workshop.extensions entry names package.

normal_name

name as a distribution or an extra is compared: lower case, one hyphen per run.

declaration

extension's declaration file, read and judged; None when none is installed.

ships_declaration

Whether an installed distribution declares extension and ships its file.

ships_elsewhere

Whether a wheel other than distribution ships the extension target.

distribution_of

The distribution that ships extension: its entry point's, else by convention.

missing_list

Why root's contract cannot mount for want of its list; empty with one.

listing

An entry of an extensions list, as the requirement grammar reads it.

enabled_steps

The steps the root contract turns on, each <phase>.<step>; empty without.

workspace_entries

Each entry of [workspace] extensions as (name, distribution), in order.

workspace_names

The extensions [workspace] extensions lists, in its order.

installed_declaration

name's declaration where one is installed; None otherwise.

composes_per_package

Whether extension composes something in a package whose set holds it.

installed_record

The step name as an installed extension declares it; None when none does.

why_inert

What extension does instead of composing a package; empty when it composes.

root_set

The root's set: [workspace] extensions and what it requires.

installed_set

The extensions the workspace installs and mounts, in composition order.

where_listed

Each extension of the installed set to the list that brings it, as notes say it.

extension_entries

Every extension of the installed set as (name, distribution), in mount order.

stack_entries

The base, then every listed extension in mount order, as name and distribution.

stack_names

The base, then every listed extension: whose content a sync delivers.

extension_package

The dotted package extension ships from: the one its entry point names.

extension_provider

The member package whose sources ship extension, by its path; empty if none.

extension_names

The extensions the workspace installs and mounts, in mount order.

extension_content

The installed extension's content/ directory, or None.

base_directory

The directory this process imported the base from.

shipped_content

Each extension of the workspace's stack with its content/ directory.

left_out

Each root entry's without: the targets its extension contributes nothing to.

snapshot

What the mount recorded, for livery.workshop._extensions.restore to put back.

restore

Put the mount's records back to state.

mount_git_plugin

Mount the git plugin; the reason it could not, printed as a note, or empty.

mount_extensions

Mount the plugin of every extension of the installed set, in mount order.

stale_declarations

The listed extensions the mount found installed from before this checkout.

unmounted

The listed extensions the mount found no installed distribution declaring.

declared_now

Of names, the extensions an installed distribution declares now.

install_places

Where each of names, the base or an extension, is installed, as read here.

check_phase_declarers

Refuse a step of extension into a phase of an extension it does not require.

check_replacements

Refuse a step of extension that replaces or deletes one it cannot reach.

register_declared

Register what additions declares for extension; whether it declares a step.

register_jobs

Add each of jobs to its builtin point, its entries' source extension.

check_api_version

Refuse an extension whose declared API version is not this workshop's.

extension_dependencies

Each listed extension's [extension] requires, name to names.

extension_tools

Each listed extension's [toolroom] requires, name to requirement strings.

notes_tools

Each listed extension that writes release notes, to its [toolroom] requires.

declared_targets

Each listed extension's [for.<target>] tables, owner to target to tables.

resolved_targets

Each extension of the installed set to its active targets, in composition order.

contributions_for

What the installed extensions declare for target, by extension.

contributing

Each listed extension to the listed targets its [for] tables apply to now.

dormancy

Each listed extension that is dormant now, to what it waits for.

describe_extensions

The lines fm extensions prints: each extension with what it declares.

enabled_problems

Each root [phases.<phase>.<step>] table turning on no step declared off.

closure_problems

Why the contracts' lists are not valid compositions in their canonical form.

root_list_problems

Why [workspace] extensions is not its canonical list; empty when it is.

composition_problems

Why each package's list is not a valid composition in its canonical form.

listing_problems

Each [workspace] extensions entry spelled as more than a name.

entry_problems

Each listed name nothing installed declares, and each package entry with options.

requirers

Each listed extension to the listed extensions that depend on it.

write_extensions

Write each package's list and the root's in its canonical form.

list_in_root

Add names to root's [workspace] extensions, as its canonical list.

available_extensions

Installed extensions the contract does not list, as (name, distribution).

Attributes:

Name Type Description
SELF
BASE_DISTRIBUTION
GROUP
MOUNTED bool
UNDECLARED tuple[str, ...]
STALE tuple[str, ...]
Entry

SELF module-attribute

SELF = 'livery.workshop'

BASE_DISTRIBUTION module-attribute

BASE_DISTRIBUTION = SELF.replace('.', '-')

GROUP module-attribute

GROUP = 'workshop.extensions'

MOUNTED module-attribute

MOUNTED: bool = False

UNDECLARED module-attribute

UNDECLARED: tuple[str, ...] = ()

STALE module-attribute

STALE: tuple[str, ...] = ()

Entry module-attribute

Entry = str | dict[str, Any]

workspace_root

workspace_root(start: Path | None = None) -> Path | None

The nearest ancestor carrying the workspace's contract, or None.

The workspace contract is the marker; a checkout without one is not a workspace and gets no extensions. A package's own workshop.toml, under packages/<name>/ or packages/<group>/<name>/ of a workspace whose root holds a contract, is passed over, so a verb run inside a package resolves the workspace it belongs to. Without start, the search starts at the running task's directory, the process's outside a run: a task never reads the process's own, which a parallel run shares.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def workspace_root(start: Path | None = None) -> Path | None:
    """The nearest ancestor carrying the workspace's contract, or None.

    The workspace contract is the marker; a checkout without one is
    not a workspace and gets no extensions. A package's own
    ``workshop.toml``, under ``packages/<name>/`` or
    ``packages/<group>/<name>/`` of a workspace whose root holds a
    contract, is passed over, so a verb run inside a package resolves
    the workspace it belongs to. Without *start*, the search starts at
    the running task's directory, the process's outside a run: a task
    never reads the process's own, which a parallel run shares.
    """
    from livery.workshop._contract import _package_workspace

    origin = (start or cwd()).resolve()
    for candidate in (origin, *origin.parents):
        contract = candidate / "workshop.toml"
        if not contract.is_file():
            continue
        above = _package_workspace(contract)
        if above is not None and (above / "workshop.toml").is_file():
            continue
        return candidate
    return None

installed_extensions

installed_extensions() -> tuple[str, ...]

The names installed distributions declare extensions under, sorted.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def installed_extensions() -> tuple[str, ...]:
    """The names installed distributions declare extensions under, sorted."""
    return tuple(sorted(_declared()))

shipping_distribution

shipping_distribution(package: str) -> Distribution | None

The installed distribution whose workshop.extensions entry names package.

None when no installed distribution declares an extension shipped from package.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def shipping_distribution(package: str) -> Distribution | None:
    """The installed distribution whose ``workshop.extensions`` entry names *package*.

    None when no installed distribution declares an extension shipped
    from *package*.
    """
    for entry in _declared().values():
        if entry.value.partition(":")[0] == package and entry.dist is not None:
            return entry.dist
    return None

normal_name

normal_name(name: str) -> str

name as a distribution or an extra is compared: lower case, one hyphen per run.

The packaging standards' normal form: ., _ and - in any run become one -.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def normal_name(name: str) -> str:
    """*name* as a distribution or an extra is compared: lower case, one hyphen per run.

    The packaging standards' normal form: ``.``, ``_`` and ``-`` in any
    run become one ``-``.
    """
    return re.sub(r"[-_.]+", "-", name).lower()

declaration

declaration(extension: str) -> Declaration | None

extension's declaration file, read and judged; None when none is installed.

Read without importing anything of the extension: footman's plugin() stays a plugin's first importer, and a step's code is imported when the step runs.

Raises:

Type Description
DeclarationError

when the package the entry point names ships no declaration file, as a release written for another workshop does, or the file says something this workshop cannot take.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def declaration(extension: str) -> Declaration | None:
    """*extension*'s declaration file, read and judged; None when none is installed.

    Read without importing anything of the extension: footman's
    ``plugin()`` stays a plugin's first importer, and a step's code
    is imported when the step runs.

    Raises:
        DeclarationError: when the package the entry point names ships
            no declaration file, as a release written for another
            workshop does, or the file says something this workshop
            cannot take.
    """
    entry = _declared().get(extension)
    if entry is None:
        return None
    package = entry.value.partition(":")[0]
    found = read(extension, package)
    if found is None:
        raise DeclarationError(
            f"extension {extension!r}: its entry point names {package}, which ships"
            f" no {FILE}; install a release of the extension written for this"
            " workshop"
        )
    return found

ships_declaration

ships_declaration(extension: str) -> bool

Whether an installed distribution declares extension and ships its file.

False for an extension no installed distribution declares, and for one whose entry point names a package without a declaration file, as an install whose files moved away leaves behind.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def ships_declaration(extension: str) -> bool:
    """Whether an installed distribution declares *extension* and ships its file.

    False for an extension no installed distribution declares, and for
    one whose entry point names a package without a declaration file,
    as an install whose files moved away leaves behind.
    """
    entry = _declared().get(extension)
    return (
        entry is not None
        and declaration_file(entry.value.partition(":")[0]) is not None
    )

ships_elsewhere

ships_elsewhere(target: str, distribution: str) -> bool

Whether a wheel other than distribution ships the extension target.

A relation to an extension of the same wheel needs no dependency and no extra: one wheel has one version, so the two cannot drift apart.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def ships_elsewhere(target: str, distribution: str) -> bool:
    """Whether a wheel other than *distribution* ships the extension *target*.

    A relation to an extension of the same wheel needs no dependency
    and no extra: one wheel has one version, so the two cannot drift
    apart.
    """
    return normal_name(distribution_of(target)) != normal_name(distribution)

distribution_of

distribution_of(extension: str) -> str

The distribution that ships extension: its entry point's, else by convention.

An extension no installed distribution declares, a newborn's list written before its environment exists, say, is taken at the convention: an import path names its distribution with its dots as hyphens, and a short name is one of the base's own family, <namespace>-extensions-<name>, never the index's package of that bare name. An entry point whose distribution's metadata is gone, moved by an install after the scan, has no name to give and is taken at the convention the same way.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def distribution_of(extension: str) -> str:
    """The distribution that ships *extension*: its entry point's, else by convention.

    An extension no installed distribution declares, a newborn's list
    written before its environment exists, say, is taken at the
    convention: an import path names its distribution with its dots as
    hyphens, and a short name is one of the base's own family,
    ``<namespace>-extensions-<name>``, never the index's package of
    that bare name. An entry point whose distribution's metadata is
    gone, moved by an install after the scan, has no name to give and
    is taken at the convention the same way.
    """
    entry = _declared().get(extension)
    name = entry.dist.name if entry is not None and entry.dist is not None else None
    if name:
        return name
    if "." in extension:
        return extension.replace(".", "-")
    return f"{SELF.partition('.')[0]}-extensions-{extension}"

missing_list

missing_list(root: Path) -> str

Why root's contract cannot mount for want of its list; empty with one.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def missing_list(root: Path) -> str:
    """Why *root*'s contract cannot mount for want of its list; empty with one."""
    workspace = _workspace_table(root)
    if workspace is None or "extensions" in workspace:
        return ""
    return (
        f"{root / 'workshop.toml'}: [workspace] extensions is required; add\n"
        "\n  extensions = []\n\n"
        "under [workspace], naming the extensions this workspace uses"
        f" (`{prog()} doctor` lists the installed ones)"
    )

listing

listing(text: str) -> Spec

An entry of an extensions list, as the requirement grammar reads it.

An entry is a name. A spelling the grammar does not read is taken whole as a name: no distribution declares it, so the mount names it, and layering.graph refuses the spelling. One it reads with brackets, a version or a scope is read as its name, and layering.graph refuses the spelling too (livery.workshop._extensions.listing_problems).

Source code in packages/workshop/src/livery/workshop/_extensions.py
def listing(text: str) -> Spec:
    """An entry of an ``extensions`` list, as the requirement grammar reads it.

    An entry is a name. A spelling the grammar does not read is taken
    whole as a name: no distribution declares it, so the mount names
    it, and ``layering.graph`` refuses the spelling. One it reads with
    brackets, a version or a scope is read as its name, and
    ``layering.graph`` refuses the spelling too
    ([livery.workshop._extensions.listing_problems][]).
    """
    from livery.toolroom.store import Spec, SpecError

    try:
        return Spec.parse(text, where="[workspace] extensions")
    except SpecError:
        return Spec(text)

enabled_steps

enabled_steps(start: Path | None = None) -> frozenset[str]

The steps the root contract turns on, each <phase>.<step>; empty without.

A step its extension declares enabled = false registers only while the root contract sets [phases.<phase>.<step>] enabled = true. Read raw, as the list is, since the mount reads it before any verb judges the contract.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def enabled_steps(start: Path | None = None) -> frozenset[str]:
    """The steps the root contract turns on, each ``<phase>.<step>``; empty without.

    A step its extension declares ``enabled = false`` registers only
    while the root contract sets ``[phases.<phase>.<step>] enabled =
    true``. Read raw, as the list is, since the mount reads it before
    any verb judges the contract.
    """
    root = workspace_root(start)
    contract = None if root is None else root / "workshop.toml"
    if contract is None or not contract.is_file():
        return frozenset()
    phases = tomllib.loads(contract.read_text("utf-8")).get("phases")
    if not isinstance(phases, dict):
        return frozenset()
    found: set[str] = set()
    for phase, steps in cast("dict[str, Any]", phases).items():
        if not isinstance(steps, dict):
            continue
        for step, table in cast("dict[str, Any]", steps).items():
            if isinstance(table, dict) and table.get("enabled") is True:
                found.add(f"{phase}.{step}")
    return frozenset(found)

workspace_entries

workspace_entries(start: Path | None = None) -> tuple[tuple[str, str], ...]

Each entry of [workspace] extensions as (name, distribution), in order.

An entry is a name, or a table { name = "...", without = [...] }. Empty outside a workspace and when the contract has no list: the mount refuses that, and a reader has nothing to read.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def workspace_entries(start: Path | None = None) -> tuple[tuple[str, str], ...]:
    """Each entry of ``[workspace] extensions`` as ``(name, distribution)``, in order.

    An entry is a name, or a table ``{ name = "...", without = [...] }``.
    Empty outside a workspace and when the contract has no list: the
    mount refuses that, and a reader has nothing to read.
    """
    entries: list[tuple[str, str]] = []
    for entry in _listed(start):
        name = listing(_spelling(entry)).name
        entries.append((name, distribution_of(name)))
    return tuple(entries)

workspace_names

workspace_names(start: Path | None = None) -> tuple[str, ...]

The extensions [workspace] extensions lists, in its order.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def workspace_names(start: Path | None = None) -> tuple[str, ...]:
    """The extensions ``[workspace] extensions`` lists, in its order."""
    return tuple(name for name, _ in workspace_entries(start))

installed_declaration

installed_declaration(name: str) -> Declaration | None

name's declaration where one is installed; None otherwise.

The lookup livery.workshop._composition reads the installed extensions through.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def installed_declaration(name: str) -> Declaration | None:
    """*name*'s declaration where one is installed; None otherwise.

    The lookup [livery.workshop._composition][] reads the installed
    extensions through.
    """
    return _readable(name)

composes_per_package

composes_per_package(extension: str) -> bool

Whether extension composes something in a package whose set holds it.

The proof reads the installed declarations alone. extension composes when it, or an extension it requires transitively, declares at its top level or in a [for.<target>] table a step in a phase whose level is package, an answer to a query whose level is package, or [categories]; or when a step of any installed extension, or a step's per-package fragment, names it in extensions. Workspace-level steps and answers, contract keys, tools, shipped files, CI jobs, verbs, templates and requires itself compose nothing in a package. An extension whose code alone reads a package's set is not seen: the declarations define what composes, so a package's list refuses such an extension. An installed declaration that cannot be read names nothing.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def composes_per_package(extension: str) -> bool:
    """Whether *extension* composes something in a package whose set holds it.

    The proof reads the installed declarations alone. *extension*
    composes when it, or an extension it requires transitively,
    declares at its top level or in a ``[for.<target>]`` table a step
    in a phase whose level is ``package``, an answer to a query whose
    level is ``package``, or ``[categories]``; or when a step of any
    installed extension, or a step's per-package fragment, names it in
    ``extensions``. Workspace-level steps and answers, contract keys,
    tools, shipped files, CI jobs, verbs, templates and ``requires``
    itself compose nothing in a package. An extension whose code alone
    reads a package's set is not seen: the declarations define what
    composes, so a package's list refuses such an extension. An
    installed declaration that cannot be read names nothing.
    """
    from livery.workshop._phases import PACKAGE_LEVEL, declared_phases
    from livery.workshop._queries import declared_queries

    phases = declared_phases()
    queries = declared_queries()
    named = _named_by_steps()
    for name in closure((extension,), installed_declaration):
        if name in named:
            return True
        found = installed_declaration(name)
        if found is None:
            continue
        # The read refused a step into a phase, and an answer to a query,
        # that no installed declaration declares, so each is known here.
        if any(
            phases[record.phase].level == PACKAGE_LEVEL
            for record in _declared_steps(found)
        ):
            return True
        answered = [*found.queries]
        for held in found.target_queries.values():
            answered += held
        if any(queries[query].level == PACKAGE_LEVEL for query in answered):
            return True
        if found.categories or any(
            table.get("categories") for table in found.target_tables.values()
        ):
            return True
    return False

installed_record

installed_record(name: str) -> StepRecord | None

The step name as an installed extension declares it; None when none does.

name is <phase>.<step>. The installed extensions are read in name order, each one's top-level tables and its [for.<target>] tables alike, and the first that declares the step answers, its record naming it. A declaration that cannot be read declares nothing here: the mount and layering.graph name it.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def installed_record(name: str) -> StepRecord | None:
    """The step *name* as an installed extension declares it; None when none does.

    *name* is ``<phase>.<step>``. The installed extensions are read in
    name order, each one's top-level tables and its ``[for.<target>]``
    tables alike, and the first that declares the step answers, its
    record naming it. A declaration that cannot be read declares
    nothing here: the mount and ``layering.graph`` name it.
    """
    for extension in installed_extensions():
        try:
            found = _readable(extension)
        except DeclarationError:
            continue
        if found is None:
            continue
        for record in _declared_steps(found):
            if record.name == name:
                return replace(record, extension=extension)
    return None

why_inert

why_inert(extension: str) -> str

What extension does instead of composing a package; empty when it composes.

The proof is composes_per_package's. For an extension that composes nothing, the words say what its own steps judge: every package that holds one of the extensions they name, the workspace as a whole when they name none, or that it declares no step. A refusal of the extension in a package's list, or in a template's, reads them after composes nothing in a package:.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def why_inert(extension: str) -> str:
    """What *extension* does instead of composing a package; empty when it composes.

    The proof is `composes_per_package`'s. For an extension that
    composes nothing, the words say what its own steps
    judge: every package that holds one of the extensions they name,
    the workspace as a whole when they name none, or that it declares
    no step. A refusal of the extension in a package's list, or in a
    template's, reads them after ``composes nothing in a package:``.
    """
    if composes_per_package(extension):
        return ""
    found = installed_declaration(extension)
    steps = _declared_steps(found) if found is not None else []
    named: dict[str, None] = {}
    for record in steps:
        named.update(dict.fromkeys(record.extensions))
    if named:
        return f"its steps judge every package that holds {_either(list(named))}"
    if steps:
        return "its steps judge the workspace as a whole"
    return "it declares no step"

root_set

root_set(start: Path | None = None) -> tuple[str, ...]

The root's set: [workspace] extensions and what it requires.

In composition order, whatever the list's order and whether an implied extension is written in it. A name no installed distribution declares stays in the set and requires nothing. A declared order with no start falls back to alphabetical, and layering.graph names the cycle. Empty outside a workspace.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def root_set(start: Path | None = None) -> tuple[str, ...]:
    """The root's set: ``[workspace] extensions`` and what it requires.

    In composition order, whatever the list's order and whether an
    implied extension is written in it. A name no installed
    distribution declares stays in the set and requires nothing. A
    declared order with no start falls back to alphabetical, and
    ``layering.graph`` names the cycle. Empty outside a workspace.
    """
    names = closure(workspace_names(start), installed_declaration)
    return order_or_sorted(names, installed_declaration)

installed_set

installed_set(start: Path | None = None) -> tuple[str, ...]

The extensions the workspace installs and mounts, in composition order.

The root's set and every package's set, each a list and every extension it requires, whatever that extension declares, in composition order (livery.workshop._composition.order): each extension after the ones it requires, ties alphabetical. Neither list's order changes it. A name no installed distribution declares stays in the set: the mount names it, and fm sync installs it. A declared order with no start falls back to alphabetical here, so a sync still runs, and layering.graph names the cycle. Empty outside a workspace.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def installed_set(start: Path | None = None) -> tuple[str, ...]:
    """The extensions the workspace installs and mounts, in composition order.

    The root's set and every package's set, each a list and every
    extension it requires, whatever that extension declares, in
    composition order ([livery.workshop._composition.order][]): each
    extension after the ones it requires, ties alphabetical. Neither
    list's order changes it. A name no installed distribution declares
    stays in the set: the mount names it, and ``fm sync`` installs it.
    A declared order with no start falls back to alphabetical here, so
    a sync still runs, and ``layering.graph`` names the cycle. Empty
    outside a workspace.
    """
    root = workspace_root(start)
    if root is None:
        return ()
    listed = list(workspace_names(root))
    for _contract, names in _package_lists(root):
        listed += [listing(name).name for name in names]
    found = closure(listed, installed_declaration)
    return order_or_sorted(found, installed_declaration)

where_listed

where_listed(start: Path | None = None) -> dict[str, str]

Each extension of the installed set to the list that brings it, as notes say it.

listed in [workspace] extensions, listed in the `extensions` of packages/<name> naming each package that lists it, or, for an extension no list names, required by <name> naming the first listed extension whose set holds it. Empty outside a workspace.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def where_listed(start: Path | None = None) -> dict[str, str]:
    """Each extension of the installed set to the list that brings it, as notes say it.

    ``listed in [workspace] extensions``, ``listed in the `extensions`
    of packages/<name>`` naming each package that lists it, or, for an
    extension no list names, ``required by <name>`` naming the first
    listed extension whose set holds it. Empty outside a workspace.
    """
    root = workspace_root(start)
    if root is None:
        return {}
    listed = list(workspace_names(root))
    found = dict.fromkeys(listed, "listed in [workspace] extensions")
    packages: dict[str, dict[str, None]] = {}
    for contract, names in _package_lists(root):
        where = contract.parent.relative_to(root).as_posix()
        for entry in names:
            name = listing(entry).name
            packages.setdefault(name, {})[where] = None
            listed.append(name)
    for name, places in packages.items():
        spoken = _spoken(list(places))
        found.setdefault(name, f"listed in the `extensions` of {spoken}")
    for name in listed:
        for needed in closure((name,), installed_declaration):
            found.setdefault(needed, f"required by {name}")
    return found

extension_entries

extension_entries(start: Path | None = None) -> tuple[tuple[str, str], ...]

Every extension of the installed set as (name, distribution), in mount order.

The set livery.workshop._extensions.installed_set composes, each with the distribution that ships it (livery.workshop._extensions.distribution_of). Empty outside a workspace.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def extension_entries(start: Path | None = None) -> tuple[tuple[str, str], ...]:
    """Every extension of the installed set as ``(name, distribution)``, in mount order.

    The set [livery.workshop._extensions.installed_set][] composes, each
    with the distribution that ships it
    ([livery.workshop._extensions.distribution_of][]). Empty outside a
    workspace.
    """
    return tuple((name, distribution_of(name)) for name in installed_set(start))

stack_entries

stack_entries(start: Path | None = None) -> tuple[tuple[str, str], ...]

The base, then every listed extension in mount order, as name and distribution.

What a reader of the whole stack walks: the base ships the template tree the extensions overlay, and composition follows the mount's order. Empty outside a workspace.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def stack_entries(start: Path | None = None) -> tuple[tuple[str, str], ...]:
    """The base, then every listed extension in mount order, as name and distribution.

    What a reader of the whole stack walks: the base ships the template
    tree the extensions overlay, and composition follows the mount's
    order. Empty outside a workspace.
    """
    root = workspace_root(start)
    if root is None or not (root / "workshop.toml").is_file():
        return ()
    return ((SELF, SELF.replace(".", "-")), *extension_entries(start))

stack_names

stack_names(start: Path | None = None) -> tuple[str, ...]

The base, then every listed extension: whose content a sync delivers.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def stack_names(start: Path | None = None) -> tuple[str, ...]:
    """The base, then every listed extension: whose content a sync delivers."""
    return tuple(name for name, _ in stack_entries(start))

extension_package

extension_package(extension: str) -> str

The dotted package extension ships from: the one its entry point names.

The base is its own; an extension no installed distribution declares is taken at its name, which a member mid-birth may be.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def extension_package(extension: str) -> str:
    """The dotted package *extension* ships from: the one its entry point names.

    The base is its own; an extension no installed distribution
    declares is taken at its name, which a member mid-birth may be.
    """
    if extension == SELF:
        return SELF
    entry = _declared().get(extension)
    if entry is None:
        return extension
    return entry.value.partition(":")[0]

extension_provider

extension_provider(extension: str, packages: tuple[Package, ...]) -> str

The member package whose sources ship extension, by its path; empty if none.

extension is the name it is listed by, which is no module: the package its entry point names is looked up instead. An extension installed from an index has no member.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def extension_provider(extension: str, packages: tuple[Package, ...]) -> str:
    """The member package whose sources ship *extension*, by its path; empty if none.

    *extension* is the name it is listed by, which is no module: the
    package its entry point names is looked up instead. An extension
    installed from an index has no member.
    """
    from livery.workshop._influence import provider_of

    return provider_of(extension_package(extension), packages)

extension_names

extension_names(start: Path | None = None) -> tuple[str, ...]

The extensions the workspace installs and mounts, in mount order.

The root's set and every package's set, in composition order (livery.workshop._extensions.installed_set). workspace_names reads the workspace list alone, and root_set the root's set.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def extension_names(start: Path | None = None) -> tuple[str, ...]:
    """The extensions the workspace installs and mounts, in mount order.

    The root's set and every package's set, in composition order
    ([livery.workshop._extensions.installed_set][]).
    ``workspace_names`` reads the workspace list alone, and
    ``root_set`` the root's set.
    """
    return installed_set(start)

extension_content

extension_content(extension: str) -> Path | None

The installed extension's content/ directory, or None.

Beside the extension's declaration file, or the base's own for the base. In the monorepo the "wheel" is the editable source tree, which is what lets the materialised links point back into the repository. None for an extension that is not installed or ships no content.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def extension_content(extension: str) -> Path | None:
    """The installed extension's ``content/`` directory, or None.

    Beside the extension's declaration file, or the base's own for
    the base. In the monorepo the "wheel" is the editable source tree,
    which is what lets the materialised links point back into the
    repository. None for an extension that is not installed or ships
    no content.
    """
    if extension == SELF:
        content = base_directory() / "content"
        return content if content.is_dir() else None
    found = declaration(extension)
    if found is None:
        return None
    content = found.path.resolve().parent / "content"
    return content if content.is_dir() else None

base_directory

base_directory() -> Path

The directory this process imported the base from.

The base's own files, its content/ among them, are read from here.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def base_directory() -> Path:
    """The directory this process imported the base from.

    The base's own files, its ``content/`` among them, are read from
    here.
    """
    return Path(__file__).resolve().parent

shipped_content

shipped_content(start: Path | None = None) -> tuple[tuple[str, Path], ...]

Each extension of the workspace's stack with its content/ directory.

The base first, then the installed set in mount order, each with the directory its shipped files live in; an extension that ships no content, or that no installed distribution declares, is left out.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def shipped_content(start: Path | None = None) -> tuple[tuple[str, Path], ...]:
    """Each extension of the workspace's stack with its ``content/`` directory.

    The base first, then the installed set in mount order, each with
    the directory its shipped files live in; an extension that ships no
    content, or that no installed distribution declares, is left out.
    """
    found: list[tuple[str, Path]] = []
    for extension in stack_names(start):
        content = extension_content(extension)
        if content is not None:
            found.append((extension, content))
    return tuple(found)

left_out

left_out(start: Path | None = None) -> dict[str, tuple[str, ...]]

Each root entry's without: the targets its extension contributes nothing to.

Cooperation is greedy: an extension contributes to every target of the installed set it declares a [for.<target>] table for, a target listed later included. A table entry's without = [...] is the workspace's opt-out, naming the targets that get nothing from it. An entry with no without leaves out nothing, and the fix of layering.graph writes a table entry that leaves out nothing as the name alone.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def left_out(start: Path | None = None) -> dict[str, tuple[str, ...]]:
    """Each root entry's ``without``: the targets its extension contributes nothing to.

    Cooperation is greedy: an extension contributes to every target of
    the installed set it declares a ``[for.<target>]`` table for, a
    target listed later included. A table entry's ``without = [...]``
    is the workspace's opt-out, naming the targets that get nothing
    from it. An entry with no ``without`` leaves out nothing, and the
    fix of ``layering.graph`` writes a table entry that leaves out
    nothing as the name alone.
    """
    found: dict[str, tuple[str, ...]] = {}
    for entry in _listed(start):
        name = listing(_spelling(entry)).name
        written = entry.get("without") if isinstance(entry, dict) else None
        found[name] = (
            tuple(str(target) for target in cast("list[object]", written))
            if isinstance(written, list)
            else ()
        )
    return found

snapshot

snapshot(*, initial: bool = False) -> tuple[bool, tuple[str, ...], tuple[str, ...]]

What the mount recorded, for livery.workshop._extensions.restore to put back.

Whether a mount ran, and the listed extensions it found undeclared and stale. With initial, the record a process starts with instead: no mount, and nothing found.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def snapshot(*, initial: bool = False) -> tuple[bool, tuple[str, ...], tuple[str, ...]]:
    """What the mount recorded, for [livery.workshop._extensions.restore][] to put back.

    Whether a mount ran, and the listed extensions it found undeclared
    and stale. With *initial*, the record a process starts with
    instead: no mount, and nothing found.
    """
    if initial:
        return False, (), ()
    return MOUNTED, UNDECLARED, STALE

restore

restore(state: tuple[bool, tuple[str, ...], tuple[str, ...]]) -> None

Put the mount's records back to state.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def restore(state: tuple[bool, tuple[str, ...], tuple[str, ...]]) -> None:
    """Put the mount's records back to *state*."""
    global MOUNTED, UNDECLARED, STALE
    MOUNTED, UNDECLARED, STALE = state

mount_git_plugin

mount_git_plugin() -> str

Mount the git plugin; the reason it could not, printed as a note, or empty.

The environment every git spawn runs with: one ssh connection per host, the tools' identity, an editor that never opens. The mount runs on every command, fm sync among them, which is what installs the entry point a checkout that just moved past the plugin's arrival lacks, so a refusal here would stop the command that repairs it.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def mount_git_plugin() -> str:
    """Mount the git plugin; the reason it could not, printed as a note, or empty.

    The environment every git spawn runs with: one ssh connection per
    host, the tools' identity, an editor that never opens. The mount
    runs on every command, ``fm sync`` among them, which is what
    installs the entry point a checkout that just moved past the
    plugin's arrival lacks, so a refusal here would stop the command
    that repairs it.
    """
    from livery.footman import plugin, prog

    try:
        plugin("livery.git")
    except ValueError as error:
        why = f"the git plugin is not mounted ({error}); `{prog()} sync` installs it"
        _note(why)
        return why
    return ""

mount_extensions

mount_extensions(start: Path | None = None) -> tuple[str, ...]

Mount the plugin of every extension of the installed set, in mount order.

Returns the names mounted. The installed set mounts in composition order (livery.workshop._extensions.installed_set), so an extension finds every extension it requires already registered, whatever either list's order. Any extension mounts from either list. Refuses an extension declared for another workshop API version, one whose declaration file says something this workshop cannot take, a step into a phase of an extension it does not require (check_phase_declarers), and a step that replaces or deletes a step of an extension it does not require (check_replacements). A contract without [workspace] extensions, an extension no installed distribution declares, and one whose installed package ships no declaration file are named on stderr, the first of these with the list that brings it, and skipped, never refused: the mount runs on every command, fm sync among them, which is what installs a missing declaration, so a refusal here would stop the command that repairs it. An entry with brackets is named the same way and read as its name alone. The gate's layering.graph and fm extensions refuse the same problems. An extension whose declaration names no plugin registers what it declares and mounts no verbs, and one that declares nothing but answers to queries, at its top level or in a [for.<target>] table, is mounted all the same, since the listed extensions' answers are read while they are listed. A plugin a branded App already mounts as a builtin is not mounted again, since claiming its tasks again puts the same task in one rung twice; what its declaration adds registers as any other extension's does. A dormant extension (livery.workshop._extensions.dormancy) registers no step and no job, at its top level or in its [for.<target>] tables, and its plugin mounts all the same, so its verbs stay.

Each template the base or a mounted extension's declaration declares becomes a verb, fm new.package.<template> (livery.workshop._templates.generate_template_verbs), read from the declarations this walk read already: a template the installed set's extensions declare is offered, and no other file is read.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def mount_extensions(start: Path | None = None) -> tuple[str, ...]:
    """Mount the plugin of every extension of the installed set, in mount order.

    Returns the names mounted. The installed set mounts in composition
    order ([livery.workshop._extensions.installed_set][]), so an
    extension finds every extension it requires already registered,
    whatever either list's order. Any extension mounts from either
    list. Refuses an extension declared for another workshop API
    version, one whose declaration file says something this workshop
    cannot take, a step into a phase of an extension it does not
    require (``check_phase_declarers``), and a step that replaces or
    deletes a step of an extension it does not require
    (``check_replacements``).
    A contract without ``[workspace] extensions``, an extension no
    installed distribution declares, and one whose installed package
    ships no declaration file are named on stderr, the first of these
    with the list that brings it, and skipped, never refused:
    the mount runs on every command, ``fm sync`` among them, which is
    what installs a missing declaration, so a refusal here would stop
    the command that repairs it. An entry with brackets is named the
    same way and read as its name alone. The gate's ``layering.graph`` and
    ``fm extensions`` refuse the same problems. An extension
    whose declaration names no ``plugin`` registers what it declares
    and mounts no verbs, and one that declares nothing but answers to
    queries, at its top level or in a ``[for.<target>]`` table, is
    mounted all the same, since the listed extensions' answers are read
    while they are listed. A plugin a branded App already mounts as a
    builtin is not mounted again, since claiming its tasks again puts
    the same task in one rung twice; what its declaration adds
    registers as any other extension's does. A dormant extension
    ([livery.workshop._extensions.dormancy][]) registers no step and no
    job, at its top level or in its ``[for.<target>]`` tables, and its
    plugin mounts all the same, so its verbs stay.

    Each template the base or a mounted extension's declaration declares
    becomes a verb, ``fm new.package.<template>``
    (`livery.workshop._templates.generate_template_verbs`), read from
    the declarations this walk read already: a template the installed
    set's extensions declare is offered, and no other file is read.
    """
    from livery.footman import builtins, plugin
    from livery.workshop._seeds import base_templates

    global MOUNTED, UNDECLARED, STALE
    MOUNTED = True
    undeclared: list[str] = []
    root = workspace_root(start)
    if root is not None and (why := missing_list(root)):
        _note(why)
    builtin = set(builtins())
    mounted = []
    stale: list[str] = []
    declared = declared_targets(start)
    active = resolved_targets(start)
    enabled = enabled_steps(start)
    contributes = _contributing(active)
    asleep = frozenset(_dormant(tuple(active), contributes))
    # The base is present before this walk; every extension joins once
    # its mount ran.
    present = [SELF]
    grafted: set[tuple[str, str]] = set()
    _graft_contributions(present, declared, active, grafted, enabled, asleep)
    named: dict[str, str] | None = None
    # The templates each declaration read below declares, the first
    # declarer of a name kept: a birth from a name two extensions
    # declare refuses naming both.
    templates = dict(base_templates())
    for extension, dist in extension_entries(start):
        if extension in builtin:
            # The App mounted it as its own builtin: its plugin is never
            # mounted here a second time, and what its declaration adds
            # registers all the same.
            found = _readable(extension)
            if found is not None:
                templates = {**found.templates, **templates}
                check_api_version(extension, found)
                check_phase_declarers(extension, found)
                check_replacements(extension, found)
                if (
                    extension not in asleep
                    and register_declared(extension, found.additions, enabled=enabled)
                ) or _answers_queries(found):
                    mounted.append(extension)
            present.append(extension)
            _graft_contributions(present, declared, active, grafted, enabled, asleep)
            continue
        package = extension_package(extension)
        if extension in _declared() and declaration_file(package) is None:
            # An environment from before this checkout's, or a release
            # written for another workshop: named and skipped, so the
            # sync that installs this checkout's can run.
            undeclared.append(extension)
            stale.append(extension)
            _note(
                f"extension {extension!r}: the installed distribution ({dist})"
                f" names {package}, which ships no {FILE}; `{prog()} sync`"
                " installs the one this workspace builds"
            )
            continue
        found = declaration(extension)
        if found is None:
            undeclared.append(extension)
            if named is None:
                named = where_listed(start)
            _note(
                f"extension {extension!r} is"
                f" {named.get(extension, 'listed')}, and no installed"
                f" distribution declares it in {GROUP}; install the distribution"
                f" that ships it ({dist} by its name), or remove the entry;"
                f" `{prog()} sync` installs it the way this workspace resolves it"
            )
            continue
        templates = {**found.templates, **templates}
        check_api_version(extension, found)
        check_phase_declarers(extension, found)
        check_replacements(extension, found)
        if (
            extension not in asleep
            and register_declared(extension, found.additions, enabled=enabled)
        ) or _answers_queries(found):
            mounted.append(extension)
        name = found.plugin
        if name and name not in builtin:
            try:
                plugin(name)
            except Exception as error:
                _note(
                    f"extension {extension!r} did not mount its plugin {name!r}:"
                    f" {error}; its distribution ({dist}) belongs in the dev"
                    f" group, and `{prog()} sync` installs it"
                )
            else:
                if extension not in mounted:
                    mounted.append(extension)
        present.append(extension)
        _graft_contributions(present, declared, active, grafted, enabled, asleep)
    # An extension's steps registered as it mounted; their verbs join the
    # ones the workshop generated as it loaded.
    from livery.workshop._steps import generate_verbs
    from livery.workshop._templates import generate_template_verbs

    generate_verbs()
    generate_template_verbs(dict(sorted(templates.items())))
    UNDECLARED = tuple(undeclared)
    STALE = tuple(stale)
    return tuple(mounted)

stale_declarations

stale_declarations(start: Path | None = None) -> tuple[str, ...]

The listed extensions the mount found installed from before this checkout.

Each has an entry point whose package ships no declaration file, so the environment's metadata is older than the source: uv sync brings it current.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def stale_declarations(start: Path | None = None) -> tuple[str, ...]:
    """The listed extensions the mount found installed from before this checkout.

    Each has an entry point whose package ships no declaration file, so
    the environment's metadata is older than the source: ``uv sync``
    brings it current.
    """
    listed = extension_names(start)
    return tuple(name for name in STALE if name in listed)

unmounted

unmounted(start: Path | None = None) -> tuple[str, ...]

The listed extensions the mount found no installed distribution declaring.

An extension the contract no longer lists is not counted.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def unmounted(start: Path | None = None) -> tuple[str, ...]:
    """The listed extensions the mount found no installed distribution declaring.

    An extension the contract no longer lists is not counted.
    """
    listed = extension_names(start)
    return tuple(name for name in UNDECLARED if name in listed)

declared_now

declared_now(names: tuple[str, ...]) -> tuple[str, ...]

Of names, the extensions an installed distribution declares now.

Reads the installed entry points again, since the process scanned them once at its start, and imports nothing: a distribution installed after the interpreter started may not be importable in it, as an editable install's path joins sys.path only when a process starts.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def declared_now(names: tuple[str, ...]) -> tuple[str, ...]:
    """Of *names*, the extensions an installed distribution declares now.

    Reads the installed entry points again, since the process scanned
    them once at its start, and imports nothing: a distribution
    installed after the interpreter started may not be importable in
    it, as an editable install's path joins `sys.path` only when a
    process starts.
    """
    if not names:
        return ()
    from livery.footman import rescan_entry_points

    rescan_entry_points()
    declared = _declared()
    return tuple(name for name in names if name in declared)

install_places

install_places(names: Iterable[str]) -> dict[str, tuple[str, str, str]]

Where each of names, the base or an extension, is installed, as read here.

Each place is three parts: the package the extension's entry point names, the declaration file this process reads for it, and the origin the installer recorded in the distribution's direct_url.json, which is empty for a distribution from an index. The file is empty when the directory this process found the package in no longer holds one, and every part is empty for an extension no installed distribution declares. The base, named by SELF, has the same three parts: its package, the directory this process imported it from (empty once that directory holds no __init__.py), and the origin of BASE_DISTRIBUTION; every part is empty when no distribution of that name is installed.

Read before an install and again after it, a place that differs names an extension this process cannot read where the environment installs it now. The directory a package was found in is kept for the process, and an editable install's path joins sys.path only when a process starts. The origin tells an editable install's tree that is still on disk from the tree the environment installs. Imports nothing.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def install_places(names: Iterable[str]) -> dict[str, tuple[str, str, str]]:
    """Where each of *names*, the base or an extension, is installed, as read here.

    Each place is three parts: the package the extension's entry point
    names, the declaration file this process reads for it, and the
    origin the installer recorded in the distribution's
    ``direct_url.json``, which is empty for a distribution from an
    index. The file is empty when the directory this process found the
    package in no longer holds one, and every part is empty for an
    extension no installed distribution declares. The base, named by
    ``SELF``, has the same three parts: its package, the directory this
    process imported it from (empty once that directory holds no
    ``__init__.py``), and the origin of ``BASE_DISTRIBUTION``; every
    part is empty when no distribution of that name is installed.

    Read before an install and again after it, a place that differs
    names an extension this process cannot read where the environment
    installs it now. The directory a package was found in is kept for
    the process, and an editable install's path joins ``sys.path`` only
    when a process starts. The origin tells an editable install's tree
    that is still on disk from the tree the environment installs.
    Imports nothing.
    """
    declared = _declared()
    places: dict[str, tuple[str, str, str]] = {}
    for name in names:
        if name == SELF:
            places[name] = _base_place()
            continue
        entry = declared.get(name)
        if entry is None:
            places[name] = ("", "", "")
            continue
        package = entry.value.partition(":")[0]
        found = declaration_file(package)
        dist = entry.dist
        origin = dist.read_text("direct_url.json") if dist is not None else None
        places[name] = (package, str(found or ""), origin or "")
    return places

check_phase_declarers

check_phase_declarers(extension: str, found: Declaration) -> None

Refuse a step of extension into a phase of an extension it does not require.

A phase is declared by the base or by an extension. A step of extension's top-level tables goes into a phase the base, extension itself or an extension it requires declares; a step of a [for.<target>] table also into one target declares. Judged from the declarations alone, every [for] table whether it applies or not, so the verdict follows no list and no list's order.

Raises:

Type Description
Failed

naming the extension, the phase and its declarer, with the two ways to write the step.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def check_phase_declarers(extension: str, found: Declaration) -> None:
    """Refuse a step of *extension* into a phase of an extension it does not require.

    A phase is declared by the base or by an extension. A step of
    *extension*'s top-level tables goes into a phase the base,
    *extension* itself or an extension it requires declares; a step of
    a ``[for.<target>]`` table also into one *target* declares. Judged
    from the declarations alone, every ``[for]`` table whether it
    applies or not, so the verdict follows no list and no list's order.

    Raises:
        Failed: naming the extension, the phase and its declarer, with
            the two ways to write the step.
    """
    from livery.footman import fail
    from livery.workshop import _phases

    reached = _reached(extension, found)
    added = {
        (phase, reached)
        for phase in (
            *(record.phase for record in found.additions.steps),
            *found.phases,
        )
    }
    for target, additions in found.targets.items():
        added |= {(record.phase, reached | {target}) for record in additions.steps}
    specs = _phases.declared_phases()
    for phase, allowed in sorted(added, key=lambda pair: (pair[0], sorted(pair[1]))):
        declarer = specs[phase].extension if phase in specs else SELF
        if declarer not in allowed:
            fail(
                f"extension {extension!r} adds steps to the {phase} phase, which"
                f" {declarer} declares, and does not require {declarer}; add"
                f" {declarer} to its [extension] requires, or move the steps into"
                f" [for.{declarer}]"
            )

check_replacements

check_replacements(extension: str, found: Declaration) -> None

Refuse a step of extension that replaces or deletes one it cannot reach.

A step names each step it replaces or deletes as <owner>:<phase>.<step>. In extension's top-level tables the owner is the base or an extension extension requires, so the owner's step registers first in every set that holds both; in a [for.<target>] table it may also be target. Judged from the declarations alone, whatever the lists hold or their order.

Raises:

Type Description
Failed

naming the step, the one it replaces or deletes, and the two ways to write it.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def check_replacements(extension: str, found: Declaration) -> None:
    """Refuse a step of *extension* that replaces or deletes one it cannot reach.

    A step names each step it replaces or deletes as
    ``<owner>:<phase>.<step>``. In *extension*'s top-level tables the
    owner is the base or an extension *extension* requires, so the
    owner's step registers first in every set that holds both; in a
    ``[for.<target>]`` table it may also be *target*. Judged from the
    declarations alone, whatever the lists hold or their order.

    Raises:
        Failed: naming the step, the one it replaces or deletes, and the
            two ways to write it.
    """
    from livery.footman import fail

    reached = _reached(extension, found)
    tables: list[tuple[frozenset[str], list[StepRecord]]] = [
        (
            reached,
            [
                *found.additions.steps,
                *(record for held in found.phases.values() for record in held),
            ],
        )
    ]
    tables += [
        (reached | {target}, list(additions.steps))
        for target, additions in found.targets.items()
    ]
    for allowed, records in tables:
        for record in records:
            for verb, named in (
                ("replaces", record.replaces),
                ("deletes", record.deletes),
            ):
                for address, _reason in named:
                    owner = address.partition(":")[0]
                    if owner not in allowed:
                        fail(
                            f"extension {extension!r}: {record.name} {verb}"
                            f" {address}, and {extension} does not require {owner};"
                            f" add {owner} to its [extension] requires, or move the"
                            f" step into [for.{owner}]"
                        )

register_declared

register_declared(extension: str, additions: Additions, *, enabled: frozenset[str] = frozenset()) -> bool

Register what additions declares for extension; whether it declares a step.

Each step registers under the extension's listed name, since the list is what decides which extension a step belongs to, and each job joins its point under the same name. A step declared enabled = false registers only when enabled, the steps the root contract turns on (livery.workshop._extensions.enabled_steps), names it.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def register_declared(
    extension: str, additions: Additions, *, enabled: frozenset[str] = frozenset()
) -> bool:
    """Register what *additions* declares for *extension*; whether it declares a step.

    Each step registers under the extension's listed name, since the
    list is what decides which extension a step belongs to, and each
    job joins its point under the same name. A step declared
    ``enabled = false`` registers only when
    *enabled*, the steps the root contract turns on
    ([livery.workshop._extensions.enabled_steps][]), names it.
    """
    from dataclasses import replace

    from livery.workshop._steps import register_step

    for record in additions.steps:
        if not record.enabled and record.name not in enabled:
            continue
        register_step(replace(record, extension=extension))
    register_jobs(extension, additions.jobs)
    return bool(additions.steps)

register_jobs

register_jobs(extension: str, jobs: tuple[JobContribution, ...]) -> None

Add each of jobs to its builtin point, its entries' source extension.

Raises:

Type Description
Failed

when another extension contributed a job of the same name to the same point.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def register_jobs(extension: str, jobs: tuple[JobContribution, ...]) -> None:
    """Add each of *jobs* to its builtin point, its entries' source *extension*.

    Raises:
        Failed: when another extension contributed a job of the same name
            to the same point.
    """
    from dataclasses import replace

    from livery.workshop._points import contribute_job

    for item in jobs:
        contribute_job(
            item.point,
            item.job,
            entries=tuple(replace(entry, source=extension) for entry in item.entries),
            gates=item.gates,
            extension=extension,
        )

check_api_version

check_api_version(extension: str, found: Declaration) -> None

Refuse an extension whose declared API version is not this workshop's.

An extension declares [extension] api-version in its declaration file; one that declares none is taken at the current version.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def check_api_version(extension: str, found: Declaration) -> None:
    """Refuse an extension whose declared API version is not this workshop's.

    An extension declares ``[extension] api-version`` in its declaration
    file; one that declares none is taken at the current version.
    """
    declared = found.api_version
    if declared != API_VERSION:
        raise RuntimeError(
            f"extension {extension!r} declares workshop API version {declared!r}; this"
            f" workshop is version {API_VERSION}. Install a release of the"
            " extension written for this workshop, or of the workshop the extension"
            " was written for."
        )

extension_dependencies

extension_dependencies(start: Path | None = None) -> dict[str, tuple[str, ...]]

Each listed extension's [extension] requires, name to names.

The base declares none here, and an extension no installed distribution declares has none to read: the mount teaches the install.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def extension_dependencies(start: Path | None = None) -> dict[str, tuple[str, ...]]:
    """Each listed extension's ``[extension] requires``, name to names.

    The base declares none here, and an extension no installed
    distribution declares has none to read: the mount teaches the
    install.
    """
    found: dict[str, tuple[str, ...]] = {}
    for extension in extension_names(start):
        declared = _readable(extension)
        found[extension] = declared.requires if declared is not None else ()
    return found

extension_tools

extension_tools(start: Path | None = None) -> dict[str, tuple[str, ...]]

Each listed extension's [toolroom] requires, name to requirement strings.

The tools the extension runs, such as cmake's cmake and ninja or a verb's docker>=27, then the tools each of its [for.<target>] tables requires while the table applies, as livery.workshop.contributions_for decides it: a measurer's tool is required while the workspace lists what it measures for, and never otherwise. An extension no installed distribution declares declares none here, and the base declares its own in its contract file, which the tool requirements read at a site of its own.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def extension_tools(start: Path | None = None) -> dict[str, tuple[str, ...]]:
    """Each listed extension's ``[toolroom] requires``, name to requirement strings.

    The tools the extension runs, such as cmake's ``cmake`` and
    ``ninja`` or a verb's ``docker>=27``, then the tools each of its
    ``[for.<target>]`` tables requires while the table applies, as
    [livery.workshop.contributions_for][] decides it: a measurer's tool
    is required while the workspace lists what it measures for, and
    never otherwise. An extension no installed distribution declares
    declares none here, and the base declares its own in its contract
    file, which the tool requirements read at a site of its own.
    """
    active = resolved_targets(start)
    applies = _contributing(active)
    found: dict[str, tuple[str, ...]] = {}
    for extension in active:
        declared = _readable(extension)
        if declared is None:
            found[extension] = ()
            continue
        found[extension] = (
            *declared.tools,
            *(
                text
                for target in applies.get(extension, ())
                for text in declared.target_tools.get(target, ())
            ),
        )
    return found

notes_tools

notes_tools(start: Path | None = None) -> dict[str, tuple[str, ...]]

Each listed extension that writes release notes, to its [toolroom] requires.

A release's entries must not depend on the machine that wrote them, so no host allowance reaches these tools (livery.workshop._tools.host_allowed).

Source code in packages/workshop/src/livery/workshop/_extensions.py
def notes_tools(start: Path | None = None) -> dict[str, tuple[str, ...]]:
    """Each listed extension that writes release notes, to its ``[toolroom] requires``.

    A release's entries must not depend on the machine that wrote
    them, so no host allowance reaches these tools
    ([livery.workshop._tools.host_allowed][]).
    """
    from livery.workshop._release_notes import RELEASE_NOTES

    found: dict[str, tuple[str, ...]] = {}
    for extension in extension_names(start):
        declared = _readable(extension)
        if declared is not None and RELEASE_NOTES.name in declared.queries:
            found[extension] = declared.tools
    return found

declared_targets

declared_targets(start: Path | None = None) -> dict[str, dict[str, Additions]]

Each listed extension's [for.<target>] tables, owner to target to tables.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def declared_targets(start: Path | None = None) -> dict[str, dict[str, Additions]]:
    """Each listed extension's ``[for.<target>]`` tables, owner to target to tables."""
    found: dict[str, dict[str, Additions]] = {}
    for extension in extension_names(start):
        declared = _readable(extension)
        found[extension] = dict(declared.targets) if declared is not None else {}
    return found

resolved_targets

resolved_targets(start: Path | None = None) -> dict[str, tuple[str, ...]]

Each extension of the installed set to its active targets, in composition order.

Every target of the installed set the extension declares a [for.<target>] table for, except those its root entry's without names: cooperation is greedy, and an opt-out names what is off (left_out).

Source code in packages/workshop/src/livery/workshop/_extensions.py
def resolved_targets(start: Path | None = None) -> dict[str, tuple[str, ...]]:
    """Each extension of the installed set to its active targets, in composition order.

    Every target of the installed set the extension declares a
    ``[for.<target>]`` table for, except those its root entry's
    ``without`` names: cooperation is greedy, and an opt-out names what
    is off (``left_out``).
    """
    names = extension_names(start)
    declared = declared_targets(start)
    off = left_out(start)
    return {
        owner: tuple(
            name
            for name in names
            if name in declared.get(owner, {}) and name not in off.get(owner, ())
        )
        for owner in names
    }

contributions_for

contributions_for(target: str, start: Path | None = None) -> dict[str, dict[str, Any]]

What the installed extensions declare for target, by extension.

The extensions come in composition order. An extension contributes its [for.<target>] table while target is listed and the extension's listing contributes to it (every listed target it declares a table for, except those its root entry's without names), the rule the mount grafts by; an extension that requires target contributes its top-level tables. The tables come as the declaration file holds them, and an extension that declares nothing for target is left out, as is every extension when target is not listed. start is a directory in the workspace, the working directory when absent.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def contributions_for(
    target: str, start: Path | None = None
) -> dict[str, dict[str, Any]]:
    """What the installed extensions declare for *target*, by extension.

    The extensions come in composition order. An extension contributes
    its ``[for.<target>]`` table while *target* is listed and the
    extension's listing contributes to it (every listed target it
    declares a table for, except those its root entry's ``without``
    names), the rule the mount grafts by; an extension that requires
    *target* contributes its top-level tables. The tables come as the
    declaration file holds them, and an extension that declares nothing
    for *target* is left out, as is every extension when *target* is
    not listed. *start* is a directory in the workspace, the working
    directory when absent.
    """
    names = extension_names(start)
    if target not in names:
        return {}
    contributes = contributing(start)
    found: dict[str, dict[str, Any]] = {}
    for owner in names:
        declared = _readable(owner)
        if declared is None or owner == target:
            continue
        if target in declared.requires:
            found[owner] = dict(declared.tables)
        elif target in contributes.get(owner, ()):
            found[owner] = dict(declared.target_tables[target])
    return found

contributing

contributing(start: Path | None = None) -> dict[str, tuple[str, ...]]

Each listed extension to the listed targets its [for] tables apply to now.

A target is listed, the owner declares a [for.<target>] table for it, and the owner's root entry does not name it in without. An extension that contributes to nothing is left out. The rule the mount grafts by, which livery.workshop.contributions_for, the delivery of a table's files and dormancy read through.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def contributing(start: Path | None = None) -> dict[str, tuple[str, ...]]:
    """Each listed extension to the listed targets its ``[for]`` tables apply to now.

    A target is listed, the owner declares a ``[for.<target>]`` table for
    it, and the owner's root entry does not name it in ``without``. An
    extension that contributes to nothing is left out. The rule the
    mount grafts by, which [livery.workshop.contributions_for][], the
    delivery of a table's files and dormancy read through.
    """
    return _contributing(resolved_targets(start))

dormancy

dormancy(start: Path | None = None) -> dict[str, str]

Each listed extension that is dormant now, to what it waits for.

An extension whose [extension] dormant-until names what another does for it, measures for coverage, is dormant while no listed extension contributes a [for.<it>] table to it (livery.workshop._extensions.contributing): it registers no step and no job, and its plugin still mounts. The text says what it waits for and names the installed extensions whose declarations carry such a table, which would wake it: nothing listed measures; cmake and pytest would. A listing kept for a contributor still to come is a statement of intent, so dormancy is named, never refused.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def dormancy(start: Path | None = None) -> dict[str, str]:
    """Each listed extension that is dormant now, to what it waits for.

    An extension whose ``[extension] dormant-until`` names what another
    does for it, ``measures`` for coverage, is dormant while no listed
    extension contributes a ``[for.<it>]`` table to it
    ([livery.workshop._extensions.contributing][]): it registers no step
    and no job, and its plugin still mounts. The text says what it waits
    for and names the installed extensions whose declarations carry such
    a table, which would wake it: ``nothing listed measures; cmake and
    pytest would``. A listing kept for a contributor still to come is a
    statement of intent, so dormancy is named, never refused.
    """
    active = resolved_targets(start)
    return _dormant(tuple(active), _contributing(active))

describe_extensions

describe_extensions(start: Path | None = None) -> list[str]

The lines fm extensions prints: each extension with what it declares.

The base, then each extension of the installed set in mount order; under each, who requires it, the packages whose sets hold it, its tools, the targets it contributes to, the targets its root entry leaves out, whether it is dormant and what would wake it, and the steps it declares off, each with whether it is on.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def describe_extensions(start: Path | None = None) -> list[str]:
    """The lines ``fm extensions`` prints: each extension with what it declares.

    The base, then each extension of the installed set in mount order;
    under each, who requires it, the packages whose sets hold it, its
    tools, the targets it contributes to, the targets its root entry
    leaves out, whether it is dormant and what would wake it, and the
    steps it declares off, each with whether it is on.
    """
    names = extension_names(start)
    who = requirers(start)
    tools = extension_tools(start)
    targets = resolved_targets(start)
    off = left_out(start)
    enabled = enabled_steps(start)
    holders = _holders(start)
    asleep = dormancy(start)
    lines: list[str] = [f"  {SELF} (the base)"]
    for name in names:
        needed = who.get(name, ())
        by = f" (required by {', '.join(needed)})" if needed else ""
        lines.append(f"  {name}{by}")
        if holders.get(name):
            lines.append(f"    packages: {', '.join(holders[name])}")
        if tools.get(name):
            lines.append(f"    tools: {', '.join(tools[name])}")
        if targets.get(name):
            lines.append(f"    for: {', '.join(targets[name])}")
        if off.get(name):
            lines.append(f"    without: {', '.join(off[name])}")
        if name in asleep:
            lines.append(f"    dormant: {asleep[name]}")
        for step in _declared_off(name):
            state = "on" if step in enabled else "off"
            phase, _, name_in_phase = step.partition(".")
            lines.append(
                f"    step {step} ({state}): declared off; the root contract turns"
                f" it on with [phases.{phase}.{name_in_phase}] enabled = true"
            )
    return lines

enabled_problems

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

Each root [phases.<phase>.<step>] table turning on no step declared off.

The root contract turns on a step a listed extension declares enabled = false; a table naming any other step, one no listed extension declares or one that is on already, is refused naming the steps declared off.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def enabled_problems(root: Path) -> list[str]:
    """Each root ``[phases.<phase>.<step>]`` table turning on no step declared off.

    The root contract turns on a step a listed extension declares
    ``enabled = false``; a table naming any other step, one no listed
    extension declares or one that is on already, is refused naming
    the steps declared off.
    """
    off = {step: name for name in extension_names(root) for step in _declared_off(name)}
    problems: list[str] = []
    for step in sorted(enabled_steps(root)):
        if step in off:
            continue
        phase, _, name = step.partition(".")
        declared = ", ".join(f"{other} ({by})" for other, by in sorted(off.items()))
        problems.append(
            f"[phases.{phase}.{name}] turns on {step}, which no listed extension"
            " declares off; the steps declared off are"
            f" {declared or 'none'}"
        )
    return problems

closure_problems

closure_problems(start: Path | None = None) -> list[str]

Why the contracts' lists are not valid compositions in their canonical form.

Empty when every target a root entry's without names is in the installed set and its extension declares a contribution for it; when every listed extension is installed and every entry is a name alone (entry_problems); when every step the root contract turns on is one a listed extension declares off (enabled_problems); when the root's list is its canonical one (root_list_problems); and when every package's list is a valid composition in its canonical form, each of its entries composing something in a package (composition_problems). The gate's --fix writes each list in its canonical form and moves a package's entry that composes nothing to the root's list (write_extensions).

Source code in packages/workshop/src/livery/workshop/_extensions.py
def closure_problems(start: Path | None = None) -> list[str]:
    """Why the contracts' lists are not valid compositions in their canonical form.

    Empty when every target a root entry's ``without`` names is in the
    installed set and its extension declares a contribution for it;
    when every listed extension is installed and every entry is a name
    alone (``entry_problems``); when every step the root contract turns
    on is one a listed extension declares off (``enabled_problems``);
    when the root's list is its canonical one (``root_list_problems``);
    and when every package's list is a valid composition in its
    canonical form, each of its entries composing something in a
    package (``composition_problems``). The gate's ``--fix`` writes
    each list in its canonical form and moves a package's entry that
    composes nothing to the root's list (``write_extensions``).
    """
    root = workspace_root(start)
    installed = set(installed_set(start))
    problems: list[str] = []
    declared = declared_targets(start)
    for owner, targets in left_out(start).items():
        if installed_declaration(owner) is None:
            # entry_problems names an extension nothing installed declares.
            continue
        for target in targets:
            if target not in declared.get(owner, {}):
                problems.append(
                    f"[workspace] extensions: the entry for {owner} names {target}"
                    f" in `without`, and {owner} declares no contribution for it;"
                    " remove it from `without`"
                )
            elif target not in installed:
                problems.append(
                    f"[workspace] extensions: the entry for {owner} names {target}"
                    " in `without`, and the installed set does not hold it; list"
                    " it, or remove it from `without`"
                )
    if root is not None:
        if why := missing_list(root):
            problems.append(why)
        problems += entry_problems(root)
        problems += listing_problems(root)
        problems += enabled_problems(root)
        problems += root_list_problems(root)
        problems += composition_problems(root)
    return problems

root_list_problems

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

Why [workspace] extensions is not its canonical list; empty when it is.

The canonical list holds each extension once, in composition order. It leaves out an entry another listed extension requires unless the entry carries a without, and writes a table entry whose without is empty or absent as the name alone. No other order means anything, so the list is written in this one, which the gate's --fix writes. A list whose set's declared order has no start names the cycle. An entry that is not an installed extension's name is named by entry_problems and listing_problems, and the list is judged once they pass.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def root_list_problems(root: Path) -> list[str]:
    """Why ``[workspace] extensions`` is not its canonical list; empty when it is.

    The canonical list holds each extension once, in composition order.
    It leaves out an entry another listed extension requires unless the
    entry carries a ``without``, and writes a table entry whose
    ``without`` is empty or absent as the name alone. No other order
    means anything, so the list is written in this one, which the
    gate's ``--fix`` writes. A list whose set's declared order has no
    start names the cycle. An entry that is not an installed
    extension's name is named by ``entry_problems`` and
    ``listing_problems``, and the list is judged once they pass.
    """
    found = _root_list(root)
    if found is None:
        return []
    if isinstance(found, str):
        return [found]
    if not found.why:
        return []
    wanted = (entry for _index, entry in found.wanted)
    return [
        f"[workspace] extensions is {_spelled_entries(found.written)}, and its"
        f" canonical list is {_spelled_entries(wanted)}{found.why}; the gate's"
        " --fix rewrites it"
    ]

composition_problems

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

Why each package's list is not a valid composition in its canonical form.

Judged for each package whose entries are names installed distributions declare: every extension its set requires is installed, each lifecycle phase can run as the set's extensions declare it (livery.workshop._phases.phase_problems), each entry no other entry requires composes something in a package, itself or through what it requires (why_inert), the set's declared order has a start, and the list is the canonical one (livery.workshop._composition.canonical). The gate's --fix writes the canonical list and moves an entry that composes nothing to [workspace] extensions (write_extensions). A requirement joins the set whatever it declares, so no other list needs to name it. A cycle of requirements shows in every package whose set holds one of its members, since a set is closed under requires.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def composition_problems(root: Path) -> list[str]:
    """Why each package's list is not a valid composition in its canonical form.

    Judged for each package whose entries are names installed
    distributions declare: every extension its set requires is
    installed, each lifecycle phase can run as the set's extensions
    declare it ([livery.workshop._phases.phase_problems][]), each entry
    no other entry requires composes something in a package, itself or
    through what it requires (`why_inert`), the set's declared order
    has a start, and the list is the canonical one
    ([livery.workshop._composition.canonical][]). The gate's ``--fix``
    writes the canonical list and moves an entry that composes nothing
    to ``[workspace] extensions`` (`write_extensions`). A requirement
    joins the set whatever it declares, so no other list needs to name
    it. A cycle of requirements shows in every package whose set holds
    one of its members, since a set is closed under requires.
    """
    from livery.workshop._composition import canonical, implied
    from livery.workshop._phases import lifecycle_phases, phase_problems, phase_steps

    problems: list[str] = []
    inert: dict[str, str] = {}
    for contract, listed in _package_lists(root):
        if not _composable(listed):
            continue
        where = contract.parent.relative_to(root).as_posix()
        names = list(listed)
        members = closure(names, installed_declaration)
        for name in members:
            found = installed_declaration(name)
            for needed in found.requires if found is not None else ():
                if installed_declaration(needed) is None:
                    problems.append(
                        f"{where}: {name} requires {needed}, which no installed"
                        f" distribution declares in {GROUP}; install it"
                    )
        for phase in lifecycle_phases():
            steps = phase_steps(phase, members, installed_declaration)
            problems += [f"{where}: {line}" for line in phase_problems(phase, steps)]
        required = implied(members, installed_declaration)
        for name in dict.fromkeys(names):
            if name in required:
                continue
            if name not in inert:
                inert[name] = why_inert(name)
            if inert[name]:
                problems.append(
                    f"{where}: `extensions` lists {name}, which composes nothing in a"
                    f" package: {inert[name]}; list it in [workspace] extensions,"
                    " where the gate's --fix moves it"
                )
        try:
            wanted = canonical(names, installed_declaration)
        except OrderCycle as error:
            problems.append(f"{where}: {error}")
            continue
        if tuple(names) != wanted:
            problems.append(
                f"{where}: `extensions` is {_spelled(names)}, and its canonical list"
                f" is {_spelled(wanted)}{_why(names, wanted)}; the gate's --fix"
                " rewrites it"
            )
    return problems

listing_problems

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

Each [workspace] extensions entry spelled as more than a name.

An entry is a name. It takes no brackets, version, ? or scope: an extension's version comes from its wheel's metadata, and the lock pins it. An extension no installed distribution declares is livery.workshop._extensions.entry_problems's to name.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def listing_problems(root: Path) -> list[str]:
    """Each ``[workspace] extensions`` entry spelled as more than a name.

    An entry is a name. It takes no brackets, version, ``?`` or scope:
    an extension's version comes from its wheel's metadata, and the
    lock pins it. An extension no installed distribution declares is
    [livery.workshop._extensions.entry_problems][]'s to name.
    """
    from livery.toolroom.store import Spec, SpecError

    problems: list[str] = []
    for entry in _listed(root):
        spelled = _spelling(entry)
        try:
            spec = Spec.parse(spelled, where="[workspace] extensions")
        except SpecError:
            spec = None
        if spec is None or spec.options or spec.optional or spec.floor or spec.scope:
            problems.append(
                f"[workspace] extensions lists {spelled!r}; an entry is a name alone,"
                " with no brackets, version or scope: the lock pins an extension's"
                " version from its wheel"
            )
    return problems

entry_problems

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

Each listed name nothing installed declares, and each package entry with options.

Every extension is one kind, which either list names. A package's entry is the extension's name alone, with no options.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def entry_problems(root: Path) -> list[str]:
    """Each listed name nothing installed declares, and each package entry with options.

    Every extension is one kind, which either list names. A package's
    entry is the extension's name alone, with no options.
    """
    problems: list[str] = []
    for name in workspace_names(root):
        if declaration(name) is None:
            problems.append(
                f"[workspace] extensions lists {name}, which no installed"
                f" distribution declares in {GROUP}"
            )
    for contract, listed in _package_lists(root):
        where = contract.parent.relative_to(root).as_posix()
        for name in listed:
            if listing(name).name != name:
                problems.append(
                    f"{where}: `extensions` lists {name!r}; a package's entry is the"
                    " extension's name alone, and takes no options"
                )
                continue
            if declaration(name) is None:
                problems.append(
                    f"{where}: `extensions` lists {name}, which no installed"
                    f" distribution declares in {GROUP}"
                )
    return problems

requirers

requirers(start: Path | None = None) -> dict[str, tuple[str, ...]]

Each listed extension to the listed extensions that depend on it.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def requirers(start: Path | None = None) -> dict[str, tuple[str, ...]]:
    """Each listed extension to the listed extensions that depend on it."""
    found: dict[str, list[str]] = {name: [] for name in extension_names(start)}
    for extension, depends in extension_dependencies(start).items():
        for needed in depends:
            found.setdefault(needed, []).append(extension)
    return {name: tuple(who) for name, who in found.items()}

write_extensions

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

Write each package's list and the root's in its canonical form.

Returns the lines written, one per list changed.

Each package's list becomes its canonical one (livery.workshop._composition.canonical) without the entries that compose nothing in a package (why_inert), which move to the root's list, and the root's list then becomes its canonical one (root_list_problems). Each entry keeps the comment lines above it and the comment after it on its line. A moved entry takes them to the root's list when that list does not hold it yet, and an entry left out takes its comments with it. A list the judge refuses for another reason, one whose order has no start, and one whose array this does not read are left for a person, and the judge names each; no entry moves while the root's array is not read. Idempotent. A root without a contract lists no extensions, so nothing is written.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def write_extensions(root: Path) -> list[str]:
    """Write each package's list and the root's in its canonical form.

    Returns the lines written, one per list changed.

    Each package's list becomes its canonical one
    ([livery.workshop._composition.canonical][]) without the entries
    that compose nothing in a package (`why_inert`), which move to the
    root's list, and the root's list then becomes its canonical one
    (``root_list_problems``). Each entry keeps the comment lines above
    it and the comment after it on its line. A moved entry takes them
    to the root's list when that list does not hold it yet, and an
    entry left out takes its comments with it. A list the judge refuses
    for another reason, one whose order has no start, and one whose
    array this does not read are left for a person, and the judge names
    each; no entry moves while the root's array is not read.
    Idempotent. A root without a contract lists no extensions, so
    nothing is written.
    """
    from livery.workshop._composition import canonical

    contract = root / "workshop.toml"
    if not contract.is_file():
        return []
    movable = _read_array(contract.read_text(encoding="utf-8"), "workspace") is not None
    moved: dict[str, _Entry] = {}
    inert: dict[str, str] = {}
    written: list[str] = []
    for package_contract, listed in _package_lists(root):
        if not _composable(listed):
            continue
        where = package_contract.parent.relative_to(root).as_posix()
        try:
            wanted = canonical(listed, installed_declaration)
        except OrderCycle:
            continue
        leaving: list[str] = []
        for name in wanted if movable else ():
            if name not in inert:
                inert[name] = why_inert(name)
            if inert[name]:
                leaving.append(name)
        kept = tuple(name for name in wanted if name not in leaving)
        if kept == listed:
            continue
        package_text = package_contract.read_text(encoding="utf-8")
        array = _read_array(package_text, None)
        if array is None or not _reads_as(array, listed):
            continue
        # The canonical list holds each extension once, each one listed.
        entries = [array.entries[listed.index(name)] for name in kept]
        package_contract.write_text(
            package_text[: array.start]
            + _array_text(array, entries)
            + package_text[array.end :],
            encoding="utf-8",
        )
        for name in leaving:
            moved.setdefault(name, array.entries[listed.index(name)])
        if leaving:
            verb = "composes" if len(leaving) == 1 else "compose"
            written.append(
                f"  layering: {where} `extensions` is {_spelled(kept)}, and"
                f" [workspace] extensions lists {_spoken(leaving)}, which {verb}"
                " nothing in a package"
            )
        else:
            written.append(
                f"  layering: {where} `extensions` is {_spelled(kept)},"
                " its canonical list"
            )
    return _write_root(root, moved) + written

list_in_root

list_in_root(root: Path, names: Iterable[str]) -> list[str]

Add names to root's [workspace] extensions, as its canonical list.

Each name the list does not hold yet joins it as an entry of its own, and the list is then written in its canonical form, as the gate's --fix writes it (write_extensions): each entry keeps its comments, and an entry another listed extension requires leaves the list. A list naming an extension no installed distribution declares keeps the order it is given, and the gate names it. Returns what write_extensions returns: a line for each list it wrote.

Raises:

Type Description
Failed

when the contract has no [workspace] extensions array this reads.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def list_in_root(root: Path, names: Iterable[str]) -> list[str]:
    """Add *names* to *root*'s ``[workspace] extensions``, as its canonical list.

    Each name the list does not hold yet joins it as an entry of its
    own, and the list is then written in its canonical form, as the
    gate's ``--fix`` writes it (`write_extensions`): each entry keeps
    its comments, and an entry another listed extension requires
    leaves the list. A list naming an extension no installed
    distribution declares keeps the order it is given, and the gate
    names it. Returns what `write_extensions` returns: a line for each
    list it wrote.

    Raises:
        Failed: when the contract has no ``[workspace] extensions``
            array this reads.
    """
    from livery.footman import fail

    contract = root / "workshop.toml"
    text = contract.read_text(encoding="utf-8")
    array = _read_array(text, "workspace")
    if array is None:
        fail(f"{contract}: no [workspace] extensions array to add to")
    held = set(workspace_names(root))
    added = [_Entry(f'"{name}"') for name in dict.fromkeys(names) if name not in held]
    if added:
        contract.write_text(
            text[: array.start]
            + _array_text(array, [*array.entries, *added])
            + text[array.end :],
            encoding="utf-8",
        )
    return write_extensions(root)

available_extensions

available_extensions(listed: tuple[str, ...], advertised: list[tuple[str, str]] | None = None) -> list[tuple[str, str]]

Installed extensions the contract does not list, as (name, distribution).

advertised is every workshop.extensions entry point as (name, distribution); read from the installed metadata when None. A footman plugin that declares no extension is not one, and is never offered. Listing is the only activation channel, so these do nothing until the contract names them, and the doctor says so.

Source code in packages/workshop/src/livery/workshop/_extensions.py
def available_extensions(
    listed: tuple[str, ...], advertised: list[tuple[str, str]] | None = None
) -> list[tuple[str, str]]:
    """Installed extensions the contract does not list, as (name, distribution).

    *advertised* is every ``workshop.extensions`` entry point as
    (name, distribution); read from the installed metadata when None.
    A footman plugin that declares no extension is not one, and is
    never offered. Listing is the only activation channel, so these
    do nothing until the contract names them, and the doctor says so.
    """
    if advertised is None:
        advertised = [
            (name, entry.dist.name if entry.dist is not None else "")
            for name, entry in sorted(_declared().items())
        ]
    return [(name, dist) for name, dist in advertised if name not in listed]