feat(toolchains): allow selecting stripped python-build-standalone archives

[gfrankliu]

Hermetic runtimes always used install_only archives, which include debug symbols. The install_only_stripped variants are much smaller; for example, a Python 3.14 zipapp shrinks from 147 MB to 65 MB.

Add the --@rules_python//python/config_settings:py_pbs_distribution flag to select the archive: auto (default, currently install_only), install_only, install_only_stripped, or full. Because it is a build flag, one workspace can build stripped and unstripped runtimes, e.g. for prod and dev.

Toolchains are registered for each archive kind as -install_only_stripped and -full platform variants, like -freethreaded; only the selected runtime is downloaded. If a version or platform has no archive of the selected kind, the install_only archive is used. Built-in manifest entries now include stripped archive hashes for releases from 20240726 onward, sourced from the official SHA256SUMS files.

Fixes #4163

[Copilot]

Copilot review overview

🟡 Changes recommended

Add coverage for the full flavor and address the noted release-note and formatting issues.

Review effort: Lite
Findings: 1 · 3

Open (4)

• Add test coverage for full archive flavor · New
• Use {obj} role for Starlark API attribute · New
• Add issue #4163 reference to news fragment · New
• Wrap lines exceeding maximum length · New

What changed in this PR

Adds configurable Python standalone archive flavors, including stripped archives and fallback selection.

Changes:

• Adds archive_flavor override support.
• Updates manifest ranking and stripped archive hashes.
• Adds tests, documentation, mocks, and release notes.

File	Summary
tests/​support/​mocks/​python_ext.bzl	Updates mock override attributes.
tests/​python/​python_tests.bzl	Tests archive selection and fallback behavior.
python/​versions.bzl	Reuses shared manifest sorting.
python/​private/​runtimes_manifest.txt	Adds stripped archive checksums.
python/​private/​python.bzl	Implements archive flavor configuration.
python/​private/​pbs_manifest.bzl	Defines flavor-aware manifest ranking.
news/​stripped-python-archives.added.md	Adds the release note.
docs/​toolchains.md	Documents archive flavor selection.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[aignas]

There are two ways about this - have the config at the extension level or via config flags. I think I would prefer the later.

Usecase - if I need to optimize the space, I use the stripped version, if not, non-stripped, that may provided extra diagnostic output if the system crashes. I may want to push both variants from the CICD so that dev-like envs can have the larger binaries and prod-like have stripped versions.

Let me know what you think.

[gfrankliu]

There are two ways about this - have the config at the extension level or via config flags. I think I would prefer the later.

Usecase - if I need to optimize the space, I use the stripped version, if not, non-stripped, that may provided extra diagnostic output if the system crashes. I may want to push both variants from the CICD so that dev-like envs can have the larger binaries and prod-like have stripped versions.

Let me know what you think.

Agreed, a flag fits the dev/prod use case much better, since the extension setting locks a workspace to one flavor. My plan: add a //python/config_settings:py_stripped flag (yes/no, default no). Register stripped toolchain variants alongside the regular ones, the same way freethreaded variants work, falling back to install_only for older releases that have no stripped archive. Drop the python.override(archive_flavor) attribute and leave full out of scope. Does that naming and scope sound right?

[rickeylev]

i may want both variants in CICD for some reason

Oh, good point. Yeah, i'd prefer a build-time flag, too.

//python/config_settings:py_stripped flag; yes/no, default: no

Name, values and default: SGTM.

---

Is there a well known term for what the "full" vs "install_only" vs "install_only_stripped" types of archives are? In the code, i called it "archive flavor" for lack of a better term.

I'm somewhat torn as to whether the name should be expressing intent ("--py_stripped=yes" means "i want stripping") or expressing the desired archive type ("--archive_type=install_only_stripped", which means you know you're getting more than just stripping).

[aignas]

Overall plan sounds good. Regarding naming, a few more ideas:

• --py_pbs_distribution=auto|full|install_only|install_only_stripped
• --py_hermetic_toolchain_variant=auto|full|install_only|install_only_stripped

I am of opinion that just using fragments from the archive name to disambiguate may be nice. If they start shipping binaries with different optimizations, that could fit the bill.

[gfrankliu]

Thanks both. I don't know of an established term: PBS's docs call the builds "distributions", but nothing names the full/install_only/stripped distinction specifically.

I like aignas's direction of archive-type values with auto as the default. It's explicit about what you get, auto keeps today's behavior, rules_python could change what auto means later without breaking anyone, and new PBS archive types just become new values. Proposal:

--@rules_python//python/config_settings:py_pbs_distribution=auto|install_only|install_only_stripped|full (default auto = install_only)

One open question: when the selected archive doesn't exist for a version/platform (e.g. stripped archives before 20240726), should we fall back to install_only, or fail toolchain resolution? I'd lean toward falling back and documenting it, since a "no matching toolchain" error is hard to diagnose, but it makes the flag a preference rather than a guarantee.

[aignas]

should we fall back to install_only, or fail toolchain resolution?

+1 for falling back. The user can do the fail if they override the toolchains and remove the URLs/sources that they do not wish to use (I think that may be possible, if it is not I think that could be a good direction to investigate if anyone needs it).

[rickeylev]

Yeah, +1 to falling back

[gfrankliu]

Thanks both, implemented in b16dc46 as discussed:

• New flag --@rules_python//python/config_settings:py_pbs_distribution=auto|install_only|install_only_stripped|full, default auto (= install_only). It's transition-enabled, so it can also be set per target via config_settings.
• Toolchains are registered as -install_only_stripped and -full platform variants, the same way -freethreaded works. The flag rule reports auto as install_only to config_setting, so the default toolchains match both.
• Unavailable archives fall back to install_only (checked with 3.12.3, which predates stripped archives). Per-platform libpython, coverage_tool, and patches settings carry over to the variants.
• python.override(archive_flavor) is removed.

Two things worth flagging:

• This triples the number of registered toolchains. Repos are still fetched lazily, so it only adds a little analysis time, not downloads.
• If single_version_platform_override points a plain platform at a custom archive, its stripped/full variants still use the official archives unless those platform keys are overridden too.

[aignas]

FYI, if the build is with -C opt, #4178 is omitting the pyi files. I am thinking that we may want to use the same approach in here.

@rickeylev, WDYT?

[aignas]

This triples the number of registered toolchains. Repos are still fetched lazily, so it only adds a little analysis time, not downloads.

I think that is fine.

If single_version_platform_override points a plain platform at a custom archive, its stripped/full variants still use the official archives unless those platform keys are overridden too.

I think that is also fine. I think users that are overriding the individual archives know what they are doing and will probably do the overrides for the other platforms as well or for a particular archive type.