Venv

Core Bazel rules for defining Python targets.

Rules

py_venv_binary
py_venv_library
py_venv_test
py_venv_toolchain
py_venv_zipapp

Functions

py_venv_common.create_dep_info
py_venv_common.create_py_info
py_venv_common.create_runfiles_collection
py_venv_common.create_venv_attrs
py_venv_common.create_venv_config_info
py_venv_common.create_venv_entrypoint
py_venv_common.get_toolchain

py_venv_binary

load("@rules_venv//python/venv:defs.bzl", "py_venv_binary")

py_venv_binary(name, deps, srcs, data, env, imports, main)

A py_venv_binary is an executable Python program consisting of a collection of .py source files (possibly belonging to other py_library rules), a *.runfiles directory tree containing all the code and data needed by the program at run-time, and a stub script that starts up the program with the correct initial environment and data.

load("@rules_venv//python/venv:defs.bzl", "py_venv_binary")

py_venv_binary(
    name = "foo",
    srcs = ["foo.py"],
    data = [":transform"],  # a cc_binary which we invoke at run time
    deps = [
        ":bar",  # a py_library
    ],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Other python targets to link to the current target.	List of labels	optional	`[]`
srcs	The list of source (.py) files that are processed to create the target.	List of labels	optional	`[]`
data	Files needed by this rule at runtime. May list file or rule targets. Generally allows any target.	List of labels	optional	`[]`
env	Dictionary of strings; values are subject to `$(location)` and "Make variable" substitution.	Dictionary: String -> String	optional	`{}`
imports	List of import directories to be added to the `PYTHONPATH`.	List of strings	optional	`[]`
main	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` is used instead. If `name` does not match any filename in `srcs`, `main` must be specified.	Label	optional	`None`

py_venv_library

load("@rules_venv//python/venv:defs.bzl", "py_venv_library")

py_venv_library(name, deps, srcs, data, imports)

A library of Python code that can be depended upon.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Other python targets to link to the current target.	List of labels	optional	`[]`
srcs	The list of source (.py) files that are processed to create the target.	List of labels	optional	`[]`
data	Files needed by this rule at runtime. May list file or rule targets. Generally allows any target.	List of labels	optional	`[]`
imports	List of import directories to be added to the `PYTHONPATH`.	List of strings	optional	`[]`

py_venv_test

load("@rules_venv//python/venv:defs.bzl", "py_venv_test")

py_venv_test(name, deps, srcs, data, env, env_inherit, imports, main)

A py_venv_test rule compiles a test. A test is a binary wrapper around some test code.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Other python targets to link to the current target.	List of labels	optional	`[]`
srcs	The list of source (.py) files that are processed to create the target.	List of labels	optional	`[]`
data	Files needed by this rule at runtime. May list file or rule targets. Generally allows any target.	List of labels	optional	`[]`
env	Dictionary of strings; values are subject to `$(location)` and "Make variable" substitution.	Dictionary: String -> String	optional	`{}`
env_inherit	Specifies additional environment variables to inherit from the external environment when the test is executed by `bazel test`.	List of strings	optional	`[]`
imports	List of import directories to be added to the `PYTHONPATH`.	List of strings	optional	`[]`
main	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` is used instead. If `name` does not match any filename in `srcs`, `main` must be specified.	Label	optional	`None`

py_venv_toolchain

load("@rules_venv//python/venv:defs.bzl", "py_venv_toolchain")

py_venv_toolchain(name, zipapp_shebang)

Declare a toolchain for rules_venv rules.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
zipapp_shebang	The shebang to use when creating zipapps (`OutputGroupInfo.python_zip_file`).	String	optional	`""`

py_venv_zipapp

load("@rules_venv//python/venv:defs.bzl", "py_venv_zipapp")

py_venv_zipapp(name, args, binary, env, inherit_args, inherit_env, shebang)

A py_venv_zipapp is an executable Python zipapp which contains all of the dependencies and runfiles for a given executable.

load("@rules_venv//python/venv:defs.bzl", "py_venv_binary", "py_venv_zipapp")

py_venv_binary(
    name = "foo",
    srcs = ["foo.py"],
)

py_venv_zipapp(
    name = "foo_pyz",
    binary = ":foo",
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
args	Arguments to add to the beginning of all invocations of the zipapp.	List of strings	optional	`[]`
binary	The binary to package as a zipapp.	Label	optional	`None`
env	Environment variables to inject into all invocations of the zipapp.	Dictionary: String -> String	optional	`{}`
inherit_args	Inherit template variable expanded arguments from `binary`.	Boolean	optional	`False`
inherit_env	Inherit template variable expanded environment variables from `binary`.	Boolean	optional	`False`
shebang	Optional shebang line to prepend to the zip (provided as content after `#!`).	String	optional	`""`

py_venv_common.create_dep_info

load("@rules_venv//python/venv:defs.bzl", "py_venv_common")

py_venv_common.create_dep_info(*, ctx, deps)

Construct dependency info required for building PyInfo

PARAMETERS

Name	Description	Default Value
ctx	The rule's context object.	none
deps	A list of python dependency targets	none

RETURNS

struct: Dependency info.

py_venv_common.create_py_info

load("@rules_venv//python/venv:defs.bzl", "py_venv_common")

py_venv_common.create_py_info(*, ctx, imports, srcs, dep_info)

Construct a PyInfo provider

PARAMETERS

Name	Description	Default Value
ctx	The rule's context object.	none
imports	The raw `imports` attribute.	none
srcs	A list of python (`.py`) source files.	none
dep_info	Dependency info from the current target.	`None`

RETURNS

PyInfo: A PyInfo provider.

py_venv_common.create_runfiles_collection

load("@rules_venv//python/venv:defs.bzl", "py_venv_common")

py_venv_common.create_runfiles_collection(*, ctx, venv_toolchain, py_toolchain, runfiles,
                                          exclude_files, name, use_zip)

Generate a runfiles directory

This functionality exists due to the lack of native support for generating runfiles in an action. For details see: https://github.com/bazelbuild/bazel/issues/15486

PARAMETERS

Name	Description	Default Value
ctx	The rule's context object.	none
venv_toolchain	A `py_venv_toolchain` toolchain.	none
py_toolchain	A `py_toolchain` toolchain.	none
runfiles	The runfiles to render into a directory	none
exclude_files	A collection of files to exclude from the collection despite them appearing in `runfiles`.	`depset([])`
name	An alternate name to use in the output instead of `ctx.label.name`.	`None`
use_zip	If True, a zip file will be generated instead of a json manifest.	`False`

RETURNS

Tuple[File, Runfiles]: The generated runfiles collection and associated runfiles.

py_venv_common.create_venv_attrs

load("@rules_venv//python/venv:defs.bzl", "py_venv_common")

py_venv_common.create_venv_attrs()

Create attributes for consumers of py_venv_common.

RETURNS

dict: Attributes unique to rules_venv rules.

py_venv_common.create_venv_config_info

load("@rules_venv//python/venv:defs.bzl", "py_venv_common")

py_venv_common.create_venv_config_info(*, label, name, imports)

Construct info used to create venvs.

PARAMETERS

Name	Description	Default Value
label	The label of the target that owns the venv.	none
name	The name for the venv.	none
imports	A list of import paths to write to `.pth` files.	none

RETURNS

struct: the data.

py_venv_common.create_venv_entrypoint

load("@rules_venv//python/venv:defs.bzl", "py_venv_common")

py_venv_common.create_venv_entrypoint(*, ctx, venv_toolchain, py_info, main, runfiles, py_toolchain,
                                      name, use_runfiles_in_entrypoint, force_runfiles)

Create an executable which constructs a python venv and subprocesses a given entrypoint.

PARAMETERS

Name	Description	Default Value
ctx	The rule's context object.	none
venv_toolchain	A `py_venv_toolchain` toolchain.	none
py_info	The `PyInfo` provider for the current target.	none
main	The main python entrypoint.	none
runfiles	Runfiles associated with the executable.	none
py_toolchain	A `py_toolchain` toolchain. If one is not provided one will be acquired via `py_venv_toolchain`.	`None`
name	An alternate name to use in the output instead of `ctx.label.name`.	`None`
use_runfiles_in_entrypoint	If true, an entrypoint will be created that relies on runfiles.	`True`
force_runfiles	If True, a rendered runfiles directory will be used over builtin runfiles where `RUNFILES_DIR` would be provided.	`False`

RETURNS

Tuple[File, Runfiles]: The generated entrypoint and associated runfiles.

py_venv_common.get_toolchain

load("@rules_venv//python/venv:defs.bzl", "py_venv_common")

py_venv_common.get_toolchain(ctx, *, cfg)

Access the py_venv_toolchain from the current configuration.

Note that for cfg = "exec" toolchains, the rule must have the attributes from py_venv_common.create_venv_attrs.

PARAMETERS

Name	Description	Default Value
ctx	The rule's context object.	none
cfg	What configuration to access the toolchain from (`exec` or `target`).	`"target"`

RETURNS

py_venv_toolchain: The accessed toolchain.