diff --git a/docs/python.md b/docs/python.md index 1726ade356..6682e48bd1 100755 --- a/docs/python.md +++ b/docs/python.md @@ -55,20 +55,73 @@ This rule allows the use of Python packages as dependencies. | srcs | The list of Python package files provided to Python targets that depend on this target. Note that currently only the .egg format is accepted. For .whl files, try the whl_library rule. We accept contributions to extend py_import to handle .whl. | List of labels | optional | [] | + + +## py_binary + +
+py_binary(attrs)
+
+ +See the Bazel core [py_binary](https://docs.bazel.build/versions/master/be/python.html#py_binary) documentation. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| attrs | Rule attributes | none | + + + + +## py_library + +
+py_library(attrs)
+
+ +See the Bazel core [py_library](https://docs.bazel.build/versions/master/be/python.html#py_library) documentation. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| attrs | Rule attributes | none | + + + + +## py_runtime + +
+py_runtime(attrs)
+
+ +See the Bazel core [py_runtime](https://docs.bazel.build/versions/master/be/python.html#py_runtime) documentation. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| attrs | Rule attributes | none | + + ## py_runtime_pair 
-py_runtime_pair(name, py2_runtime, py3_runtime)
+py_runtime_pair(name, py2_runtime, py3_runtime, attrs)
A toolchain rule for Python. -This wraps up to two Python runtimes, one for Python 2 and one for Python 3. -The rule consuming this toolchain will choose which runtime is appropriate. -Either runtime may be omitted, in which case the resulting toolchain will be -unusable for building Python code using that version. +This used to wrap up to two Python runtimes, one for Python 2 and one for Python 3. +However, Python 2 is no longer supported, so it now only wraps a single Python 3 +runtime. Usually the wrapped runtimes are declared using the `py_runtime` rule, but any rule returning a `PyRuntimeInfo` provider may be used. @@ -78,7 +131,7 @@ schema: ```python platform_common.ToolchainInfo( - py2_runtime = <PyRuntimeInfo or None>, + py2_runtime = None, py3_runtime = <PyRuntimeInfo or None>, ) ``` @@ -90,12 +143,6 @@ Example usage: load("@rules_python//python:defs.bzl", "py_runtime_pair") -py_runtime( - name = "my_py2_runtime", - interpreter_path = "/system/python2", - python_version = "PY2", -) - py_runtime( name = "my_py3_runtime", interpreter_path = "/system/python3", @@ -104,7 +151,6 @@ py_runtime( py_runtime_pair( name = "my_py_runtime_pair", - py2_runtime = ":my_py2_runtime", py3_runtime = ":my_py3_runtime", ) @@ -123,68 +169,15 @@ register_toolchains("//my_pkg:my_toolchain") ``` -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| py2_runtime | The runtime to use for Python 2 targets. Must have python_version set to PY2. | Label | optional | None | -| py3_runtime | The runtime to use for Python 3 targets. Must have python_version set to PY3. | Label | optional | None | - - - - -## py_binary - -
-py_binary(attrs)
-
- -See the Bazel core [py_binary](https://docs.bazel.build/versions/master/be/python.html#py_binary) documentation. - **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| attrs | Rule attributes | none | - - - - -## py_library - -
-py_library(attrs)
-
- -See the Bazel core [py_library](https://docs.bazel.build/versions/master/be/python.html#py_library) documentation. - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| attrs | Rule attributes | none | - - - - -## py_runtime - -
-py_runtime(attrs)
-
- -See the Bazel core [py_runtime](https://docs.bazel.build/versions/master/be/python.html#py_runtime) documentation. - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| attrs | Rule attributes | none | +| name | str, the name of the target | none | +| py2_runtime | optional Label; must be unset or None; an error is raised otherwise. | None | +| py3_runtime | Label; a target with PyRuntimeInfo for Python 3. | None | +| attrs | Extra attrs passed onto the native rule | none | diff --git a/python/defs.bzl b/python/defs.bzl index 88f28c5fc0..7b60c6513b 100644 --- a/python/defs.bzl +++ b/python/defs.bzl @@ -17,7 +17,6 @@ Core rules for building Python projects. """ load("@bazel_tools//tools/python:srcs_version.bzl", _find_requirements = "find_requirements") -load("@bazel_tools//tools/python:toolchain.bzl", _py_runtime_pair = "py_runtime_pair") load( "//python/private:reexports.bzl", "internal_PyInfo", @@ -25,6 +24,7 @@ load( _py_binary = "py_binary", _py_library = "py_library", _py_runtime = "py_runtime", + _py_runtime_pair = "py_runtime_pair", _py_test = "py_test", ) diff --git a/python/private/reexports.bzl b/python/private/reexports.bzl index 6ad9e0cdcc..987187c155 100644 --- a/python/private/reexports.bzl +++ b/python/private/reexports.bzl @@ -37,6 +37,8 @@ different name. Then we can load it from defs.bzl and export it there under the original name. """ +load("@bazel_tools//tools/python:toolchain.bzl", _py_runtime_pair = "py_runtime_pair") + # The implementation of the macros and tagging mechanism follows the example # set by rules_cc and rules_java. @@ -64,6 +66,8 @@ def py_library(**attrs): Args: **attrs: Rule attributes """ + if attrs.get("srcs_version") in ("PY2", "PY2ONLY"): + fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886") # buildifier: disable=native-python native.py_library(**_add_tags(attrs)) @@ -74,6 +78,10 @@ def py_binary(**attrs): Args: **attrs: Rule attributes """ + if attrs.get("python_version") == "PY2": + fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886") + if attrs.get("srcs_version") in ("PY2", "PY2ONLY"): + fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886") # buildifier: disable=native-python native.py_binary(**_add_tags(attrs)) @@ -84,6 +92,10 @@ def py_test(**attrs): Args: **attrs: Rule attributes """ + if attrs.get("python_version") == "PY2": + fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886") + if attrs.get("srcs_version") in ("PY2", "PY2ONLY"): + fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886") # buildifier: disable=native-python native.py_test(**_add_tags(attrs)) @@ -94,6 +106,78 @@ def py_runtime(**attrs): Args: **attrs: Rule attributes """ + if attrs.get("python_version") == "PY2": + fail("Python 2 is no longer supported: see https://github.com/bazelbuild/rules_python/issues/886") # buildifier: disable=native-python native.py_runtime(**_add_tags(attrs)) + +# NOTE: This doc is copy/pasted from the builtin py_runtime_pair rule so our +# doc generator gives useful API docs. +def py_runtime_pair(name, py2_runtime = None, py3_runtime = None, **attrs): + """A toolchain rule for Python. + + This used to wrap up to two Python runtimes, one for Python 2 and one for Python 3. + However, Python 2 is no longer supported, so it now only wraps a single Python 3 + runtime. + + Usually the wrapped runtimes are declared using the `py_runtime` rule, but any + rule returning a `PyRuntimeInfo` provider may be used. + + This rule returns a `platform_common.ToolchainInfo` provider with the following + schema: + + ```python + platform_common.ToolchainInfo( + py2_runtime = None, + py3_runtime = , + ) + ``` + + Example usage: + + ```python + # In your BUILD file... + + load("@rules_python//python:defs.bzl", "py_runtime_pair") + + py_runtime( + name = "my_py3_runtime", + interpreter_path = "/system/python3", + python_version = "PY3", + ) + + py_runtime_pair( + name = "my_py_runtime_pair", + py3_runtime = ":my_py3_runtime", + ) + + toolchain( + name = "my_toolchain", + target_compatible_with = <...>, + toolchain = ":my_py_runtime_pair", + toolchain_type = "@rules_python//python:toolchain_type", + ) + ``` + + ```python + # In your WORKSPACE... + + register_toolchains("//my_pkg:my_toolchain") + ``` + + Args: + name: str, the name of the target + py2_runtime: optional Label; must be unset or None; an error is raised + otherwise. + py3_runtime: Label; a target with `PyRuntimeInfo` for Python 3. + **attrs: Extra attrs passed onto the native rule + """ + if attrs.get("py2_runtime"): + fail("PYthon 2 is no longer supported: see https://github.com/bazelbuild/rules_python/issues/886") + _py_runtime_pair( + name = name, + py2_runtime = py2_runtime, + py3_runtime = py3_runtime, + **attrs + )