feat(bzlmod): python.override for toolchain customization

CHANGELOG.md

@@ -25,7 +25,12 @@ A brief description of the categories of changes:
 [x.x.x]: https://github.com/bazelbuild/rules_python/releases/tag/x.x.x
 
 ### Changed
-* (gazelle): Update error messages when unable to resolve a dependency to be more human-friendly.
+* (gazelle): Update error messages when unable to resolve a dependency to be
+  more human-friendly.
+* (toolchain): The toolchain patches now expose the `patch_strip` attribute
+  that one should use when patching toolchains. Please set it if you are
+  patching python interpreter. In the next release the default will be set to
+  `0` which better reflects the defaults used in public `bazel` APIs.
 
 ### Fixed
 * (whl_library): Remove `--no-index` and add `--no-build-isolation` to the
@@ -43,7 +48,11 @@ A brief description of the categories of changes:
 * (bzlmod) Properly handle relative path URLs in parse_simpleapi_html.bzl
 
 ### Added
-* Nothing yet
+* (bzlmod): Toolchain overrides can now be done to fully override anything from
+  within the TOOL_VERSIONS dict using the new 
+  {rule}`python.override`,
+  {rule}`python.single_version_override` and
+  {rule}`python.single_version_platform_override`.
 
 ### Removed
 * Nothing yet

MODULE.bazel

@@ -81,7 +81,7 @@ dev_python = use_extension(
     "python",
     dev_dependency = True,
 )
-dev_python.rules_python_private_testing(
+dev_python.override(
     register_all_versions = True,
 )
 

docs/BUILD.bazel

@@ -94,6 +94,8 @@ sphinx_stardocs(
         "//python/private/common:py_library_rule_bazel_bzl",
         "//python/private/common:py_runtime_rule_bzl",
         "//python/private/common:py_test_rule_bazel_bzl",
+        # FIXME @aignas 2024-08-26: should we have this here?
+        "//python:repositories_bzl",
     ] + ([
         # Bazel 6 + Stardoc isn't able to parse something about the python bzlmod extension
         "//python/extensions:python_bzl",

examples/bzlmod/MODULE.bazel

@@ -37,6 +37,47 @@ python.toolchain(
     python_version = "3.10",
 )
 
+# One can override the actual toolchain versions that are available
+python.override(
+    available_python_versions = [
+        "3.10.9",
+        "3.9.19",
+        # Keep the following versions which are present in MINOR_MAPPING, but
+        # are not present above
+        "3.10.14",
+    ],
+)
+
+# Or the sources that the toolchains come from for all platforms
+python.single_version_override(
+    patch_strip = 1,
+    # The user can specify patches to be applied to all interpreters, they will
+    # be applied before the platform specific patches are applied.
+    patches = [],
+    sha256 = {
+        "aarch64-apple-darwin": "1409acd9a506e2d1d3b65c1488db4e40d8f19d09a7df099667c87a506f71c0ef",
+        "aarch64-unknown-linux-gnu": "8f351a8cc348bb45c0f95b8634c8345ec6e749e483384188ad865b7428342703",
+        "x86_64-apple-darwin": "8146ad4390710ec69b316a5649912df0247d35f4a42e2aa9615bffd87b3e235a",
+        "x86_64-pc-windows-msvc": "a1d9a594cd3103baa24937ad9150c1a389544b4350e859200b3e5c036ac352bd",
+        "x86_64-unknown-linux-gnu": "9b64eca2a94f7aff9409ad70bdaa7fbbf8148692662e764401883957943620dd",
+    },
+    urls = ["20220227/cpython-{python_version}+20220227-{platform}-{build}.tar.gz"],
+    version = "3.10.2",
+)
+
+# Or a single platform. This can be used in combination with the
+# `single_version_override` and `single_version_platform_override` will be
+# applied after `single_version_override`.
+# TODO @aignas 2024-08-27: implement that
+python.single_version_platform_override(
+    patch_strip = 1,
+    patches = [],
+    platform = "aarch64-apple-darwin",
+    sha256 = "1409acd9a506e2d1d3b65c1488db4e40d8f19d09a7df099667c87a506f71c0ef",
+    urls = ["20220227/cpython-{python_version}+20220227-{platform}-{build}.tar.gz"],
+    version = "3.10.2",
+)
+
 # You only need to load this repositories if you are using multiple Python versions.
 # See the tests folder for various examples on using multiple Python versions.
 # The names "python_3_9" and "python_3_10" are autmatically created by the repo

python/private/BUILD.bazel

@@ -131,11 +131,11 @@ bzl_library(
     name = "python_bzl",
     srcs = ["python.bzl"],
     deps = [
+        ":python_repositories_bzl",
         ":pythons_hub_bzl",
         ":repo_utils_bzl",
         ":toolchains_repo_bzl",
         ":util_bzl",
-        "//python:repositories_bzl",
         "@bazel_features//:features",
     ],
 )
@@ -298,6 +298,7 @@ bzl_library(
     srcs = ["toolchains_repo.bzl"],
     deps = [
         ":repo_utils_bzl",
+        ":text_util_bzl",
         "//python:versions_bzl",
     ],
 )

python/private/common/py_runtime_rule.bzl

@@ -204,8 +204,8 @@ See @bazel_tools//tools/python:python_bootstrap_template.txt for more variables.
         "coverage_tool": attr.label(
             allow_files = False,
             doc = """
-This is a target to use for collecting code coverage information from `py_binary`
-and `py_test` targets.
+This is a target to use for collecting code coverage information from
+{rule}`py_binary` and {rule}`py_test` targets.
 
 If set, the target must either produce a single file or be an executable target.
 The path to the single file, or the executable if the target is executable,
@@ -214,7 +214,7 @@ runfiles will be added to the runfiles when coverage is enabled.
 
 The entry point for the tool must be loadable by a Python interpreter (e.g. a
 `.py` or `.pyc` file).  It must accept the command line arguments
-of coverage.py (https://coverage.readthedocs.io), at least including
+of [`coverage.py`](https://coverage.readthedocs.io), at least including
 the `run` and `lcov` subcommands.
 """,
         ),
@@ -306,7 +306,7 @@ The template to use when two stage bootstrapping is enabled
             default = DEFAULT_STUB_SHEBANG,
             doc = """
 "Shebang" expression prepended to the bootstrapping Python stub script
-used when executing `py_binary` targets.
+used when executing {rule}`py_binary` targets.
 
 See https://github.com/bazelbuild/bazel/issues/8685 for
 motivation.