Skip to content

livery.workshop._phases

livery.workshop._phases

The declared phases, the context a step receives, and the walk that runs steps.

A phase is declared, by the base in the [phases] section of its contract.toml and by an extension under [phases.<phase>] in its extension.toml, in one grammar (livery.workshop._phases.PhaseSpec): the keys the engine running it gives its steps, typed; its level, package for a phase whose steps run once per package and workspace for one whose steps run once; whether fm check runs it; the phases it follows in the train's order; and whether a verb is generated for it. livery.workshop._phases.declared_phases is every declared phase by name, the base's and then each installed extension's; a phase nobody declares refuses naming the declared ones, and two extensions declaring one phase refuse naming both.

Every phase's steps run through the one walk, livery.workshop._phases.walk_steps: each step a footman step inside one parallel() block, a workspace step once and a package step once per package in scope, independent steps concurrently, a step after the steps it names in after and after the providers of the keys it reads. The gate runs its phases through it with its own engine around it (livery.workshop._quality.walk); the release train and fm run run a package's lifecycle phases through it (livery.workshop._lifecycle), the steps those of the package's set (livery.workshop._phases.phase_steps); fm sync runs the sync phase's registered steps through it over the workspace, and livery.workshop.run_phase those of any phase the gate never runs, first removing what a step that stopped running declared it writes. Each step receives the one context, livery.workshop.PhaseContext.

A step table's deletes names steps of other extensions, each <owner>:<phase>.<step> with its reason, that never run for a package whose set holds the deleting extension: the set's steps leave them out, and the walk skips such a package for a registered step it deletes, saying why. A package whose set does not hold the deleting extension runs them.

The engine running a walk gives each phase its keys, by phase. The train builds on the isolated side in the release configuration and tests on the isolated side once per resolution it proves; the gate builds on the tree side in the instrumented configuration, and fm run on the tree side in debug. A phase whose declaration holds isolated has two sides: the tree, and the isolated one, from a copy of the sources in a fresh environment. A step that declares isolated serves the side it names alone, and one that declares nothing serves both (livery.workshop._phases.serves).

Two steps providing one key, a key nobody provides, a step declaring a side of a phase that has one side, and an order with no start refuse before any step runs (livery.workshop._phases.phase_problems); layering.graph names them for each package.

Classes:

Name Description
PhaseSpec

A phase as its declarer declares it: one [phases.<phase>] table.

PhaseError

A phase whose steps cannot run as declared, or a step's misuse of the context.

PhaseContext

What a run hands a step: the workspace, the run's scope, and the phase's keys.

Functions:

Name Description
base_phases

The base's phases, read from the [phases] section of its contract file.

declared_phases

Every declared phase by name: the base's, then each installed extension's.

phase_spec

The declared phase name; refuses naming the declared ones.

lifecycle_phases

The package-level phases, in declaration order: a package's lifecycle.

phase_steps

The steps the extensions members add to phase, in their order.

step_address

record's address among every extension's steps: <owner>:<phase>.<step>.

deletions

The steps the extensions members delete, by address, to the deleter and why.

set_deletions

The steps package's set deletes, by address, to the deleter and why.

serves

Whether record runs on the side of its phase the engine's given keys name.

phase_order

steps in the order the walk starts them.

phase_problems

Why steps cannot run as phase; empty when they can.

walk_steps

Run steps as footman steps inside one parallel() block.

run_registered

Run the steps registered for the phase ctx names, through the walk.

output_refusal

Why output cannot name what a step writes, or "" when it can.

run_phase

Run a phase the gate never runs over the workspace at root; the shared context.

Attributes:

Name Type Description
PACKAGE_LEVEL
WORKSPACE_LEVEL
LEVELS
TYPES
BASE
ISOLATED
OUTPUTS_RECORD
IN_EACH_PACKAGE

PACKAGE_LEVEL module-attribute

PACKAGE_LEVEL = 'package'

WORKSPACE_LEVEL module-attribute

WORKSPACE_LEVEL = 'workspace'

LEVELS module-attribute

TYPES module-attribute

TYPES = ('str', 'int', 'bool', 'path', 'strs', 'paths', 'table')

BASE module-attribute

BASE = 'livery.workshop'

ISOLATED module-attribute

ISOLATED = 'isolated'

OUTPUTS_RECORD module-attribute

OUTPUTS_RECORD = '.workshop/state/outputs.json'

IN_EACH_PACKAGE module-attribute

IN_EACH_PACKAGE = 'package/'

PhaseSpec dataclass

PhaseSpec(name: str, keys: Mapping[str, str] = dict[str, str](), level: str = PACKAGE_LEVEL, gated: bool = False, after: tuple[str, ...] = (), verb: bool = False, extension: str = BASE)

A phase as its declarer declares it: one [phases.<phase>] table.

Attributes:

Name Type Description
name str

The phase's name, build.

keys Mapping[str, str]

