docs/pypi/use.md

:::{default-domain} bzl
:::

# Use in BUILD.bazel files

Once you have set up the dependencies, you are ready to start using them in your `BUILD.bazel`
files. If you haven't done so yet, set it up by following these docs:
1. [WORKSPACE](./download-workspace)
2. [bzlmod](./download)

To refer to targets in a hub repo `pypi`, you can do one of two things:
```starlark
py_library(
    name = "my_lib",
    deps = [
        "@pypi//numpy",
    ],
)
```

Or use the `requirement` helper that needs to be loaded from the `hub` repo itself:
```starlark
load("@pypi//:requirements.bzl", "requirement")

py_library(
    deps = [
        requirement("numpy")
    ],
)
```

Note that the usage of the `requirement` helper is not advised and can be problematic. See the
[notes below](#requirement-helper).

Note that the hub repo contains the following targets for each package:
* `@pypi//numpy` - shorthand for `@pypi//numpy:numpy`. This is an {obj}`alias` to
  `@pypi//numpy:pkg`.
* `@pypi//numpy:pkg` - the {obj}`py_library` target automatically generated by the repository
  rules.
* `@pypi//numpy:data` - the {obj}`filegroup` for all of the extra files that are included
  as data in the `pkg` target.
* `@pypi//numpy:dist_info` - the {obj}`filegroup` for all of the files in the `<pkg prefix with version>.distinfo` directory.
* `@pypi//numpy:extracted_whl_files` - a {obj}`filegroup` of all the files
  extracted from the whl file.
* `@pypi//numpy:whl` - the {obj}`filegroup` that is the `.whl` file itself, which includes all
  transitive dependencies via the {attr}`filegroup.data` attribute.

:::{versionadded} 1.6.0

The `:extracted_whl_files` target was added
:::

## Entry points

If you would like to access [entry points][whl_ep], see the `py_console_script_binary` rule documentation,
which can help you create a `py_binary` target for a particular console script exposed by a package.

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

## 'Extras' dependencies

Any "extras" specified in the requirements lock file will be automatically added
as transitive dependencies of the package. In the example above, you'd just put
`requirement("useful_dep")` or `@pypi//useful_dep`.

## Consuming Wheel Dists Directly

If you need to depend on the wheel dists themselves (for instance, to pass them
to some other packaging tool), you can get a handle to them with the
`whl_requirement` macro. For example:

```starlark
load("@pypi//:requirements.bzl", "whl_requirement")

filegroup(
    name = "whl_files",
    data = [
        # This is equivalent to "@pypi//boto3:whl"
        whl_requirement("boto3"),
    ]
)
```

## Creating a filegroup of files within a whl

The rule {obj}`whl_filegroup` exists as an easy way to extract the necessary files
from a whl file without needing to modify the `BUILD.bazel` contents of the
whl repositories generated via `pip_repository`. Use it similarly to the `filegroup`
above. See the API docs for more information.

(requirement-helper)=
## A note about using the requirement helper

Each extracted wheel repo contains a `py_library` target representing
the wheel's contents. There are two ways to access this library. The
first uses the `requirement()` function defined in the central
repo's `//:requirements.bzl` file. This function maps a pip package
name to a label:

```starlark
load("@my_deps//:requirements.bzl", "requirement")

py_library(
    name = "mylib",
    srcs = ["mylib.py"],
    deps = [
        ":myotherlib",
        requirement("some_pip_dep"),
        requirement("another_pip_dep"),
    ]
)
```

The reason `requirement()` exists is to insulate users from
changes to the underlying repository and label strings. However, those
labels have become directly used, so they aren't able to easily change regardless.

On the other hand, using the `requirement()` helper has several drawbacks:

- It doesn't work with `buildifier`.
- It doesn't work with `buildozer`.
- It adds an extra layer on top of normal mechanisms to refer to targets.
- It does not scale well, as each type of target needs a new macro to be loaded and imported.

If you don't want to use `requirement()`, you can use the library labels directly instead. For
`pip_parse`, the labels are of the following form:

```starlark
@{name}//{package}
```

Here `name` is the `name` attribute that was passed to `pip_parse` and
`package` is the pip package name with characters that are illegal in
Bazel label names (e.g. `-`, `.`) replaced with `_`. If you need to
update `name` from "old" to "new", then you can run the following
`buildozer` command:

```shell
buildozer 'substitute deps @old//([^/]+) @new//${1}' //...:*
```