//python:py_runtime_info.bzl

Public entry point for PyRuntimeInfo.

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.