//python/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 areimplementation details and may change more frequently.

Added in version 1.3.0.

Returns:

ruleb.Rule with the necessary settingsfor creating apy_test rule.

rulepy_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 valueto use. PassLabel objects or canonical label strings for the keys to ensurethey resolve as expected (canonical labels start with@@ and can beobtained by callingstr(Label(...))).

  Most@rules_python//python/config_setting settings can be used here, whichallows, for example, making only a certainpy_binary use--boostrap_impl=script.

  Additional or custom config settings can be registered using theadd_transition_setting API. This allows, for example, forcing aparticular CPU, or defining a custom setting thatselect() uses elsewhereto pick betweenpip.parse hubs. See the [How to guide on multipleversions of a library] for a more concrete example.

  Note

  These values are transitioned on, so will affect the analysis graph and theassociated memory overhead. The more unique configurations in your overallbuild, the more memory and (often unnecessary) re-analysis and re-buildingcan occur. Seehttps://bazel.build/extending/config#memory-performance-considerations formore 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 aboutthedata attribute typically defined by rules.

  There is nopy_embed_data like there iscc_embed_data andgo_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 aboutthedeps attribute typically defined byrules.These are typicallypy_library rules.

  Targets that only provide data files used at runtime belong in thedataattribute.

  Note

  The order of this list can matter because it affects the order that informationfrom dependencies is merged in, which can be relevant depending on the orderingmode of depsets that are merged.

  • PyInfo.venv_symlinks uses default ordering.

  SeePyInfo for more information about the ordering of its depsets andhow 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 “Makevariable” substitution.

  Specifies additional environment variables to set when the target is executed bytest orrun.

  optional

• env_inherit –(list[str])(default[])

  List of strings; optional

  Specifies additional environment variables to inherit from the externalenvironment 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 addedfor this rule and all rules that depend on it (note: not the rules this ruledepends on. Each directory will be added toPYTHONPATH bypy_binary rulesthat depend on this rule. The strings are repo-runfiles-root relative,

  Absolute paths (paths that start with/) and paths that references a pathabove 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. ForCPython, see https://docs.python.org/3/using/cmdline.html.

  Note

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

  See also

  TheRULES_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 sharedlibraries, and every parent directory of those directories, excluding the reporoot directory. The default,-1 (auto), means true unless--incompatible_default_to_explicit_init_py is used. If false, the user isresponsible for creating (possibly empty)__init__.py files and adding them tothesrcs of Python targets as required.

  optional

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

  optional

• main –(label)(defaultNone)

  Optional; the name of the source file that is the main entry point of theapplication. This file must also be listed insrcs. If left unspecified,name, with.py appended, is used instead. Ifname does not match anyfilename insrcs,main must be specified.

  This is mutually exclusive withmain_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 isprovided by a dependency.

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

  This is mutually exclusive withmain.

  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 filesfor 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 casesand will affect all targets when building.

  • Thepyc_collection attribute for transitively enabling precompiling ona per-target basis.

  • ThePrecompiling 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 associatedsource files. Possible values are:

  • auto: The effective value will be automatically determined by other buildsettings.

  • checked_hash: Use the pyc file if the hash of the source file matches the hashrecorded in the pyc file. This is most useful when working with code thatyou may modify.

  • unchecked_hash: Always use the pyc file; don’t check the pyc’s hash againstthe source file. This is most useful when the code won’t be modified.

  For more information on pyc invalidation modes, seehttps://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode

  optional

• precompile_optimize_level –(int)(default0)

  The optimization level for precompiled files.

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

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

  optional

• precompile_source_retention –(str)(default“inherit”)

  Determines, when a source file is compiled, if the source file is keptin 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 specifyprecompile="inherit".

  • disabled: Don’t add implicitly generated pyc files. Note thatpyc files may still come from dependencies that enable precompiling at thetarget level.

  optional

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

  Dependencies providing type definitions the library needs.

  These are dependencies that satisfy imports guarded bytyping.TYPE_CHECKING.These are build-time only dependencies and not included as part of a runnableprogram (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 specificformats are allowed. These files are build-time only dependencies and not includedas 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 inX.Y orX.Y.Z (or compatible) format. If empty orunspecified, the incoming configuration’s--python_version flag isinherited. For backwards compatibility, the valuesPY2 andPY3 areaccepted, but treated as an empty/unspecified value.

  Note

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

  Changed in version 1.1.0:This attribute was changed from only acceptingPY2 andPY3 values toaccepting arbitrary Python versions.

  optional

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

  The list of Python source files that are processed to create the target. Thisincludes all your checked-in code and may include generated source files. The.py files belong insrcs and library targets belong indeps. Other binaryfiles that may be needed at run time belong indata.

  optional

• srcs_version –(str)(default“”)

  Defunct, unused, does nothing.

  optional

• stamp –(int)(default0)

  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 killsremote caching for the binary and any downstream actions that depend on it.

  • stamp=0: Always replace build information by constant values. This givesgood 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.

  WARNING: Stamping can harm build performance by reducing cache hits and shouldbe avoided if possible.

  optional