feat(toolchains): support dynamic registration from remote manifest

Currently, all supported Python runtime versions and their
platform-specific metadata (URLs, SHA256s, strip_prefix) must be
hardcoded in `python/versions.bzl`. This makes it slow and difficult
to adopt new Python versions or custom builds without updating
`rules_python` itself.

This PR introduces the ability to dynamically fetch and register
Python runtimes from a remote python-build-standalone (PBS) manifest
file (e.g., `SHA256SUMS`).

This is supported via two new attributes in `python.override`:
- `add_runtime_manifest_urls`: A list of URLs pointing to manifest
  files to parse and register.
- `runtime_manifest_sha`: The SHA256 hash of the manifest file.

Author: rickeylev

.bazelrc.deleted_packages

@@ -38,6 +38,7 @@ common --deleted_packages=tests/integration/pip_parse
 common --deleted_packages=tests/integration/pip_parse/empty
 common --deleted_packages=tests/integration/pip_parse_isolated
 common --deleted_packages=tests/integration/py_cc_toolchain_registered
+common --deleted_packages=tests/integration/runtime_manifests
 common --deleted_packages=tests/integration/toolchain_target_settings
 common --deleted_packages=tests/modules/another_module
 common --deleted_packages=tests/modules/other

CHANGELOG.md

