Skip to content

livery.toolroom.bench._toolfetch

livery.toolroom.bench._toolfetch

Past releases of a curated tool, for priming its option history.

Provisioning fetches the latest of everything into one prefix. Priming is the other direction: one specific release at a time, into a throwaway environment, read once and thrown away — walking backwards from the newest because the current version is the one that matters most, and because a backward walk appends to the history rather than rewriting it.

The listable tiers: PyPI (uv), npm (node), release assets from GitHub, GitLab and Gitea — which covers bun's own releases too — CPython, whose index is the provisioned uv's own, and docker's static-build directory. What remains unlistable is the system tier (git, read from the host). A tool footman cannot list is named and skipped rather than silently treated as having no history — the same doctrine audit follows.

Classes:

Name Description
Release

One published release: what to install, and when it was published.

Unreachable

An index that could not be read at all.

Functions:

Name Description
read_python

The interpreter to read a release on: its era, raised to its minimum.

can_list

Whether this tool's past releases can be enumerated.

releases

Every published release, newest first, whatever the tier.

nodejs_assets

[(asset name, download url)] for node at version, one per build.

dotnet_assets

[(asset name, download url)] for the SDK at version, one per build.

home_beside

The throwaway home that belongs to the release in bindir.

install_plugin

Place the plugin release a user of that tool release would have had.

install

Install one release into its own directory; return the bin to read.

Attributes:

Name Type Description
PYPI
TIMEOUT
PYTHON_RELEASES

When each CPython arrived, newest first — the eras a release is read in.

LISTABLE

The tiers with a release index footman can read. system is absent

NODEJS_FILES

The builds node publishes per release that the six hosts map to, by

DOTNET_FILES

The SDK builds Microsoft publishes per release that the six hosts map

PYPI module-attribute

PYPI = 'https://pypi.org/pypi/{package}/json'

TIMEOUT module-attribute

TIMEOUT = 30

PYTHON_RELEASES module-attribute

PYTHON_RELEASES = (('3.14', '2025-10-07'), ('3.13', '2024-10-07'), ('3.12', '2023-10-02'), ('3.11', '2022-10-24'), ('3.10', '2021-10-04'))

When each CPython arrived, newest first — the eras a release is read in.

A release has to be read in roughly the world it shipped into or it cannot be read at all: twine 5.1.0 indexes metadata["home-page"] at import, a key importlib_metadata 8 stopped returning and started raising KeyError on, so under today's resolution it dies before argparse runs. --exclude-newer at the release's own date fixes that, and only resolves on an interpreter old enough to have wheels from that date — a 2022 cryptography has no cp314 build and will not compile against one.

So the interpreter is the newest CPython that existed when the release shipped, not one fixed version. That is what makes the reading of its era rather than merely old: a 2026 release is read on 3.14 exactly as it is today, and a 2022 release on 3.11, because that is what anyone running it then would have seen.

It also settles what a fixed floor could not. Python 3.13 taught argparse to print every alias, so pytest reports --junitxml alongside --junit-xml there and only --junit-xml below it. Reading everything on one old interpreter would have quietly dropped those aliases from releases that really do show them; reading each release in its own era records the aliases exactly where they appeared, and the surface corrects itself as the walk crosses October 2024.

Upstream release days, not the build dates in uv's index — python-build- standalone shipped 3.11 in January 2023, three months late, which would have read that autumn's releases on 3.10.

LISTABLE module-attribute

LISTABLE = ('uv', 'node', 'nodejs', 'nuget', 'dotnet', 'github', 'gitlab', 'gitea', 'bun', 'python', 'docker', 'man')

The tiers with a release index footman can read. system is absent because git and docker are read from the host and have no fetch source.

NODEJS_FILES module-attribute

NODEJS_FILES = {'darwin-arm64': 'tar.gz', 'darwin-x64': 'tar.gz', 'linux-x64': 'tar.gz', 'linux-arm64': 'tar.gz', 'win-x64': 'zip', 'win-arm64': 'zip'}

