Import pip requirements into Bazel.

## whl_library_alias

whl_library_alias(name, default_version, repo_mapping, version_map, wheel_name)

**ATTRIBUTES**

| Name  | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name |  A unique name for this repository.   | Name (https://bazel.build/concepts/labels#target-names) | required |  |
| default_version |  -   | String | required |  |
| repo_mapping |  A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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 (https://bazel.build/rules/lib/dict) | required |  |
| version_map |  -   | Dictionary: String -> String (https://bazel.build/rules/lib/dict) | required |  |
| wheel_name |  -   | String | required |  |

## compile_pip_requirements

compile_pip_requirements(name, extra_args, extra_deps, py_binary, py_test, requirements_in,
                         requirements_txt, requirements_darwin, requirements_linux,
                         requirements_windows, visibility, tags, kwargs)

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`

**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.   |  [] |
| 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

multi_pip_parse(name, default_version, python_versions, python_interpreter_target,
                requirements_lock, kwargs)

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

package_annotation(additive_build_content, copy_files, copy_executables, data, data_exclude_glob,
                   srcs_exclude_glob)

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

[cf]: https://github.com/bazelbuild/bazel-skylib/blob/main/docs/copy_file_doc.md

**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][cf]   |  {} |
| copy_executables |  A mapping of src and out files for [@bazel_skylib//rules:copy_file.bzl][cf]. 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

pip_install(requirements, name, kwargs)

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

```python
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](./pip_repository.md) repository rule.   |  none |

## pip_parse

pip_parse(requirements, requirements_lock, name, kwargs)

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`](./pip_repository.md) rule that invokes `pip`.
In your WORKSPACE file:

```python
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:

```python
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][whl_ep] as `py_binary` targets as well.

[whl_ep]: https://packaging.python.org/specifications/entry-points/

```python
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.

```python
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`](https://github.com/bazelbuild/bazel-gazelle#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](./pip_repository.md) repository rule.   |  none |

