feat(wheel): Add support for add_path_prefix

.bazelrc.deleted_packages

@@ -27,8 +27,8 @@ common --deleted_packages=gazelle/manifest/hasher
 common --deleted_packages=gazelle/manifest/test
 common --deleted_packages=gazelle/modules_mapping
 common --deleted_packages=gazelle/python
-common --deleted_packages=gazelle/pythonconfig
 common --deleted_packages=gazelle/python/private
+common --deleted_packages=gazelle/pythonconfig
 common --deleted_packages=tests/integration/compile_pip_requirements
 common --deleted_packages=tests/integration/compile_pip_requirements_test_from_external_repo
 common --deleted_packages=tests/integration/custom_commands

CHANGELOG.md

@@ -127,6 +127,8 @@ Other changes:
   Implements [#2731](https://github.com/bazel-contrib/rules_python/issues/2731).
 * (wheel) Specifying a path ending in `/` as a destination in `data_files`
   will now install file(s) to a folder, preserving their basename.
+* (wheel) Add support for `add_path_prefix` argument in `py_wheel` which can be
+  used to prepend a prefix to the files in the wheel.
 
 {#v1-9-0}
 ## [1.9.0] - 2026-02-21

examples/wheel/BUILD.bazel

@@ -230,6 +230,25 @@ py_wheel(
     ],
 )
 
+# An example of how to change the wheel package root directory using 'add_path_prefix'.
+py_wheel(
+    name = "custom_prefix_package_root",
+    add_path_prefix = "custom_prefix",
+    # Package data. We're building "examples_custom_prefix_package_root-0.0.1-py3-none-any.whl"
+    distribution = "examples_custom_prefix_package_root",
+    entry_points = {
+        "console_scripts": ["main = foo.bar:baz"],
+    },
+    python_tag = "py3",
+    strip_path_prefixes = [
+        "examples",
+    ],
+    version = "0.0.1",
+    deps = [
+        ":example_pkg",
+    ],
+)
+
 py_wheel(
     name = "python_requires_in_a_package",
     distribution = "example_python_requires_in_a_package",

python/private/py_wheel.bzl

@@ -170,6 +170,22 @@ entry_points, e.g. `{'console_scripts': ['main = examples.wheel.main:main']}`.
 }
 
 _other_attrs = {
+    "add_path_prefix": attr.string(
+        default = "",
+        doc = """\
+Path prefix to prepend to files added to the generated package.
+This prefix will be prepended **after** the paths are first stripped of the prefixes
+specified in `strip_path_prefixes`.
+
+For example:
++ `"foo/" will prepend to `"bar/baz/file.py"` as `"foo/bar/baz/file.py"`
++ `"foo_" will prepend to `"bar/baz/file.py"` as `"foo_bar/baz/file.py"`
++ `stripping ["bar/"] and adding "foo/" will change `"bar/baz/file.py"` to `"foo/baz/file.py"`
+:::{versionadded} VERSION_NEXT_FEATURE
+The {attr}`add_path_prefix` attribute was added.
+:::
+""",
+    ),
     "author": attr.string(
         doc = "A string specifying the author of the package.",
         default = "",
@@ -389,6 +405,7 @@ def _py_wheel_impl(ctx):
     args.add("--out", outfile)
     args.add("--name_file", name_file)
     args.add_all(ctx.attr.strip_path_prefixes, format_each = "--strip_path_prefix=%s")
+    args.add("--path_prefix", ctx.attr.add_path_prefix)
 
     # Pass workspace status files if stamping is enabled
     if is_stamping_enabled(ctx.attr):

tests/tools/wheelmaker_test.py

@@ -1,5 +1,6 @@
 import io
 import unittest
+from dataclasses import dataclass, field
 
 import tools.wheelmaker as wheelmaker
 
@@ -34,41 +35,108 @@ def test_quote_all_false_leaves_simple_filenames_unquoted(self) -> None:
     def test_quote_all_quotes_filenames_with_commas(self) -> None:
         """Filenames with commas are always quoted, regardless of quote_all_filenames."""
         whl = self._make_whl_file(quote_all=True)
-        self.assertEqual(whl._quote_filename("foo,bar/baz.py"), '"foo,bar/baz.py"')
+        self.assertEqual(
+            whl._quote_filename("foo,bar/baz.py"), '"foo,bar/baz.py"'
+        )
 
         whl = self._make_whl_file(quote_all=False)
-        self.assertEqual(whl._quote_filename("foo,bar/baz.py"), '"foo,bar/baz.py"')
+        self.assertEqual(
+            whl._quote_filename("foo,bar/baz.py"), '"foo,bar/baz.py"'
+        )
+
+
+@dataclass
+class ArcNameTestCase:
+    name: str
+    expected: str
+    distribution_prefix: str = ""
+    strip_path_prefixes: list[str] = field(default_factory=list)
+    add_path_prefix: str = ""
 
 
 class ArcNameFromTest(unittest.TestCase):
     def test_arcname_from(self) -> None:
-        # (name, distribution_prefix, strip_path_prefixes, want) tuples
-        checks = [
-            ("a/b/c/file.py", "", [], "a/b/c/file.py"),
-            ("a/b/c/file.py", "", ["a"], "/b/c/file.py"),
-            ("a/b/c/file.py", "", ["a/b/"], "c/file.py"),
+        test_cases = [
+            ArcNameTestCase(name="a/b/c/file.py", expected="a/b/c/file.py"),
+            ArcNameTestCase(
+                name="a/b/c/file.py",
+                strip_path_prefixes=["a"],
+                expected="/b/c/file.py",
+            ),
+            ArcNameTestCase(
+                name="a/b/c/file.py",
+                strip_path_prefixes=["a/b/"],
+                expected="c/file.py",
+            ),
             # only first found is used and it's not cumulative.
-            ("a/b/c/file.py", "", ["a/", "b/"], "b/c/file.py"),
+            ArcNameTestCase(
+                name="a/b/c/file.py",
+                strip_path_prefixes=["a/", "b/"],
+                expected="b/c/file.py",
+            ),
             # Examples from docs
-            ("foo/bar/baz/file.py", "", ["foo", "foo/bar/baz"], "/bar/baz/file.py"),
-            ("foo/bar/baz/file.py", "", ["foo/bar/baz", "foo"], "/file.py"),
-            ("foo/file2.py", "", ["foo/bar/baz", "foo"], "/file2.py"),
+            ArcNameTestCase(
+                name="foo/bar/baz/file.py",
+                strip_path_prefixes=["foo", "foo/bar/baz"],
+                expected="/bar/baz/file.py",
+            ),
+            ArcNameTestCase(
+                name="foo/bar/baz/file.py",
+                strip_path_prefixes=["foo/bar/baz", "foo"],
+                expected="/file.py",
+            ),
+            ArcNameTestCase(
+                name="foo/file2.py",
+                strip_path_prefixes=["foo/bar/baz", "foo"],
+                expected="/file2.py",
+            ),
             # Files under the distribution prefix (eg mylib-1.0.0-dist-info)
             # are unmodified
-            ("mylib-0.0.1-dist-info/WHEEL", "mylib", [], "mylib-0.0.1-dist-info/WHEEL"),
-            ("mylib/a/b/c/WHEEL", "mylib", ["mylib"], "mylib/a/b/c/WHEEL"),
+            ArcNameTestCase(
+                name="mylib-0.0.1-dist-info/WHEEL",
+                distribution_prefix="mylib",
+                expected="mylib-0.0.1-dist-info/WHEEL",
+            ),
+            ArcNameTestCase(
+                name="mylib/a/b/c/WHEEL",
+                distribution_prefix="mylib",
+                strip_path_prefixes=["mylib"],
+                expected="mylib/a/b/c/WHEEL",
+            ),
+            # Check that prefixes are added
+            ArcNameTestCase(
+                name="a/b/c/file.py",
+                add_path_prefix="namespace/",
+                expected="namespace/a/b/c/file.py",
+            ),
+            ArcNameTestCase(
+                name="a/b/c/file.py",
+                strip_path_prefixes=["a"],
+                add_path_prefix="namespace",
+                expected="namespace/b/c/file.py",
+            ),
+            ArcNameTestCase(
+                name="a/b/c/file.py",
+                strip_path_prefixes=["a/b/"],
+                add_path_prefix="namespace_",
+                expected="namespace_c/file.py",
+            ),
         ]
-        for name, prefix, strip, want in checks:
+        for test_case in test_cases:
             with self.subTest(
-                name=name,
-                distribution_prefix=prefix,
-                strip_path_prefixes=strip,
-                want=want,
+                name=test_case.name,
+                distribution_prefix=test_case.distribution_prefix,
+                strip_path_prefixes=test_case.strip_path_prefixes,
+                add_path_prefix=test_case.add_path_prefix,
+                want=test_case.expected,
             ):
                 got = wheelmaker.arcname_from(
-                    name=name, distribution_prefix=prefix, strip_path_prefixes=strip
+                    name=test_case.name,
+                    distribution_prefix=test_case.distribution_prefix,
+                    strip_path_prefixes=test_case.strip_path_prefixes,
+                    add_path_prefix=test_case.add_path_prefix,
                 )
-                self.assertEqual(got, want)
+                self.assertEqual(got, test_case.expected)
 
 
 class GetNewRequirementLineTest(unittest.TestCase):
@@ -77,7 +145,9 @@ def test_requirement(self):
         self.assertEqual(result, "Requires-Dist: requests>=2.0")
 
     def test_requirement_and_extra(self):
-        result = wheelmaker.get_new_requirement_line("requests>=2.0", "extra=='dev'")
+        result = wheelmaker.get_new_requirement_line(
+            "requests>=2.0", "extra=='dev'"
+        )
         self.assertEqual(result, "Requires-Dist: requests>=2.0; extra=='dev'")
 
     def test_requirement_with_url(self):