Skip to content

livery.workshop._words

livery.workshop._words

Steps in words: a tool and its arguments in a declaration, and their engine.

A step whose verdict is its tool's exit code needs no code. Its declaration names the tool and the words it is called with: main in its [phases.<phase>.<step>] table, and fix and safe-fix for one that rewrites. The engine does the rest. It selects what the run reaches, as the step's scope and narrowing say; puts the paths and the words after -- on the step's verb where the template stands them; splits a long path list into the fewest calls under the command-line limit; and runs the tool through its toolroom handle, which prints the tool's output. A non-zero exit refuses, and the refusals of every call merge into one.

The template places both itself: {paths} stands where each batch of the paths goes, and a template without it runs whole, once with no path; {arguments} stands where the words after -- go, and a template without it takes none. Each stands alone as one word, which the engine expands into many.

A word may name a placeholder, {name}, answered per call: {cache}, the step's own directory under .workshop/.cache/; {package}, the directory of the package a call judges; {compile-commands}, the directory of that package's compilation database, without which the call does not run; and each key of matrix, which runs one call per value in parallel, each its own verdict. env gives every call variables over the run's own.

A step the words cannot say, one whose verdict is not its tool's exit code or whose paths need reshaping first, declares a reference to its code instead: main as a string, module:function.

Classes:

Name Description
Words

A step's words, as its declaration spells them.

Command

One mode of a step in words, called as the step's run or fix.

Functions:

Name Description
run_words

Run command over what the run reaches, as its step's scope and narrowing say.

run_tool

Call tool's toolroom handle with argv, from cwd; a non-zero exit refuses.

explained

The lines fm explain <step> prints: what the step runs, and over what.

Attributes:

Name Type Description
PLACEHOLDERS
PACKAGE_PLACEHOLDERS
PATHS_WORD
ARGUMENTS_WORD
PLACED

PLACEHOLDERS module-attribute

PLACEHOLDERS = ('cache', 'package', 'compile-commands', 'paths', 'arguments')

PACKAGE_PLACEHOLDERS module-attribute

PACKAGE_PLACEHOLDERS = ('package', 'compile-commands')

PATHS_WORD module-attribute

PATHS_WORD = '{paths}'

ARGUMENTS_WORD module-attribute

ARGUMENTS_WORD = '{arguments}'

PLACED module-attribute

Words dataclass

Words(judge: tuple[str, ...], fix: tuple[str, ...] = (), safe_fix: tuple[str, ...] = (), env: tuple[tuple[str, str], ...] = (), matrix: tuple[tuple[str, tuple[str, ...]], ...] = ())

A step's words, as its declaration spells them.

Attributes:

Name Type Description
judge tuple[str, ...]

The tool's name, as the step's tools name it, and the arguments that judge.

fix tuple[str, ...]

The tool and the arguments that rewrite under --fix; empty for a step that only judges.

safe_fix tuple[str, ...]

The tool and the arguments that rewrite under --safe-fix, removing no code; empty to rewrite with fix.

env tuple[tuple[str, str], ...]

The variables every call gets, over the run's own, by name.

matrix tuple[tuple[str, tuple[str, ...]], ...]

Each placeholder the calls vary, with its values: one call per combination.

Methods:

Name Description
placeholders

Every placeholder the words name, in any mode or variable.

unanswered

The placeholders neither the engine nor the matrix answers, sorted.

unvaried

The matrix keys no word names, in the matrix's order.

judge instance-attribute

judge: tuple[str, ...]

fix class-attribute instance-attribute

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

safe_fix class-attribute instance-attribute

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

env class-attribute instance-attribute

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

matrix class-attribute instance-attribute

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

tool property

tool: str

The tool every call runs, the first word of judge.

placeholders

placeholders() -> frozenset[str]

Every placeholder the words name, in any mode or variable.

Source code in packages/workshop/src/livery/workshop/_words.py
def placeholders(self) -> frozenset[str]:
    """Every placeholder the words name, in any mode or variable."""
    texts = [*self.judge, *self.fix, *self.safe_fix]
    texts += [value for _name, value in self.env]
    return frozenset(name for text in texts for name in _PLACEHOLDER.findall(text))

unanswered

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