The keys the engine running the phase gives its steps, each to its type; a step reads one like any key, and no step provides one.

level str

package for a phase whose steps run once per package in scope; workspace for one whose steps run once over the workspace.

gated bool

Whether fm check runs the phase.

after tuple[str, ...]

The phases this one follows in the train's order.

verb bool

Whether a verb is generated for the phase, fm <phase> with a sub-task per step.

extension str

The extension that declares the phase; the base for its own.

name instance-attribute

name: str

keys class-attribute instance-attribute

keys: Mapping[str, str] = field(default_factory=dict[str, str])

level class-attribute instance-attribute

level: str = PACKAGE_LEVEL

gated class-attribute instance-attribute

gated: bool = False

after class-attribute instance-attribute

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

verb class-attribute instance-attribute

verb: bool = False

extension class-attribute instance-attribute

extension: str = BASE

PhaseError

Bases: RuntimeError

A phase whose steps cannot run as declared, or a step's misuse of the context.

Raised before any step runs for the phase's own problems, and from livery.workshop.PhaseContext.provide or livery.workshop.PhaseContext.read for a key the running step's table does not declare, or a value of another type.

PhaseContext dataclass

PhaseContext(root: Path, packages: tuple[Package, ...] = (), subset: tuple[Package, ...] | None = None, tests: Mapping[str, tuple[str, ...]] = dict[str, tuple[str, ...]](), examples: tuple[str, ...] = (), fix: bool = False, files: tuple[str, ...] = (), safe: bool = False, point: str = '', shard: Shard = ONE, catalogue: Mapping[str, tuple[tuple[str, str], ...]] | None = None, package: Package | None = None, selection: tuple[str, ...] = (), changes: Changes | None = None, arguments: tuple[str, ...] = (), step: str = '', phase: str = '', _steps: Mapping[str, StepRecord] = dict[str, 'StepRecord'](), _given: Mapping[str, Mapping[str, object]] = dict[str, Mapping[str, object]](), _shared: _Shared = _Shared())

What a run hands a step: the workspace, the run's scope, and the phase's keys.

One context serves one walk, and every step receives its own view of it, with the step named in step and, for a package step, the package it runs over in package. A step writes the keys its table provides with livery.workshop.PhaseContext.provide and reads the ones it reads with livery.workshop.PhaseContext.read; the views share what is written, so the engine reads a provided key back from the context the walk returns (livery.workshop.PhaseContext.result). The run phase's step that starts the executable records its exit code with livery.workshop.PhaseContext.exit. A view is frozen: a step that assigns an attribute changes a copy nobody reads, so the keys and the exit code go through the methods.

Attributes:

Name Type Description
root Path

The workspace root.

packages tuple[Package, ...]

Every package the workspace carries.

subset tuple[Package, ...] | None

The packages a scoped gate judges, or None for the whole gate.

tests Mapping[str, tuple[str, ...]]

Per package path, the test files that stand for the package's suite in this run.

examples tuple[str, ...]

The package paths whose changed files are examples and nothing else: their examples run and no suite.

fix bool

Whether the rewriters run in their fix mode.

files tuple[str, ...]

The files the run is limited to, root-relative, from fm check <paths>; empty when the scope decides.

safe bool

Whether the fixers run in their in-flight mode, which removes no code: --safe-fix.

point str

The CI point whose tests the test phase selects; empty for the gate's own.

shard Shard

The shard of a sharded check leg this run is, as fm check --shard or the leg's label names it (livery.workshop.Shard); one shard of one for a run that is not split. A step that declares shard among its flags runs its share of it, and the walk runs every other step on the first shard alone (livery.workshop._steps.on_this_shard).

catalogue Mapping[str, tuple[tuple[str, str], ...]] | None

Every file the run may read, by unit, each with its category, listed once per walk by livery.workshop._steps.catalogue; None when there is no listing, and then every step that applies runs.

package Package | None

The package a package step runs over, else None.

selection tuple[str, ...]

The test files selected for that package, relative to it, else empty.

changes Changes | None

What changed since the tree the run measures from, which selects what each workspace step with declared inputs judges (livery.workshop._influence.select); None when the run knows nothing of it, and then each judges everything.

arguments tuple[str, ...]

The words after --, the same for every step of the run: on a step's own verb, which a step that takes them hands its tool (StepRecord.arguments, a template's {arguments}), and on fm run, which the step starting the executable passes it; empty in every other run.

step str

The running step's name, <phase>.<step>, which the walk sets as it hands the context to the step; empty outside a step's run.

phase str

The phase the engine runs, build, whose given keys livery.workshop.PhaseContext.result reads back; on a step's view, the step's own phase, whose given keys the step reads. Empty for a walk over several phases, the gate's.

Methods:

Name Description
exit

Record code as the exit code fm run exits with.

for_package

This context narrowed to one package and its selected tests.

provide

Write value under key, a key the running step's table provides.

