Skip to content

livery.toolroom.bench

livery.toolroom.bench

The bench: where toolroom's handles are made and refreshed.

The drivers that enumerate a tool's releases, the observation of a release's help on the platform, the tool history, the stub generator that writes the checked-in stubs of livery.toolroom.tools, the pin verb, the docs generator for the per-tool pages, and the fm tools.* verbs that run them. A consumer of the handles never installs this; a workspace that keeps the handles current names it as an extension, and footman's plugin loading is the only way in.

The package exposes its one group, tasks, the tools verbs, which its plugin entry point names; and the refresh's data, livery.toolroom.bench.Refreshed and livery.toolroom.bench.submit_refresh, for a scheduled job that reads the release decision.

Classes:

Name Description
Refreshed

What a refresh found — the release decision, as data.

Functions:

Name Description
submit_refresh

Commit a refresh that moved something and open its pull request.

Attributes:

Name Type Description
tasks Group
__version__

TYPE_CHECKING module-attribute

TYPE_CHECKING = False

tasks module-attribute

tasks: Group = Group('toolroom', help='Keep the tool records honest')

__all__ module-attribute

__all__ = ['Refreshed', '__version__', 'submit_refresh', 'tasks']

__version__ module-attribute

__version__ = '0.4.0'

Refreshed dataclass

Refreshed(read: dict[str, list[str]], events: dict[str, list[str]], unreachable: dict[str, str], skipped: list[str], holes: dict[str, list[str]] = dict(), wrote_changelog: bool = False, release: bool = False, additions_only: bool = False, ingest: dict[str, list[str]] = dict(), ingest_ok: bool = True, artifacts: dict[str, list[str]] = dict())

What a refresh found — the release decision, as data.

Returned rather than printed, so fm --json toolroom.refresh hands a scheduled job the same answer a person reads.

Methods:

Name Description
__post_init__

Attributes:

Name Type Description
read dict[str, list[str]]

Releases newly observed, per tool, oldest first.

events dict[str, list[str]]

The subset of those that are newer than anything seen before and

unreachable dict[str, str]

Indexes that would not answer, and why. Not the same as a tool with

skipped list[str]

Tools with no index to read, or no record to add to.

holes dict[str, list[str]]

Releases that were listed but could not be observed — an install that

wrote_changelog bool

Whether the events reached CHANGELOG.md. False with nothing to say,

release bool

Whether any tool's surface moved — decision 4, in one line. A field

additions_only bool

Whether every surface change across every announced event only ADDED

ingest dict[str, list[str]]

Per announced tool, the ingest verification's lines: the verdict,

ingest_ok bool

Whether every ingest check passed on every host of every event

artifacts dict[str, list[str]]

Per tool read from a forge tier, the artifact step's lines: the

armed bool

Whether the pull request arms: additions only and every check passed.

read instance-attribute

read: dict[str, list[str]]

Releases newly observed, per tool, oldest first.

events instance-attribute

events: dict[str, list[str]]

The subset of those that are newer than anything seen before and changed the tool's surface. This is the release decision and the CHANGELOG line at once — so a backfill, which reaches only downwards, is saved and reported but never announced.

unreachable instance-attribute

unreachable: dict[str, str]

Indexes that would not answer, and why. Not the same as a tool with nothing new — see _toolfetch.Unreachable.

skipped instance-attribute

skipped: list[str]

Tools with no index to read, or no record to add to.

holes class-attribute instance-attribute

holes: dict[str, list[str]] = field(default_factory=dict)

Releases that were listed but could not be observed — an install that failed, a binary that would not describe itself. A hole is not an error: the record stays whole by construction, a later run fills it, and until then a change the missing release carried reads as arriving at the next release actually read.

wrote_changelog class-attribute instance-attribute

wrote_changelog: bool = False

Whether the events reached CHANGELOG.md. False with nothing to say, and false when the file has no [Unreleased] section to write into — which a caller should notice rather than assume the notes got written.

release class-attribute instance-attribute

release: bool = False

