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

.github/workflows/backport_create_releases.yaml

@@ -43,5 +43,7 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ISSUE: ${{ inputs.issue }}
         run: |
-          bazel run //dev/release -- \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- \
             backport-create-releases --issue=$ISSUE --no-dry-run

.github/workflows/backport_prepare.yaml

@@ -72,5 +72,7 @@ jobs:
               ARGS+=("--to-minor=$TO_MINOR")
             fi
           fi
-          bazel run //dev/release -- \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- \
             backport-prepare "${ARGS[@]}" --no-dry-run

.github/workflows/on_pr_closed.yaml

@@ -63,7 +63,9 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ needs.parse_pr.outputs.pr_number }}
         run: |
-          bazel run //dev/release -- on-pr-merged \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- on-pr-merged \
             "$PR_NUMBER" \
             --remote origin \
             --no-dry-run

.github/workflows/release_add_backports.yaml

@@ -53,6 +53,8 @@ jobs:
           # Convert CSV to array
           IFS=',' read -r -a pr_array <<< "$PRS"
           
-          bazel run //dev/release -- add-backports \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- add-backports \
             "${pr_array[@]}" \
             "${ARGS[@]}"

.github/workflows/release_complete_prepare.yaml

@@ -68,7 +68,9 @@ jobs:
             ARGS+=("--issue=$ISSUE")
           fi
           # Run the complete-prepare subcommand in the release tool to cleanly update checklist metadata
-          bazel run //dev/release -- \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- \
             complete-prepare "${ARGS[@]}"
 
   call_create_release_branch:

.github/workflows/release_create_rc.yaml

@@ -58,7 +58,9 @@ jobs:
           if [ -n "$COMMENT_ID" ]; then
             ARGS+=("--triggering-comment=$COMMENT_ID")
           fi
-          bazel run //dev/release -- \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- \
             create-rc --issue "$ISSUE" --remote origin "${ARGS[@]}"
 
   call_release:

.github/workflows/release_create_release_branch.yaml

@@ -41,7 +41,9 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          bazel run //dev/release -- \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- \
             create-release-branch --issue "${{ inputs.issue }}" --remote origin
 
   # A no-op job that always runs to prevent "no jobs ran" failures

.github/workflows/release_prepare.yaml

@@ -47,5 +47,7 @@ jobs:
           if [ -n "$ISSUE" ]; then
             ARGS+=("--issue=$ISSUE")
           fi
-          bazel run //dev/release -- \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- \
             prepare "${ARGS[@]}" --no-dry-run

.github/workflows/release_process_backports.yaml

@@ -70,7 +70,9 @@ jobs:
             ARGS+=("--triggering-comment=$COMMENT_ID")
           fi
           
-          bazel run //dev/release -- process-backports \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- process-backports \
             --issue "$ISSUE" \
             --remote origin \
             --no-dry-run \

.github/workflows/release_promote.yaml

@@ -60,7 +60,9 @@ jobs:
           ARGS+=("--remote=origin")
           ARGS+=("--no-dry-run")
           
-          bazel run //dev/release -- promote "${ARGS[@]}"
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- promote "${ARGS[@]}"
 
   publish:
     needs: promote

.github/workflows/release_sync_changelog.yaml

@@ -42,5 +42,7 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          bazel run //dev/release -- sync-changelog \
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- sync-changelog \
             --remote origin

.github/workflows/release_sync_changelog_complete.yaml

@@ -42,4 +42,6 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          bazel run //dev/release -- complete-sync-changelog
+          bazel run \
+            --//python/config_settings:py_pbs_distribution=install_only_stripped \
+            //dev/release -- complete-sync-changelog

docs/api/rules_python/python/config_settings/index.md

@@ -300,6 +300,27 @@ Values:
 :::
 ::::
 
+::::{bzl:flag} py_pbs_distribution
+Set which python-build-standalone archive the hermetic Python toolchains use.
+
+Values:
+* `auto`: Let `rules_python` choose; currently the same as `install_only`,
+  default.
+* `install_only`: Use the runtime with debug symbols.
+* `install_only_stripped`: Use the runtime without debug symbols, which is
+  substantially smaller.
+* `full`: Use the runtime that also includes build artifacts.
+
+If a Python version or platform has no archive of the selected kind, the
+`install_only` archive is used instead.
+
+See {ref}`Selecting the runtime archive <selecting-the-runtime-archive>` for
+details.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
+::::
+
 ::::{bzl:flag} pip_env_marker_config
 The target that provides the values for pip env marker evaluation.
 

