version: ReleaseKey, a release-group key that needs no render

[jonyoder]

What

Adds version.ReleaseKey — a version's position in PEP 440's release order: its epoch and its release segments with trailing zeros stripped, and nothing else. Version.ReleaseKey() derives one, ReleaseKey.Compare orders two, ReleaseKey.String renders the smallest version string carrying a key.

It is deliberately coarser than the version order: 1.0, 1.0.0, 1.00, 1.0a1, 1.0.post3.dev2 and 1.0+ubuntu1 all occupy one position, because PEP 440 gives every one of them epoch 0 and, after stripping, the release tuple (1).

Why

Until now the only way to reach a version's release from outside this package was BaseVersion(), which renders the version back to text — a bytes.Buffer plus one math/big decimal conversion per segment — and left the caller splitting the result apart again.

go-pyresolver's PEP 440 set algebra did exactly that, once per candidate version per containment test. Measured at go-pyresolver v0.6.0, that derivation is 32.0% of a warm app-set resolution and 23.1% of wide-versions, with math/big.nat.itoa alone at 13.9%.

Deriving the key from the parsed fields instead:

BenchmarkReleaseKeyVsBaseVersionSplit/ReleaseKey-16          16.15 ns/op      0 B/op    0 allocs/op
BenchmarkReleaseKeyVsBaseVersionSplit/BaseVersionSplit-16   219.60 ns/op    192 B/op   10 allocs/op

13.6x faster, and the allocations go to zero — which is the point, since what the churn was buying was garbage collection. Comparing two keys is ~3 ns packed, ~8–11 ns on the general path.

How

Most keys pack into three words of six 32-bit segment fields, ordered by three integer comparisons. The rest — a nonzero epoch, more than six segments, or a segment at or above 2^32 — compare as arbitrary-precision integers. PEP 440 puts no ceiling on an epoch or a release segment (the grammar is [0-9]+) and datestamped and calendar versions push real segments high, so the general path is not optional.

packVersion's release-word assembly moves out into a shared packRelease, so the layout has one definition rather than two that could drift. That drift is the failure mode no single-encoding test can see: two copies would each order versions consistently within themselves while disagreeing with each other.

No allocation anywhere: the epoch is a by-value copy of a math/big header, and the release is a subslice of the Version's own — with its capacity clipped, so a later append by a holder of the key cannot write through into the Version's segments. That is the same aliasing hazard that made go-version's Parts.Padding a data race between two copies of one Version.

The zero value, which differs from Compare on purpose

The zero ReleaseKey compares equal to the key of "0" and "0.0", because those strip to an empty release too — where Version.Compare sorts an uninitialized Version strictly below every real version. That distinction lives in the full version order; the release grouping genuinely cannot see it. Both behaviours are asserted side by side in TestReleaseKeyZeroValue, so anyone who "fixes" one to match the other reads why first.

Testing

Check	What holds it up
TestReleaseKeyConformanceFixture	pypa/packaging 26.2's own release key (Version._key[0:2]), frozen into pypa-26.2-releasekey.ranked.gz. The only test holding ReleaseKey to the reference implementation directly rather than through Version's parse. Covers epochs and segments beyond a machine word, eight-segment releases, and leading zeros inside a segment — none of which the existing packed grid contains.
TestReleaseKeyMatchesBaseVersionSplit	the render-and-split derivation this replaces, component by component over 348,752 corpus versions plus 980,000 ordering pairs. This is what says the migration changes no answer.
TestReleaseKeyPackedAgreesWithGeneral	the two encodings against each other, pairwise, with a guard that fails if nothing in the sample packed (which would pass vacuously).
TestReleaseKeyRefinesVersionOrder	the frozen full-version ranks: PEP 440's key is lexicographic with (epoch, release) first, so a strictly smaller release key must rank strictly below. Independent of the render-and-split reference.
TestPackReleaseIsTheOnlyReleaseLayout	the refactor — every packable version's whole-version key must carry exactly packRelease's words.
TestReleaseKeyAllocatesNothing	AllocsPerRun == 0 for both derivation and comparison, on five shapes including the unpackable ones.
TestReleaseKeyDoesNotAliasIntoTheVersion	the capacity clip, by appending and checking the Version did not move.
Groups / ordering / total-order / suffix-ignoring	hand-checked tables.

Each of the four load-bearing assertions was mutation-checked: removing the capacity clip, packing regardless of epoch, breaking the length tie-break in the general path, and under-stripping trailing zeros each turn the suite red, with the failure naming the defect.

go test ./... green, gofmt -l silent, golangci-lint run ./... (v2.11.2, from the module root) reports 0 issues.

Compatibility

Purely additive. No existing behaviour changes: the packVersion refactor is exact — the old strip loop's smallUint(seg, packedSegMax) == 0 test and the new big.Int.Sign() != 0 test agree on every input the grammar admits.

🤖 Generated with Claude Code