The builds node publishes per release that the six hosts map to, by node's own platform spelling, with each one's archive suffix.

DOTNET_FILES module-attribute

DOTNET_FILES = {'osx-arm64': 'tar.gz', 'osx-x64': 'tar.gz', 'linux-x64': 'tar.gz', 'linux-arm64': 'tar.gz', 'win-x64': 'zip', 'win-arm64': 'zip'}

The SDK builds Microsoft publishes per release that the six hosts map to, by runtime identifier and archive suffix.

Release dataclass

Release(version: str, tag: str = '', date: str = '', requires_python: str = '', published: str = '')

One published release: what to install, and when it was published.

Attributes:

Name Type Description
version str
tag str

What the forge calls this release, when that differs from the version

date str

YYYY-MM-DD, from the index. Not the ordering key — the version is —

requires_python str

The release's own Requires-Python, verbatim from the index. What

published str

The day the release finished publishing, where date is the day it

version instance-attribute

version: str

tag class-attribute instance-attribute

tag: str = ''

What the forge calls this release, when that differs from the version it reports — bun tags bun-v1.3.13 for a binary answering 1.3.13. Carried rather than guessed: an install that pattern-matched the tag could only ever cover the spellings someone had already met.

date class-attribute instance-attribute

date: str = ''

YYYY-MM-DD, from the index. Not the ordering key — the version is — but what breaks a tie between two builds of one base (0.6.0-wk.5), which is the one comparison a version cannot make.

requires_python class-attribute instance-attribute

requires_python: str = ''

The release's own Requires-Python, verbatim from the index. What keeps the floor from becoming a ceiling: zensical asks for >=3.10 today and something will ask for more tomorrow, so the interpreter to read on is the higher of this and READ_PYTHON, never READ_PYTHON flat.

published class-attribute instance-attribute

published: str = ''

The day the release finished publishing, where date is the day it started. Usually the same day and usually uninteresting, but publishing is a window rather than an instant: ninja 1.11.1 took 76 days to upload its seventeen files, cmake 4.3.1 three. A date cutoff at the near edge of that window filters out the release's own later files, which is how a release ends up unable to install itself.

Unreachable

Unreachable(source: str, cause: object)

Bases: Exception

An index that could not be read at all.

Raised rather than returned as an empty listing, because the two are opposite answers that used to share a value. A release job asks "is there anything new" and stops when the answer is no; a throttled registry answering {} would end that job with "nothing new, nothing to release" when the truth is that nobody looked. An exception is the shape that cannot be read past by accident.

Attributes:

Name Type Description
source
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolfetch.py
def __init__(self, source: str, cause: object) -> None:
    super().__init__(f"cannot read {source}: {cause}")
    self.source = source

source instance-attribute

source = source

read_python

read_python(requires_python: str = '', date: str = '') -> str

The interpreter to read a release on: its era, raised to its minimum.

The era is the newest CPython that had shipped by date. A release that will not run on it — one asking for more than its own era offered, which happens while a Python is still in prerelease — is read on the oldest it will run on instead. Without a date there is no era to pick, so the newest is used, which is what reading an unstamped release already meant.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolfetch.py
def read_python(requires_python: str = "", date: str = "") -> str:
    """The interpreter to read a release on: its era, raised to its minimum.

    The era is the newest CPython that had shipped by *date*. A release
    that will not run on it — one asking for more than its own era offered,
    which happens while a Python is still in prerelease — is read on the
    oldest it will run on instead. Without a date there is no era to pick,
    so the newest is used, which is what reading an unstamped release
    already meant.
    """
    era = (
        next((v for v, since in PYTHON_RELEASES if date >= since), READ_PYTHON)
        if date
        else PYTHON_RELEASES[0][0]
    )
    found = _MIN_PYTHON.search(requires_python or "")
    minimum = int(found.group(1)) if found else 0
    return f"3.{max(int(era.split('.')[1]), minimum)}"

can_list

can_list(driver: Driver) -> bool

Whether this tool's past releases can be enumerated.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolfetch.py
def can_list(driver: Driver) -> bool:
    """Whether this tool's past releases can be enumerated."""
    return driver.provision.kind in LISTABLE and driver.source != "manual"

