@aspect_rules_py//py:defs.bzl

Documentation for @aspect_rules_py@v1.8.4 — View source

Re-implementations of py_binary and py_test

Choosing the Python version

The python_version attribute must refer to a python toolchain version which has been registered in the WORKSPACE or MODULE.bazel file. When using WORKSPACE, this may look like this:

load("@rules_python//python:repositories.bzl", "py_repositories", "python_register_toolchains")

python_register_toolchains(
    name = "python_toolchain_3_8",
    python_version = "3.8.12",
    # setting set_python_version_constraint makes it so that only matches py_* rule
    # which has this exact version set in the `python_version` attribute.
    set_python_version_constraint = True,
)

# It's important to register the default toolchain last it will match any py_* target.
python_register_toolchains(
    name = "python_toolchain",
    python_version = "3.9",
)

Configuring for MODULE.bazel may look like this:

python = use_extension("@rules_python//python/extensions:python.bzl", "python")
python.toolchain(python_version = "3.8.12", is_default = False)
python.toolchain(python_version = "3.9", is_default = True)

Rule: `py_pex_binary`

Build a pex executable from a py_binary Kind: Executable rule

Attributes

name

required

A unique name for this target.

binary

label

required

A py_binary target

inject_env

dictionary: String → String

default:"{}"

Environment variables to set when running the pex binary.

inherit_path

string

default:"\"\""

Whether to inherit the sys.path (aka PYTHONPATH) of the environment that the binary runs in.Use false to not inherit sys.path; use fallback to inherit sys.path after packaged dependencies; and use prefer to inherit sys.path before packaged dependencies.

python_shebang

string

default:"#!/usr/bin/env python3"

python_interpreter_constraints

list of strings

default:"[\"CPython=={major}.{minor}.*\"]"

Python interpreter versions this PEX binary is compatible with. A list of semver strings. The placeholder strings {major}, {minor}, {patch} can be used for gathering version information from the hermetic python toolchain.

Rule: `py_binary_rule`

Run a Python program under Bazel. Most users should use the py_binary macro instead of loading this directly. Kind: Executable rule

Attributes

name

required

A unique name for this target.

env

dictionary: String → String

default:"{}"

Environment variables to set when running the binary.

main

label

default:"None"

Script to execute with the Python interpreter.Must be a label pointing to a .py source file. If such a label is provided, it will be honored.If no label is provided AND there is only one srcs file, that srcs file will be used.If there are more than one srcs, a file matching {name}.py is searched for. This is for historical compatibility with the Bazel native py_binary and rules_python. Relying on this behavior is STRONGLY discouraged, may produce warnings and may be deprecated in the future.

venv

string

default:"\"\""

The name of the Python virtual environment within which deps should be resolved.Part of the aspect_rules_py//uv system, has no effect in rules_python’s pip.

python_version

string

default:"\"\""

Whether to build this target and its transitive deps for a specific python version.

package_collisions

string

default:"error"

The action that should be taken when a symlink collision is encountered when creating the venv. A collision can occur when multiple packages providing the same file are installed into the venv. The possible values are:

“error”: When conflicting symlinks are found, an error is reported and venv creation halts.
“warning”: When conflicting symlinks are found, an warning is reported, however venv creation continues.
“ignore”: When conflicting symlinks are found, no message is reported and venv creation continues.

interpreter_options

list of strings

default:"[]"

Additional options to pass to the Python interpreter in addition to -B and -I passed by rules_py

srcs

list of labels

default:"[]"

Python source files.

deps

list of labels

default:"[]"

Targets that produce Python code, commonly py_library rules.

data

list of labels

default:"[]"

Runtime dependencies of the program.The transitive closure of the data dependencies will be available in the .runfiles folder for this binary/test. The program may optionally use the Runfiles lookup library to locate the data files, see https://pypi.org/project/bazel-runfiles/.

imports

list of strings

default:"[]"

List of import directories to be added to the PYTHONPATH.

resolutions

dictionary: Label → String

default:"{}"

Satisfy a virtual_dep with a mapping from external package name to the label of an installed package that provides it. See virtual_deps.

Rule: `py_test_rule`

Run a Python program under Bazel. Most users should use the py_test macro instead of loading this directly. Kind: Test rule

