docs/refactor: Use python.defaults, not is_default (#2924)

When there are multiple Python toolchains, there are currently two ways
of setting the default version: the `is_default` attribute of the
`python.toolchain()` tag class and the `python.defaults()` tag class.
The latter is more powerful, since it also supports files and
environment variables. This patch updates the examples and the docs to
use `python.defaults()`.

Relates to pull request #2588 and issue #2587.

Author: vonschultz

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

@@ -10,7 +10,8 @@
 A target to directly run a Python interpreter.
 
 By default, it uses the Python version that toolchain resolution matches
-(typically the one marked `is_default=True` in `MODULE.bazel`).
+(typically the one set with `python.defaults(python_version = ...)` in
+`MODULE.bazel`).
 
 This runs a Python interpreter in a similar manner as when running `python3`
 on the command line. It can be invoked using `bazel run`. Remember that in

docs/toolchains.md

@@ -44,7 +44,8 @@ you should read the dev-only library module section.
 bazel_dep(name="rules_python", version=...)
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
-python.toolchain(python_version = "3.12", is_default = True)
+python.defaults(python_version = "3.12")
+python.toolchain(python_version = "3.12")
 ```
 
 ### Library modules
@@ -72,7 +73,8 @@ python = use_extension(
     dev_dependency = True
 )
 
-python.toolchain(python_version = "3.12", is_default=True)
+python.defaults(python_version = "3.12")
+python.toolchain(python_version = "3.12")
 ```
 
 #### Library modules without version constraints
@@ -161,9 +163,13 @@ Multiple versions can be specified and used within a single build.
 # MODULE.bazel
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
+python.defaults(
+    # The environment variable takes precedence if set.
+    python_version = "3.11",
+    python_version_env = "BAZEL_PYTHON_VERSION",
+)
 python.toolchain(
     python_version = "3.11",
-    is_default = True,
 )
 
 python.toolchain(
@@ -264,7 +270,8 @@ bazel_dep(name = "rules_python", version = "0.40.0")
 
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
-python.toolchain(is_default = True, python_version = "3.10")
+python.defaults(python_version = "3.10")
+python.toolchain(python_version = "3.10")
 
 use_repo(python, "python_3_10", "python_3_10_host")
 ```

examples/bzlmod/MODULE.bazel

@@ -28,10 +28,13 @@ bazel_dep(name = "rules_rust", version = "0.54.1")
 # We next initialize the python toolchain using the extension.
 # You can set different Python versions in this block.
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.defaults(
+    # Use python.defaults if you have defined multiple toolchain versions.
+    python_version = "3.9",
+    python_version_env = "BAZEL_PYTHON_VERSION",
+)
 python.toolchain(
     configure_coverage_tool = True,
-    # Only set when you have multiple toolchain versions.
-    is_default = True,
     python_version = "3.9",
 )
 

examples/bzlmod/other_module/MODULE.bazel

@@ -25,14 +25,16 @@ PYTHON_NAME_39 = "python_3_9"
 PYTHON_NAME_311 = "python_3_11"
 
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.defaults(
+    # In a submodule this is ignored
+    python_version = "3.11",
+)
 python.toolchain(
     configure_coverage_tool = True,
     python_version = "3.9",
 )
 python.toolchain(
     configure_coverage_tool = True,
-    # In a submodule this is ignored
-    is_default = True,
     python_version = "3.11",
 )
 

examples/bzlmod_build_file_generation/MODULE.bazel

@@ -46,9 +46,13 @@ python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
 # We next initialize the python toolchain using the extension.
 # You can set different Python versions in this block.
+python.defaults(
+    # The environment variable takes precedence if set.
+    python_version = "3.9",
+    python_version_env = "BAZEL_PYTHON_VERSION",
+)
 python.toolchain(
     configure_coverage_tool = True,
-    is_default = True,
     python_version = "3.9",
 )
 

examples/multi_python_versions/MODULE.bazel

@@ -17,8 +17,6 @@ python.defaults(
 )
 python.toolchain(
     configure_coverage_tool = True,
-    # Only set when you have mulitple toolchain versions.
-    is_default = True,
     python_version = "3.9",
 )
 python.toolchain(

python/extensions/python.bzl

@@ -20,10 +20,8 @@ The simplest way to configure the toolchain with `rules_python` is as follows.
 
 ```starlark
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
-python.toolchain(
-    is_default = True,
-    python_version = "3.11",
-)
+python.defaults(python_version = "3.11")
+python.toolchain(python_version = "3.11")
 use_repo(python, "python_3_11")
 ```
 

python/private/python.bzl

@@ -223,7 +223,7 @@ def parse_modules(*, module_ctx, _fail = fail):
     # A default toolchain is required so that the non-version-specific rules
     # are able to match a toolchain.
     if default_toolchain == None:
-        fail("No default Python toolchain configured. Is rules_python missing `is_default=True`?")
+        fail("No default Python toolchain configured. Is rules_python missing `python.defaults()`?")
     elif default_toolchain.python_version not in global_toolchain_versions:
         fail('Default version "{python_version}" selected by module ' +
              '"{module_name}", but no toolchain with that version registered'.format(
@@ -891,10 +891,8 @@ In order to use a different name than the above, you can use the following `MODU
 syntax:
 ```starlark
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
-python.toolchain(
-    is_default = True,
-    python_version = "3.11",
-)
+python.defaults(python_version = "3.11")
+python.toolchain(python_version = "3.11")
 
 use_repo(python, my_python_name = "python_3_11")
 ```
@@ -930,7 +928,7 @@ Whether the toolchain is the default version.
 
 :::{versionchanged} 1.4.0
 This setting is ignored if the default version is set using the `defaults`
-tag class.
+tag class (encouraged).
 :::
 """,
         ),