read

The value under key, a key the running step's table reads.

result

The value under key once the phase ran, for the engine that ran it.

root instance-attribute

root: Path

packages class-attribute instance-attribute

packages: tuple[Package, ...] = ()

subset class-attribute instance-attribute

subset: tuple[Package, ...] | None = None

tests class-attribute instance-attribute

tests: Mapping[str, tuple[str, ...]] = field(default_factory=dict[str, tuple[str, ...]])

examples class-attribute instance-attribute

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

fix class-attribute instance-attribute

fix: bool = False

files class-attribute instance-attribute

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

safe class-attribute instance-attribute

safe: bool = False

point class-attribute instance-attribute

point: str = ''

shard class-attribute instance-attribute

shard: Shard = ONE

catalogue class-attribute instance-attribute

catalogue: Mapping[str, tuple[tuple[str, str], ...]] | None = None

package class-attribute instance-attribute

package: Package | None = None

selection class-attribute instance-attribute

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

changes class-attribute instance-attribute

changes: Changes | None = None

arguments class-attribute instance-attribute

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

step class-attribute instance-attribute

step: str = ''

phase class-attribute instance-attribute

phase: str = ''

scoped property

scoped: bool

Whether this is a package-scoped gate.

judged property

judged: tuple[Package, ...]

The packages under judgment: the subset, or every package.

member property

member: Package

The package the step runs over, for a step that runs once per package.

Raises:

Type Description
Failed

when the run names none: a workspace step, or a context built outside a package step's run.

exit_code property

exit_code: int

The exit code the run phase's step recorded; 0 until one does.

exit

exit(code: int) -> None

Record code as the exit code fm run exits with.

The run phase's step that starts the executable calls it with the executable's; the walk hands the code to the verb through the context it returns.

Source code in packages/workshop/src/livery/workshop/_phases.py
def exit(self, code: int) -> None:
    """Record *code* as the exit code ``fm run`` exits with.

    The ``run`` phase's step that starts the executable calls it
    with the executable's; the walk hands the code to the verb
    through the context it returns.
    """
    self._shared.exit_code = code

for_package

for_package(package: Package) -> PhaseContext

This context narrowed to one package and its selected tests.

Source code in packages/workshop/src/livery/workshop/_phases.py
def for_package(self, package: Package) -> PhaseContext:
    """This context narrowed to one package and its selected tests."""
    files = self.tests.get(package.path, ())
    relative = tuple(path[len(package.path) + 1 :] for path in files)
    return replace(self, package=package, selection=relative)

provide

provide(key: str, value: object) -> None

Write value under key, a key the running step's table provides.

Raises:

Type Description
PhaseError

when the step's table does not provide key, or value is not of the type it declares.

Source code in packages/workshop/src/livery/workshop/_phases.py
def provide(self, key: str, value: object) -> None:
    """Write *value* under *key*, a key the running step's table provides.

    Raises:
        PhaseError: when the step's table does not provide *key*,
            or *value* is not of the type it declares.
    """
    record = self._running()
    provided = dict(record.provides)
    if key not in provided:
        raise PhaseError(
            f"{self.step} provides {key}, and its {self._table()} table does"
            " not name it in provides"
        )
    if not _holds(provided[key], value):
        raise PhaseError(
            f"{self.step} provides {key} as {type(value).__name__}, and its"
            f" {self._table()} table declares it {provided[key]}"
        )
    with self._shared.lock:
        self._shared.values.setdefault(self._unit(), {})[key] = value

read

read(key: str) -> object

The value under key, a key the running step's table reads.

Its type is the one its provider declares, or the one the phase's declaration gives an engine key.

Raises:

Type Description
PhaseError

when the step's table does not read key, the engine did not give it, or its provider wrote nothing under it.

Source code in packages/workshop/src/livery/workshop/_phases.py
def read(self, key: str) -> object:
    """The value under *key*, a key the running step's table reads.

    Its type is the one its provider declares, or the one the
    phase's declaration gives an engine key.

    Raises:
        PhaseError: when the step's table does not read *key*, the
            engine did not give it, or its provider wrote nothing
            under it.
    """
    record = self._running()
    if key not in record.reads:
        raise PhaseError(
            f"{self.step} reads {key}, and its {self._table()} table does not"
            " name it in reads"
        )
    if key in self._engine():
        given = self._given.get(self.phase, {})
        if key not in given:
            raise PhaseError(
                f"{self.step} reads {key}, which the engine running the"
                f" {self.phase} phase did not give it"
            )
        return given[key]
    values = self._shared.values.get(self._unit(), {})
    if key not in values:
        provider = next(
            (
                name
                for name, held in self._steps.items()
                if key in dict(held.provides)
            ),
            "its provider",
        )
        raise PhaseError(
            f"{self.step} reads {key}, which {provider} has not provided in"
            f" the {self.phase} phase"
        )
    return values[key]