@@ -104,6 +104,9 @@ END_UNRELEASED_TEMPLATE
 
 {#v0-0-0-added}
 ### Added
+* (toolchains) Support dynamically fetching and registering Python runtimes
+  from a python-build-standalone manifest file using
+  `python.override(add_runtime_manifest_urls = ..., runtime_manifest_sha = ...)`.
 * (toolchain) Added {obj}`python.override.toolchain_target_settings` to allow
   adding `config_setting` labels to all registered toolchains.
 * (windows) Full venv support for Windows is available. Set

docs/toolchains.md

@@ -242,6 +242,8 @@ existing attributes:
   {attr}`python.single_version_platform_override.coverage_tool`.
 * Adding additional Python versions via {bzl:obj}`python.single_version_override` or
   {bzl:obj}`python.single_version_platform_override`.
+* Adding additional Python versions dynamically from a remote manifest file
+  via {attr}`python.override.add_runtime_manifest_urls`.
 
 ### Registering custom runtimes
 
@@ -310,6 +312,65 @@ Added support for custom platform names, `target_compatible_with`, and
 `target_settings` with `single_version_platform_override`.
 :::
 
+### Registering runtimes from a manifest
+
+If you want to register multiple custom runtimes or versions at once, you can
+use a python-build-standalone manifest file. This is useful if you want to
+adopt new versions that are not yet built into `rules_python` without having
+to manually define each one using `single_version_platform_override`.
+
+To do this, specify the `add_runtime_manifest_urls` and `runtime_manifest_sha`
+attributes in `python.override` in your `MODULE.bazel`.
+
+In the example below, we register all runtimes available in a specific PBS
+release manifest:
+
+```
+# File: MODULE.bazel
+python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.override(
+    add_runtime_manifest_urls = [
+        "https://github.com/astral-sh/python-build-standalone/releases/download/20260414/SHA256SUMS",
+    ],
+    runtime_manifest_sha = "ce18fdfd47c66830a40ea9b9e314a14b1636bbfd684501bc5ca1fc6d55a7933f",
+)
+```
+
+#### Manifest file format
+
+The manifest must be a plain text file where each line contains the SHA256 hash
+and the location of a runtime archive, separated by whitespace:
+
+```
+<sha256> <location>
+```
+
+The `<location>` can be either:
+- A relative filename (e.g.,
+  `cpython-3.10.20+20260414-x86_64-unknown-linux-gnu-install_only.tar.zst`).
+  In this case, the download URL is constructed by appending the filename to the
+  parent directory of each URL in `add_runtime_manifest_urls` (treating them as
+  mirrors).
+- An absolute URL (e.g.,
+  `https://example.com/downloads/cpython-3.10.20+20260414-x86_64-unknown-linux-gnu-install_only.tar.zst`).
+  In this case, the URL is used directly to download the archive.
+
+In both cases, the filename or the last path segment of the URL must follow the
+standard python-build-standalone naming convention. `rules_python` parses this
+name to extract runtime metadata (such as Python version, target architecture,
+operating system, and libc).
+
+Notes:
+- `rules_python` will download the manifest, parse it, and automatically
+  register toolchains for all valid Python runtimes found in it that match
+  supported platforms.
+- Only runtimes matching known platforms in `rules_python` will be registered.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+Added support for registering runtimes from a manifest using
+`add_runtime_manifest_urls` and `runtime_manifest_sha` in `python.override`.
+:::
+
 ### Using defined toolchains from WORKSPACE
 
 It is possible to use toolchains defined in `MODULE.bazel` in `WORKSPACE`. For example,

python/private/BUILD.bazel

@@ -252,6 +252,11 @@ bzl_library(
     srcs = ["normalize_name.bzl"],
 )
 
+bzl_library(
+    name = "pbs_manifest_bzl",
+    srcs = ["pbs_manifest.bzl"],
+)
+
 bzl_library(
     name = "precompile_bzl",
     srcs = ["precompile.bzl"],
@@ -274,6 +279,7 @@ bzl_library(
     srcs = ["python.bzl"],
     deps = [
         ":full_version_bzl",
+        ":pbs_manifest_bzl",
         ":platform_info_bzl",
         ":python_register_toolchains_bzl",
         ":pythons_hub_bzl",

python/private/pbs_manifest.bzl

@@ -0,0 +1,116 @@
+"""Helper functions to parse python-build-standalone manifests."""
+
+def parse_filename(filename):
+    """Parses a python-build-standalone filename (or URL) into its components.
+
+    Example: cpython-3.10.20+20260414-x86_64_v2-unknown-linux-musl-lto-full.tar.zst
+
+    Args:
+      filename: The filename or URL of the python-build-standalone release asset.
+
+    Returns:
+      A dictionary of parsed components if parsed successfully, else None.
+    """
+    basename = filename.rpartition("/")[-1]
+    if basename.endswith(".tar.zst"):
+        name = basename.removesuffix(".tar.zst")
+    elif basename.endswith(".tar.gz"):
+        name = basename.removesuffix(".tar.gz")
+    else:
+        return None
+
+    if not name.startswith("cpython-"):
+        return None
+    name = name.removeprefix("cpython-")
+
+    left, plus, tail = name.partition("+")
+    if plus:
+        python_version = left
+        build_version, sep, rest = tail.partition("-")
+        if not sep:
+            return None
+    else:
+        python_version, sep, rest = left.partition("-")
+        if not sep:
+            return None
+        build_version = ""
+
+    arch, sep, rest = rest.partition("-")
+    if not sep:
+        return None
+
+    microarch = ""
+    arch_base, sep_v, microarch_num = arch.partition("_v")
+    if sep_v:
+        arch = arch_base
+        microarch = "v" + microarch_num
+
+    vendor, sep, rest = rest.partition("-")
+    if not sep:
+        return None
+
+    os, sep, rest = rest.partition("-")
+    if not sep:
+        return None
+
+    libc = ""
+    next_part, _, remaining = rest.partition("-")
+    if os == "linux" and next_part in ["gnu", "musl"]:
+        libc = next_part
+        flavor = remaining
+    elif os == "windows" and next_part == "msvc":
+        libc = next_part
+        flavor = remaining
+    else:
+        libc = ""
+        flavor = rest
+
+    return {
+        "arch": arch,
+        "build_version": build_version,
+        "flavor": flavor,
+        "libc": libc,
+        "location": filename,
+        "microarch": microarch,
+        "os": os,
+        "python_version": python_version,
+        "vendor": vendor,
+    }
+
+def parse_sha_manifest(content):
+    """Parses the SHA256SUMS file content into a list of structs.
+
+    Args:
+      content: The raw content of the manifest file.
+
+    Returns:
+      A list of structs capturing the parsed components of each valid entry.
+      Each struct contains the following fields:
+        - arch: CPU architecture (e.g., "x86_64").
+        - build_version: Standalone release date (e.g., "20260414").
+        - location: Full package filename or URL (e.g., "cpython-3.11.15..." or "https://...").
+        - flavor: Build configuration flavor (e.g., "install_only").
+        - libc: C library type (e.g., "gnu", "musl", "msvc", or "").
+        - microarch: Microarchitecture level (e.g., "v2", "v3", or "").
+        - os: Operating system (e.g., "linux", "darwin", "windows").
+        - python_version: Python semver version (e.g., "3.11.15").
+        - sha256: SHA256 integrity hash of the release asset.
+        - vendor: Platform vendor (e.g., "unknown", "apple").
+    """
+    results = []
+    for line in content.split("\n"):
+        line = line.strip()
+        if not line:
+            continue
+        parts = [p for p in line.split(" ") if p]
+        if len(parts) != 2:
+            continue
+        sha256, filename = parts
+
+        parsed = parse_filename(filename)
+        if parsed:
+            results.append(struct(
+                sha256 = sha256,
+                **parsed
+            ))
+    return results

python/private/python.bzl

@@ -18,6 +18,7 @@ load("@bazel_features//:features.bzl", "bazel_features")
 load("//python:versions.bzl", "DEFAULT_RELEASE_BASE_URL", "PLATFORMS", "TOOL_VERSIONS")
 load(":auth.bzl", "AUTH_ATTRS")
 load(":full_version.bzl", "full_version")
+load(":pbs_manifest.bzl", "parse_sha_manifest")
 load(":platform_info.bzl", "platform_info")
 load(":python_register_toolchains.bzl", "python_register_toolchains")
 load(":pythons_hub.bzl", "hub_repo")
@@ -76,7 +77,7 @@ def parse_modules(*, module_ctx, logger = None, _fail = fail):
     # Map of string Major.Minor or Major.Minor.Patch to the toolchain_info struct
     global_toolchain_versions = {}
 
-    config = _get_toolchain_config(modules = module_ctx.modules, _fail = _fail)
+    config = _get_toolchain_config(mctx = module_ctx, modules = module_ctx.modules, _fail = _fail)
 
     default_python_version = _compute_default_python_version(module_ctx)
 
@@ -741,10 +742,71 @@ def _override_defaults(*overrides, modules, _fail = fail, default):
 
             override.fn(tag = tag, _fail = _fail, default = default)
 
-def _get_toolchain_config(*, modules, _fail = fail):
+def _populate_from_pbs_manifest(*, mctx, add_runtime_manifest_urls, runtime_manifest_sha = "", available_versions, _fail):
+    manifest_path = mctx.path("runtime_manifest")
+    result = mctx.download(
+        url = add_runtime_manifest_urls,
+        output = manifest_path,
+        sha256 = runtime_manifest_sha,
+    )
+    if not result.success:
+        _fail("Failed to download manifest from {}: {}".format(add_runtime_manifest_urls, result))
+        return
+
+    content = mctx.read(manifest_path)
+    base_download_urls = [url.rpartition("/")[0] for url in add_runtime_manifest_urls]
+
+    parsed_entries = parse_sha_manifest(content)
+
+    for entry in parsed_entries:
+        location = entry.location
+        sha256 = entry.sha256
+        py_version = entry.python_version
+
+        # Fallback to matching against PLATFORMS keys as before to ensure compatibility
+        # with rules_python expected platform keys.
+        matched_platform = None
+        for platform in PLATFORMS.keys():
+            if platform in location:
+                matched_platform = platform
+                break
+
+        if not matched_platform:
+            continue
+
+        expects_full = matched_platform in [
+            "aarch64-apple-darwin",
+            "aarch64-unknown-linux-gnu",
+            "ppc64le-unknown-linux-gnu",
+            "riscv64-unknown-linux-gnu",
+            "s390x-unknown-linux-gnu",
+            "x86_64-apple-darwin",
+            "x86_64-pc-windows-msvc",
+            "x86_64-unknown-linux-gnu",
+            "x86_64-unknown-linux-musl",
+        ]
+        is_full = entry.flavor.endswith("-full")
+        if expects_full != is_full:
+            continue
+
+        if "://" in location:
+            urls = [location]
+        else:
+            urls = ["{}/{}".format(base_url, location) for base_url in base_download_urls]
+
+        v_dict = available_versions.setdefault(py_version, {})
+        v_dict.setdefault("sha256", {})[matched_platform] = sha256
+        v_dict.setdefault("url", {})[matched_platform] = urls
+        if is_full:
+            v_dict.setdefault("strip_prefix", {})[matched_platform] = "python/install"
+        else:
+            v_dict.setdefault("strip_prefix", {})[matched_platform] = "python"
+
+def _get_toolchain_config(*, mctx, modules, _fail = fail):
     """Computes the configs for toolchains.
 
     Args:
+        mctx: The module context.
         modules: The modules from module_ctx
         _fail: Function to call for failing; only used for testing.
 
@@ -786,6 +848,19 @@ def _get_toolchain_config(*, modules, _fail = fail):
         else:
             available_versions[py_version]["url"] = dict(url)
 
+    # Check for add_runtime_manifest_urls in override tags in root module
+    root_module = modules[0] if modules else None
+    if root_module and root_module.is_root:
+        for tag in root_module.tags.override:
+            if tag.add_runtime_manifest_urls:
+                _populate_from_pbs_manifest(
+                    mctx = mctx,
+                    add_runtime_manifest_urls = tag.add_runtime_manifest_urls,
+                    runtime_manifest_sha = tag.runtime_manifest_sha,
+                    available_versions = available_versions,
+                    _fail = _fail,
+                )
+
     default = {
         "base_url": DEFAULT_RELEASE_BASE_URL,
         "platforms": dict(PLATFORMS),  # Copy so it's mutable.
@@ -1111,6 +1186,21 @@ _override = tag_class(
 :::
 """,
     attrs = {
+        "add_runtime_manifest_urls": attr.string_list(
+            mandatory = False,
+            doc = """
+URLs pointing to python-build-standalone manifest files (e.g., SHA256SUMS).
+
+Example:
+`https://github.com/astral-sh/python-build-standalone/releases/download/20260414/SHA256SUMS`
+
+Note that `/latest/` can be used in place of a specific release date (e.g., `20260414`) to automatically use the latest release:
+`https://github.com/astral-sh/python-build-standalone/releases/latest/download/SHA256SUMS`
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
+""",
+        ),
         "add_target_settings": attr.string_list(
             mandatory = False,
             doc = """\
@@ -1180,6 +1270,15 @@ The values in this mapping override the default values and do not replace them.
             default = {},
         ),
         "register_all_versions": attr.bool(default = False, doc = "Add all versions"),
+        "runtime_manifest_sha": attr.string(
+            mandatory = False,
+            doc = """
+SHA256 hash for the add_runtime_manifest_urls.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
+""",
+        ),
     } | AUTH_ATTRS,
 )
 

tests/integration/BUILD.bazel

@@ -101,6 +101,10 @@ rules_python_integration_test(
     workspace_path = "py_cc_toolchain_registered",
 )
 
+rules_python_integration_test(
+    name = "runtime_manifests_test",
+)
+
 rules_python_integration_test(
     name = "custom_commands_test",
     py_main = "custom_commands_test.py",

tests/integration/runtime_manifests/.bazelrc

@@ -0,0 +1,4 @@
+# Copy of fast-tests config
+common:fast-tests --build_tests_only=true
+common:fast-tests --build_tag_filters=-large,-enormous,-integration-test
+common:fast-tests --test_tag_filters=-large,-enormous,-integration-test