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.
diff --git a/docs/api/rules_python/python/bin/index.md b/docs/api/rules_python/python/bin/index.md
index 8bea6b5..873b644 100644
--- a/docs/api/rules_python/python/bin/index.md
+++ b/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
diff --git a/docs/toolchains.md b/docs/toolchains.md
index a2a2b5b..ada887c 100644
--- a/docs/toolchains.md
+++ b/docs/toolchains.md
@@ -44,7 +44,8 @@
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 @@
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 @@
# 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 @@
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")
```
diff --git a/examples/bzlmod/MODULE.bazel b/examples/bzlmod/MODULE.bazel
index 69e384e..841c096 100644
--- a/examples/bzlmod/MODULE.bazel
+++ b/examples/bzlmod/MODULE.bazel
@@ -28,10 +28,13 @@
# 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",
)
diff --git a/examples/bzlmod/other_module/MODULE.bazel b/examples/bzlmod/other_module/MODULE.bazel
index 959501a..f9d6706 100644
--- a/examples/bzlmod/other_module/MODULE.bazel
+++ b/examples/bzlmod/other_module/MODULE.bazel
@@ -25,14 +25,16 @@
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",
)
diff --git a/examples/bzlmod_build_file_generation/MODULE.bazel b/examples/bzlmod_build_file_generation/MODULE.bazel
index 9bec25f..b9b428d 100644
--- a/examples/bzlmod_build_file_generation/MODULE.bazel
+++ b/examples/bzlmod_build_file_generation/MODULE.bazel
@@ -46,9 +46,13 @@
# 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",
)
diff --git a/examples/multi_python_versions/MODULE.bazel b/examples/multi_python_versions/MODULE.bazel
index 8514036..4e4a047 100644
--- a/examples/multi_python_versions/MODULE.bazel
+++ b/examples/multi_python_versions/MODULE.bazel
@@ -17,8 +17,6 @@
)
python.toolchain(
configure_coverage_tool = True,
- # Only set when you have mulitple toolchain versions.
- is_default = True,
python_version = "3.9",
)
python.toolchain(
diff --git a/python/extensions/python.bzl b/python/extensions/python.bzl
index abd5080..b8b755e 100644
--- a/python/extensions/python.bzl
+++ b/python/extensions/python.bzl
@@ -20,10 +20,8 @@
```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")
```
diff --git a/python/private/python.bzl b/python/private/python.bzl
index 24ce38a..a7e2576 100644
--- a/python/private/python.bzl
+++ b/python/private/python.bzl
@@ -223,7 +223,7 @@
# 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 @@
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 @@
:::{versionchanged} 1.4.0
This setting is ignored if the default version is set using the `defaults`
-tag class.
+tag class (encouraged).
:::
""",
),
