livery.toolroom.bench._surfaces¶
livery.toolroom.bench._surfaces ¶
What each curated tool accepted, version by version, in its record.
A tool's record (livery.toolroom.store.Record) carries each
version's surface one verb at a time, forward and inherited; this
module is the bench's side of it. Reading a tool gives a surface,
surface_of; several platforms' readings of one version fold into one
surface and one sidecar of who missed what, fold; a version is placed
in its record at its own position, place, or a later reading is
merged into a version already there, merge; and union is what every
stub renders: every option the tool has ever had, each with the
interval and the platform verdicts the record can prove.
The sidecar and every standing claim are kept apart on purpose. A
record stores only what a platform saw at the version it looked at;
"Windows lacks --fork", "added in 1.2.0" and "gone since 2.0.0" are
derived at render time from those observations, where a later sighting
revises them, and never written down where they would harden.
Classes:
| Name | Description |
|---|---|
LossyReading |
A reading that lost bytes on the way in, refused rather than stored. |
Chain |
A record resolved once: every version read, newest first, with its observation. |
Functions:
| Name | Description |
|---|---|
surface_of |
A ToolSpec reduced to what a release is, losing nothing else. |
delta |
How to step back from newer to older, per option. |
fold |
One release seen by several platforms → one surface and its sidecar. |
versions |
Every version read, newest first: the versions whose delta carries a surface. |
floor |
The oldest version read, how far back the record reaches. |
observation |
What version accepted and who read it, or |
at |
The surface of version, its help and verbs, or |
platforms_of |
The platforms that read version; empty when none did. |
absent_of |
Who looked at version and did not find each option, keyed |
new |
A record of one version read. A record this short is a valid record, |
place |
version placed at its own position in the record, wherever that is. |
merge |
Fold another platform's reading into a version the record already has. |
changed |
Whether version's reading moved the surface against the version read before it. |
changes |
What changed between two versions read, as one step. |
spellings |
How version spells each option key on the command line. |
load |
The record in the file path, or |
save |
Write record to the file path, one JSON object per line. |
union |
Every option the tool has ever had, each with its interval. |
union_of |
The union over chain; see |
Attributes:
| Name | Type | Description |
|---|---|---|
EXTRACTOR |
The extractor generation that produced an observation. |
|
PLATFORM_PRIORITY |
Whose words to keep when two platforms describe one option differently. |
EXTRACTOR
module-attribute
¶
The extractor generation that produced an observation.
Recorded per release so improving _toolhelp/_toolspec, or a tool
flipping between the click and --help paths, rewrites state without
counting as the tool having changed. Bump it when extraction starts
producing different words for the same tool, and a gather will offer those
releases again: a reading is only as good as the extractor that took it.
2, reading each release in the era it shipped in. Under today's
dependencies twine 5.1.0 indexes metadata["home-page"], which
importlib_metadata 8 raises on, so it died before argparse ran and three
releases were recorded with no options at all. Pinning the resolution and
the interpreter to the release's own date changes what extraction can see,
which is exactly what this number is for.
3, reading a tool's description rather than the furniture around it.
A manual names itself after an en dash on mdoc pages, which the NAME
pattern did not match, so every OpenSSH page fell back to its running
header: SSH(1) General Commands Manual SSH(1), justified to whatever
width the reader rendered at. A tool that signs its help instead of
describing itself, git-cliff 2.13.1, markdownlint-cli2's banner and
URL, had the signature stored as its description, and bun's trailing
build stamp went in with the sentence it followed. Each of those made a
version bump read back as the tool rewording itself, and none of them was
ever what the tool said it did.
4, reading the builder docker actually installs. docker build is
buildx wherever buildx is installed, and the driver installs it, but with
DOCKER_BUILDKIT unset the CLI only routes build that way for a Linux
daemon and a reader has no daemon. Linux and macOS read buildx while
Windows read the builder docker shipped with before 2019, so one verb was
stored as two surfaces and twelve options were recorded as a per-platform
difference that no user has. The opt-in is pinned for the read now.
PLATFORM_PRIORITY
module-attribute
¶
Whose words to keep when two platforms describe one option differently.
A tie-break, and nothing more. The store keeps one copy of an option's text,
so without a fixed, order-independent pick, alternating matrix legs would
flip a divergent help string every week, and every flip is a revert in a
store whose whole question is "did anything change". Fixed and explicit
because sorted() is not it: ASCII puts macOS after Windows.
LossyReading ¶
Bases: Exception
A reading that lost bytes on the way in, refused rather than stored.
U+FFFD is the decoder saying it could not represent something it read.
Whatever the tool printed there, this is not it, and because help text
is state, storing it manufactures an event: djLint's banner · arrived
as one cp1252 byte on Windows, decoded to U+FFFD under UTF-8, and the
store recorded 1.43.2 as having changed a description that never moved.
Refusing costs one release on one platform, reported as a hole and filled by the next run. Recording costs the store its meaning, because nothing downstream can tell a mangled byte from a real edit.
Chain
dataclass
¶
Chain(versions: list[str], seen: dict[str, Observation])
A record resolved once: every version read, newest first, with its observation.
The union asks the same questions of every version for every option, so the record is resolved one time and read from here, never through the record again.
Attributes:
| Name | Type | Description |
|---|---|---|
versions |
list[str]
|
The versions read, newest first. |
seen |
dict[str, Observation]
|
Each version's observation. |
Methods:
| Name | Description |
|---|---|
of |
record resolved; with upto, only the versions up to and including it. |
surface |
The help and verbs of version. |
platforms |
Who read version. |
absent |
Who looked at version and did not find each option, by |
of
classmethod
¶
record resolved; with upto, only the versions up to and including it.
Raises:
| Type | Description |
|---|---|
ValueError
|
when upto is not a version the record has read, or nothing was read at all. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
surface ¶
platforms ¶
absent ¶
Who looked at version and did not find each option, by verb\toption.
surface_of ¶
A ToolSpec reduced to what a release is, losing nothing else.
Refuses a reading that lost bytes, see LossyReading. This is the one
door every stored surface comes through, whichever task minted it.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
delta ¶
How to step back from newer to older, per option.
Three moves, and an empty delta means the release was observed and changed nothing, which is not the same as a release nobody looked at. Those are simply absent.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
fold ¶
One release seen by several platforms → one surface and its sidecar.
readings maps platform to that platform's surface for a single release. Folding before the chain is touched is what keeps a matrix run from writing churn into history: an option only Linux has would otherwise be inserted, then dropped by macOS, then resurrected by Windows, each step a real delta. Folded first, the chain sees one finished surface and one sidecar.
An option any platform saw is in the surface, the union, so nothing
observed is lost, and the platforms that looked without finding it are
the sidecar. Divergent text is settled by PLATFORM_PRIORITY.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
versions ¶
Every version read, newest first: the versions whose delta carries a surface.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
floor ¶
observation ¶
observation(record: Record, version: str) -> Observation | None
What version accepted and who read it, or None when no reading was taken.
A version the record does not track answers None too: to a reader
of surfaces an unknown version and an unread one are one case.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
at ¶
The surface of version, its help and verbs, or None when it was never read.
Shared with the record, not copied: a caller that changes it copies it first.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
platforms_of ¶
The platforms that read version; empty when none did.
absent_of ¶
Who looked at version and did not find each option, keyed verb\toption.
A bare verb\t marks the whole verb missing. Only ever what was seen
to be missing: every platform named read the version.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
new ¶
new(name: str, *, kind: str, version: str, date: str, surface: dict[str, Any], platforms: list[str], prime: str = '', runtime: str = '') -> Record
A record of one version read. A record this short is a valid record, which is what lets a tool ship before anything has been primed. prime is the oldest version the history will reach, the driver's provision floor, stamped on the axis when one is declared; runtime is what an npm package runs on, stamped the same way.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
place ¶
place(record: Record, *, version: str, date: str, surface: dict[str, Any], platforms: list[str], absent: dict[str, list[str]] | None = None) -> Record | None
version placed at its own position in the record, wherever that is.
Above the newest, below the oldest, or between two the record already holds: the deltas are renumbered and the version after it re-anchored, and nothing any other version resolves to moves. What it buys is that gathering need not be ordered: installing a release and reading its help depends on no other release having been read, so a walk fetches in whatever order it likes and assembles as results arrive. A release that would not install stops being fatal to a tool's whole walk, since the gap is filled by a later run.
A gap costs precision until it is filled, not correctness. An option that arrived in the missing release reads as arriving at the next release that was read, the same honest imprecision the record carries wherever an index has no build to offer.
A version the record tracks but never read, one with an artifact
alone, takes this reading as its first. Returns None for a version
already read, which is left exactly as it is.
Raises:
| Type | Description |
|---|---|
ValueError
|
when version and date tie a version already there on every component the comparator has, since there is then no honest place for it. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 | |
merge ¶
merge(record: Record, *, version: str, surface: dict[str, Any], platforms: list[str], absent: dict[str, list[str]] | None = None) -> tuple[Record, bool]
Fold another platform's reading into a version the record already has.
The other way a reading reaches the record beside place, and the one
a matrix needs: a version observed on macOS in May and on Windows in
July is one version with two witnesses, not two records.
Merging never removes an option. An absence is recorded in the sidecar,
where it says who failed to find it rather than that it stopped
existing, so the surface only grows, and the versions either side of
this one move only when the tool differs, never when coverage does.
The reading is stamped with today's EXTRACTOR, whatever it found.
Returns the record and whether the stored surface changed. A merge
that only widened coverage answers False and costs the neighbours
nothing. A version tracked but never read takes the reading whole;
a version the record does not track is left alone.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 | |
changed ¶
Whether version's reading moved the surface against the version read before it.
The release decision, answered from the record rather than remembered from arrival order: a gap just below a version makes its delta span the gap, so the change is attributed to the version actually read. The oldest version read has nothing below it to have changed from.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
changes ¶
What changed between two versions read, as one step.
The net effect, not a concatenation of the steps between: an option a tool added and then withdrew across the span cancels out, which is what someone reading a release note wants to know. Computed from both ends' surfaces, so it cannot disagree with the record.
Returned in the shape of delta and read the same way round: drop
is what the newer version added, add is what it removed, because it
is a step back from until to since.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
spellings ¶
How version spells each option key on the command line.
A step records the option's Python-side name, which is what the
surface is keyed by; a reader of a release note recognises
--all-files. The flags live in the surface, so the spelling is a
lookup rather than something the step has to carry.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
load ¶
The record in the file path, or None when there is none yet.
Raises:
| Type | Description |
|---|---|
RecordError
|
for a record that is there and does not validate; a broken record is corrected, never read as no record. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
save ¶
union ¶
Every option the tool has ever had, each with its interval.
The stub renders this rather than the newest version alone: a removed flag stays completable, because the reader may be running a version that still has it, and its docstring says when it went. An option's properties come from the newest version that had it, the most recent word the tool said about itself.
since is left empty for anything already present at the oldest
version read. The record reaches only as far as it was primed, and
"at or before the floor" is not a since. With upto, the union
runs to that version and no further: what a reader at that version
may be told, which is what its stub in the index carries.
Raises:
| Type | Description |
|---|---|
ValueError
|
when upto is not a version the record has read. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
union_of ¶
The union over chain; see union.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 | |