You only need to specify extras in the requirement macro if using legacy pip_import (#445)
diff --git a/README.md b/README.md index 85df2c9..eefa5ac 100644 --- a/README.md +++ b/README.md
@@ -188,7 +188,7 @@ pip_install() ``` -An example can be found in [`examples/legacy_pip_import](examples/legacy_pip_import). +An example can be found in [`examples/legacy_pip_import`](examples/legacy_pip_import). ### Consuming `pip` dependencies @@ -197,9 +197,7 @@ would require hardcoding the wheel repo's mangled name into your BUILD files -- you should instead use the `requirement()` function defined in the central repo's `//:requirements.bzl` file. This function maps a pip package name to a -label. (["Extras"]( -https://packaging.python.org/tutorials/installing-packages/#installing-setuptools-extras) -can be referenced using the `pkg[extra]` syntax.) +label. ```python load("@my_deps//:requirements.bzl", "requirement") @@ -210,17 +208,35 @@ deps = [ ":myotherlib", requirement("some_pip_dep"), - requirement("another_pip_dep[some_extra]"), + requirement("another_pip_dep"), ] ) ``` + For reference, the wheel repos are canonically named following the pattern: `@{central_repo_name}_pypi__{distribution}_{version}`. Characters in the distribution and version that are illegal in Bazel label names (e.g. `-`, `.`) are replaced with `_`. While this naming pattern doesn't change often, it is -not guaranted to remain stable, so use of the `requirement()` function is -recommended. +not guaranted to remain stable, so use of the `requirement()` function is recommended. + +#### 'Extras' requirement consumption + +When using the legacy `pip_import`, you must specify the extra in the argument to the `requirement` macro. For example: + +```python +py_library( + name = "mylib", + srcs = ["mylib.py"], + deps = [ + requirement("useful_dep[some_extra]"), + ] +) +``` + +If using `pip_install` or `pip_parse`, any extras specified in the requirements file will be automatically +linked as a dependency of the package so that you don't need to specify the extra. In the example above, +you'd just put `requirement("useful_dep")`. ### Consuming Wheel Dists Directly