releases

releases(driver: Driver) -> list[Release]

Every published release, newest first, whatever the tier.

A tier with no index at all returns nothing: the caller names it as skipped, and a tool nobody can list is not a tool with no history.

An index that exists and could not be read raises Unreachable instead. The two used to share the empty list, which is the wrong shape for the question a release job asks — "is there anything new" answered "no" by a throttled registry ends the job with "nothing to release".

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolfetch.py
def releases(driver: Driver) -> list[Release]:
    """Every published release, **newest first**, whatever the tier.

    A tier with no index at all returns nothing: the caller names it as
    skipped, and a tool nobody can list is not a tool with no history.

    An index that *exists* and could not be read raises `Unreachable`
    instead. The two used to share the empty list, which is the wrong shape
    for the question a release job asks — "is there anything new" answered
    "no" by a throttled registry ends the job with "nothing to release".
    """
    if not can_list(driver):
        # Not just the unlistable tiers: a hand-written stub carries the
        # *default* provision kind, so `bash` would otherwise be looked up on
        # PyPI — where a package by that name exists and is a different thing
        # entirely.
        return []
    kind = driver.provision.kind
    if kind == "uv":
        found = _pypi(driver)
    elif kind == "node":
        found = _npm(driver)
    elif kind in ("github", "gitlab", "gitea", "bun"):
        found = _forge(driver, kind if kind in ("gitlab", "gitea") else "github")
    elif kind == "python":
        found = _uv_python()
    elif kind == "nodejs":
        found = _nodejs_index()
    elif kind == "dotnet":
        found = _dotnet_index()
    elif kind == "nuget":
        found = _nuget(driver)
    elif kind == "docker":
        found = _docker_index()
    elif kind == "man":
        found = _man_index(driver)
    else:
        return []
    found = _stable(found)
    if driver.provision.floor:
        from livery.toolroom.tools import version_tuple

        cut = version_tuple(driver.provision.floor)
        found = [r for r in found if version_tuple(r.version) >= cut]
    return found

nodejs_assets

nodejs_assets(version: str) -> list[tuple[str, str]]

[(asset name, download url)] for node at version, one per build.

Built from the version rather than listed, since node names every build the same way on every release; the asset matcher then picks each host's the way it picks a forge's.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolfetch.py
def nodejs_assets(version: str) -> list[tuple[str, str]]:
    """`[(asset name, download url)]` for node at *version*, one per build.

    Built from the version rather than listed, since node names every
    build the same way on every release; the asset matcher then picks
    each host's the way it picks a forge's.
    """
    tag = f"v{version}"
    return [
        (
            f"node-{tag}-{platform_}.{suffix}",
            _NODEJS_DIST.format(tag=tag, name=f"node-{tag}-{platform_}.{suffix}"),
        )
        for platform_, suffix in NODEJS_FILES.items()
    ]

dotnet_assets

dotnet_assets(version: str) -> list[tuple[str, str]]

[(asset name, download url)] for the SDK at version, one per build.

Built from the version, since Microsoft names every build the same way at a versioned address; the asset matcher then picks each host's the way it picks a forge's.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolfetch.py
def dotnet_assets(version: str) -> list[tuple[str, str]]:
    """`[(asset name, download url)]` for the SDK at *version*, one per build.

    Built from the version, since Microsoft names every build the same
    way at a versioned address; the asset matcher then picks each
    host's the way it picks a forge's.
    """
    return [
        (
            f"dotnet-sdk-{version}-{rid}.{suffix}",
            _DOTNET_SDK.format(version=version, rid=rid, suffix=suffix),
        )
        for rid, suffix in DOTNET_FILES.items()
    ]

home_beside

home_beside(bindir: Path) -> Path

The throwaway home that belongs to the release in bindir.

