Skip to content

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 None when no reading was taken.

at

The surface of version, its help and verbs, or None when it was never read.

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.

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 None when there is none yet.

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 union.

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

EXTRACTOR = 4

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

PLATFORM_PRIORITY = ('Linux', 'macOS', 'Windows')

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 verb\toption.

versions instance-attribute

versions: list[str]

seen instance-attribute

of classmethod

of(record: Record, *, upto: str = '') -> Chain

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
@classmethod
def of(cls, record: Record, *, upto: str = "") -> Chain:
    """*record* resolved; with *upto*, only the versions up to and including it.

    Raises:
        ValueError: when *upto* is not a version the record has read,
            or nothing was read at all.
    """
    from livery.toolroom.store import observations

    found = list(observations(record))
    if upto:
        spots = [n for n, seen in enumerate(found) if seen.version == upto]
        if not spots:
            raise ValueError(
                f"{record.name}: no reading of {upto}; the versions read are"
                f" {', '.join(seen.version for seen in found) or 'none'}"
            )
        found = found[: spots[0] + 1]
    if not found:
        raise ValueError(f"{record.name}: no version was read")
    return cls(
        [seen.version for seen in reversed(found)], {s.version: s for s in found}
    )

surface

surface(version: str) -> dict[str, Any]

The help and verbs of version.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
def surface(self, version: str) -> dict[str, Any]:
    """The help and verbs of *version*."""
    seen = self.seen[version]
    return {"help": seen.help, "verbs": seen.verbs}

platforms

platforms(version: str) -> list[str]

Who read version.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
def platforms(self, version: str) -> list[str]:
    """Who read *version*."""
    return list(self.seen[version].platforms)

absent

absent(version: str) -> dict[str, list[str]]

Who looked at version and did not find each option, by verb\toption.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
def absent(self, version: str) -> dict[str, list[str]]:
    """Who looked at *version* and did not find each option, by `verb\\toption`."""
    return _flatten(self.seen[version].absent)

surface_of

surface_of(spec: ToolSpec) -> dict[str, Any]

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
def surface_of(spec: ToolSpec) -> dict[str, Any]:
    """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.
    """
    surface = _surface(spec)
    _refuse_lossy(spec, surface)
    return surface

delta

delta(newer: dict[str, Any], older: dict[str, Any]) -> dict[str, Any]

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
def delta(newer: dict[str, Any], older: dict[str, Any]) -> dict[str, Any]:
    """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.
    """
    out: dict[str, Any] = {}
    new_opts, old_opts = _flat(newer), _flat(older)
    if drop := sorted(set(new_opts) - set(old_opts)):
        out["drop"] = drop  # the newer release added these
    if add := sorted(set(old_opts) - set(new_opts)):
        out["add"] = {key: old_opts[key] for key in add}  # ...and removed these
    revert = {
        k: old_opts[k]
        for k in old_opts.keys() & new_opts.keys()
        if old_opts[k] != new_opts[k]
    }
    if revert:
        out["revert"] = dict(sorted(revert.items()))
    if verbs := _verb_delta(newer, older):
        out["verbs"] = verbs
    if older.get("help", "") != newer.get("help", ""):
        out["help"] = older.get("help", "")
    return out

fold