The placeholders neither the engine nor the matrix answers, sorted.

Source code in packages/workshop/src/livery/workshop/_words.py
def unanswered(self) -> tuple[str, ...]:
    """The placeholders neither the engine nor the matrix answers, sorted."""
    known = {*PLACEHOLDERS, *(key for key, _values in self.matrix)}
    return tuple(sorted(self.placeholders() - known))

unvaried

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

The matrix keys no word names, in the matrix's order.

Source code in packages/workshop/src/livery/workshop/_words.py
def unvaried(self) -> tuple[str, ...]:
    """The matrix keys no word names, in the matrix's order."""
    named = self.placeholders()
    return tuple(key for key, _values in self.matrix if key not in named)

Command dataclass

Command(words: Words, step: str, fixing: bool = False)

One mode of a step in words, called as the step's run or fix.

Attributes:

Name Type Description
words Words

The step's words.

step str

The step's name, lint.ruff, which a run that names no step judges by.

fixing bool

Whether this is the fix mode, which runs safe-fix under --safe-fix where the words declare it.

Methods:

Name Description
argv

The words this mode runs: the tool's name, then its arguments.

__call__

Run this mode over what ctx reaches; a non-zero exit refuses.

__str__

The words this mode runs, as the declaration spells them.

words instance-attribute

words: Words

step instance-attribute

step: str

fixing class-attribute instance-attribute

fixing: bool = False

argv

argv(*, safe: bool = False) -> tuple[str, ...]

The words this mode runs: the tool's name, then its arguments.

Source code in packages/workshop/src/livery/workshop/_words.py
def argv(self, *, safe: bool = False) -> tuple[str, ...]:
    """The words this mode runs: the tool's name, then its arguments."""
    if not self.fixing:
        return self.words.judge
    return self.words.safe_fix if safe and self.words.safe_fix else self.words.fix

__call__

__call__(ctx: PhaseContext) -> None

Run this mode over what ctx reaches; a non-zero exit refuses.

Source code in packages/workshop/src/livery/workshop/_words.py
def __call__(self, ctx: PhaseContext) -> None:
    """Run this mode over what *ctx* reaches; a non-zero exit refuses."""
    run_words(self, ctx)

__str__

__str__() -> str

The words this mode runs, as the declaration spells them.

Source code in packages/workshop/src/livery/workshop/_words.py
def __str__(self) -> str:
    """The words this mode runs, as the declaration spells them."""
    return " ".join(self.argv())

run_words

run_words(command: Command, ctx: PhaseContext) -> None

Run command over what the run reaches, as its step's scope and narrowing say.

A package step calls the tool on the package's files the run reaches, from the package's directory, and calls nothing when there are none. A workspace step that narrows by paths calls it on the paths the run reaches, with none when the run is whole, and not at all when the run reaches nothing it reads; one that narrows by packages calls it once per package; any other calls it once, with no path.

Raises:

Type Description
Failed

when a call exits non-zero, every call's reason merged.

Source code in packages/workshop/src/livery/workshop/_words.py
def run_words(command: Command, ctx: PhaseContext) -> None:
    """Run *command* over what the run reaches, as its step's scope and narrowing say.

    A package step calls the tool on the package's files the run
    reaches, from the package's directory, and calls nothing when there
    are none. A workspace step that narrows by paths calls it on the
    paths the run reaches, with none when the run is whole, and not at
    all when the run reaches nothing it reads; one that narrows by
    packages calls it once per package; any other calls it once, with no
    path.

    Raises:
        Failed: when a call exits non-zero, every call's reason merged.
    """
    from livery.workshop._steps import (
        PACKAGE,
        PACKAGES,
        PATHS,
        WHOLE,
        scoped_files,
        scoped_packages,
        scoped_paths,
        step_for,
    )

    record = step_for(ctx.step or command.step)
    ctx = replace(ctx, step=record.name)
    argv = command.argv(safe=ctx.safe)
    if record.scope == PACKAGE:
        if ctx.package is None:
            fail(f"{record.name} judges one package at a time, and this run names none")
        files = tuple(str(path) for path in scoped_files(ctx, record.name))
        if files:
            _calls(record, command.words, argv, ctx, ctx.package, files)
        return
    if record.narrowing == PATHS:
        chosen = scoped_paths(ctx, record.name)
        if not chosen:
            return  # the run reaches nothing the step reads
        _calls(
            record, command.words, argv, ctx, None, () if chosen == WHOLE else chosen
        )
        return
    if record.narrowing == PACKAGES:
        for package in scoped_packages(ctx, record.name):
            _calls(record, command.words, argv, ctx, package, ())
        return
    _calls(record, command.words, argv, ctx, None, ())

