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__ |
|
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 |
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
¶
Releases newly observed, per tool, oldest first.
events
instance-attribute
¶
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
¶
Indexes that would not answer, and why. Not the same as a tool with
nothing new — see _toolfetch.Unreachable.
skipped
instance-attribute
¶
Tools with no index to read, or no record to add to.
holes
class-attribute
instance-attribute
¶
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
¶
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
¶
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.
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
1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 | |
__getattr__ ¶
Serve a public name from its module on first use, then keep it.