feat: support manifest_urls fallback mirrors and parsing in python.override

Introduces support for mirror fallback download urls inside python.override and parses python-build-standalone SHA manifests dynamically in Bzlmod.

Features:

 - Added 'add_runtime_manifest_urls' (string_list) and 'runtime_manifest_sha' (string) tags inside python.override, allowing multiple mirrors for hermetic manifest and release asset downloads.

 - Implemented Starlark manifest parser in 'python/private/pbs_manifest.bzl' containing 'parse_filename' (filename components dictionary parser) and 'parse_sha_manifest' (spaces-robust manifest entries parser).

 - Resolved C header compilation issues in full hermetic builds by dynamically setting strip_prefix to 'python/install' for full builds and 'python' for stripped runtimes, and filtered flavor downloads to prevent install_only overrides.

 - Added 'tests/support/mocks/python_ext.bzl' mock helper automatically injecting default tag/module attributes to simplify Bzlmod extension mock unit tests.

 - Wrote comprehensive Starlark unit tests in 'tests/python_bzlmod_ext' and Bazel-in-Bazel integration tests verifying the hermetic interpreter path, exact version (3.11.15), and build date (20260414).

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

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,115 @@
+"""Helper functions to parse python-build-standalone manifests."""
+
+def parse_filename(filename):
+    """Parses a python-build-standalone filename into its components.
+
+    Example: cpython-3.10.20+20260414-x86_64_v2-unknown-linux-musl-lto-full.tar.zst
+
+    Args:
+      filename: The filename of the python-build-standalone release asset.
+
+    Returns:
+      A dictionary of parsed components if parsed successfully, else None.
+    """
+    if filename.endswith(".tar.zst"):
+        name = filename.removesuffix(".tar.zst")
+    elif filename.endswith(".tar.gz"):
+        name = filename.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,
+        "filename": filename,
+        "flavor": flavor,
+        "libc": libc,
+        "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 filename.
+      Each struct contains the following fields:
+        - arch: CPU architecture (e.g., "x86_64").
+        - build_version: Standalone release date (e.g., "20260414").
+        - filename: Full package filename (e.g., "cpython-3.11.15...").
+        - 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,68 @@ 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:
+        filename = entry.filename
+        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 filename:
+                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
+
+        urls = ["{}/{}".format(base_url, filename) 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 +845,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 +1183,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 +1267,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/BUILD.bazel

@@ -0,0 +1,7 @@
+load("@rules_python//python:py_test.bzl", "py_test")
+
+py_test(
+    name = "basic_test",
+    srcs = ["basic_test.py"],
+    python_version = "3.11",
+)

tests/integration/runtime_manifests/MODULE.bazel

@@ -0,0 +1,19 @@
+module(name = "runtime_manifests")
+
+bazel_dep(name = "rules_python", version = "0.0.0")
+local_path_override(
+    module_name = "rules_python",
+    path = "../../..",
+)
+
+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",
+    ],
+    register_all_versions = True,
+    runtime_manifest_sha = "ce18fdfd47c66830a40ea9b9e314a14b1636bbfd684501bc5ca1fc6d55a7933f",
+)
+python.toolchain(
+    python_version = "3.11.15",
+)

tests/integration/runtime_manifests/WORKSPACE

@@ -0,0 +1 @@
+# Workspace boundary file required by rules_bazel_integration_test

tests/integration/runtime_manifests/basic_test.py

@@ -0,0 +1,28 @@
+import datetime
+import platform
+import sys
+import unittest
+
+
+class BasicTest(unittest.TestCase):
+
+    def test_basic(self):
+        print("Hello World from Python {}!".format(sys.version))
+        print("Interpreter executable path: {}".format(sys.executable))
+
+        # Verify that the hermetic interpreter inside Bazel's output/sandbox tree is used
+        self.assertIn(".cache/bazel", sys.executable)
+
+        # Verify that the exact custom version (3.11.15) parsed from the manifest is used
+        self.assertEqual(sys.version_info[:3], (3, 11, 15))
+
+        # Verify that the exact build version (20260414) parsed from the manifest is used
+        buildno, builddate = platform.python_build()
+        date_str = " ".join(builddate.split()[:3])
+        dt = datetime.datetime.strptime(date_str, "%b %d %Y")
+        formatted_date = dt.strftime("%Y%m%d")
+        self.assertEqual(formatted_date, "20260414")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/python_bzlmod_ext/BUILD.bazel

@@ -0,0 +1,6 @@
+load(":parse_sha_manifest_tests.bzl", "parse_sha_manifest_test_suite")
+load(":runtime_manifests_tests.bzl", "runtime_manifests_test_suite")
+
+parse_sha_manifest_test_suite(name = "parse_sha_manifest_tests")
+
+runtime_manifests_test_suite(name = "runtime_manifests_tests")