run_tool

run_tool(tool: str, argv: tuple[str, ...], *, cwd: Path, ctx: PhaseContext, env: dict[str, str]) -> None

Call tool's toolroom handle with argv, from cwd; a non-zero exit refuses.

The handle prints the tool's output. A call from the workspace root runs in the run's own directory, and one with no variables in the run's own environment, so neither is passed.

Raises:

Type Description
Failed

when the tool exits non-zero, with the handle's reason.

Source code in packages/workshop/src/livery/workshop/_words.py
def run_tool(
    tool: str,
    argv: tuple[str, ...],
    *,
    cwd: Path,
    ctx: PhaseContext,
    env: dict[str, str],
) -> None:
    """Call *tool*'s toolroom handle with *argv*, from *cwd*; a non-zero exit refuses.

    The handle prints the tool's output. A call from the workspace root
    runs in the run's own directory, and one with no variables in the
    run's own environment, so neither is passed.

    Raises:
        Failed: when the tool exits non-zero, with the handle's reason.
    """
    import livery.toolroom.tools as tools
    from livery.footman import RunFailed

    handle = getattr(tools, tool)
    chosen: dict[str, object] = {}
    if cwd != ctx.root:
        chosen["cwd"] = cwd
    if env:
        chosen["env"] = {**os.environ, **env}
    try:
        (handle.opts(**chosen) if chosen else handle)(*argv)
    except (tools.ToolError, RunFailed) as error:
        # A failed call refuses as a step's call does, so a batched
        # run collects every batch's reason, the tool's output in each,
        # before it refuses.
        fail(str(error))

explained

explained(record: StepRecord) -> list[str]

The lines fm explain <step> prints: what the step runs, and over what.

A step in words shows each mode's command as the tool's handle spells it, the placeholders left for the engine to answer, then what the engine puts where {paths} and {arguments} stand; a step that runs code names its references.

Source code in packages/workshop/src/livery/workshop/_words.py
def explained(record: StepRecord) -> list[str]:
    """The lines ``fm explain <step>`` prints: what the step runs, and over what.

    A step in words shows each mode's command as the tool's handle
    spells it, the placeholders left for the engine to answer, then
    what the engine puts where ``{paths}`` and ``{arguments}`` stand;
    a step that runs code names its references.
    """
    from livery.workshop._steps import PACKAGE, PACKAGES, PATHS

    lines = [f"  {record.name}", f"    extension: {record.extension}"]
    if record.scope == PACKAGE:
        lines.append("    scope: one package at a time, from its directory")
    elif record.narrowing in (PATHS, PACKAGES):
        lines.append(f"    scope: the workspace, narrowed by {record.narrowing}")
    else:
        lines.append("    scope: the workspace, whole every run")
    words = record.words
    if words is None:
        lines.append(f"    main: {record.run} (code)")
        if record.fix is not None:
            lines.append(f"    fix: {record.fix} (code)")
        return lines
    for mode, argv in (
        ("main", words.judge),
        ("fix", words.fix),
        ("safe-fix", words.safe_fix),
    ):
        if argv:
            lines.append(f"    {mode}: {' '.join(_shown(argv))}")
    for key, values in words.matrix:
        lines.append(f"    matrix: {key} = {', '.join(values)}, one call each")
    for name, value in words.env:
        lines.append(f"    env: {name}={value}")
    if "cache" in words.placeholders():
        lines.append(f"    {{cache}}: .workshop/.cache/{record.step}")
    if "paths" in words.placeholders():
        reached = "files" if record.scope == PACKAGE else "paths"
        lines.append(f"    {{paths}}: the {reached} the run reaches, a batch per call")
    if "arguments" in words.placeholders():
        lines.append("    {arguments}: the words after --")
    return lines