//python:defs.bzl¶

Core rules for building Python projects.

current_py_toolchain¶

current_py_toolchain(name)

This rule exists so that the current python toolchain can be used in the toolchains attribute of other rules, such as genrule. It allows exposing a python toolchain after toolchain resolution has happened, to a rule which expects a concrete implementation of a toolchain, rather than a toolchain_type which could be resolved to that toolchain.

Provides: no providers advertised.

ATTRIBUTES ¶

name¶:: (required Name) A unique name for this target.

find_requirements¶

Propagates on attributes: deps

The aspect definition. Can be invoked on the command line as

bazel build //pkg:my_py_binary_target –aspects=@rules_python//python:defs.bzl%find_requirements –output_groups=pyversioninfo

ATTRIBUTES ¶

name¶:: (required Name) A unique name for this target.

py_binary¶

py_binary(attrs)

See the Bazel core py_binary documentation.

PARAMETERS ¶

attrs¶:: Rule attributes

py_import¶

py_import(name, deps=[], srcs=[])

This rule allows the use of Python packages as dependencies.

It imports the given .egg file(s), which might be checked in source files, fetched externally as with http_file, or produced as outputs of other rules.

It may be used like a py_library, in the deps of other Python rules.

This is similar to java_import.

Provides: no providers advertised.

ATTRIBUTES ¶

name¶:

(required Name) A unique name for this target.

deps¶:

(optional list of labels, default []) The list of other libraries to be linked in to the binary target.

Required providers: PyInfo

srcs¶:

(optional list of labels, default []) 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.

py_library¶

py_library(attrs)

See the Bazel core py_library documentation.

PARAMETERS ¶

attrs¶:: Rule attributes

py_runtime¶

py_runtime(attrs)

See the Bazel core py_runtime documentation.

PARAMETERS ¶

attrs¶:: Rule attributes

py_runtime_pair¶

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:

platform_common.ToolchainInfo(
    py2_runtime = None,
    py3_runtime = <PyRuntimeInfo or None>,
)

Example usage:

# In your BUILD file...

load("@rules_python//python:py_runtime.bzl", "py_runtime")
load("@rules_python//python:py_runtime_pair.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",
)

# In your WORKSPACE...

register_toolchains("//my_pkg:my_toolchain")

PARAMETERS ¶

name¶:: str, the name of the target
py2_runtime¶:: (default None) optional Label; must be unset or None; an error is raised otherwise.
py3_runtime¶:: (default None) Label; a target with PyRuntimeInfo for Python 3.
attrs¶:: Extra attrs passed onto the native rule

py_test¶

py_test(attrs)

See the Bazel core py_test documentation.

PARAMETERS ¶

attrs¶:: Rule attributes

PyInfo¶

PyInfo(has_py2_only_sources, has_py3_only_sources, imports, transitive_sources, uses_shared_libraries)

Encapsulates information provided by the Python rules.

FIELDS ¶

has_py2_only_sources¶:

Whether any of this target’s transitive sources requires a Python 2 runtime.

has_py3_only_sources¶:

Whether any of this target’s transitive sources requires a Python 3 runtime.

imports¶:

A depset of import path strings to be added to the PYTHONPATH of executable Python targets. These are accumulated from the transitive deps. The order of the depset is not guaranteed and may be changed in the future. It is recommended to use default order (the default).

transitive_sources¶:

A (postorder-compatible) depset of .py files appearing in the target’s srcs and the srcs of the target’s transitive deps.

uses_shared_libraries¶:

Whether any of this target’s transitive deps has a shared library file (such as a .so file).

This field is currently unused in Bazel and may go away in the future.

PyRuntimeInfo¶

PyRuntimeInfo(bootstrap_template, coverage_files, coverage_tool, files, interpreter, interpreter_path, interpreter_version_info, python_version, stub_shebang)

Contains information about a Python runtime, as returned by the py_runtime rule.

A Python runtime describes either a platform runtime or an in-build runtime. A platform runtime accesses a system-installed interpreter at a known path, whereas an in-build runtime points to a File that acts as the interpreter. In both cases, an “interpreter” is really any executable binary or wrapper script that is capable of running a Python script passed on the command line, following the same conventions as the standard CPython interpreter.

FIELDS ¶

bootstrap_template¶:

See py_runtime_rule.bzl%py_runtime.bootstrap_template for docs.

coverage_files¶:

The files required at runtime for using coverage_tool. Will be None if no coverage_tool was provided.

coverage_tool¶:

If set, this field is a File representing tool used for collecting code coverage information from python tests. Otherwise, this is None.

files¶:

If this is an in-build runtime, this field is a depset of Filesthat need to be added to the runfiles of an executable target that uses this runtime (in particular, files needed by interpreter). The value of interpreter need not be included in this field. If this is a platform runtime then this field is None.

interpreter¶:

If this is an in-build runtime, this field is a File representing the interpreter. Otherwise, this is None. Note that an in-build runtime can use either a prebuilt, checked-in interpreter or an interpreter built from source.

interpreter_path¶:

If this is a platform runtime, this field is the absolute filesystem path to the interpreter on the target platform. Otherwise, this is None.

interpreter_version_info¶:

Version information about the interpreter this runtime provides. It should match the format given by sys.version_info, however for simplicity, the micro, releaselevel, and serial values are optional.A struct with the following fields:

major: int, the major version number
minor: int, the minor version number
micro: optional int, the micro version number
releaselevel: optional str, the release level
serial: optional int, the serial number of the release

python_version¶:

Indicates whether this runtime uses Python major version 2 or 3. Valid values are (only) "PY2" and "PY3".

stub_shebang¶:

“Shebang” expression prepended to the bootstrapping Python stub script used when executing py_binary targets. Does not apply to Windows.