Lines Matching +full:python +full:- +full:version
1 :::{default-domain} bzl
4 # Configuring Python toolchains and runtimes
6 This documents how to configure the Python toolchain and runtimes for different
12 you're using Python. There are 4 basic use cases:
14 1. A root module that always uses Python. For example, you're building a
15 Python application.
16 2. A library module with dev-only uses of Python. For example, a Java project
17 that only uses Python as part of testing itself.
18 3. A library module without version constraints. For example, a rule set with
19 Python build tools, but defers to the user as to what Python version is used
21 4. A library module with version constraints. For example, a rule set with
22 Python build tools, and the module requires a specific version of Python
27 Root modules are always the top-most module. These are special in two ways:
34 explicitly specify the Python version you want to use. This ensures that
35 dependencies don't change the Python version out from under you. Remember that
36 `rules_python` will set a version by default, but it will change regularly as
37 it tracks a recent Python version.
39 NOTE: If your root module only uses Python for development of the module itself,
40 you should read the dev-only library module section.
43 bazel_dep(name="rules_python", version=...)
44 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
46 python.toolchain(python_version = "3.12", is_default = True)
52 bzlmod module graph -- it's unknown where in the breadth-first search order the
56 #### Library modules with dev-only Python usage
58 A library module with dev-only Python usage is usually one where Python is only
60 Python program to generate test data, but real usage of the rules don't need
61 Python to work. To configure this, follow the root-module setup, but remember to
66 bazel_dep(name = "rules_python", version=..., dev_dependency = True)
68 python = use_extension(
69 "@rules_python//python/extensions:python.bzl",
70 "python",
74 python.toolchain(python_version = "3.12", is_default=True)
77 #### Library modules without version constraints
79 A library module without version constraints is one where the version of Python
80 used for the Python programs it runs isn't chosen by the module itself. Instead,
81 it's up to the root module to pick an appropriate version of Python.
84 the normal `//python:py_binary.bzl` et al rules. There is no need to call
85 `python.toolchain` -- rules_python ensures _some_ Python version is available,
86 but more often the root module will specify some version.
90 bazel_dep(name = "rules_python", version=...)
93 #### Library modules with version constraints
95 A library module with version constraints is one where the module requires a
96 specific Python version be used with its tools. This has some pros/cons:
98 * It allows the library's tools to use a different version of Python than
99 the rest of the build. For example, a user's program could use Python 3.12,
100 while the library module's tools use Python 3.10.
102 to test for the particular Python version they intend to run as.
103 * It raises the support burden for the library module because the version of
104 Python being used needs to be regularly incremented.
108 To configure this, request the Python versions needed in MODULE.bazel and use
109 the version-aware rules for `py_binary`.
113 bazel_dep(name = "rules_python", version=...)
115 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
116 python.toolchain(python_version = "3.12")
124 ### Pinning to a Python version
126 Pinning to a version allows targets to force that a specific Python version is
127 used, even if the root module configures a different version as a default. This
130 1. For submodules to ensure they run with the appropriate Python version
131 2. To allow incremental, per-target, upgrading to newer Python versions,
132 typically in a mono-repo situation.
134 To configure a submodule with the version-aware rules, request the particular
135 version you need, then use the `@python_versions` repo to use the rules that
139 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
141 python.toolchain(
144 use_repo(python, "python_versions")
148 the rules that force that particular version. Multiple versions can be specified
151 For more documentation, see the bzlmod examples under the {gh-path}`examples`
156 The `python.toolchain()` call makes its contents available under a repo named
158 `python.toolchain(python_version="3.11")` creates the repo `@python_3_11`.
160 `use_repo(python, "python_3_11")`
164 Python toolchains can be utilized in other bazel rules, such as `genrule()`, by
165 adding the `toolchains=["@rules_python//python:current_py_toolchain"]`
166 attribute. You can obtain the path to the Python interpreter using the
168 Variables](https://bazel.build/reference/be/make-variables). See the
169 {gh-path}`test_current_py_toolchain <tests/load_from_macro/BUILD.bazel>` target
179 via {attr}`python.override.available_python_versions`.
180 * Setting particular `X.Y.Z` Python versions when modules request `X.Y` version
181 via {attr}`python.override.minor_mapping`.
182 * Per-version control of the coverage tool used using
183 {attr}`python.single_version_platform_override.coverage_tool`.
184 * Adding additional Python versions via {bzl:obj}`python.single_version_override` or
185 {bzl:obj}`python.single_version_platform_override`.
193 To depend on a particular unreleased version, you can do the following:
199 # Update the SHA and VERSION to the lastest version available here:
204 VERSION="0.23.1"
209 strip_prefix = "rules_python-{}".format(VERSION),
210 …b.com/bazelbuild/rules_python/releases/download/{}/rules_python-{}.tar.gz".format(VERSION,VERSION),
213 load("@rules_python//python:repositories.bzl", "py_repositories")
220 To register a hermetic Python toolchain rather than rely on a system-installed interpreter for runt…
223 load("@rules_python//python:repositories.bzl", "python_register_toolchains")
227 # Available versions are listed in @rules_python//python:versions.bzl.
228 # We recommend using the same version your team is already standardized on.
234 load("@rules_python//python:pip.bzl", "pip_parse")
243 After registration, your Python targets will use the toolchain's interpreter during execution, but …
244 is still used to 'bootstrap' Python targets (see https://github.com/bazelbuild/rules_python/issues/…
245 …olchain. Please refer to [python-build-standalone documentation's _Quirks_ section](https://gregor…
253 the Python runtime).
255 Bazel itself automatically registers `@bazel_tools//tools/python:autodetecting_toolchain`
258 automatically registers a higher-priority toolchain; it won't be used unless
261 To aid migration off the Bazel-builtin toolchain, rules_python provides
262 {bzl:obj}`@rules_python//python/runtime_env_toolchains:all`. This is an equivalent
278 information necessary to build Python targets. Each one has an
284 {obj}`RBE`, cross-platform building, multiple Python versions,
285 building Python from source, embeding Python (as opposed to building separate
292 The target toolchain type is {obj}`//python:toolchain_type`, and it
293 is for _target configuration_ runtime information, e.g., the Python version
298 Python 2 transition, `py_runtime` is wrapped in {obj}`py_runtime_pair`,
308 ### Python C toolchain type
310 The Python C toolchain type ("py cc") is {obj}`//python/cc:toolchain_type`, and
312 provide `Python.h`.
319 relating to the C/C++ information for the Python runtime. As such, when defining
327 The exec tools toolchain type is {obj}`//python:exec_tools_toolchain_type`,
331 This toolchain type is intended to hold only _exec configuration_ values --
332 usually tools (prebuilt or from-source) used to build Python targets.
340 {external:bzl:obj}`toolchain.target_settings` to the Python version the tools
343 target configuration (e.g. Python version), then for one to be chosen based on
349 * If you had a precompiler that supported any version of Python, then
350 putting the Python version in `target_settings` is unnecessary.
364 Here, we show an example for a semi-complicated toolchain suite, one that is:
366 * A CPython-based interpreter
367 * For Python version 3.12.0
368 * Using an in-build interpreter built from source
380 load("@rules_python//python:py_cc_toolchain.bzl", "py_cc_toolchain")
381 load("@rules_python//python:py_exec_tools_toolchain.bzl", "py_exec_tools_toolchain")
382 load("@rules_python//python:py_runtime.bzl", "py_runtime")
383 load("@rules_python//python:py_runtime_pair.bzl", "py_runtime_pair")
391 interpreter = ":python",
413 exec_interpreter = "@rules_python/python:none",
414 precompiler = "precompiler-cpython-3.12"
428 toolchain_type = "@rules_python//python:toolchain_type",
434 toolchain_type = "@rules_python//python/cc:toolchain_type",
441 toolchain_type = "@rules_python//python:exec_tools_toolchain_type",
443 "@rules_python//python/config_settings:is_python_3.12",
454 order](https://bazel.build/extending/toolchains#toolchain-resolution). In brief,
455 toolchain order is the BFS-order of the modules; see the bazel docs for a more
467 * {obj}`--@rules_python//python/config_settings:py_linux_libc` for selecting the Linux libc variant.
468 * {obj}`--@rules_python//python/config_settings:py_freethreaded` for selecting
469 the freethreaded experimental Python builds available from `3.13.0` onwards.