Whether any tool's surface moved — decision 4, in one line. A field rather than a property, and recomputed from events on construction: dataclasses.asdict serialises fields only, and this is the one value the scheduled job reads out of fm --json toolroom.refresh.

additions_only class-attribute instance-attribute

additions_only: bool = False

Whether every surface change across every announced event only ADDED to a tool's surface — nothing dropped, no verb withdrawn. Half of the graded release trigger's green light: additions cannot break a caller. False when there are no events at all (nothing to ship is not "safe to ship"). Rewordings count as additions-safe: they change what a stub says, never what a tool accepts.

ingest class-attribute instance-attribute

ingest: dict[str, list[str]] = field(default_factory=dict)

Per announced tool, the ingest verification's lines: the verdict, each finding and each host's structural diff, for every event version that has a host (livery.toolroom.bench._ingest). Empty for a tool whose versions have no host, since there is nothing to stage.

ingest_ok class-attribute instance-attribute

ingest_ok: bool = True

Whether every ingest check passed on every host of every event version: the other half of the green light. True when nothing had a host to check, so a tool read but never downloaded arms as before.

artifacts class-attribute instance-attribute

artifacts: dict[str, list[str]] = field(default_factory=dict)

Per tool read from a forge tier, the artifact step's lines: the hosts each fresh version gained, the assets they came from, and any version whose artifacts could not be recorded.

armed property

armed: bool

Whether the pull request arms: additions only and every check passed.

__post_init__

__post_init__() -> None
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
def __post_init__(self) -> None:
    object.__setattr__(self, "release", any(self.events.values()))

submit_refresh

submit_refresh(found: Refreshed, *, git: Callable[..., Result] | None = None, submit: Callable[[list[str]], int] | None = None, on: date | None = None, dry_run: bool | None = None) -> list[str]

Commit a refresh that moved something and open its pull request.

The branch is chore/tools-refresh-<date>, cut from HEAD, and a refresh submits only from the history of origin's default branch: on another checkout it submits nothing and says so, and the files it wrote stand. When origin already holds the day's branch, from an earlier refresh on another machine or in another job, the refresh compares and moves nothing: when that branch holds every file this refresh wrote, with the same content, it submits nothing and says the day's refresh is already submitted; otherwise it stops, naming the branch and the files that differ, for a person to merge or close that pull request and run the refresh again. The checkout stays on its own tree either way: the run reads its code and declarations from the checkout after the refresh, and the day's branch can be cut from an older main. Origin is asked before anything in the checkout changes, so a refresh that cannot ask it leaves the checkout as the walk left it.

The pull request is armed when Refreshed.armed holds, every change an addition and every ingest check passed, and unarmed otherwise, so a dropped verb or a deployment that does not stand waits for a person. The commit body carries the ingest lines, so the pull request's summary is the structural diff. A refresh that moved nothing opens nothing and says so. Under a dry run nothing is committed or submitted: the lines say what would happen, the arming decision included.

git, submit, on and dry_run are the seams the tests drive; the defaults are the git tool handle, the runner's own submit verb, today, and the run's own dry-run flag. git answers each command with its exit code and output and never raises; a code this does not expect fails the refresh in git's own words.

Returns:

Type Description
list[str]

