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 |
|
dotnet_assets |
|
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 |
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. |
|
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 |
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
|
|
requires_python |
str
|
The release's own |
published |
str
|
The day the release finished publishing, where |
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 ¶
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
read_python ¶
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
can_list ¶
Whether this tool's past releases can be enumerated.
releases ¶
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
nodejs_assets ¶
[(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
dotnet_assets ¶
[(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
home_beside ¶
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
install_plugin ¶
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
install ¶
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.