fold(readings: dict[str, dict[str, Any]]) -> tuple[dict[str, Any], dict[str, list[str]]]

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
def fold(
    readings: dict[str, dict[str, Any]],
) -> tuple[dict[str, Any], dict[str, list[str]]]:
    """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`.
    """
    looked = list(readings)
    surface: dict[str, Any] = {"help": "", "verbs": {}}
    missing: dict[str, list[str]] = {}

    def rank(platform: str) -> int:
        order = PLATFORM_PRIORITY
        return order.index(platform) if platform in order else len(order)

    for platform in sorted(looked, key=rank):  # best last: it overwrites
        surface["help"] = readings[platform].get("help", "") or surface["help"]
    for platform in sorted(looked, key=rank):
        for verb_name, verb in readings[platform].get("verbs", {}).items():
            held = surface["verbs"].setdefault(verb_name, _empty_verb())
            held.update({k: v for k, v in verb.items() if k != "options"})
            held["options"].update(verb.get("options", {}))

    for verb_name, verb in surface["verbs"].items():
        for platform in looked:
            seen = readings[platform].get("verbs", {})
            if verb_name not in seen:
                missing.setdefault(f"{verb_name}\t", []).append(platform)
                continue
            for option_name in verb["options"]:
                if option_name not in seen[verb_name].get("options", {}):
                    missing.setdefault(f"{verb_name}\t{option_name}", []).append(
                        platform
                    )
    # A whole verb nobody found on a platform is said once, not per option.
    for verb_name in surface["verbs"]:
        for platform in missing.get(f"{verb_name}\t", []):
            for key in list(missing):
                if key.startswith(f"{verb_name}\t") and key != f"{verb_name}\t":
                    missing[key] = [p for p in missing[key] if p != platform]
    return {"help": surface["help"], "verbs": _ordered(surface["verbs"])}, {
        key: who for key, who in missing.items() if who
    }

versions

versions(record: Record) -> list[str]

Every version read, newest first: the versions whose delta carries a surface.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
def versions(record: Record) -> list[str]:
    """Every version read, newest first: the versions whose delta carries a surface."""
    from livery.toolroom.store import observations

    return [seen.version for seen in reversed(observations(record))]

floor

floor(record: Record) -> str

