• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright 2023 The Bazel Authors. All rights reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""Public entry point for py_runtime_pair."""
16
17load("@bazel_tools//tools/python:toolchain.bzl", _py_runtime_pair = "py_runtime_pair")
18
19# NOTE: This doc is copy/pasted from the builtin py_runtime_pair rule so our
20# doc generator gives useful API docs.
21def py_runtime_pair(name, py2_runtime = None, py3_runtime = None, **attrs):
22    """A toolchain rule for Python.
23
24    This used to wrap up to two Python runtimes, one for Python 2 and one for Python 3.
25    However, Python 2 is no longer supported, so it now only wraps a single Python 3
26    runtime.
27
28    Usually the wrapped runtimes are declared using the `py_runtime` rule, but any
29    rule returning a `PyRuntimeInfo` provider may be used.
30
31    This rule returns a `platform_common.ToolchainInfo` provider with the following
32    schema:
33
34    ```python
35    platform_common.ToolchainInfo(
36        py2_runtime = None,
37        py3_runtime = <PyRuntimeInfo or None>,
38    )
39    ```
40
41    Example usage:
42
43    ```python
44    # In your BUILD file...
45
46    load("@rules_python//python:defs.bzl", "py_runtime_pair")
47
48    py_runtime(
49        name = "my_py3_runtime",
50        interpreter_path = "/system/python3",
51        python_version = "PY3",
52    )
53
54    py_runtime_pair(
55        name = "my_py_runtime_pair",
56        py3_runtime = ":my_py3_runtime",
57    )
58
59    toolchain(
60        name = "my_toolchain",
61        target_compatible_with = <...>,
62        toolchain = ":my_py_runtime_pair",
63        toolchain_type = "@rules_python//python:toolchain_type",
64    )
65    ```
66
67    ```python
68    # In your WORKSPACE...
69
70    register_toolchains("//my_pkg:my_toolchain")
71    ```
72
73    Args:
74        name: str, the name of the target
75        py2_runtime: optional Label; must be unset or None; an error is raised
76            otherwise.
77        py3_runtime: Label; a target with `PyRuntimeInfo` for Python 3.
78        **attrs: Extra attrs passed onto the native rule
79    """
80    if attrs.get("py2_runtime"):
81        fail("PYthon 2 is no longer supported: see https://github.com/bazelbuild/rules_python/issues/886")
82    _py_runtime_pair(
83        name = name,
84        py2_runtime = py2_runtime,
85        py3_runtime = py3_runtime,
86        **attrs
87    )
88