private:py_test_rule.bzl

Implementation of py_test rule.

create_py_test_rule_builder()

Create a rule builder for a py_test.

Important

Public, but volatile, API. Some parts are stable, while others are implementation details and may change more frequently.

Added in version 1.3.0.

Returns:: ruleb.Rule with the necessary settings for creating a py_test rule.

rule py_test(name, config_settings={}, data=[], deps=[], distribs=[], env={}, env_inherit=[], imports=[], interpreter_args=[], legacy_create_init=-1, licenses=[], main=None, main_module='', precompile='inherit', precompile_invalidation_mode='auto', precompile_optimize_level=0, precompile_source_retention='inherit', pyc_collection='inherit', pyi_deps=[], pyi_srcs=[], python_version='', srcs=[], srcs_version='', stamp=0)

Provides:

PyExecutableInfo | PyInfo

Attributes:

name – (Name)
A unique name for this target.

mandatory
config_settings – (dict[label, str]) (default {})
Config settings to change for this target.

The keys are labels for settings, and the values are strings for the new value to use. Pass Label objects or canonical label strings for the keys to ensure they resolve as expected (canonical labels start with @@ and can be obtained by calling str(Label(...))).

Most @rules_python//python/config_setting settings can be used here, which allows, for example, making only a certain py_binary use --boostrap_impl=script.

Additional or custom config settings can be registered using the add_transition_setting API. This allows, for example, forcing a particular CPU, or defining a custom setting that select() uses elsewhere to pick between pip.parse hubs. See the [How to guide on multiple versions of a library] for a more concrete example.

Note

These values are transitioned on, so will affect the analysis graph and the associated memory overhead. The more unique configurations in your overall build, the more memory and (often unnecessary) re-analysis and re-building can occur. See https://bazel.build/extending/config#memory-performance-considerations for more information about risks and considerations.

Added in version 1.7.0.

optional
data – (list[label]) (default [])
The list of files need by this library at runtime. See comments about the data attribute typically defined by rules.

There is no py_embed_data like there is cc_embed_data and go_embed_data. This is because Python has a concept of runtime resources.

optional
deps – (list[label]) (default [])
List of additional libraries to be linked in to the target. See comments about the deps attribute typically defined by rules. These are typically py_library rules.

Targets that only provide data files used at runtime belong in the data attribute.
Note

The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged.
- PyInfo.venv_symlinks uses default ordering.
See PyInfo for more information about the ordering of its depsets and how its fields are merged.
optional

Required providers: PyInfo | CcInfo
distribs – (list[str]) (default [])

optional
env – (dict[str, str]) (default {})
Dictionary of strings; optional; values are subject to $(location) and “Make variable” substitution.

Specifies additional environment variables to set when the target is executed by test or run.

optional
env_inherit – (list[str]) (default [])
List of strings; optional

Specifies additional environment variables to inherit from the external environment when the test is executed by bazel test.

optional
imports – (list[str]) (default [])
List of import directories to be added to the PYTHONPATH.

Subject to “Make variable” substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to PYTHONPATH by py_binary rules that depend on this rule. The strings are repo-runfiles-root relative,

Absolute paths (paths that start with /) and paths that references a path above the execution root are not allowed and will result in an error.

optional
interpreter_args – (list[str]) (default [])
Arguments that are only applicable to the interpreter.

The args an interpreter supports are specific to the interpreter. For CPython, see https://docs.python.org/3/using/cmdline.html.

Note

Only supported for --bootstrap_impl=script. Ignored otherwise.

See also

The RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS environment variable

Added in version 1.3.0.

optional
legacy_create_init – (int) (default -1)
Whether to implicitly create empty __init__.py files in the runfiles tree. These are created in every directory containing Python source code or shared libraries, and every parent directory of those directories, excluding the repo root directory. The default, -1 (auto), means true unless --incompatible_default_to_explicit_init_py is used. If false, the user is responsible for creating (possibly empty) __init__.py files and adding them to the srcs of Python targets as required.

optional
licenses – (list[str]) (default [])

optional
main – (label) (default None)
Optional; the name of the source file that is the main entry point of the application. This file must also be listed in srcs. If left unspecified, name, with .py appended, is used instead. If name does not match any filename in srcs, main must be specified.

This is mutually exclusive with main_module.