The oldest version read, how far back the record reaches.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
def floor(record: Record) -> str:
    """The oldest version read, how far back the record reaches."""
    return versions(record)[-1]

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
def 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.
    """
    from livery.toolroom.store import surface_at

    if version not in record.versions:
        return None
    return surface_at(record, version)

at

at(record: Record, version: str) -> dict[str, Any] | None

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
def at(record: Record, version: str) -> dict[str, Any] | None:
    """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.
    """
    seen = observation(record, version)
    if seen is None:
        return None
    return {"help": seen.help, "verbs": seen.verbs}

platforms_of

platforms_of(record: Record, version: str) -> list[str]

The platforms that read version; empty when none did.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
def platforms_of(record: Record, version: str) -> list[str]:
    """The platforms that read *version*; empty when none did."""
    seen = observation(record, version)
    return list(seen.platforms) if seen else []

absent_of

absent_of(record: Record, version: str) -> dict[str, list[str]]

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
def absent_of(record: Record, version: str) -> dict[str, list[str]]:
    """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.
    """
    seen = observation(record, version)
    return _flatten(seen.absent) if seen else {}

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
def 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.
    """
    from livery.toolroom.store import Record

    return Record(
        name,
        kind=kind,
        prime=prime,
        runtime=runtime,
        deltas=(
            RecordDelta(
                1,
                version,
                date,
                surface=Surface(
                    tuple(sorted(platforms)),
                    EXTRACTOR,
                    surface.get("help", ""),
                    _ordered(surface.get("verbs", {})),
                ),
            ),
        ),
    )

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
def 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:
        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.
    """
    from livery.toolroom.bench._toolfetch import _patchlevel

    readings = _readings(record)
    for reading in readings:
        if reading.delta.version == version:
            if reading.surface is not None:
                return None
            return _set(
                record,
                version,
                surface=surface,
                platforms=platforms,
                absent=absent or {},
                extractor=EXTRACTOR,
            )

    def placed(name: str, when: str) -> tuple[tuple[int, ...], int, str]:
        # The patchlevel rides between the tuple and the date because
        # `version_tuple` deliberately reads OpenSSH's `9.9p1` and `9.9p2`
        # as one base and leaves the tie to the caller. Two patchlevels of
        # one release often share a day, so the date alone cannot break it.
        return version_tuple(name), _patchlevel(name), when

    mine = placed(version, date)
    keys = [placed(r.delta.version, r.delta.date) for r in readings]
    if mine in keys:
        raise ValueError(f"{version} ties a version already in the record")
    spot = sum(1 for key in keys if key < mine)
    readings.insert(
        spot,
        _Reading(
            RecordDelta(0, version, date),
            {
                "help": surface.get("help", ""),
                "verbs": _ordered(surface.get("verbs", {})),
            },
            sorted(platforms),
            EXTRACTOR,
            absent or {},
        ),
    )
    return _assemble(record, readings)

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
def 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.
    """
    if version not in record.versions:
        return record, False
    stored = at(record, version)
    if stored is None:
        return (
            _set(
                record,
                version,
                surface=surface,
                platforms=platforms,
                absent=absent or {},
                extractor=EXTRACTOR,
            ),
            True,
        )
    was = platforms_of(record, version)
    observers = sorted({*was, *platforms})
    before = json.dumps(stored, sort_keys=True)

    known = _flat(stored)
    incoming = _flat(surface)
    missing = {key: list(who) for key, who in absent_of(record, version).items()}
    merged = json.loads(json.dumps(stored))  # a deep copy; surfaces are plain data

    for verb_name, reading in surface.get("verbs", {}).items():
        # A verb's own fields, its summary and its positional shape, settle
        # by the same rule its options do. Left out, they would be frozen at
        # whatever the first reading said, and no better extractor could
        # ever replace them, which is the one thing a record of
        # observations must never need a hand to fix.
        held = merged.setdefault("verbs", {}).setdefault(verb_name, _empty_verb())
        fields = {k: v for k, v in reading.items() if k != "options"}
        chosen = _preferred(
            {k: v for k, v in held.items() if k != "options"}
            if verb_name in stored.get("verbs", {})
            else None,
            fields,
            was,
            platforms,
            missing,
            f"{verb_name}\t",
        )
        held.update(chosen)

    for key, option in incoming.items():
        verb_name, _, option_name = key.partition("\t")
        verb = merged.setdefault("verbs", {}).setdefault(verb_name, _empty_verb())
        if key not in known:
            # Nobody who looked before found it, or it would be stored.
            missing[key] = [p for p in was if p not in platforms]
        verb["options"][option_name] = _preferred(
            known.get(key), option, was, platforms, missing, key
        )
    for key in known:
        if key not in incoming:
            missing.setdefault(key, [])
            missing[key] = sorted({*missing[key], *platforms})
    for key in list(missing):
        if key in incoming:
            missing[key] = [p for p in missing[key] if p not in platforms]
    for key, who in (absent or {}).items():
        missing[key] = sorted({*missing.get(key, []), *who})

    # The tool's own description settles by the rule its verbs' summaries
    # already use, never by whichever reading is non-empty. Ranked, an
    # empty reading from the platform that owns the text replaces it, so a
    # signature a better extractor stops reading as a description can be
    # corrected, while a lower-ranked platform's silence still cannot
    # erase a good line.
    widened = {
        "help": _preferred(
            {"help": stored.get("help", "")},
            {"help": surface.get("help", "")},
            was,
            platforms,
            missing,
            _TOOL_HELP,
        )["help"],
        "verbs": _ordered(merged.get("verbs", {})),
    }
    tidy = {
        key: [p for p in sorted(set(who)) if p in observers]
        for key, who in sorted(missing.items())
    }
    moved = json.dumps(widened, sort_keys=True) != before
    return (
        _set(
            record,
            version,
            surface=widened,
            platforms=observers,
            absent={key: who for key, who in tidy.items() if who},
            extractor=EXTRACTOR,
        ),
        moved,
    )

changed

changed(record: Record, version: str) -> bool

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
def changed(record: Record, version: str) -> bool:
    """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.
    """
    delta = record.delta_for(version)
    if delta.surface is None:
        return False
    chain = versions(record)
    if chain.index(version) + 1 >= len(chain):
        return False
    return delta.surface.help is not None or bool(delta.surface.verbs)

changes

changes(record: Record, *, since: str, until: str = '') -> dict[str, Any]

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
def changes(record: Record, *, since: str, until: str = "") -> dict[str, Any]:
    """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*.
    """
    newer = at(record, until or versions(record)[0])
    older = at(record, since)
    if newer is None or older is None:
        return {}
    return delta(newer, older)

spellings