A plugin is found by looking under the user's home, so reading one without reading the machine's own means giving the tool a different home for as long as it is being read. Keeping it beside the binaries is what lets the reader find it later from the binary alone, with no extra argument threaded through five call sites.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolfetch.py
def home_beside(bindir: Path) -> Path:
    """The throwaway home that belongs to the release in *bindir*.

    A plugin is found by looking under the user's home, so reading one
    without reading the machine's own means giving the tool a different
    home for as long as it is being read. Keeping it beside the binaries
    is what lets the reader find it later from the binary alone, with no
    extra argument threaded through five call sites.
    """
    return bindir.parent / "home"

install_plugin

install_plugin(plugin: Plugin, on_or_before: str, home: Path) -> bool

Place the plugin release a user of that tool release would have had.

Paired by date, newest that is not newer. A plugin has its own release line, so there is no version to match on — but "what shipped alongside" is a fact the two dates settle between them, the same answer every time. A plugin older than any release (or a listing that cannot be reached) leaves the home empty, and the verbs it owns simply read as absent, which is what a walk of an era before the plugin existed should say.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolfetch.py
def install_plugin(plugin: Plugin, on_or_before: str, home: Path) -> bool:
    """Place the plugin release a user of that tool release would have had.

    Paired by date, newest that is not newer. A plugin has its own release
    line, so there is no version to match on — but "what shipped alongside"
    is a fact the two dates settle between them, the same answer every
    time. A plugin older than any release (or a listing that cannot be
    reached) leaves the home empty, and the verbs it owns simply read as
    absent, which is what a walk of an era before the plugin existed
    should say.
    """
    from livery.toolroom.bench import _provision
    from livery.toolroom.tools import version_tuple

    found = _listing(plugin.repo, 3)
    floor = version_tuple(plugin.since) if plugin.since else ()
    dated = [
        r
        for r in found
        if r.date
        and (not on_or_before or r.date <= on_or_before)
        and version_tuple(r.version) >= floor
    ]
    if not dated:
        return False
    release = dated[0]  # _forge orders newest first
    into = home / plugin.path
    into.mkdir(parents=True, exist_ok=True)
    for tag in (release.tag, release.version, f"v{release.version}"):
        if not tag:
            continue
        try:
            assets = _provision.assets_for("github", plugin.repo, tag)
            _name, url = _provision._pick_asset(assets)
            archive = _provision._download(url, home)
            _provision.place_binary(archive, plugin.name, into, launcher=False)
        except (_provision.ProvisionError, OSError, ValueError):
            continue
        return True
    # We know which release belongs here and could not get it — a rate
    # limit, an outage, a withdrawn asset. Read past, that becomes "this
    # docker had no compose", which is a different claim entirely and one
    # that would be written into the history as a removal.
    raise Unreachable(f"{plugin.repo} {release.version}", "could not be placed")

install

install(driver: Driver, release: Release, into: Path) -> Path | None

Install one release into its own directory; return the bin to read.

Per release rather than into a shared prefix, because the point is to read this version's --help and then forget it. None means this release could not be had — the caller ends that tool's walk rather than leaving a hole in the chain.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolfetch.py
def install(driver: Driver, release: Release, into: Path) -> Path | None:
    """Install one release into its own directory; return the `bin` to read.

    Per release rather than into a shared prefix, because the point is to read
    *this* version's `--help` and then forget it. `None` means this release
    could not be had — the caller ends that tool's walk rather than leaving a
    hole in the chain.
    """
    kind = driver.provision.kind
    into.mkdir(parents=True, exist_ok=True)
    if kind == "uv":
        return _install_pypi(driver, release, into)
    if kind == "node":
        return _install_npm(driver, release.version, into)
    if kind == "nodejs":
        return _install_nodejs(release, into)
    if kind == "dotnet":
        return _install_dotnet(release, into)
    if kind == "nuget":
        return _install_nuget(driver, release.version, into)
    if kind in ("github", "gitlab", "gitea", "bun"):
        return _install_asset(driver, release, into)
    if kind == "python":
        return _install_python(release.version, into)
    if kind == "docker":
        return _install_docker(driver, release, into)
    if kind == "man":
        return _install_man(driver, release, into)
    return None