docs/toolchains.md

@@ -228,6 +228,35 @@ locations. These will be helpful if you need to set environment variables of bin
 while using [`--nolegacy_external_runfiles`](https://bazel.build/reference/command-line-reference#flag--legacy_external_runfiles).
 The original make variables still work in exec contexts such as genrules.
 
+(selecting-the-runtime-archive)=
+### Selecting the runtime archive
+
+python-build-standalone publishes each runtime as several kinds of archive. The
+{obj}`--@rules_python//python/config_settings:py_pbs_distribution`
+flag selects which one the hermetic toolchains use:
+
+* `auto` (default): let `rules_python` choose; currently `install_only`.
+* `install_only`: the runtime with debug symbols.
+* `install_only_stripped`: the runtime without debug symbols, which is
+  substantially smaller. This reduces the size of runtimes and
+  {obj}`py_zipapp_binary` outputs.
+* `full`: the runtime plus build artifacts.
+
+Because this is a build flag, a single workspace can build with different
+archives, for example keeping debug symbols in development builds and using
+stripped runtimes in production builds:
+
+```
+# File: .bazelrc
+build:prod --@rules_python//python/config_settings:py_pbs_distribution=install_only_stripped
+```
+
+A toolchain is registered for each archive kind, and only the archive a build
+selects is downloaded. If a Python version or platform has no archive of the
+selected kind, the `install_only` archive is used instead. For example,
+stripped archives are only available for runtimes released from `20240726`
+onward.
+
 ### Overriding toolchain defaults and adding more versions
 
 One can perform various overrides for the registered toolchains from the root
@@ -875,6 +904,9 @@ Currently the following flags are used to influence toolchain selection:
 * {obj}`--@rules_python//python/config_settings:py_linux_libc` for selecting the Linux libc variant.
 * {obj}`--@rules_python//python/config_settings:py_freethreaded` for selecting
   the freethreaded experimental Python builds available from `3.13.0` onwards.
+* {obj}`--@rules_python//python/config_settings:py_pbs_distribution`
+  for selecting which python-build-standalone archive to use, e.g. stripped
+  runtimes.
 
 ## Running the underlying interpreter
 

news/4163.added.md

@@ -0,0 +1,6 @@
+(toolchains) Added the
+{obj}`--@rules_python//python/config_settings:py_pbs_distribution`
+flag to select which python-build-standalone archive the hermetic toolchains
+use. Setting it to `install_only_stripped` uses runtimes without debug symbols,
+which reduces runtime and zipapp size.
+([#4163](https://github.com/bazel-contrib/rules_python/issues/4163))

news/4163.changed.md

@@ -0,0 +1,5 @@
+(toolchains) Added `install_only_stripped` python-build-standalone runtime
+archives for releases from `20240726` onward. They can be used by setting
+{obj}`--@rules_python//python/config_settings:py_pbs_distribution` to
+`install_only_stripped` to reduce runtime download size.
+([#4163](https://github.com/bazel-contrib/rules_python/issues/4163))

python/config_settings/BUILD.bazel

@@ -9,11 +9,13 @@ load(
     "ExecToolsToolchainFlag",
     "FreeThreadedFlag",
     "LibcFlag",
+    "PbsDistributionFlag",
     "PrecompileFlag",
     "PrecompileSourceRetentionFlag",
     "ValidateTestMainFlag",
     "VenvsSitePackages",
     "VenvsUseDeclareSymlinkFlag",
+    "pbs_distribution_flag",
     rp_string_flag = "string_flag",
 )
 load("//python/private:visibility.bzl", "NOT_ACTUALLY_PUBLIC")  # buildifier: disable=bzl-visibility
@@ -38,6 +40,7 @@ construct_config_settings(
         ":pip_whl_osx_version",
         ":py_freethreaded",
         ":py_linux_libc",
+        ":py_pbs_distribution",
     ],
     minor_mapping = MINOR_MAPPING,
     versions = PYTHON_VERSIONS,
@@ -137,6 +140,12 @@ string_flag(
     visibility = ["//visibility:public"],
 )
 
+pbs_distribution_flag(
+    name = "py_pbs_distribution",
+    build_setting_default = PbsDistributionFlag.AUTO,
+    visibility = ["//visibility:public"],
+)
+
 alias(
     name = "is_py_freethreaded",
     actual = ":_is_py_freethreaded_yes",

python/private/BUILD.bazel

@@ -338,6 +338,7 @@ bzl_library(
     name = "config_settings",
     srcs = ["config_settings.bzl"],
     deps = [
+        ":common_labels",
         ":text_util",
         ":version",
         ":visibility",
@@ -769,6 +770,7 @@ bzl_library(
     deps = [
         ":coverage_deps",
         ":full_version",
+        ":pbs_manifest",
         ":python_repository",
         ":toolchains_repo",
         "//python:versions",
@@ -874,6 +876,7 @@ bzl_library(
     name = "toolchains_repo",
     srcs = ["toolchains_repo.bzl"],
     deps = [
+        ":pbs_manifest",
         ":repo_utils",
         ":text_util",
         "//python:versions",

python/private/common_labels.bzl

@@ -29,6 +29,7 @@ labels = struct(
     PYTHON_VERSION_MAJOR_MINOR = str(Label("//python/config_settings:python_version_major_minor")),
     PY_FREETHREADED = str(Label("//python/config_settings:py_freethreaded")),
     PY_LINUX_LIBC = str(Label("//python/config_settings:py_linux_libc")),
+    PY_PBS_DISTRIBUTION = str(Label("//python/config_settings:py_pbs_distribution")),
     REPL_DEP = str(Label("//python/bin:repl_dep")),
     VALIDATE_TEST_MAIN = str(Label("//python/config_settings:validate_test_main")),
     VENV = str(Label("//python/config_settings:venv")),

python/private/config_settings.bzl

@@ -17,6 +17,7 @@
 
 load("@bazel_skylib//lib:selects.bzl", "selects")
 load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo")
+load(":common_labels.bzl", "labels")
 load(":text_util.bzl", "render")
 load(":version.bzl", "version")
 load(":visibility.bzl", "NOT_ACTUALLY_PUBLIC")
@@ -179,6 +180,15 @@ def construct_config_settings(
         visibility = NOT_ACTUALLY_PUBLIC,
     )
 
+    # NOTE: The py_pbs_distribution flag reports `auto` as `install_only`, so
+    # the install_only setting also matches the default.
+    for distribution in ["install_only", "install_only_stripped", "full"]:
+        native.config_setting(
+            name = "_is_py_pbs_distribution_" + distribution,
+            flag_values = {labels.PY_PBS_DISTRIBUTION: distribution},
+            visibility = NOT_ACTUALLY_PUBLIC,
+        )
+
 def _python_version_flag_impl(ctx):
     value = ctx.build_setting_value
     return [

python/private/flags.bzl

@@ -261,3 +261,45 @@ LibcFlag = FlagEnum(
     MUSL = "musl",
     get_value = _libc_flag_get_value,
 )
+
+# Determines which python-build-standalone distribution (archive) is used for
+# the hermetic runtimes.
+#
+# buildifier: disable=name-conventions
+PbsDistributionFlag = FlagEnum(
+    # Let rules_python choose; currently the same as install_only.
+    AUTO = "auto",
+    # The install_only archive, which includes debug symbols.
+    INSTALL_ONLY = "install_only",
+    # The install_only_stripped archive, which omits debug symbols.
+    INSTALL_ONLY_STRIPPED = "install_only_stripped",
+    # The full archive, which includes build artifacts.
+    FULL = "full",
+)
+
+def _pbs_distribution_flag_impl(ctx):
+    value = ctx.build_setting_value
+    if value not in PbsDistributionFlag.flag_values():
+        fail((
+            "Invalid value for {name}: got {value}, must be one of {allowed}"
+        ).format(
+            name = ctx.label,
+            value = value,
+            allowed = PbsDistributionFlag.flag_values(),
+        ))
+
+    # config_setting matches against the FeatureFlagInfo value, so `auto` is
+    # resolved here and toolchains only need to match concrete distributions.
+    effective = value
+    if value == PbsDistributionFlag.AUTO:
+        effective = PbsDistributionFlag.INSTALL_ONLY
+    return [
+        BuildSettingInfo(value = value),
+        config_common.FeatureFlagInfo(value = effective),
+    ]
+
+pbs_distribution_flag = rule(
+    implementation = _pbs_distribution_flag_impl,
+    build_setting = config.string(flag = True),
+    doc = "The python-build-standalone distribution to use for hermetic runtimes.",
+)