//python/private:py_runtime_rule.bzl

Implementation of py_runtime rule.

rulepy_runtime(name,abi_flags='<AUTO>',bootstrap_template='@rules_python//python/private:bootstrap_template',coverage_tool=None,files=[],implementation_name='cpython',interpreter=None,interpreter_path='',interpreter_version_info={},pyc_tag='',python_version='PY3',site_init_template='@rules_python//python/private:site_init_template',stage2_bootstrap_template='@rules_python//python/private:stage2_bootstrap_template',stub_shebang='#!/usr/bin/envpython3',supports_build_time_venv=True,zip_main_template='@rules_python//python/private:zip_main_template')

Represents a Python runtime used to execute Python code.

Apy_runtime target can represent either aplatform runtime or anin-buildruntime. A platform runtime accesses a system-installed interpreter at a knownpath, whereas an in-build runtime points to an executable target that acts asthe interpreter. In both cases, an “interpreter” means any executable binary orwrapper script that is capable of running a Python script passed on the commandline, following the same conventions as the standard CPython interpreter.

A platform runtime is by its nature non-hermetic. It imposes a requirement onthe target platform to have an interpreter located at a specific path. Anin-build runtime may or may not be hermetic, depending on whether it points toa checked-in interpreter or a wrapper script that accesses the systeminterpreter.

Example

load("@rules_python//python:py_runtime.bzl","py_runtime")py_runtime(name="python-2.7.12",files=glob(["python-2.7.12/**"]),interpreter="python-2.7.12/bin/python",)py_runtime(name="python-3.6.0",interpreter_path="/opt/pyenv/versions/3.6.0/bin/python",)
Attributes:

  • name –(Name)

    A unique name for this target.

    mandatory

  • abi_flags –(str)(default“<AUTO>”)

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

    If not set, then it will be set based on flags.

    optional

  • bootstrap_template –(label)(default“@rules_python//python/private:bootstrap_template”)

    The bootstrap script template file to use. Should have %python_binary%,

    This template, after expansion, becomes the executable file used to start theprocess, so it is responsible for initial bootstrapping actions such as findingthe Python interpreter, runfiles, and constructing an environment to run theintended Python application.

    While this attribute is currently optional, it will become required when thePython rules are moved out of Bazel itself.

    The exact variable names expanded is an unstable API and is subject to change.The API will become more stable when the Python rules are moved out of Bazelitself.

    See @bazel_tools//tools/python:python_bootstrap_template.txt for more variables.

    optional

  • coverage_tool –(label)(defaultNone)

    This is a target to use for collecting code coverage information frompy_binary andpy_test targets.

    If set, the target must either produce a single file or be an executable target.The path to the single file, or the executable if the target is executable,determines the entry point for the python coverage tool. The target and itsrunfiles will be added to the runfiles when coverage is enabled.

    The entry point for the tool must be loadable by a Python interpreter (e.g. a.py or.pyc file). It must accept the command line argumentsofcoverage.py, at least includingtherun andlcov subcommands.

    optional

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

    For an in-build runtime, this is the set of files comprising this runtime.These files will be added to the runfiles of Python binaries that use thisruntime. For a platform runtime this attribute must not be set.

    optional

  • implementation_name –(str)(default“cpython”)

    The Python implementation name (sys.implementation.name)

    optional

  • interpreter –(label)(defaultNone)

    For an in-build runtime, this is the target to invoke as the interpreter. Itcan be either of:

    • A single file, which will be the interpreter binary. It’s assumed suchinterpreters are either self-contained single-file executables or anysupporting files are specified infiles.

    • An executable target. The target’s executable will be the interpreter binary.Any other default outputs (target.files) and plain files runfiles(runfiles.files) will be automatically included as if specified in thefiles attribute.

      NOTE: the runfiles of the target may not yet be properly respected/propagatedto consumers of the toolchain/interpreter, seebazel-contrib/rules_python/issues/1612

    For a platform runtime (i.e.interpreter_path being set) this attribute mustnot be set.

    optional

  • interpreter_path –(str)(default“”)

    For a platform runtime, this is the absolute path of a Python interpreter onthe target platform. For an in-build runtime this attribute must not be set.

    optional

  • interpreter_version_info –(dict[str,str])(default{})

    Version information about the interpreter this runtime provides.

    If not specified, uses--python_version

    The supported keys match the names forsys.version_info. While the inputvalues are strings, most are converted to ints. The supported keys are:

    • 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

    Changed in version 0.36.0:--python_version determines the default value.

    optional

  • pyc_tag –(str)(default“”)

    Optional string; 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 no pyc_tag isavailable, then only source-less pyc generation will function correctly.

    optional

  • python_version –(str)(default“PY3”)

    Whether this runtime is for Python major version 2 or 3. Valid values are"PY2"and"PY3".

    The default value is controlled by the--incompatible_py3_is_default flag.However, in the future this attribute will be mandatory and have no defaultvalue.

    optional

  • site_init_template –(label)(default“@rules_python//python/private:site_init_template”)

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

    Added in version 0.41.0.

    optional

  • stage2_bootstrap_template –(label)(default“@rules_python//python/private:stage2_bootstrap_template”)

    The template to use when two stage bootstrapping is enabled

    optional

  • stub_shebang –(str)(default“#!/usr/bin/env python3”)

    “Shebang” expression prepended to the bootstrapping Python stub scriptused when executingpy_binary targets.

    See https://github.com/bazelbuild/bazel/issues/8685 formotivation.

    Does not apply to Windows.

    optional

  • supports_build_time_venv –(bool)(defaultTrue)

    Whether this runtime supports virtualenvs created at build time.

    SeePyRuntimeInfo.supports_build_time_venv for docs.

    Added in version 1.5.0.

    optional

  • zip_main_template –(label)(default“@rules_python//python/private:zip_main_template”)

    The template to use for a zip’s top-level__main__.py file.

    This becomes the entry point executed whenpythonfoo.zip is run.

    optional