//python:defs.bzl

Core rules for building Python projects.

rulecurrent_py_toolchain(name)

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

Changed in version 1.4.0:From now on, we also expose$(PYTHON2_ROOTPATH) and$(PYTHON3_ROOTPATH) which are runfileslocations equivalents of$(PYTHON2) and `$(PYTHON3) respectively.

Attributes:

• name –(Name)

  A unique name for this target.

  mandatory

py_binary(**attrs)

Creates an executable Python program.

This is the public macro wrapping the underlying rule. Args are forwardedon as-is unless otherwise specified. See the underlyingpy_binaryrule for detailed attribute documentation.

This macro affects the following args:

• python_version: cannot bePY2

• srcs_version: cannot bePY2 orPY2ONLY

• tags: May have special marker values added, if not already present.

Args:

• attrs – Rule attributes forwarded onto the underlyingpy_binary.

rulepy_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 withhttp_file, or produced as outputs of other rules.

It may be used like apy_library, in thedeps of other Python rules.

This is similar tojava_import.

Attributes:

• name –(Name)

  A unique name for this target.

  mandatory

• deps –(list[label])(default[])

  The list of other libraries to be linked in to the binary target.

  optional

  Required providers:PyInfo

• srcs –(list[label])(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.

  optional

py_library(**attrs)

Creates an executable Python program.

This is the public macro wrapping the underlying rule. Args are forwardedon as-is unless otherwise specified. Seepy_library for detailed attribute documentation.

This macro affects the following args:

• srcs_version: cannot bePY2 orPY2ONLY

• tags: May have special marker values added, if not already present.

Args:

• attrs – Rule attributes forwarded ontopy_library.

py_runtime(**attrs)

Creates an executable Python program.

This is the public macro wrapping the underlying rule. Args are forwardedon as-is unless otherwise specified. Seepy_runtimefor detailed attribute documentation.

This macro affects the following args:

• python_version: cannot bePY2

• srcs_version: cannot bePY2 orPY2ONLY

• tags: May have special marker values added, if not already present.

Args:

• attrs – Rule attributes forwarded ontopy_runtime.

py_runtime_pair(name,py2_runtime=None,py3_runtime=None,**attrs)

A toolchain rule for Python.

This is a macro around the underlyingpy_runtime_pair rule.

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 3runtime.

Usually the wrapped runtimes are declared using thepy_runtime rule, but anyrule returning aPyRuntimeInfo provider may be used.

This rule returns aplatform_common.ToolchainInfo provider with the followingschema:

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

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")

Args:

• name – str, the name of the target

• py2_runtime –(defaultNone)

  optional Label; must be unset or None; an error is raisedotherwise.

• py3_runtime –(defaultNone)

  Label; a target withPyRuntimeInfo for Python 3.

• attrs – Extra attrs passed onto the native rule

py_test(**attrs)

Creates an executable Python program.

This is the public macro wrapping the underlying rule. Args are forwardedon as-is unless otherwise specified. Seepy_test for detailed attribute documentation.

This macro affects the following args:

• python_version: cannot bePY2

• srcs_version: cannot bePY2 orPY2ONLY

• tags: May have special marker values added, if not already present.

Args:

• attrs – Rule attributes forwarded ontopy_test.

providerPyInfo

Encapsulates information provided by the Python rules.

Instead of creating this object directly, usePyInfoBuilder andthePyCommonApi utilities.

PyInfo.<init>(direct_original_sources,direct_pyc_files,direct_pyi_files,has_py2_only_sources,has_py3_only_sources,imports,transitive_implicit_pyc_files,transitive_implicit_pyc_source_files,transitive_original_sources,transitive_pyc_files,transitive_pyi_files,transitive_sources,uses_shared_libraries,venv_symlinks)

PyInfo.direct_original_sources:depset[File]

The.py source files (if any) that are considered directly provided bythe target. This field is intended so that static analysis tools can recover theoriginal Python source files, regardless of any build settings (e.g.precompiling), so they can analyze source code. The values are typically the.py files in thesrcs attribute (or equivalent).

Added in version 1.1.0.

PyInfo.direct_pyc_files:depset[File]

Precompiled Python files that are considered directly providedby the target andmust be included.

These files usually come from, e.g., a library settingprecompile=enabledto forcibly enable precompiling for itself. Downstream binaries are expectedto always include these files, as the originating target expects them to exist.

PyInfo.direct_pyi_files:depset[File]

Type definition files (usually.pyi files) for the Python modules provided bythis target. Usually they describe the source files listed indirect_original_sources. This field is primarily for static analysis tools.

These files areusually build-time only and not included as part of a runnableprogram.

Note

This may contain implementation-specific file types specific to a particulartype checker.

Added in version 1.1.0.

PyInfo.has_py2_only_sources:bool

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

PyInfo.has_py3_only_sources:bool

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

PyInfo.imports:depset[str]

A depset of import path strings to be added to thePYTHONPATH of executablePython targets. These are accumulated from the transitivedeps.The order of the depset is not guaranteed and may be changed in the future. Itis recommended to usedefault order (the default).

PyInfo.transitive_implicit_pyc_files:depset[File]

Automatically generated pyc files that downstream binaries (or equivalent)can choose to include in their output. If not included, thentransitive_implicit_pyc_source_files should be included instead.

Added in version 0.37.0.

PyInfo.transitive_implicit_pyc_source_files:depset[File]

Source.py files fortransitive_implicit_pyc_files that downstreambinaries (or equivalent) can choose to include in their output. If not included,thentransitive_implicit_pyc_files should be included instead.

Added in version 0.37.0.

PyInfo.transitive_original_sources:depset[File]

The transitive set of.py source files (if any) that are considered theoriginal sources for this target and its transitive dependencies. This field isintended so that static analysis tools can recover the original Python sourcefiles, regardless of any build settings (e.g. precompiling), so they can analyzesource code. The values are typically the.py files in thesrcs attribute(or equivalent).

This is superset ofdirect_original_sources.

Added in version 1.1.0.

PyInfo.transitive_pyc_files:depset[File]

The transitive set of precompiled files that must be included.

These files usually come from, e.g., a library settingprecompile=enabledto forcibly enable precompiling for itself. Downstream binaries are expectedto always include these files, as the originating target expects them to exist.

PyInfo.transitive_pyi_files:depset[File]

The transitive set of type definition files (usually.pyi files) for thePython modules for this target and its transitive dependencies. this target.Usually they describe the source files listed intransitive_original_sources.This field is primarily for static analysis tools.

These files areusually build-time only and not included as part of a runnableprogram.

Note

This may contain implementation-specific file types specific to a particulartype checker.

Added in version 1.1.0.

PyInfo.transitive_sources:depset[File]

A (postorder-compatible) depset of.py files that are considered requiredand downstream binaries (or equivalent)must include in their outputsto have a functioning program.

Normally, these are the.py files in the appearing in the target’ssrcs andthesrcs of the target’s transitivedeps,however, precompile settingsmay cause.py files to be omitted. In particular, pyc-only builds may resultin this depset beingempty.

Changed in version 0.37.0:The files are considered necessary for downstream binaries to function;previously they were considerd informational and largely unused.

PyInfo.uses_shared_libraries:bool

Whether any of this target’s transitivedeps has a shared library file (suchas a.so file).

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

PyInfo.venv_symlinks:depset[VenvSymlinkEntry]

Warning

Experimental API. This API is still under development and may change or beremoved without notice.

Added in version 1.5.0.

providerPyRuntimeInfo

Contains information about a Python runtime, as returned by thepy_runtimerule.

Warning

This is anunstable public API. It may change more frequently and has weakercompatibility guarantees.

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

PyRuntimeInfo.<init>(abi_flags,bootstrap_template,coverage_files,coverage_tool,files,implementation_name,interpreter,interpreter_path,interpreter_version_info,pyc_tag,python_version,site_init_template,stage2_bootstrap_template,stub_shebang,supports_build_time_venv,zip_main_template)

PyRuntimeInfo.abi_flags:str

The runtime’s ABI flags, i.e.sys.abiflags.

Added in version 1.0.0.

PyRuntimeInfo.bootstrap_template:File

A template of code responsible for the initial startup of a program.

This code is responsible for:

• Locating the target interpreter. Typically it is in runfiles, but not always.

• Setting necessary environment variables, command line flags, or otherconfiguration that can’t be modified after the interpreter starts.

• Invoking the appropriate entry point. This is usually a second-stage bootstrapthat performs additional setup prior to running a program’s actual entry point.

The--bootstrap_impl flag affects how this stage 1 bootstrapis expected to behave and the substutitions performed.

• --bootstrap_impl=system_python substitutions:%is_zipfile%,%python_binary%,%target%,%workspace_name,%coverage_tool%,%import_all%,%imports%,%main%,%shebang%

• --bootstrap_impl=script substititions:%is_zipfile%,%python_binary%,%python_binary_actual%,%target%,%workspace_name,%shebang%,%stage2_bootstrap%

Substitution definitions:

• %shebang%: The shebang to use with the bootstrap; the bootstrap templatemay choose to ignore this.

• %stage2_bootstrap%: A runfiles-relative path to the stage 2 bootstrap.

• %python_binary%: The path to the target Python interpreter. There are threetypes of paths:

  • An absolute path to a system interpreter (e.g. begins with/).

  • A runfiles-relative path to an interpreter (e.g.somerepo/bin/python3)

  • A program to search for on PATH, i.e. a word without spaces, e.g.python3.

  When--bootstrap_impl=script is used, this is always a runfiles-relativepath to a venv-based interpreter executable.

• %python_binary_actual%: The path to the interpreter that%python_binary% invokes. There are three types of paths:

  • An absolute path to a system interpreter (e.g. begins with/).

  • A runfiles-relative path to an interpreter (e.g.somerepo/bin/python3)

  • A program to search for on PATH, i.e. a word without spaces, e.g.python3.

  Only set for zip builds with--bootstrap_impl=script; other builds will usean empty string.

• %workspace_name%: The name of the workspace the target belongs to.

• %is_zipfile%: The string1 if this template is prepended to a zipfile tocreate a self-executable zip file. The string0 otherwise.

For the other substitution definitions, see thestage2_bootstrap_templatedocs.

Changed in version 0.33.0:The set of substitutions depends on--bootstrap_impl

PyRuntimeInfo.coverage_files:depset[File]|None

The files required at runtime for usingcoverage_tool. Will beNone if nocoverage_tool was provided.

PyRuntimeInfo.coverage_tool:File|None

If set, this field is aFile representing tool used for collecting codecoverage information from python tests. Otherwise, this isNone.

PyRuntimeInfo.files:depset[File]|None

If this is an in-build runtime, this field is adepset ofFiles that need tobe added to the runfiles of an executable target that uses this runtime (inparticular, files needed byinterpreter). The value ofinterpreter need notbe included in this field. If this is a platform runtime then this field isNone.

PyRuntimeInfo.implementation_name:str|None

The Python implementation name (sys.implementation.name)

PyRuntimeInfo.interpreter:File|None

If this is an in-build runtime, this field is aFile representing theinterpreter. Otherwise, this isNone. Note that an in-build runtime can useeither a prebuilt, checked-in interpreter or an interpreter built from source.

PyRuntimeInfo.interpreter_path:str|None

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

PyRuntimeInfo.interpreter_version_info:struct

Version information about the interpreter this runtime provides.It should match the format given bysys.version_info, howeverfor simplicity, the micro, releaselevel, and serial values areoptional.A struct with the following fields:

• major:int, the major version number

• minor:int, the minor version number

• micro:int|None, the micro version number

• releaselevel:str|None, the release level

• serial:int|None, the serial number of the release

PyRuntimeInfo.pyc_tag:str|None

The tag portion of a pyc filename, e.g. thecpython-39 infixoffoo.cpython-39.pyc. See PEP 3147. If not specified, it will be computedfromimplementation_name andinterpreter_version_info. If nopyc_tag is available, then only source-less pyc generation will functioncorrectly.

PyRuntimeInfo.python_version:str

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

PyRuntimeInfo.site_init_template:File

The template to use for the binary-specific site-init hook run by theinterpreter at startup.

Added in version 1.0.0.

PyRuntimeInfo.stage2_bootstrap_template:File

A template of Python code that runs under the desired interpreter and isresponsible for orchestrating calling the program’s actual main code. Thisbootstrap is responsible for affecting the current runtime’s state, such asimport paths or enabling coverage, so that, when it runs the program’s actualmain code, it works properly under Bazel.

The following substitutions are made during template expansion:

• %main%: A runfiles-relative path to the program’s actual main file. Thiscan be a.py or.pyc file, depending on precompile settings.

• %coverage_tool%: Runfiles-relative path to the coverage library’s entry point.If coverage is not enabled or available, an empty string.

• %import_all%: The stringTrue if all repositories in the runfiles shouldbe added to sys.path. The stringFalse otherwise.

• %imports%: A colon-delimited string of runfiles-relative paths to add tosys.path.

• %target%: The name of the target this is for.

• %workspace_name%: The name of the workspace the target belongs to.

Added in version 0.33.0.

PyRuntimeInfo.stub_shebang:str

“Shebang” expression prepended to the bootstrapping Python stubscript used when executingpy_binary targets. Does notapply to Windows.

PyRuntimeInfo.supports_build_time_venv:bool

True if this toolchain supports the build-time created virtual environment.False if not or unknown. If build-time venv creation isn’t supported, then binaries mayfallback to non-venv solutions or creating a venv at runtime.

In order to use the build-time created virtual environment, a toolchain needsto meet two criteria:

1. Specifying the underlying executable (e.g./usr/bin/python3, as reported bysys._base_executable) for the venv executable ($venv/bin/python3, as reportedbysys.executable). This typically requires relative symlinking the venvpath to the underlying path at build time, or using thePYTHONEXECUTABLEenvironment variable (Python 3.11+) at runtime.

2. Having the build-time created site-packages directory(<venv>/lib/python{version}/site-packages) recognized by the runtimeinterpreter. This typically requires the Python version to be known atbuild-time and match at runtime.

Added in version 1.5.0.

PyRuntimeInfo.zip_main_template:File

A template of Python code that becomes a zip file’s top-level__main__.pyfile. The top-level__main__.py file is used when the zip file is explicitlypassed to a Python interpreter. See PEP 441 for more information about zipappsupport. Note that py_binary-generated zip files are self-executing andskip calling__main__.py.

The following substitutions are made during template expansion:

• %stage2_bootstrap%: A runfiles-relative string to the stage 2 bootstrap file.

• %python_binary%: The path to the target Python interpreter. There are threetypes of paths:

  • An absolute path to a system interpreter (e.g. begins with/).

  • A runfiles-relative path to an interpreter (e.g.somerepo/bin/python3)

  • A program to search for on PATH, i.e. a word without spaces, e.g.python3.

• %workspace_name%: The name of the workspace for the built target.

Added in version 0.33.0.