refactor: move unpack.py into a configurable toolchain

docs/interpreter.md

@@ -318,6 +318,10 @@ This interpreter provisioning is designed to coexist with `rules_python`:
   interpreters only through `rules_python`'s `python.toolchain()`. rules_py
   registers nothing under `rules_python`'s exec-tools type, leaving it —
   including precompiling — entirely to `rules_python`.
+- The exec-tools toolchain also carries the wheel-unpack tool
+  (`unpack_tool`: executable + argument prefix + inputs) that
+  wheel-installing build actions run — see
+  [Custom wheel-unpack tool](#custom-wheel-unpack-tool).
 
 Note that runtimes provisioned by `interpreters.toolchain()` carry
 `rules_python`'s public `PyRuntimeInfo` (re-exported from
@@ -329,3 +333,45 @@ these runtimes is unavailable.
 You can migrate incrementally: replace `python.toolchain()` calls with
 `interpreters.toolchain()` and remove the `rules_python` interpreter
 configuration while keeping everything else.
+
+## Custom wheel-unpack tool
+
+The `WhlInstall` action (uv-generated `whl_install` targets; full flag set)
+and the `PyUnpackedWheel` action (hand-written `py_unpacked_wheel` targets;
+always-passed flags only) install each wheel by running the exec-tools
+toolchain's `unpack_tool`: its argument prefix, then the flags below. A
+toolchain registered with a custom `unpack_tool` (e.g. a prebuilt binary)
+replaces the default script. `@aspect_rules_py//py/tools/unpack` is
+the reference implementation — match its observable behavior, including the
+failure guards on patching and exclusion.
+
+| Flag | Repeated | Passed | Purpose |
+|---|---|---|---|
+| `--into <dir>` | | always | output tree artifact; install the wheel here |
+| `--wheel <file>` | | always | the `.whl` to install |
+| `--python-version <M.m>` | | always | target interpreter major.minor version |
+| `--exclude-glob <pattern>` | yes | on feature | remove matching site-packages files post-install |
+| `--patch <file>` | yes | on feature | patch the installed tree, in order, cwd `<into>` |
+| `--patch-strip <N>` | | with `--patch` | `-p<N>` strip count |
+| `--preserve-path <path>` | yes | with `--patch` | fail if patching changes these paths' layout |
+| `--compile-pyc <interpreter>` | | on feature | pre-compile `.pyc` bytecode with this exec-config interpreter (a declared input) |
+| `--pyc-invalidation-mode <mode>` | | with `--compile-pyc` | PEP 552 mode |
+
+Requirements:
+
+- Install into `<into>/lib/python<M>.<m>/site-packages/` per the wheel spec's
+  install operation: PEP 427 `.data/` routing, entry-point launchers under
+  `bin/` and rewritten `#!python` shebangs (both relocatable, resolving the
+  venv-sibling `python3`), executable bits, regenerated `RECORD` plus
+  `INSTALLER`/`REQUESTED`.
+- `<M>.<m>` is the *target* version and only names that directory — never run
+  target Python; under cross-compilation it may not run on the build host.
+- Order: unpack, patch, exclude, compile. Exit non-zero on any failure.
+- When patching, preserve the layout of every `--preserve-path` and reject
+  additions or removals outside site-packages; analysis-time wheel metadata
+  cannot reflect either change.
+- Deterministic, path-mapping-safe output (`supports-path-mapping`): no
+  absolute or configuration-dependent paths in installed files; the action is
+  sandboxed to its declared inputs.
+- The tool must not resolve a Python toolchain: the exec-tools toolchain
+  depends on it, so that resolution would cycle.

e2e/cases/MODULE.bazel

@@ -5,6 +5,7 @@ bazel_dep(name = "bazel_features", version = "1.38.0")
 bazel_dep(name = "bazel_skylib", version = "1.4.2")
 bazel_dep(name = "bazel_lib", version = "3.0.0")
 bazel_dep(name = "rules_cc", version = "0.2.16")
+bazel_dep(name = "zlib", version = "1.3.2")
 bazel_dep(name = "tar.bzl", version = "0.10.1")
 bazel_dep(name = "platforms", version = "1.0.0")
 bazel_dep(name = "llvm", version = "0.8.3")
@@ -51,6 +52,11 @@ interpreters.toolchain(
 )
 use_repo(interpreters, "python_interpreters")
 
+# Flag-gated custom wheel-unpack toolchain (a C binary). Registered ahead of
+# the default interpreter toolchains so it wins exec-tools resolution when its
+# target_settings flag is set; inert otherwise.
+register_toolchains("//custom-unpack-tool:c_unpack_toolchain")
+
 register_toolchains("@python_interpreters//:all")
 
 # rules_py tools — provides the native_build_toolchain entries for sdist builds.

e2e/cases/custom-unpack-tool/BUILD.bazel

@@ -0,0 +1,86 @@
+load("@aspect_rules_py//py:defs.bzl", "py_test")
+load("@bazel_lib//lib:transitions.bzl", "platform_transition_test")
+load("@bazel_skylib//rules:common_settings.bzl", "bool_flag")
+load("@rules_cc//cc:cc_binary.bzl", "cc_binary")
+load(":toolchain.bzl", "custom_unpack_toolchain")
+
+# End-to-end check for the exec-tools toolchain's swappable `unpack_tool`
+# (docs/interpreter.md, "Custom wheel-unpack tool"): a self-contained C binary
+# replaces the default unpack.py for the WhlInstall action installing a real
+# uv-locked wheel (iniconfig, reused from uv-whl-install-output-group's hub).
+#
+# The toolchain is registered module-wide (see MODULE.bazel) but gated by
+# `target_settings` on the flag below, flipped only inside
+# platform_transition_test — sibling cases keep the default tool. Each tool
+# writes a distinctive dist-info INSTALLER (the C tool its own marker, the
+# reference unpack.py `aspect_rules_py`); the tests read it to prove which
+# tool installed the wheel in each configuration.
+
+# POSIX-only C tool; mirror the unpack_test guard.
+_NOT_WINDOWS = select({
+    "@platforms//os:windows": ["@platforms//:incompatible"],
+    "//conditions:default": [],
+})
+
+bool_flag(
+    name = "use_custom_unpack",
+    build_setting_default = False,
+)
+
+config_setting(
+    name = "custom_unpack_enabled",
+    flag_values = {":use_custom_unpack": "true"},
+)
+
+cc_binary(
+    name = "unpack_tool",
+    srcs = ["unpack_tool.c"],
+    target_compatible_with = _NOT_WINDOWS,
+    deps = ["@zlib"],
+)
+
+custom_unpack_toolchain(
+    name = "c_unpack",
+    unpack_tool = ":unpack_tool",
+)
+
+toolchain(
+    name = "c_unpack_toolchain",
+    target_settings = [":custom_unpack_enabled"],
+    toolchain = ":c_unpack",
+    toolchain_type = "@aspect_rules_py//py/private/toolchain:exec_tools_toolchain_type",
+)
+
+platform(
+    name = "custom_unpack_platform",
+    flags = ["--//custom-unpack-tool:use_custom_unpack=true"],
+    parents = ["@platforms//host"],
+)
+
+py_test(
+    name = "custom_test_bin",
+    srcs = ["custom_test.py"],
+    dep_group = "uv-whl-install-output-group",
+    main = "custom_test.py",
+    tags = ["manual"],
+    target_compatible_with = _NOT_WINDOWS,
+    deps = ["@pypi_uv_whl_install_output_group//iniconfig"],
+)
+
+platform_transition_test(
+    name = "custom_test",
+    binary = ":custom_test_bin",
+    target_compatible_with = _NOT_WINDOWS,
+    target_platform = ":custom_unpack_platform",
+)
+
+# Control: without the flag the gated toolchain must not match and the
+# default unpack.py installs the wheel.
+py_test(
+    name = "default_test",
+    srcs = ["default_test.py"],
+    dep_group = "uv-whl-install-output-group",
+    main = "default_test.py",
+    target_compatible_with = _NOT_WINDOWS,
+    deps = ["@pypi_uv_whl_install_output_group//iniconfig"],
+)

e2e/cases/custom-unpack-tool/custom_test.py

@@ -0,0 +1,25 @@
+"""Runs with --//custom-unpack-tool:use_custom_unpack=true: the wheel must
+have been installed by the C unpack tool, not the default unpack.py."""
+
+import pathlib
+
+import iniconfig
+
+site_packages = pathlib.Path(iniconfig.__file__).resolve().parent.parent
+dist_infos = sorted(site_packages.glob("iniconfig-*.dist-info"))
+assert len(dist_infos) == 1, "expected one iniconfig dist-info, found %s" % dist_infos
+
+installer = dist_infos[0] / "INSTALLER"
+assert installer.is_file(), (
+    "INSTALLER missing: the custom C unpack tool did not run (%s)" % installer
+)
+content = installer.read_text(encoding="utf-8")
+assert content == "rules_py-e2e-c-unpack-tool\n", (
+    "unexpected INSTALLER content %r: wheel was not installed by the C tool" % content
+)
+assert (dist_infos[0] / "REQUESTED").is_file()
+
+# whl_install passes --compile-pyc by default; the C tool must have run
+# compileall under the exec interpreter.
+pycs = list((site_packages / "iniconfig" / "__pycache__").glob("__init__.*.pyc"))
+assert pycs, "no compiled bytecode: the C tool skipped --compile-pyc"

e2e/cases/custom-unpack-tool/default_test.py

@@ -0,0 +1,21 @@
+"""Runs without the flag: the default unpack.py must have installed the wheel.
+
+The reference tool stamps dist-info INSTALLER with `aspect_rules_py`; the C
+tool's marker here would mean the flag-gated custom toolchain leaked into the
+default configuration."""
+
+import pathlib
+
+import iniconfig
+
+site_packages = pathlib.Path(iniconfig.__file__).resolve().parent.parent
+dist_infos = sorted(site_packages.glob("iniconfig-*.dist-info"))
+assert len(dist_infos) == 1, "expected one iniconfig dist-info, found %s" % dist_infos
+
+installer = dist_infos[0] / "INSTALLER"
+assert installer.is_file(), "INSTALLER missing from %s" % dist_infos[0]
+content = installer.read_text(encoding="utf-8")
+assert content == "aspect_rules_py", (
+    "unexpected INSTALLER content %r: custom unpack toolchain matched without its flag"
+    % content
+)

e2e/cases/custom-unpack-tool/toolchain.bzl

@@ -0,0 +1,33 @@
+"""Test-only exec-tools toolchain wrapping a self-contained unpack binary.
+
+Mirrors what a user registering a custom `unpack_tool` writes today: the
+toolchain resolves the standard Python toolchain type for its runtime payloads
+(safe — this target is registered only under the exec-tools type, so that
+resolution cannot cycle back into it) and exposes the binary as the opaque
+`unpack_tool` struct consumed by PyUnpackedWheel/WhlInstall actions.
+"""
+
+PY_TOOLCHAIN = "@bazel_tools//tools/python:toolchain_type"
+
+def _custom_unpack_toolchain_impl(ctx):
+    return [platform_common.ToolchainInfo(
+        exec_runtime = ctx.toolchains[PY_TOOLCHAIN].py3_runtime,
+        unpack_tool = struct(
+            executable = ctx.attr.unpack_tool[DefaultInfo].files_to_run,
+            arguments = [],
+            inputs = depset(),
+        ),
+    )]
+
+custom_unpack_toolchain = rule(
+    implementation = _custom_unpack_toolchain_impl,
+    attrs = {
+        "unpack_tool": attr.label(
+            doc = "Self-contained executable implementing the unpack CLI contract.",
+            executable = True,
+            cfg = "target",
+            mandatory = True,
+        ),
+    },
+    toolchains = [PY_TOOLCHAIN],
+)