From d1b26a930db5f0c8f82a2f695995a1768a08a906 Mon Sep 17 00:00:00 2001 From: Christian von Schultz Date: Tue, 20 May 2025 20:37:47 +0200 Subject: [PATCH 1/2] 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 #2588 and issue #2587. --- MODULE.bazel | 6 ++---- docs/api/rules_python/python/bin/index.md | 3 ++- docs/toolchains.md | 15 +++++++++++---- examples/bzlmod/MODULE.bazel | 7 +++++-- examples/bzlmod/other_module/MODULE.bazel | 6 ++++-- .../bzlmod_build_file_generation/MODULE.bazel | 6 +++++- examples/multi_python_versions/MODULE.bazel | 2 -- python/extensions/python.bzl | 6 ++---- python/private/python.bzl | 10 ++++------ 9 files changed, 35 insertions(+), 26 deletions(-) diff --git a/MODULE.bazel b/MODULE.bazel index d0f7cc4afa..fcda6daf63 100644 --- a/MODULE.bazel +++ b/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", diff --git a/docs/api/rules_python/python/bin/index.md b/docs/api/rules_python/python/bin/index.md index 8bea6b54bd..873b644341 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 a2a2b5b63e..ada887c945 100644 --- a/docs/toolchains.md +++ b/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") ``` diff --git a/examples/bzlmod/MODULE.bazel b/examples/bzlmod/MODULE.bazel index 69e384e42b..841c096dcf 100644 --- a/examples/bzlmod/MODULE.bazel +++ b/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", ) diff --git a/examples/bzlmod/other_module/MODULE.bazel b/examples/bzlmod/other_module/MODULE.bazel index 959501abc2..f9d6706120 100644 --- a/examples/bzlmod/other_module/MODULE.bazel +++ b/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", ) diff --git a/examples/bzlmod_build_file_generation/MODULE.bazel b/examples/bzlmod_build_file_generation/MODULE.bazel index 9bec25fcbb..b9b428d365 100644 --- a/examples/bzlmod_build_file_generation/MODULE.bazel +++ b/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", ) diff --git a/examples/multi_python_versions/MODULE.bazel b/examples/multi_python_versions/MODULE.bazel index 85140360bb..4e4a0473c2 100644 --- a/examples/multi_python_versions/MODULE.bazel +++ b/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( diff --git a/python/extensions/python.bzl b/python/extensions/python.bzl index abd5080dd8..b8b755ebca 100644 --- a/python/extensions/python.bzl +++ b/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") ``` diff --git a/python/private/python.bzl b/python/private/python.bzl index 0cc19382d0..0e8cc3091e 100644 --- a/python/private/python.bzl +++ b/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). ::: """, ), From 3d42ba8998055ac825538e21db426b392bff225f Mon Sep 17 00:00:00 2001 From: Christian von Schultz Date: Thu, 22 May 2025 08:10:34 +0200 Subject: [PATCH 2/2] fix: Revert changes to top-level MODULE.bazel Apparently changing the top-level MODULE.bazel can break things, so that will keep using is_default for now. --- MODULE.bazel | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/MODULE.bazel b/MODULE.bazel index fcda6daf63..d0f7cc4afa 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -42,8 +42,10 @@ 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.defaults(python_version = "3.11") -python.toolchain(python_version = "3.11") +python.toolchain( + is_default = True, + python_version = "3.11", +) use_repo( python, "python_3_11",