fix(toolchains): prefer non-debug builds from runtime manifests (#4442)

Runtime manifests added with
`python.override(add_runtime_manifest_urls = ...)` or
`add_runtime_manifest_files` can list python-build-standalone debug
(`Py_DEBUG`) builds; the upstream `SHA256SUMS` does. It is sorted by
name, so for each platform the `debug-full` archive comes before the
optimized `full` one. The first entry for a platform key wins and the
sort ignores the build flavor, so:

- `--@rules_python//python/config_settings:py_pbs_distribution=full`
  selects the debug archive. With PBS 20261026 that is every `-full`
  key, 132 of them for 3.11 to 3.16.0a1.
- In releases that ship free-threaded runtimes only as `full` archives
  (for example 20241016 and 20250115), the free-threaded keys get the
  debug archive under the default distribution too.

A debug archive has a different layout (`include/python3.14d`,
`libpython3.14d.so`, `python_d.exe`) that the runtime repo does not
handle. For example, a `cc_library` on `current_py_cc_headers` fails
with `Python.h: No such file or directory`.

Rank debug builds (`-debug` and `+debug` flavors) last when sorting
parsed runtime manifest entries, so non-debug archives are preferred
whenever available.

Related to #1823.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Richard Levasseur <richardlev@gmail.com>
diff --git a/news/manifest-no-debug-builds.fixed.md b/news/manifest-no-debug-builds.fixed.md
new file mode 100644
index 0000000..14025a6
--- /dev/null
+++ b/news/manifest-no-debug-builds.fixed.md
@@ -0,0 +1,5 @@
+(toolchains) Runtime manifests added with
+{obj}`python.override.add_runtime_manifest_urls` or
+{obj}`python.override.add_runtime_manifest_files` now prefer non-debug
+python-build-standalone builds over debug (`Py_DEBUG`) builds
+([#4442](https://github.com/bazel-contrib/rules_python/issues/4442)).
diff --git a/python/private/pbs_manifest.bzl b/python/private/pbs_manifest.bzl
index 04b604a..8a849ea 100644
--- a/python/private/pbs_manifest.bzl
+++ b/python/private/pbs_manifest.bzl
@@ -55,6 +55,8 @@
     Returns:
       A sortable tuple where lower values are preferred.
     """
+    flavor_parts = entry.build_flavor.replace("-", "+").split("+")
+    debug_rank = 1 if "debug" in flavor_parts else 0
     flavor_rank = {
         "full": 3,
         "install_only": 1,
@@ -67,7 +69,7 @@
         microarch_rank = int(microarch[1:])
     else:
         microarch_rank = 999
-    return (flavor_rank, microarch_rank)
+    return (debug_rank, flavor_rank, microarch_rank)
 
 def parse_filename(filename):
     """Parses a python-build-standalone filename (or URL) into its components.
@@ -240,4 +242,4 @@
                 sha256 = sha256,
                 **parsed
             ))
-    return results
+    return sorted(results, key = manifest_entry_sort_key)
diff --git a/tests/python_bzlmod_ext/parse_runtime_manifest_tests.bzl b/tests/python_bzlmod_ext/parse_runtime_manifest_tests.bzl
index 8c9176a..a073037 100644
--- a/tests/python_bzlmod_ext/parse_runtime_manifest_tests.bzl
+++ b/tests/python_bzlmod_ext/parse_runtime_manifest_tests.bzl
@@ -181,21 +181,6 @@
     })
 
     env.expect.that_dict(structs.to_dict(parsed[2])).contains_exactly({
-        "arch": "x86_64",
-        "archive_flavor": "full",
-        "build_flavor": "lto",
-        "build_version": "20260414",
-        "freethreaded": False,
-        "libc": "musl",
-        "location": "https://example.com/cpython-3.10.20+20260414-x86_64_v2-unknown-linux-musl-lto-full.tar.zst",
-        "microarch": "v2",
-        "os": "linux",
-        "python_version": "3.10.20",
-        "sha256": "ce18fdfd47c66830a40ea9b9e314a14b1636bbfd684501bc5ca1fc6d55a7933f",
-        "vendor": "unknown",
-    })
-
-    env.expect.that_dict(structs.to_dict(parsed[3])).contains_exactly({
         "arch": "aarch64",
         "archive_flavor": "full",
         "build_flavor": "pgo+lto",
@@ -210,8 +195,53 @@
         "vendor": "apple",
     })
 