Attributes

name

required

A unique name for this target.

env

dictionary: String → String

default:"{}"

Environment variables to set when running the binary.

main

label

default:"None"

venv

string

default:"\"\""

The name of the Python virtual environment within which deps should be resolved.Part of the aspect_rules_py//uv system, has no effect in rules_python’s pip.

python_version

string

default:"\"\""

Whether to build this target and its transitive deps for a specific python version.

package_collisions

string

default:"error"

“error”: When conflicting symlinks are found, an error is reported and venv creation halts.
“warning”: When conflicting symlinks are found, an warning is reported, however venv creation continues.
“ignore”: When conflicting symlinks are found, no message is reported and venv creation continues.

interpreter_options

list of strings

default:"[]"

Additional options to pass to the Python interpreter in addition to -B and -I passed by rules_py

srcs

list of labels

default:"[]"

Python source files.

deps

list of labels

default:"[]"

Targets that produce Python code, commonly py_library rules.

data

list of labels

default:"[]"

imports

list of strings

default:"[]"

List of import directories to be added to the PYTHONPATH.

resolutions

dictionary: Label → String

default:"{}"

Satisfy a virtual_dep with a mapping from external package name to the label of an installed package that provides it. See virtual_deps.

env_inherit

list of strings

default:"[]"

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

Rule: `py_library`

Attributes

name

required

A unique name for this target.

virtual_deps

list of strings

default:"[]"

srcs

list of labels

default:"[]"

Python source files.

deps

list of labels

default:"[]"

Targets that produce Python code, commonly py_library rules.

data

list of labels

default:"[]"

imports

list of strings

default:"[]"

List of import directories to be added to the PYTHONPATH.

resolutions

dictionary: Label → String

default:"{}"

Satisfy a virtual_dep with a mapping from external package name to the label of an installed package that provides it. See virtual_deps.

Rule: `py_unpacked_wheel`

Attributes

name

required

A unique name for this target.

src

label

required

The Wheel file, as defined by https://packaging.python.org/en/latest/specifications/binary-distribution-format/#binary-distribution-format

Function: `py_pytest_main`

py_pytest_main wraps the template rendering target and the final py_library.

Parameters

name

required

The name of the runable target that updates the test entry file.

py_library

name

Use this attribute to override the default py_library rule.

deps

name

default:"[]"

A list containing the pytest library target, e.g., @pypi_pytest//:pkg.

data

name

default:"[]"

A list of data dependencies to pass to the py_library target.

testonly

name

default:"True"

A boolean indicating if the py_library target is testonly.

kwargs

string_list

The extra arguments passed to the template rendering target.

Function: `py_venv`

Build a Python virtual environment and produce a script to link it into the build directory.

Parameters

venv_name

name

default:"None"

srcs

name

default:"[]"

kwargs

string_list

Function: `py_venv_link`

Build a Python virtual environment and produce a script to link it into the build directory.

Parameters

venv_name

name

default:"None"

srcs

name

default:"[]"

kwargs

string_list

Function: `py_image_layer`

Produce a separate tar output for each layer of a python app

Requires awk to be installed on the host machine/rbe runner.

For better performance, it is recommended to split the output of a py_binary into multiple layers. This can be done by grouping files into layers based on their path by using the layer_groups attribute. The matching order for layer groups is as follows:

layer_groups are checked first.
If no match is found for layer_groups, the default layer groups are checked.
Any remaining files are placed into the default layer.

The default layer groups are:

{
    "packages": "\.runfiles/.*/site-packages",, # contains third-party deps
    "interpreter": "\.runfiles/python.*-.*/", # contains the python interpreter
}

Parameters

name

required

base name for targets

binary

name

required

a py_binary target

root

name

default:"/"

Path to where the layers should be rooted. If not specified, the layers will be rooted at the workspace root.

layer_groups

name

default:"{}"

Additional layer groups to create. They are used to group files into layers based on their path. In the form of: {"<name>": "regex_to_match_against_file_paths"}

compress

name

default:"gzip"

Compression algorithm to use. Default is gzip. See: https://github.com/bazel-contrib/bazel-lib/blob/main/docs/tar.md#tar_rule-compress

