docs/refactor: Use python.defaults, not is_default

When there are multiple Python toolchains, there are currently two
ways of setting the default version: the is_default attribute of
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, docs and the MODULE.bazel
file to use python.defaults().

Relates to pull request bazel-contrib#2588 and issue bazel-contrib#2587.

Author: vonschultz

MODULE.bazel

@@ -42,10 +42,8 @@ python = use_extension("//python/extensions:python.bzl", "python")
 # NOTE: This is not a stable version. It is provided for convenience, but will
 # change frequently to track the most recent Python version.
 # NOTE: The root module can override this.
-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",

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).
 :::
 """,
         ),