+    env.expect.that_dict(structs.to_dict(parsed[3])).contains_exactly({
+        "arch": "x86_64",
+        "archive_flavor": "full",
+        "build_flavor": "lto",
+        "build_version": "20260414",
+        "freethreaded": False,
+        "libc": "musl",
+        "location": "https://example.com/cpython-3.10.20+20260414-x86_64_v2-unknown-linux-musl-lto-full.tar.zst",
+        "microarch": "v2",
+        "os": "linux",
+        "python_version": "3.10.20",
+        "sha256": "ce18fdfd47c66830a40ea9b9e314a14b1636bbfd684501bc5ca1fc6d55a7933f",
+        "vendor": "unknown",
+    })
+
 _tests.append(_test_parse_runtime_manifest)
 
+def _test_parse_runtime_manifest_ranks_debug_last(name):
+    rt_util.helper_target(
+        native.filegroup,
+        name = name + "_subject",
+    )
+    analysis_test(
+        name = name,
+        target = name + "_subject",
+        impl = _test_parse_runtime_manifest_ranks_debug_last_impl,
+    )
+
+def _test_parse_runtime_manifest_ranks_debug_last_impl(env, target):
+    _ = target  # @unused
+    content = """
+1111111111111111111111111111111111111111111111111111111111111111  cpython-3.11.18+20261026-ppc64le-unknown-linux-gnu-debug-full.tar.zst
+2222222222222222222222222222222222222222222222222222222222222222  cpython-3.14.10+20261026-armv7-unknown-linux-gnueabi-freethreaded+debug-full.tar.zst
+3333333333333333333333333333333333333333333333333333333333333333  cpython-3.14.10+20261026-armv7-unknown-linux-gnueabi-freethreaded+pgo+lto-full.tar.zst
+4444444444444444444444444444444444444444444444444444444444444444  cpython-3.11.18+20261026-ppc64le-unknown-linux-gnu-pgo+lto-full.tar.zst
+"""
+    parsed = parse_runtime_manifest(content)
+    got_locations = [entry.location for entry in parsed]
+    env.expect.that_collection(got_locations).contains_exactly([
+        "cpython-3.14.10+20261026-armv7-unknown-linux-gnueabi-freethreaded+pgo+lto-full.tar.zst",
+        "cpython-3.11.18+20261026-ppc64le-unknown-linux-gnu-pgo+lto-full.tar.zst",
+        "cpython-3.11.18+20261026-ppc64le-unknown-linux-gnu-debug-full.tar.zst",
+        "cpython-3.14.10+20261026-armv7-unknown-linux-gnueabi-freethreaded+debug-full.tar.zst",
+    ]).in_order()
+
+_tests.append(_test_parse_runtime_manifest_ranks_debug_last)
+
 def parse_runtime_manifest_test_suite(name):
     """Defines the test suite for manifest parsing.
 
diff --git a/tests/python_bzlmod_ext/runtime_manifests_tests.bzl b/tests/python_bzlmod_ext/runtime_manifests_tests.bzl
index 682afa1..557ea94 100644
--- a/tests/python_bzlmod_ext/runtime_manifests_tests.bzl
+++ b/tests/python_bzlmod_ext/runtime_manifests_tests.bzl
@@ -167,6 +167,94 @@
 
 _tests.append(_test_dynamic_manifest_files)
 
+def _test_dynamic_manifest_skips_debug_builds(name):
+    rt_util.helper_target(
+        native.filegroup,
+        name = name + "_subject",
+    )
+    analysis_test(
+        name = name,
+        target = name + "_subject",
+        impl = _test_dynamic_manifest_skips_debug_builds_impl,
+    )
+
+def _test_dynamic_manifest_skips_debug_builds_impl(env, target):
+    _ = target  # @unused
+
+    root_module = python_ext.module(
+        name = "runtime_manifests",
+        override = [
+            python_ext.override(
+                add_runtime_manifest_files = [
+                    Label("//:SHA256SUMS"),
+                ],
+                base_urls = ["https://example.com/dl"],
+                register_all_versions = True,
+            ),
+        ],
+        defaults = [
+            python_ext.defaults(
+                python_version = "3.14.99",
+            ),
+        ],
+    )
+
+    # SHA256SUMS is sorted by name, so the debug builds come first.
+    mock_mctx = python_ext.mctx(
+        modules = [root_module],
+        mock_files = {
+            str(Label("//:SHA256SUMS")): """
+1111111111111111111111111111111111111111111111111111111111111111  cpython-3.14.99+20261026-x86_64-unknown-linux-gnu-debug-full.tar.zst
+2222222222222222222222222222222222222222222222222222222222222222  cpython-3.14.99+20261026-x86_64-unknown-linux-gnu-freethreaded+debug-full.tar.zst
+3333333333333333333333333333333333333333333333333333333333333333  cpython-3.14.99+20261026-x86_64-unknown-linux-gnu-freethreaded+pgo+lto-full.tar.zst
+4444444444444444444444444444444444444444444444444444444444444444  cpython-3.14.99+20261026-x86_64-unknown-linux-gnu-pgo+lto-full.tar.zst
+""",
+        },
+    )
+
+    res = parse_modules(
+        module_ctx = mock_mctx,
+        logger = _mock_logger,
+    )
+
+    tool_versions = res.config.default["tool_versions"]
+    env.expect.that_bool("3.14.99" in tool_versions).equals(True)
+
+    version_info = tool_versions["3.14.99"]
+
+    # Debug builds sort last, so the optimized full archives are used for
+    # both the plain and the full keys.
+    env.expect.that_dict(version_info).contains_exactly({
+        "sha256": {
+            "x86_64-unknown-linux-gnu": "4444444444444444444444444444444444444444444444444444444444444444",
+            "x86_64-unknown-linux-gnu-freethreaded": "3333333333333333333333333333333333333333333333333333333333333333",
+            "x86_64-unknown-linux-gnu-freethreaded-full": "3333333333333333333333333333333333333333333333333333333333333333",
+            "x86_64-unknown-linux-gnu-full": "4444444444444444444444444444444444444444444444444444444444444444",
+        },
+        "strip_prefix": {
+            "x86_64-unknown-linux-gnu": "python/install",
+            "x86_64-unknown-linux-gnu-freethreaded": "python/install",
+            "x86_64-unknown-linux-gnu-freethreaded-full": "python/install",
+            "x86_64-unknown-linux-gnu-full": "python/install",
+        },
+        "url": {
+            "x86_64-unknown-linux-gnu": [
+                "https://example.com/dl/cpython-3.14.99+20261026-x86_64-unknown-linux-gnu-pgo+lto-full.tar.zst",
+            ],
+            "x86_64-unknown-linux-gnu-freethreaded": [
+                "https://example.com/dl/cpython-3.14.99+20261026-x86_64-unknown-linux-gnu-freethreaded+pgo+lto-full.tar.zst",
+            ],
+            "x86_64-unknown-linux-gnu-freethreaded-full": [
+                "https://example.com/dl/cpython-3.14.99+20261026-x86_64-unknown-linux-gnu-freethreaded+pgo+lto-full.tar.zst",
+            ],
+            "x86_64-unknown-linux-gnu-full": [
+                "https://example.com/dl/cpython-3.14.99+20261026-x86_64-unknown-linux-gnu-pgo+lto-full.tar.zst",
+            ],
+        },
+    })
+
+_tests.append(_test_dynamic_manifest_skips_debug_builds)
+
 def _test_dynamic_manifest_files_default_base_urls(name):
     rt_util.helper_target(
         native.filegroup,