result

result(key: str) -> object | None

The value under key once the phase ran, for the engine that ran it.

A key a step provided for the context's package, else one the engine gave the context's phase; None when neither wrote one.

Source code in packages/workshop/src/livery/workshop/_phases.py
def result(self, key: str) -> object | None:
    """The value under *key* once the phase ran, for the engine that ran it.

    A key a step provided for the context's package, else one the
    engine gave the context's phase; None when neither wrote one.
    """
    values = self._shared.values.get(self._unit(), {})
    return values.get(key, self._given.get(self.phase, {}).get(key))

base_phases cached

base_phases() -> dict[str, PhaseSpec]

The base's phases, read from the [phases] section of its contract file.

In the file's order, each spec naming the base as its declarer.

Raises:

Type Description
DeclarationError

when a section is off the shape a phase's declaration has.

Source code in packages/workshop/src/livery/workshop/_phases.py
@functools.cache
def base_phases() -> dict[str, PhaseSpec]:
    """The base's phases, read from the ``[phases]`` section of its contract file.

    In the file's order, each spec naming the base as its declarer.

    Raises:
        DeclarationError: when a section is off the shape a phase's
            declaration has.
    """
    from livery.workshop._contract_keys import BASE_FILE, base_contract
    from livery.workshop._declaration import phase_specs_of

    return phase_specs_of(base_contract(), BASE_FILE, extension=BASE)

declared_phases cached

declared_phases() -> dict[str, PhaseSpec]

Every declared phase by name: the base's, then each installed extension's.

An installed extension's declaration is read whether the workspace lists it or not, so a step into its phase reads the same anywhere; the mount refuses the step while the declarer is not listed. Each phase's after names declared phases, and the order they give has a start.

Raises:

Type Description
DeclarationError

when two extensions declare one phase, a phase follows one nobody declares, or the order has no start.

Source code in packages/workshop/src/livery/workshop/_phases.py
@functools.cache
def declared_phases() -> dict[str, PhaseSpec]:
    """Every declared phase by name: the base's, then each installed extension's.

    An installed extension's declaration is read whether the workspace
    lists it or not, so a step into its phase reads the same anywhere;
    the mount refuses the step while the declarer is not listed. Each
    phase's ``after`` names declared phases, and the order they give
    has a start.

    Raises:
        DeclarationError: when two extensions declare one phase, a
            phase follows one nobody declares, or the order has no
            start.
    """
    from livery.footman import installed_entry_points
    from livery.workshop._declaration import DeclarationError, phase_declarations

    found = dict(base_phases())
    for entry in installed_entry_points("workshop.extensions"):
        for spec in phase_declarations(entry.name, entry.value.partition(":")[0]):
            held = found.get(spec.name)
            if held is not None and held.extension != spec.extension:
                both = " and ".join(sorted((held.extension, spec.extension)))
                raise DeclarationError(
                    f"the {spec.name} phase is declared by both {both}; one extension"
                    " declares a phase"
                )
            found[spec.name] = spec
    _judge_after(found)
    return found

phase_spec

phase_spec(name: str) -> PhaseSpec

The declared phase name; refuses naming the declared ones.

Raises:

Type Description
PhaseError

when no extension declares name.

Source code in packages/workshop/src/livery/workshop/_phases.py
def phase_spec(name: str) -> PhaseSpec:
    """The declared phase *name*; refuses naming the declared ones.

    Raises:
        PhaseError: when no extension declares *name*.
    """
    specs = declared_phases()
    found = specs.get(name)
    if found is None:
        raise PhaseError(
            f"{name} is not a declared phase; the phases are {', '.join(specs)}"
        )
    return found

lifecycle_phases

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

The package-level phases, in declaration order: a package's lifecycle.

Source code in packages/workshop/src/livery/workshop/_phases.py
def lifecycle_phases() -> tuple[str, ...]:
    """The package-level phases, in declaration order: a package's lifecycle."""
    return tuple(
        name for name, spec in declared_phases().items() if spec.level == PACKAGE_LEVEL
    )

phase_steps

phase_steps(phase: str, members: tuple[str, ...], lookup: Lookup) -> tuple[StepRecord, ...]

The steps the extensions members add to phase, in their order.

Each member's steps in declaration order, the members in the order given, which for a package's set is its composition order. A step one of members deletes is left out, so it never runs for the set (deletions).

Source code in packages/workshop/src/livery/workshop/_phases.py
def phase_steps(
    phase: str, members: tuple[str, ...], lookup: Lookup
) -> tuple[StepRecord, ...]:
    """The steps the extensions *members* add to *phase*, in their order.

    Each member's steps in declaration order, the members in the order
    given, which for a package's set is its composition order. A step
    one of *members* deletes is left out, so it never runs for the set
    (`deletions`).
    """
    deleted = deletions(members, lookup)
    found: list[StepRecord] = []
    for name in members:
        declared = lookup(name)
        if declared is not None:
            found += [
                record
                for record in declared.phases.get(phase, ())
                if step_address(record) not in deleted
            ]
    return tuple(found)