tar_args

name

default:"[]"

Additional arguments to pass to the tar rule. Default is []. See: https://github.com/bazel-contrib/bazel-lib/blob/main/docs/tar.md#tar_rule-args

compute_unused_inputs

name

default:"1"

Whether to compute unused inputs. Default is 1. See: https://github.com/bazel-contrib/bazel-lib/blob/main/docs/tar.md#tar_rule-compute_unused_inputs

platform

name

default:"None"

The platform to use for the transition. Default is None. See: https://github.com/bazel-contrib/bazel-lib/blob/main/docs/transitions.md#platform_transition_binary-target_platform

owner

name

default:"None"

An owner uid for the uncompressed files. See mtree_mutate: https://github.com/bazel-contrib/bazel-lib/blob/main/docs/tar.md#mutating-the-tar-contents

group

name

default:"None"

A group uid for the uncompressed files. See mtree_mutate: https://github.com/bazel-contrib/bazel-lib/blob/main/docs/tar.md#mutating-the-tar-contents

kwargs

string_list

attribute that apply to all targets expanded by the macro

Returns: A list of labels for each layer.

Function: `resolutions.empty`

Function: `resolutions.from_requirements`

Parameters

base

name

required

requirement_fn

name

Function: `py_binary`

Wrapper macro for py_binary_rule. Creates a py_venv target to constrain the interpreter and packages used at runtime. Users can bazel run [name].venv to create this virtualenv, then use it in the editor or other tools.

Parameters

name

required

Name of the rule.

srcs

name

default:"[]"

Python source files.

main

name

default:"None"

Entry point. Like rules_python, this is treated as a suffix of a file that should appear among the srcs. If absent, then [name].py is tried. As a final fallback, if the srcs has a single file, that is used as the main.

kwargs

string_list

additional named parameters to py_binary_rule.

Function: `py_test`

Identical to py_binary, but produces a target that can be used with bazel test.

Parameters

name

required

Name of the rule.

srcs

name

default:"[]"

Python source files.

main

name

default:"None"

pytest_main

name

default:"False"

If set, generate a py_pytest_main script and use it as the main. The deps should include the pytest package (as well as the coverage package if desired).

kwargs

string_list

additional named parameters to py_binary_rule.

Overview

JavaScript, TypeScript, HTML & CSS

Python

Ruby

Shell

Utility

Choosing the Python version

Rule: `py_pex_binary`

Attributes

Rule: `py_binary_rule`

Attributes

Rule: `py_test_rule`

Attributes

Rule: `py_library`

Attributes

Rule: `py_unpacked_wheel`

Attributes

Function: `py_pytest_main`

Parameters

Function: `py_venv`

Parameters

Function: `py_venv_link`

Parameters

Function: `py_image_layer`

Parameters

Function: `resolutions.empty`

Function: `resolutions.from_requirements`

Parameters

Function: `py_binary`

Parameters

Function: `py_test`

Parameters

Overview

JavaScript, TypeScript, HTML & CSS

Python

Ruby

Shell

Utility

Documentation Index

​Choosing the Python version

​Rule: py_pex_binary

​Attributes

​Rule: py_binary_rule

​Attributes

​Rule: py_test_rule

​Attributes

​Rule: py_library

​Attributes

​Rule: py_unpacked_wheel

​Attributes

​Function: py_pytest_main

​Parameters

​Function: py_venv

​Parameters

​Function: py_venv_link

​Parameters

​Function: py_image_layer

​Parameters

​Function: resolutions.empty

​Function: resolutions.from_requirements

​Parameters

​Function: py_binary

​Parameters

​Function: py_test

​Parameters

Choosing the Python version

Rule: `py_pex_binary`

Attributes

Rule: `py_binary_rule`

Attributes

Rule: `py_test_rule`

Attributes

Rule: `py_library`

Attributes

Rule: `py_unpacked_wheel`

Attributes

Function: `py_pytest_main`

Parameters

Function: `py_venv`

Parameters

Function: `py_venv_link`

Parameters

Function: `py_image_layer`

Parameters

Function: `resolutions.empty`

Function: `resolutions.from_requirements`

Parameters

Function: `py_binary`

Parameters

Function: `py_test`

Parameters