spellings(record: Record, version: str, keys: Iterable[str]) -> dict[str, str]

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
def spellings(record: Record, version: str, keys: Iterable[str]) -> dict[str, str]:
    """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.
    """
    surface = at(record, version) or {}
    found: dict[str, str] = {}
    for key in keys:
        verb, _, option = key.partition("\t")
        entry = surface.get("verbs", {}).get(verb, {}).get("options", {}).get(option)
        flags = (entry or {}).get("flags") or []
        # The long spelling when there is one: `--all-files` over `-a`.
        found[key] = max(flags, key=len) if flags else option
    return found

load

load(path: Path) -> Record | None

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
def load(path: Path) -> Record | None:
    """The record in the file *path*, or `None` when there is none yet.

    Raises:
        RecordError: for a record that is there and does not validate;
            a broken record is corrected, never read as no record.
    """
    from livery.toolroom.store import Record

    if not path.is_file():
        return None
    return Record.load(path)

save

save(record: Record, path: Path) -> None

Write record to the file path, one JSON object per line.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
def save(record: Record, path: Path) -> None:
    """Write *record* to the file *path*, one JSON object per line."""
    record.save(path.parent)

union

union(record: Record, *, name: str, in_process: bool = False, upto: str = '') -> ToolSpec

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
def union(
    record: Record, *, name: str, in_process: bool = False, upto: str = ""
) -> ToolSpec:
    """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:
        ValueError: when *upto* is not a version the record has read.
    """
    return union_of(Chain.of(record, upto=upto), name=name, in_process=in_process)

union_of

union_of(chain: Chain, *, name: str, in_process: bool = False) -> ToolSpec

The union over chain; see union.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_surfaces.py
def union_of(chain: Chain, *, name: str, in_process: bool = False) -> ToolSpec:
    """The union over *chain*; see `union`."""
    from livery.toolroom.store import Option, ToolSpec, Verb

    versions_ = chain.versions  # newest first
    floor_ = versions_[-1]
    surfaces = {version: chain.surface(version) for version in versions_}
    verdicts = _verdicts(chain, surfaces)

    verbs: dict[str, dict[str, Any]] = {}
    first: dict[tuple[str, str], str] = {}
    last: dict[tuple[str, str], str] = {}
    for version in reversed(versions_):  # oldest first, so "first" means first
        surface = surfaces[version]
        for verb_name, verb in surface.get("verbs", {}).items():
            verbs.setdefault(verb_name, verb)
            merged = {
                **verbs[verb_name].get("options", {}),
                **verb.get("options", {}),
            }
            # Sorted, so the stub does not reorder itself as the record
            # deepens: merged oldest-first, insertion order would otherwise
            # mean "which version mentioned it first".
            verbs[verb_name] = {**verb, "options": dict(sorted(merged.items()))}
            for option_name in verb.get("options", {}):
                key = (verb_name, option_name)
                first.setdefault(key, version)
                last[key] = version

    newer = {older: new for new, older in itertools.pairwise(versions_)}
    spec = spec_from(
        {"help": surfaces[versions_[0]].get("help", ""), "verbs": verbs},
        name=name,
        version=versions_[0],
        in_process=in_process,
    )
    return ToolSpec(
        name=spec.name,
        help=spec.help,
        version=spec.version,
        in_process=spec.in_process,
        verbs=tuple(
            Verb(
                name=verb.name,
                help=verb.help,
                wraps=verb.wraps,
                positional=verb.positional,
                lead=verb.lead,
                not_on=verdicts.get(f"{verb.name}\t", ()),
                options=tuple(
                    Option(
                        **_option_fields(
                            option,
                            not_on=verdicts.get(f"{verb.name}\t{option.name}", ()),
                            since=""
                            if first[(verb.name, option.name)] == floor_
                            or _only_here(
                                chain,
                                first[(verb.name, option.name)],
                                verb.name,
                                option,
                            )
                            else first[(verb.name, option.name)],
                            until=newer.get(last[(verb.name, option.name)], "")
                            if last[(verb.name, option.name)] != versions_[0]
                            and _corroborated(
                                chain, last[(verb.name, option.name)], verb.name, option
                            )
                            else "",
                        )
                    )
                    for option in verb.options
                ),
            )
            for verb in spec.verbs
        ),
    )