step_address

step_address(record: StepRecord) -> str

record's address among every extension's steps: <owner>:<phase>.<step>.

Source code in packages/workshop/src/livery/workshop/_phases.py
def step_address(record: StepRecord) -> str:
    """*record*'s address among every extension's steps: ``<owner>:<phase>.<step>``."""
    return f"{record.extension}:{record.name}"

deletions

deletions(members: Iterable[str], lookup: Lookup) -> dict[str, tuple[str, str]]

The steps the extensions members delete, by address, to the deleter and why.

An address is <owner>:<phase>.<step>, as a step table's deletes names it; the first of members to delete a step is its deleter.

Source code in packages/workshop/src/livery/workshop/_phases.py
def deletions(members: Iterable[str], lookup: Lookup) -> dict[str, tuple[str, str]]:
    """The steps the extensions *members* delete, by address, to the deleter and why.

    An address is ``<owner>:<phase>.<step>``, as a step table's
    ``deletes`` names it; the first of *members* to delete a step is
    its deleter.
    """
    found: dict[str, tuple[str, str]] = {}
    for name in members:
        declared = lookup(name)
        if declared is None:
            continue
        for records in declared.phases.values():
            for record in records:
                for address, reason in record.deletes:
                    found.setdefault(address, (name, reason))
    return found

set_deletions

set_deletions(package: Package) -> dict[str, tuple[str, str]]

The steps package's set deletes, by address, to the deleter and why.

Source code in packages/workshop/src/livery/workshop/_phases.py
def set_deletions(package: Package) -> dict[str, tuple[str, str]]:
    """The steps *package*'s set deletes, by address, to the deleter and why."""
    from livery.workshop._composition import extension_set
    from livery.workshop._extensions import installed_declaration

    return deletions(extension_set(package), installed_declaration)

serves

serves(record: StepRecord, given: Mapping[str, object]) -> bool

Whether record runs on the side of its phase the engine's given keys name.

given are the keys the engine gives the step's phase. A step declaring isolated = true runs when the engine gives isolated true; one declaring false runs when the engine gives false or nothing; one declaring neither runs on both sides.

Source code in packages/workshop/src/livery/workshop/_phases.py
def serves(record: StepRecord, given: Mapping[str, object]) -> bool:
    """Whether *record* runs on the side of its phase the engine's *given* keys name.

    *given* are the keys the engine gives the step's phase. A step
    declaring ``isolated = true`` runs when the engine gives
    ``isolated`` true; one declaring false runs when the engine gives
    false or nothing; one declaring neither runs on both sides.
    """
    if record.isolated is None:
        return True
    return record.isolated == (given.get(ISOLATED) is True)

phase_order

phase_order(steps: Iterable[StepRecord], *, after: bool = True) -> tuple[StepRecord, ...]

steps in the order the walk starts them.

Each step after the providers of the keys it reads, in its own phase, and, with after, after the steps it names in after; otherwise in the given order. An after naming a step outside steps orders nothing.

Raises:

Type Description
OrderCycle

when the order has no start, naming the members of one cycle.

Source code in packages/workshop/src/livery/workshop/_phases.py
def phase_order(
    steps: Iterable[StepRecord], *, after: bool = True
) -> tuple[StepRecord, ...]:
    """*steps* in the order the walk starts them.

    Each step after the providers of the keys it reads, in its own
    phase, and, with *after*, after the steps it names in ``after``;
    otherwise in the given order. An ``after`` naming a step outside
    *steps* orders nothing.

    Raises:
        OrderCycle: when the order has no start, naming the members
            of one cycle.
    """
    from livery.workshop._composition import OrderCycle, cycle_of

    by_name = {record.name: record for record in steps}
    providers = _providers(by_name.values())
    waiting = {
        name: _earlier(record, by_name, providers, after=after)
        for name, record in by_name.items()
    }
    done: list[str] = []
    while len(done) < len(by_name):
        ready = next(
            (
                name
                for name in by_name
                if name not in done and not waiting[name].difference(done)
            ),
            None,
        )
        if ready is None:
            left = {name: waiting[name] for name in by_name if name not in done}
            raise OrderCycle(cycle_of(left))
        done.append(ready)
    return tuple(by_name[name] for name in done)

phase_problems

phase_problems(phase: str, steps: Iterable[StepRecord]) -> list[str]

Why steps cannot run as phase; empty when they can.

Two extensions declaring one step, two steps providing one key, a step providing a key the phase's engine gives, a step declaring a side of a phase whose declaration gives no isolated, a key a step reads and no step provides, and an order with no start.

Raises:

Type Description
PhaseError

when no extension declares phase.

