Bazel Central Registry

@aspect_rules_py//py:defs.bzl

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)

Functions & Macros

py_pytest_main

py_pytest_main wraps the template rendering target and the final py_library.

Parameters

`*name`	The name of the runable target that updates the test entry file.
`py_library`	Use this attribute to override the default py_library rule. Default: `<rule py_library>`
`deps`	A list containing the pytest library target, e.g., @pypi_pytest//:pkg. Default: `[]`
`data`	A list of data dependencies to pass to the py_library target. Default: `[]`
`testonly`	A boolean indicating if the py_library target is testonly. Default: `True`
`kwargs`	The extra arguments passed to the template rendering target.

py_venv

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

Parameters

`venv_name`	Default: `None`
`srcs`	Default: `[]`
`kwargs`

py_venv_link

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

Parameters

`venv_name`	Default: `None`
`srcs`	Default: `[]`
`kwargs`

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:
1. layer_groups are checked first.
2. If no match is found for layer_groups, the default layer groups are checked.
3. 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`	base name for targets
`*binary`	a py_binary target
`root`	Path to where the layers should be rooted. If not specified, the layers will be rooted at the workspace root. Default: `"/"`
`layer_groups`	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"}` Default: `{}`
`compress`	Compression algorithm to use. Default is gzip. See: https://github.com/bazel-contrib/bazel-lib/blob/main/docs/tar.md#tar_rule-compress Default: `"gzip"`
`tar_args`	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 Default: `[]`
`compute_unused_inputs`	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 Default: `1`
`platform`	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 Default: `None`
`owner`	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 Default: `None`
`group`	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 Default: `None`
`kwargs`	attribute that apply to all targets expanded by the macro

resolutions.empty

resolutions.from_requirements

Parameters

`*base`
`requirement_fn`	Default: `<function lambda from //py/private:virtual.bzl>`

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`	Name of the rule.
`srcs`	Python source files. Default: `[]`
`main`	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. Default: `None`
`kwargs`	additional named parameters to `py_binary_rule`.

py_test

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

Parameters

`*name`	Name of the rule.
`srcs`	Python source files. Default: `[]`
`main`	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. Default: `None`
`pytest_main`	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). Default: `False`
`kwargs`	additional named parameters to `py_binary_rule`.

Rules

py_pex_binary

Build a pex executable from a py_binary

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*binary`	`label`	A py_binary target
`inject_env`	`dictionary: String → String`	Environment variables to set when running the pex binary. Default: `{}`
`inherit_path`	`string`	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. Default: `""`
`python_shebang`	`string`	Default: `"#!/usr/bin/env python3"`
`python_interpreter_constraints`	`list of strings`	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. Default: `["CPython=={major}.{minor}.*"]`

py_binary_rule

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

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`env`	`dictionary: String → String`	Environment variables to set when running the binary. Default: `{}`
`main`	`label`	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. Default: `None`
`venv`	`string`	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. Default: `""`
`python_version`	`string`	Whether to build this target and its transitive deps for a specific python version. Default: `""`
`package_collisions`	`string`	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. Default: `"error"`
`interpreter_options`	`list of strings`	Additional options to pass to the Python interpreter in addition to -B and -I passed by rules_py Default: `[]`
`srcs`	`list of labels`	Python source files. Default: `[]`
`deps`	`list of labels`	Targets that produce Python code, commonly `py_library` rules. Default: `[]`
`data`	`list of labels`	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/. Default: `[]`
`imports`	`list of strings`	List of import directories to be added to the PYTHONPATH. Default: `[]`
`resolutions`	`dictionary: Label → String`	Satisfy a virtual_dep with a mapping from external package name to the label of an installed package that provides it. See virtual_deps. Default: `{}`

py_test_rule

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

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`env`	`dictionary: String → String`	Environment variables to set when running the binary. Default: `{}`
`main`	`label`	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. Default: `None`
`venv`	`string`	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. Default: `""`
`python_version`	`string`	Whether to build this target and its transitive deps for a specific python version. Default: `""`
`package_collisions`	`string`	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. Default: `"error"`
`interpreter_options`	`list of strings`	Additional options to pass to the Python interpreter in addition to -B and -I passed by rules_py Default: `[]`
`srcs`	`list of labels`	Python source files. Default: `[]`
`deps`	`list of labels`	Targets that produce Python code, commonly `py_library` rules. Default: `[]`
`data`	`list of labels`	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/. Default: `[]`
`imports`	`list of strings`	List of import directories to be added to the PYTHONPATH. Default: `[]`
`resolutions`	`dictionary: Label → String`	Satisfy a virtual_dep with a mapping from external package name to the label of an installed package that provides it. See virtual_deps. Default: `{}`
`env_inherit`	`list of strings`	Specifies additional environment variables to inherit from the external environment when the test is executed by bazel test. Default: `[]`

py_library

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`virtual_deps`	`list of strings`	Default: `[]`
`srcs`	`list of labels`	Python source files. Default: `[]`
`deps`	`list of labels`	Targets that produce Python code, commonly `py_library` rules. Default: `[]`
`data`	`list of labels`	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/. Default: `[]`
`imports`	`list of strings`	List of import directories to be added to the PYTHONPATH. Default: `[]`
`resolutions`	`dictionary: Label → String`	Satisfy a virtual_dep with a mapping from external package name to the label of an installed package that provides it. See virtual_deps. Default: `{}`

py_unpacked_wheel

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*src`	`label`	The Wheel file, as defined by https://packaging.python.org/en/latest/specifications/binary-distribution-format/#binary-distribution-format

@aspect_rules_py//py:repositories.bzl

Declare runtime dependencies

These are needed for local dev, and users must install them as well.
See https://docs.bazel.build/versions/main/skylark/deploying.html#dependencies

Functions & Macros

http_archive

Parameters

`*name`
`kwargs`

rules_py_dependencies

Fetch rules_py's dependencies

@aspect_rules_py//py:toolchains.bzl

Declare toolchains

Functions & Macros

register_autodetecting_python_toolchain

Registers a Python toolchain that will auto detect the location of Python that can be used with rules_py.

The autodetecting Python toolchain replaces the automatically registered one under bazel, and correctly handles the
Python virtual environment indirection created by rules_py. However it is recommended to instead use one of the prebuilt
Python interpreter toolchains from rules_python, rather than rely on the the correct Python binary being present on the host.

Parameters

*name

rules_py_toolchains

Create a downloaded toolchain for every tool under every supported platform.

Parameters

`name`	prefix used in created repositories Default: `"rules_py_tools"`
`register`	whether to call the register_toolchains, should be True for WORKSPACE and False for bzlmod. Default: `True`
`is_prerelease`	True iff there are no pre-built tool binaries for this version of rules_py Default: `True`

@aspect_rules_py//py/unstable:defs.bzl

Preview features.

Unstable rules and preview machinery.
No promises are made about compatibility across releases.

Functions & Macros

py_venv

Parameters

kwargs

py_venv_link

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

Parameters

`venv_name`	Default: `None`
`srcs`	Default: `[]`
`kwargs`

py_venv_binary

Parameters

kwargs

py_venv_test

Parameters

kwargs