You only need to specify extras in the requirement macro if using legacy pip_import (bazel-contrib#445)

Jonathon Belotti · web-flow · commit 5126cf1bd3d4 · 2021-04-01T12:21:20.000-07:00
diff --git a/README.md b/README.md
@@ -188,7 +188,7 @@ load("@my_deps//:requirements.bzl", "pip_install")
 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 @@ wheel's contents. Rather than depend on this target's label directly -- which
 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 @@ py_library(
     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
 