Source code in packages/workshop/src/livery/workshop/_phases.py
def phase_problems(phase: str, steps: Iterable[StepRecord]) -> list[str]:
    """Why *steps* cannot run as *phase*; empty when they can.

    Two extensions declaring one step, two steps providing one key, a
    step providing a key the phase's engine gives, a step declaring a
    side of a phase whose declaration gives no ``isolated``, a key a
    step reads and no step provides, and an order with no start.

    Raises:
        PhaseError: when no extension declares *phase*.
    """
    from livery.workshop._composition import OrderCycle

    records = tuple(steps)
    problems: list[str] = []
    engine = phase_spec(phase).keys
    owners: dict[str, list[str]] = {}
    for record in records:
        owners.setdefault(record.name, []).append(record.extension)
    for name, extensions in owners.items():
        if len(extensions) > 1:
            problems.append(
                f"the {phase} phase: {' and '.join(sorted(extensions))} both declare"
                f" {name}; one extension of a package declares a step"
            )
    providers = _providers(records)
    for key, names in sorted(providers.items()):
        if key in engine:
            verb = "provides" if len(names) == 1 else "provide"
            problems.append(
                f"the {phase} phase: {' and '.join(sorted(names))} {verb} {key},"
                " which the engine running the phase provides; a step reads it"
            )
        elif len(names) > 1:
            problems.append(
                f"the {phase} phase: {' and '.join(sorted(names))} both provide"
                f" {key}; one step of a package provides a key"
            )
    if ISOLATED not in engine:
        problems += [
            f"the {phase} phase: {record.name} declares isolated, and the phase"
            " has one side: its declaration gives no isolated key"
            for record in records
            if record.isolated is not None
        ]
    for record in records:
        for key in record.reads:
            if key not in providers and key not in engine:
                problems.append(
                    f"the {phase} phase: {record.name} reads {key}, which no step of"
                    " the package provides"
                )
    try:
        phase_order(records)
    except OrderCycle as error:
        cycle = " before ".join((*error.members, error.members[0]))
        problems.append(
            f"the {phase} phase: its steps' order has no start: {cycle}; remove a"
            " key read or an after among them"
        )
    return problems

walk_steps

walk_steps(ctx: PhaseContext, steps: Iterable[StepRecord], *, inputs: Mapping[str, Mapping[str, object]] | None = None, fixing: bool = False) -> PhaseContext

Run steps as footman steps inside one parallel() block.

