pip integration

This contains a set of rules that are used to support inclusion of third-party dependencies via fully locked requirements.txt files. Some of the exported symbols should not be used and they are either undocumented here or marked as for internal use only.

Import pip requirements into Bazel.

whl_library_alias

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
default_version	Optional Python version in major.minor format, e.g. ‘3.10’.The Python version of the wheel to use when the versions from `version_map` don‘t match. This allows the default (version unaware) rules to match and select a wheel. If not specified, then the default rules won’t be able to resolve a wheel and an error will occur.	String	optional	`""`
repo_mapping	A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).	Dictionary: String -> String	required
version_map	-	Dictionary: String -> String	required
wheel_name	-	String	required

compile_pip_requirements

Generates targets for managing pip dependencies with pip-compile.

By default this rules generates a filegroup named “[name]” which can be included in the data of some other compile_pip_requirements rule that references these requirements (e.g. with -r ../other/requirements.txt).

It also generates two targets for running pip-compile:

validate with bazel test [name]_test
update with bazel run [name].update

If you are using a version control system, the requirements.txt generated by this rule should be checked into it to ensure that all developers/users have the same dependency versions.

PARAMETERS

Name	Description	Default Value
name	base name for generated targets, typically “requirements”.	none
extra_args	passed to pip-compile.	`[]`
extra_deps	extra dependencies passed to pip-compile.	`[]`
generate_hashes	whether to put hashes in the requirements_txt file.	`True`
py_binary	the py_binary rule to be used.	`<function py_binary>`
py_test	the py_test rule to be used.	`<function py_test>`
requirements_in	file expressing desired dependencies.	`None`
requirements_txt	result of “compiling” the requirements.in file.	`None`
requirements_darwin	File of darwin specific resolve output to check validate if requirement.in has changes.	`None`
requirements_linux	File of linux specific resolve output to check validate if requirement.in has changes.	`None`
requirements_windows	File of windows specific resolve output to check validate if requirement.in has changes.	`None`
visibility	passed to both the _test and .update rules.	`["//visibility:private"]`
tags	tagging attribute common to all build rules, passed to both the _test and .update rules.	`None`
kwargs	other bazel attributes passed to the “_test” rule.	none

multi_pip_parse

NOT INTENDED FOR DIRECT USE!

This is intended to be used by the multi_pip_parse implementation in the template of the multi_toolchain_aliases repository rule.

PARAMETERS

Name	Description	Default Value
name	the name of the multi_pip_parse repository.	none
default_version	the default Python version.	none
python_versions	all Python toolchain versions currently registered.	none
python_interpreter_target	a dictionary which keys are Python versions and values are resolved host interpreters.	none
requirements_lock	a dictionary which keys are Python versions and values are locked requirements files.	none
kwargs	extra arguments passed to all wrapped pip_parse.	none

RETURNS

The internal implementation of multi_pip_parse repository rule.

package_annotation

Annotations to apply to the BUILD file content from package generated from a pip_repository rule.

PARAMETERS

Name	Description	Default Value
additive_build_content	Raw text to add to the generated `BUILD` file of a package.	`None`
copy_files	A mapping of `src` and `out` files for @bazel_skylib//rules:copy_file.bzl	`{}`
copy_executables	A mapping of `src` and `out` files for @bazel_skylib//rules:copy_file.bzl. Targets generated here will also be flagged as executable.	`{}`
data	A list of labels to add as `data` dependencies to the generated `py_library` target.	`[]`
data_exclude_glob	A list of exclude glob patterns to add as `data` to the generated `py_library` target.	`[]`
srcs_exclude_glob	A list of labels to add as `srcs` to the generated `py_library` target.	`[]`

RETURNS

str: A json encoded string of the provided content.

pip_install

Accepts a locked/compiled requirements file and installs the dependencies listed within.

load("@rules_python//python:pip.bzl", "pip_install")

pip_install(
    name = "pip_deps",
    requirements = ":requirements.txt",
)

load("@pip_deps//:requirements.bzl", "install_deps")

install_deps()

PARAMETERS

Name	Description	Default Value
requirements	A ‘requirements.txt’ pip requirements file.	`None`
name	A unique name for the created external repository (default ‘pip’).	`"pip"`
kwargs	Additional arguments to the `pip_repository` repository rule.	none

pip_parse

Accepts a locked/compiled requirements file and installs the dependencies listed within.

Those dependencies become available in a generated requirements.bzl file. You can instead check this requirements.bzl file into your repo, see the “vendoring” section below.

This macro wraps the pip_repository rule that invokes pip. In your WORKSPACE file:

load("@rules_python//python:pip.bzl", "pip_parse")

pip_parse(
    name = "pip_deps",
    requirements_lock = ":requirements.txt",
)

load("@pip_deps//:requirements.bzl", "install_deps")

install_deps()

You can then reference installed dependencies from a BUILD file with:

load("@pip_deps//:requirements.bzl", "requirement")

py_library(
    name = "bar",
    ...
    deps = [
       "//my/other:dep",
       requirement("requests"),
       requirement("numpy"),
    ],
)

In addition to the requirement macro, which is used to access the generated py_library target generated from a package's wheel, The generated requirements.bzl file contains functionality for exposing entry points as py_binary targets as well.

load("@pip_deps//:requirements.bzl", "entry_point")

alias(
    name = "pip-compile",
    actual = entry_point(
        pkg = "pip-tools",
        script = "pip-compile",
    ),
)

Note that for packages whose name and script are the same, only the name of the package is needed when calling the entry_point macro.

load("@pip_deps//:requirements.bzl", "entry_point")

alias(
    name = "flake8",
    actual = entry_point("flake8"),
)

Vendoring the requirements.bzl file

In some cases you may not want to generate the requirements.bzl file as a repository rule while Bazel is fetching dependencies. For example, if you produce a reusable Bazel module such as a ruleset, you may want to include the requirements.bzl file rather than make your users install the WORKSPACE setup to generate it. See https://github.com/bazelbuild/rules_python/issues/608

This is the same workflow as Gazelle, which creates go_repository rules with update-repos

To do this, use the “write to source file” pattern documented in https://blog.aspect.dev/bazel-can-write-to-the-source-folder to put a copy of the generated requirements.bzl into your project. Then load the requirements.bzl file directly rather than from the generated repository. See the example in rules_python/examples/pip_parse_vendored.

PARAMETERS

Name	Description	Default Value
requirements	Deprecated. See requirements_lock.	`None`
requirements_lock	A fully resolved ‘requirements.txt’ pip requirement file containing the transitive set of your dependencies. If this file is passed instead of ‘requirements’ no resolve will take place and pip_repository will create individual repositories for each of your dependencies so that wheels are fetched/built only for the targets specified by ‘build/run/test’. Note that if your lockfile is platform-dependent, you can use the `requirements_[platform]` attributes.	`None`
name	The name of the generated repository. The generated repositories containing each requirement will be of the form `<name>_<requirement-name>`.	`"pip_parsed_deps"`
kwargs	Additional arguments to the `pip_repository` repository rule.	none