From 466da1d9710289bfb01061b9be7bb124132996e0 Mon Sep 17 00:00:00 2001 From: J Schmidt Date: Tue, 28 Jan 2025 22:53:57 +0100 Subject: [PATCH] docs: using python_version attribute for specifying python version (#2589) Updates examples and docs to tell to use the base rules and the python_version attribute instead of the wrapper transition rules. --- CHANGELOG.md | 1 + docs/_includes/py_console_script_binary.md | 21 +++++-- docs/toolchains.md | 66 +++++++++++++++++++--- 3 files changed, 73 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f8da580a1..cba9a8a8c5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -62,6 +62,7 @@ Unreleased changes template. {#v0-0-0-fixed} ### Fixed +* (docs) Using `python_version` attribute for specifying python versions introduced in `v1.1.0` * (gazelle) Providing multiple input requirements files to `gazelle_python_manifest` now works correctly. * (pypi) Handle trailing slashes in pip index URLs in environment variables, fixes [#2554](https://github.com/bazelbuild/rules_python/issues/2554). diff --git a/docs/_includes/py_console_script_binary.md b/docs/_includes/py_console_script_binary.md index 7373c8a7b2..aa356e0e94 100644 --- a/docs/_includes/py_console_script_binary.md +++ b/docs/_includes/py_console_script_binary.md @@ -12,7 +12,8 @@ py_console_script_binary( ) ``` -Or for more advanced setups you can also specify extra dependencies and the +#### Specifying extra dependencies +You can also specify extra dependencies and the exact script name you want to call. It is useful for tools like `flake8`, `pylint`, `pytest`, which have plugin discovery methods and discover dependencies from the PyPI packages available in the `PYTHONPATH`. @@ -34,17 +35,26 @@ py_console_script_binary( ) ``` -A specific Python version can be forced by using the generated version-aware -wrappers, e.g. to force Python 3.9: +#### Using a specific Python version + +A specific Python version can be forced by passing the desired Python version, e.g. to force Python 3.9: ```starlark -load("@python_versions//3.9:defs.bzl", "py_console_script_binary") +load("@rules_python//python/entry_points:py_console_script_binary.bzl", "py_console_script_binary") py_console_script_binary( name = "yamllint", pkg = "@pip//yamllint", + python_version = "3.9" ) ``` +#### Using a specific Python Version directly from a Toolchain +:::{deprecated} 1.1.0 +The toolchain specific `py_binary` and `py_test` symbols are aliases to the regular rules. +i.e. Deprecated `load("@python_versions//3.11:defs.bzl", "py_binary")` and `load("@python_versions//3.11:defs.bzl", "py_test")` + +You should instead specify the desired python version with `python_version`; see above example. +::: Alternatively, the [`py_console_script_binary.binary_rule`] arg can be passed the version-bound `py_binary` symbol, or any other `py_binary`-compatible rule of your choosing: @@ -60,5 +70,4 @@ py_console_script_binary( ``` [specification]: https://packaging.python.org/en/latest/specifications/entry-points/ -[`py_console_script_binary.binary_rule`]: #py_console_script_binary_binary_rule - +[`py_console_script_binary.binary_rule`]: #py_console_script_binary_binary_rule \ No newline at end of file diff --git a/docs/toolchains.md b/docs/toolchains.md index 32f4a541d9..6eaa244b1f 100644 --- a/docs/toolchains.md +++ b/docs/toolchains.md @@ -116,9 +116,9 @@ python = use_extension("@rules_python//python/extensions:python.bzl", "python") python.toolchain(python_version = "3.12") # BUILD.bazel -load("@python_versions//3.12:defs.bzl", "py_binary") +load("@rules_python//python:py_binary.bzl", "py_binary") -py_binary(...) +py_binary(..., python_version="3.12") ``` ### Pinning to a Python version @@ -132,21 +132,59 @@ is most useful for two cases: typically in a mono-repo situation. To configure a submodule with the version-aware rules, request the particular -version you need, then use the `@python_versions` repo to use the rules that -force specific versions: +version you need when defining the toolchain: ```starlark +# MODULE.bazel python = use_extension("@rules_python//python/extensions:python.bzl", "python") python.toolchain( python_version = "3.11", ) -use_repo(python, "python_versions") +use_repo(python) +``` + +Then use the `@rules_python` repo in your BUILD file to explicity pin the Python version when calling the rule: + +```starlark +# BUILD.bazel +load("@rules_python//python:py_binary.bzl", "py_binary") + +py_binary(..., python_version = "3.11") +py_test(..., python_version = "3.11") ``` -Then use e.g. `load("@python_versions//3.11:defs.bzl", "py_binary")` to use -the rules that force that particular version. Multiple versions can be specified -and use within a single build. +Multiple versions can be specified and used within a single build. + +```starlark +# MODULE.bazel +python = use_extension("@rules_python//python/extensions:python.bzl", "python") + +python.toolchain( + python_version = "3.11", + is_default = True, +) + +python.toolchain( + python_version = "3.12", +) + +# BUILD.bazel +load("@rules_python//python:py_binary.bzl", "py_binary") +load("@rules_python//python:py_test.bzl", "py_test") + +# Defaults to 3.11 +py_binary(...) +py_test(...) + +# Explicitly use Python 3.11 +py_binary(..., python_version = "3.11") +py_test(..., python_version = "3.11") + +# Explicitly use Python 3.12 +py_binary(..., python_version = "3.12") +py_test(..., python_version = "3.12") +``` For more documentation, see the bzlmod examples under the {gh-path}`examples` folder. Look for the examples that contain a `MODULE.bazel` file. @@ -159,6 +197,16 @@ The `python.toolchain()` call makes its contents available under a repo named Remember to call `use_repo()` to make repos visible to your module: `use_repo(python, "python_3_11")` + +:::{deprecated} 1.1.0 +The toolchain specific `py_binary` and `py_test` symbols are aliases to the regular rules. +i.e. Deprecated `load("@python_versions//3.11:defs.bzl", "py_binary")` & `load("@python_versions//3.11:defs.bzl", "py_test")` + +Usages of them should be changed to load the regular rules directly; +i.e. Use `load("@rules_python//python:py_binary.bzl", "py_binary")` & `load("@rules_python//python:py_test.bzl", "py_test")` and then specify the `python_version` when using the rules corresponding to the python version you defined in your toolchain. {ref}`Library modules with version constraints` +::: + + #### Toolchain usage in other rules Python toolchains can be utilized in other bazel rules, such as `genrule()`, by @@ -508,4 +556,4 @@ of available toolchains. Currently the following flags are used to influence toolchain selection: * {obj}`--@rules_python//python/config_settings:py_linux_libc` for selecting the Linux libc variant. * {obj}`--@rules_python//python/config_settings:py_freethreaded` for selecting - the freethreaded experimental Python builds available from `3.13.0` onwards. + the freethreaded experimental Python builds available from `3.13.0` onwards. \ No newline at end of file