The lines to print, one per step.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
def submit_refresh(
    found: Refreshed,
    *,
    git: Callable[..., Result] | None = None,
    submit: Callable[[list[str]], int] | None = None,
    on: date | None = None,
    dry_run: bool | None = None,
) -> list[str]:
    """Commit a refresh that moved something and open its pull request.

    The branch is `chore/tools-refresh-<date>`, cut from HEAD, and a
    refresh submits only from the history of origin's default branch:
    on another checkout it submits nothing and says so, and the files it
    wrote stand. When origin already
    holds the day's branch, from an earlier refresh on another machine
    or in another job, the refresh compares and moves nothing: when
    that branch holds every file this refresh wrote, with the same
    content, it submits nothing and says the day's refresh is already
    submitted; otherwise it stops, naming the branch and the files that
    differ, for a person to merge or close that pull request and run
    the refresh again. The checkout stays on its own tree either way:
    the run reads its code and declarations from the checkout after the
    refresh, and the day's branch can be cut from an older main. Origin
    is asked before anything in the checkout changes, so a refresh that
    cannot ask it leaves the checkout as the walk left it.

    The pull request is armed when `Refreshed.armed` holds, every change
    an addition and every ingest check passed, and unarmed otherwise, so
    a dropped verb or a deployment that does not stand waits for a
    person. The commit body carries the ingest lines,
    so the pull request's summary is the structural diff. A refresh that
    moved nothing opens nothing and says so. Under a dry run nothing is
    committed or submitted: the lines say what would happen, the arming
    decision included.

    *git*, *submit*, *on* and *dry_run* are the seams the tests drive;
    the defaults are the git tool handle, the runner's own submit verb,
    today, and the run's own dry-run flag. *git* answers each command
    with its exit code and output and never raises; a code this does
    not expect fails the refresh in git's own words.

    Returns:
        The lines to print, one per step.
    """
    import livery.toolroom.tools as tools

    if not found.release:
        return ["  nothing moved: no branch, no pull request"]
    when = on or date.today()
    branch = f"chore/tools-refresh-{when:%Y%m%d}"
    moved = ", ".join(sorted(found.events))
    title = f"chore(toolroom): tool refresh {when:%Y-%m-%d}"
    reason = (
        "additions only, every ingest check passed"
        if found.armed
        else "a surface lost something, a person decides"
        if found.ingest_ok
        else "an ingest check found something, a person decides"
    )
    rehearsal = current().dry_run if dry_run is None else dry_run
    if rehearsal:
        return [
            f"  would refresh {moved} on {branch}",
            f"  would submit {'armed' if found.armed else 'unarmed'}: {reason}",
        ]
    run_git: Callable[..., Result] = git or tools.git.opts(nofail=True, recorded=False)
    body = "\n".join(
        [
            moved,
            *(
                line.strip()
                for key in sorted(found.ingest)
                for line in found.ingest[key]
            ),
        ]
    )
    message = f"{title}\n\n{body}"
    tracking = f"refs/remotes/origin/{branch}"
    held = _origin_holds(run_git, branch)
    if not _on_default_branch(run_git):
        return [
            "  the checkout is not on origin's default branch, so nothing is"
            " submitted: a refresh submits from the default branch alone, and"
            " the files it wrote stand in the checkout"
        ]
    if held:
        _git_step(run_git, "fetch", "origin", f"+refs/heads/{branch}:{tracking}")
    _git_step(run_git, "switch", "-c", branch)
    _git_step(run_git, "add", "-A")
    _git_step(run_git, "commit", "-m", message)
    if held:
        differ = _differing(run_git, tracking)
        if not differ:
            return [
                f"  the day's refresh is already submitted: {branch} on origin"
                " holds every file this one wrote, so nothing is submitted"
            ]
        fail(
            f"{branch} on origin holds an earlier refresh, and this one wrote"
            f" {', '.join(differ)} differently. Merge or close that pull"
            " request, then run the refresh again; this refresh's commit"
            f" stands on the local branch {branch}."
        )
    argv = [_prog(), "submit", f"--title={title}"]
    if found.armed:
        argv.append("--armed")
    code = (submit or _run_submit)(argv)
    if code != 0:
        fail(f"the refresh's submit exited {code}; the branch {branch} stands")
    return [
        f"  refreshed {moved} on {branch}",
        f"  submitted {'armed' if found.armed else 'unarmed'}: {reason}",
    ]

__getattr__

__getattr__(name: str) -> object

Serve a public name from its module on first use, then keep it.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/__init__.py
def __getattr__(name: str) -> object:
    """Serve a public name from its module on first use, then keep it."""
    import importlib

    module = _EXPORTS.get(name)
    if module is None:
        raise AttributeError(
            f"module 'livery.toolroom.bench' has no attribute {name!r}"
        )
    value = getattr(importlib.import_module(module), name)
    globals()[name] = value
    return value