A step runs on the side of its phase the engine gives (livery.workshop._phases.serves), and a step serving the other side is not run. A workspace step runs once. A package step runs once per package in scope (the context's judged) it judges: one whose set holds an extension the step names and none that deletes the step, that has not turned the step off, that has a file the step's claims reach, and whose change is not confined to its tests unless the step is tests-only; each other package is said and not run. Independent steps run concurrently, and a step starts once the steps it names in after and the providers of the keys it reads have run, for the same package. A step whose earlier step failed is not run and says so; the earlier failure is the verdict, and the steps that depend on nothing failed still run, as footman runs a block. inputs are the keys the engine gives each phase, by phase, each phase's judged against its declaration before any step runs. fixing runs each step's fix body instead of its main, a step without one running nothing, in the given order: a fix rewrites what its own tool reads, and the gate runs its fixers one at a time, so after orders nothing there.

Returns:

Type Description
PhaseContext

The context the steps shared, which the engine reads a provided

PhaseContext

key or the exit code back from.

Raises:

Type Description
PhaseError

before any step runs, when the context or inputs names a phase nobody declares, when inputs gives a phase a key it does not take or a value of another type, or when the steps cannot run as declared (livery.workshop._phases.phase_problems).

Exception

the first failing step's, raised again once every step ran.

Source code in packages/workshop/src/livery/workshop/_phases.py
def walk_steps(
    ctx: PhaseContext,
    steps: Iterable[StepRecord],
    *,
    inputs: Mapping[str, Mapping[str, object]] | None = None,
    fixing: bool = False,
) -> PhaseContext:
    """Run *steps* as footman steps inside one ``parallel()`` block.

    A step runs on the side of its phase the engine gives
    ([livery.workshop._phases.serves][]), and a step serving the other
    side is not run. A workspace step runs once. A package step runs
    once per package in scope (the context's ``judged``) it judges:
    one whose set holds an extension the step names and none that
    deletes the step, that has not turned the step off, that has a
    file the step's claims reach, and whose change is not confined to
    its tests unless the step is tests-only; each other package is
    said and not run. Independent
    steps run concurrently, and a step starts once the steps it names
    in ``after`` and the providers of the keys it reads have run, for
    the same package. A step whose earlier step failed is not run and
    says so; the earlier failure is the verdict, and the steps that
    depend on nothing failed still run, as footman runs a block.
    *inputs* are the keys the engine gives each phase, by phase, each
    phase's judged against its declaration before any step runs.
    *fixing* runs each step's fix body instead of its main, a step
    without one running nothing, in the given order: a fix rewrites
    what its own tool reads, and the gate runs its fixers one at a
    time, so ``after`` orders nothing there.

    Returns:
        The context the steps shared, which the engine reads a provided
        key or the exit code back from.

    Raises:
        PhaseError: before any step runs, when the context or *inputs*
            names a phase nobody declares, when *inputs* gives a phase
            a key it does not take or a value of another type, or when
            the steps cannot run as declared
            ([livery.workshop._phases.phase_problems][]).
        Exception: the first failing step's, raised again once every
            step ran.
    """
    from livery.workshop._steps import (
        PACKAGE,
        judges_package,
        members,
        option_value,
        reads_files,
    )

    records = tuple(steps)
    where = f"{ctx.package.path}: " if ctx.package is not None else ""
    given = {phase: dict(keys) for phase, keys in (inputs or {}).items()}
    if ctx.phase:
        # A context naming a phase nobody declares refuses here, before
        # any step runs, as an input to such a phase does.
        phase_spec(ctx.phase)
    _judge_inputs(given, where)
    problems: list[str] = []
    for phase in dict.fromkeys(record.phase for record in records):
        problems += phase_problems(
            phase, (record for record in records if record.phase == phase)
        )
    if problems:
        raise PhaseError(where + "; ".join(problems))
    ordered = phase_order(records, after=not fixing)
    held = replace(
        ctx, _steps={record.name: record for record in records}, _given=given
    )
    units: list[_Unit] = []
    removed: dict[str, dict[str, tuple[str, str]]] = {}
    for record in ordered:
        if (record.fix if fixing else record.run) is None:
            continue
        if not serves(record, given.get(record.phase, {})):
            continue
        if record.scope != PACKAGE:
            units.append(_Unit(record, None))
            continue
        for package in members(held):
            if not judges_package(record, held, package):
                continue
            if package.path not in removed:
                removed[package.path] = set_deletions(package)
            deleted = removed[package.path].get(step_address(record))
            if deleted is not None:
                deleter, reason = deleted
                print(
                    f"  {record.name}: {package.path} skips ({deleter} deletes it:"
                    f" {reason})"
                )
                continue
            if not reads_files(record, held, (package.path,)):
                print(f"  {record.name}: {package.path} has no file it reads; not run")
                continue
            if not option_value(record, package, "enabled"):
                print(
                    f"  {record.name}: {package.path} skips (turned off in"
                    f" {package.path}/workshop.toml)"
                )
                continue
            units.append(_Unit(record, package))
    _link(units, ordered, after=not fixing)
    bodies = [_resolved(unit, fixing) for unit in units]
    with parallel() as block:
        for unit, body in zip(units, bodies, strict=True):
            built = step(_body(held, unit, body), title=unit.title)
            block(built.opts(capture=False)())
    return held

run_registered

run_registered(ctx: PhaseContext) -> PhaseContext

Run the steps registered for the phase ctx names, through the walk.

The steps the mount registered for ctx.phase, in registration order: each listed extension's own, and those of the [for.<target>] tables that apply. They run as walk_steps runs any steps, so a phase the gate never runs, one declared with gated = false, runs this way over the workspace its context names. A workspace step that names extensions runs once while a package the context judges holds one of them; while none does, a line says so and the step does not run. A phase with no registered step runs nothing.

Returns:

Type Description
PhaseContext

The context the steps shared.

Raises:

Type Description
PhaseError

when ctx names no phase, or one nobody declares.

Exception

the first failing step's, raised again once every step ran.

Source code in packages/workshop/src/livery/workshop/_phases.py
def run_registered(ctx: PhaseContext) -> PhaseContext:
    """Run the steps registered for the phase *ctx* names, through the walk.

    The steps the mount registered for ``ctx.phase``, in registration
    order: each listed extension's own, and those of the
    ``[for.<target>]`` tables that apply. They run as `walk_steps` runs
    any steps, so a phase the gate never runs, one declared with
    ``gated = false``, runs this way over the workspace its context
    names. A workspace step that names extensions runs once while a
    package the context judges holds one of them; while none does, a
    line says so and the step does not run. A phase with no registered
    step runs nothing.

    Returns:
        The context the steps shared.

    Raises:
        PhaseError: when *ctx* names no phase, or one nobody declares.
        Exception: the first failing step's, raised again once every
            step ran.
    """
    running, _idle = _registered(ctx)
    return walk_steps(ctx, running)

output_refusal

output_refusal(output: str) -> str

Why output cannot name what a step writes, or "" when it can.

An output is a path relative to the workspace root, or package/<path> for that path in each package; a directory ends in /. It lies below the root, or below the package, and it is never docs/ itself, the root's or a package's, which holds the authored pages. The text completes a sentence about the output.

Source code in packages/workshop/src/livery/workshop/_phases.py
def output_refusal(output: str) -> str:
    """Why *output* cannot name what a step writes, or ``""`` when it can.

    An output is a path relative to the workspace root, or
    ``package/<path>`` for that path in each package; a directory ends
    in ``/``. It lies below the root, or below the package, and it is
    never ``docs/`` itself, the root's or a package's, which holds the
    authored pages. The text completes a sentence about the output.
    """
    import re

    inner = output.removeprefix(IN_EACH_PACKAGE)
    where = "each package" if inner != output else "the root"
    parts = tuple(part for part in inner.split("/") if part not in ("", "."))
    if (
        "\\" in output
        or inner.startswith("/")
        or re.match(r"[A-Za-z]:", inner)
        or ".." in parts
    ):
        return (
            f"names {output!r}, which leaves the root; an output is a path below"
            " the root, or package/<path> for the path in each package"
        )
    if not parts:
        return f"names {output!r}, {where} itself; an output is a path below it"
    if parts == ("docs",):
        tree = "each package's" if inner != output else "the root's"
        return (
            f"names {output!r}, {tree} docs/ itself, which holds the authored"
            " pages; an output is a path below it"
        )
    return ""

run_phase

run_phase(root: Path, phase: str, *, outputs: Iterable[str] = ()) -> PhaseContext

Run a phase the gate never runs over the workspace at root; the shared context.

The steps the listed extensions register for phase, their own and those of the [for.<target>] tables that apply, run side by side through the walk every phase runs through, each workspace step once and each package step once per package whose set holds an extension it names. A workspace step that names extensions runs while a package holds one of them; while none does, a line says so and the step does not run. A phase with no registered step runs nothing.

Before the steps run, the paths a step declares under outputs are settled: each one the phase's last run recorded, or a step that does not run now declares, is removed unless a step that runs now declares it, and a line names each path removed. So a step that stops running, its extension unlisted or no longer installed or the step turned off, leaves nothing behind wherever it wrote, and a running step finds its own output as it left it. The record lives in the checkout's .workshop/state/.

Parameters:

Name Type Description Default
root Path

The workspace root.

required
phase str

The phase, one declared with gated = false.

required
outputs Iterable[str]

Paths this run writes that no step declares, such as those of the verbs a step runs: each in the shape a step declares one, and removed and recorded as a running step's are.

()

Returns:

Type Description
PhaseContext

The context the steps shared.

Raises:

Type Description
PhaseError

when nobody declares phase, naming the declared phases; when the gate runs it; or when an output in outputs is not a path below the root, or names docs/ itself.

Exception

the first failing step's, raised again once every step ran.

Source code in packages/workshop/src/livery/workshop/_phases.py
def run_phase(root: Path, phase: str, *, outputs: Iterable[str] = ()) -> PhaseContext:
    """Run a phase the gate never runs over the workspace at *root*; the shared context.

    The steps the listed extensions register for *phase*, their own and
    those of the ``[for.<target>]`` tables that apply, run side by side
    through the walk every phase runs through, each workspace step once
    and each package step once per package whose set holds an
    extension it names. A workspace step that names extensions runs
    while a package holds one of them; while none does, a line says so
    and the step does not run. A phase with no registered step runs
    nothing.

    Before the steps run, the paths a step declares under ``outputs``
    are settled: each one the phase's last run recorded, or a step that
    does not run now declares, is removed unless a step that runs now
    declares it, and a line names each path removed. So a step that
    stops running, its extension unlisted or no longer installed or the
    step turned off, leaves nothing behind wherever it wrote, and a
    running step finds its own output as it left it. The record lives
    in the checkout's ``.workshop/state/``.

    Args:
        root: The workspace root.
        phase: The phase, one declared with ``gated = false``.
        outputs: Paths this run writes that no step declares, such as
            those of the verbs a step runs: each in the shape a step
            declares one, and removed and recorded as a running step's
            are.

    Returns:
        The context the steps shared.

    Raises:
        PhaseError: when nobody declares *phase*, naming the declared
            phases; when the gate runs it; or when an output in
            *outputs* is not a path below the root, or names ``docs/``
            itself.
        Exception: the first failing step's, raised again once every
            step ran.
    """
    from livery.workshop._packages import discover_packages

    spec = phase_spec(phase)
    if spec.gated:
        raise PhaseError(
            f"the gate runs the {phase} phase; run_phase runs a phase declared"
            " with gated = false, and run_phase_over runs a gated phase's steps"
            " over named packages"
        )
    given = tuple(outputs)
    for output in given:
        refusal = output_refusal(output)
        if refusal:
            raise PhaseError(f"an output of the {phase} phase {refusal}")
    ctx = PhaseContext(root=root, packages=discover_packages(root), phase=phase)
    running, idle = _registered(ctx)
    _remove_outputs(
        root,
        phase,
        (*(o for record in running for o in record.outputs), *given),
        tuple(o for record in idle for o in record.outputs),
        ctx.packages,
    )
    return walk_steps(ctx, running)