optional
main_module – (str) (default “”)
Module name to execute as the main program.

When set, srcs is not required, and it is assumed the module is provided by a dependency.

See https://docs.python.org/3/using/cmdline.html#cmdoption-m for more information about running modules as the main program.

This is mutually exclusive with main.

Added in version 1.3.0.

Changed in version 1.7.0: Support added for --bootstrap_impl=system_python.

optional
precompile – (str) (default “inherit”)
Whether py source files for this target should be precompiled.

Values:
- inherit: Allow the downstream binary decide if precompiled files are used.
- enabled: Compile Python source files at build time.
- disabled: Don’t compile Python source files at build time.
See also
- The --precompile flag, which can override this attribute in some cases and will affect all targets when building.
- The pyc_collection attribute for transitively enabling precompiling on a per-target basis.
- The Precompiling docs for a guide about using precompiling.
optional
precompile_invalidation_mode – (str) (default “auto”)
How precompiled files should be verified to be up-to-date with their associated source files. Possible values are:
- auto: The effective value will be automatically determined by other build settings.
- checked_hash: Use the pyc file if the hash of the source file matches the hash recorded in the pyc file. This is most useful when working with code that you may modify.
- unchecked_hash: Always use the pyc file; don’t check the pyc’s hash against the source file. This is most useful when the code won’t be modified.
For more information on pyc invalidation modes, see https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode

optional
precompile_optimize_level – (int) (default 0)
The optimization level for precompiled files.

For more information about optimization levels, see the compile() function’s optimize arg docs at https://docs.python.org/3/library/functions.html#compile

NOTE: The value -1 means “current interpreter”, which will be the interpreter used at build time when pycs are generated, not the interpreter used at runtime when the code actually runs.

optional
precompile_source_retention – (str) (default “inherit”)
Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are:
- inherit: Inherit the value from the --precompile_source_retention flag.
- keep_source: Include the original Python source.
- omit_source: Don’t include the original py source.
optional
pyc_collection – (str) (default “inherit”)
Determines whether pyc files from dependencies should be manually included.

Valid values are:
- inherit: Inherit the value from --precompile.
- include_pyc: Add implicitly generated pyc files from dependencies. i.e. pyc files for targets that specify precompile="inherit".
- disabled: Don’t add implicitly generated pyc files. Note that pyc files may still come from dependencies that enable precompiling at the target level.
optional
pyi_deps – (list[label]) (default [])
Dependencies providing type definitions the library needs.

These are dependencies that satisfy imports guarded by typing.TYPE_CHECKING. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however).

Added in version 1.1.0.

optional

Required providers: PyInfo | CcInfo
pyi_srcs – (list[label]) (default [])
Type definition files for the library.

These are typically .pyi files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however).

Added in version 1.1.0.

optional
python_version – (str) (default “”)
The Python version this target should use.

The value should be in X.Y or X.Y.Z (or compatible) format. If empty or unspecified, the incoming configuration’s --python_version flag is inherited. For backwards compatibility, the values PY2 and PY3 are accepted, but treated as an empty/unspecified value.

Note

In order for the requested version to be used, there must be a toolchain configured to match the Python version. If there isn’t, then it may be silently ignored, or an error may occur, depending on the toolchain configuration.

Changed in version 1.1.0: This attribute was changed from only accepting PY2 and PY3 values to accepting arbitrary Python versions.

optional
srcs – (list[label]) (default [])
The list of Python source files that are processed to create the target. This includes all your checked-in code and may include generated source files. The .py files belong in srcs and library targets belong in deps. Other binary files that may be needed at run time belong in data.

optional
srcs_version – (str) (default “”)
Defunct, unused, does nothing.

optional
stamp – (int) (default 0)
Whether to encode build information into the binary. Possible values:
- stamp = 1: Always stamp the build information into the binary, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the binary and any downstream actions that depend on it.
- stamp = 0: Always replace build information by constant values. This gives good build result caching.
- stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.
Stamped binaries are not rebuilt unless their dependencies change.

Stamped build information can accessed using the bazel_binary_info module. See the [Accessing build information docs] for more information.

Warning

Stamping can harm build performance by reducing cache hits and should be avoided if possible.

In addition, this transitions the --stamp flag, which can additional config state overhead.

Note

Stamping of build data output is always disabled for the exec config.

optional