docs: tell how to emulate dependency groups with pip-compile (bazel-contrib#3089)

rickeylev · aignas · web-flow · commit 65a1c8541b8f · 2025-07-15T01:29:31.000Z
While pyproject.toml is supported by piptools, dependency groups aren't. They can be emulated by using multiple files. Explain how to do that in the docs and link to the upstream feature request (jazzband/pip-tools#2062) Along the way, link to our own feature request for pylock.toml support in pip.parse. --------- Co-authored-by: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
diff --git a/docs/pypi/lock.md b/docs/pypi/lock.md
@@ -5,6 +5,8 @@
 
 :::{note}
 Currently `rules_python` only supports `requirements.txt` format.
+
+#{gh-issue}`2787` tracks `pylock.toml` support.
 :::
 
 ## requirements.txt
@@ -37,11 +39,33 @@ This rule generates two targets:
 Once you generate this fully specified list of requirements, you can install the requirements ([bzlmod](./download)/[WORKSPACE](./download-workspace)).
 
 :::{warning}
-If you're specifying dependencies in `pyproject.toml`, make sure to include the `[build-system]` configuration, with pinned dependencies. `compile_pip_requirements` will use the build system specified to read your project's metadata, and you might see non-hermetic behavior if you don't pin the build system.
+If you're specifying dependencies in `pyproject.toml`, make sure to include the
+`[build-system]` configuration, with pinned dependencies.
+`compile_pip_requirements` will use the build system specified to read your
+project's metadata, and you might see non-hermetic behavior if you don't pin the
+build system.
 
-Not specifying `[build-system]` at all will result in using a default `[build-system]` configuration, which uses unpinned versions ([ref](https://peps.python.org/pep-0518/#build-system-table)).
+Not specifying `[build-system]` at all will result in using a default
+`[build-system]` configuration, which uses unpinned versions
+([ref](https://peps.python.org/pep-0518/#build-system-table)).
 :::
 
+
+#### pip compile Dependency groups
+
+pip-compile doesn't yet support pyproject.toml dependency groups. Follow
+[pip-tools #2062](https://github.com/jazzband/pip-tools/issues/2062)
+to see the status of their support.
+
+In the meantime, support can be emulated by passing multiple files to `srcs`:
+
+```starlark
+compile_pip_requirements(
+    srcs = ["pyproject.toml", "requirements-dev.in"]
+    ...
+)
+```
+
 ### uv pip compile (bzlmod only)
 
 We also have experimental setup for the `uv pip compile` way of generating lock files.
diff --git a/python/private/pypi/pip_compile.bzl b/python/private/pypi/pip_compile.bzl
@@ -40,7 +40,7 @@ def pip_compile(
         tags = None,
         constraints = [],
         **kwargs):
-    """Generates targets for managing pip dependencies with pip-compile.
+    """Generates targets for managing pip dependencies with pip-compile (piptools).
 
     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
@@ -65,7 +65,10 @@ def pip_compile(
             * a requirements text file, usually named `requirements.in`
             * A `.toml` file, where the `project.dependencies` list is used as per
               [PEP621](https://peps.python.org/pep-0621/).
-        extra_args: passed to pip-compile.
+        extra_args: passed to pip-compile (aka `piptools`). See the
+            [pip-compile docs](https://pip-tools.readthedocs.io/en/latest/cli/pip-compile)
+            for args and meaning (passing `-h` and/or `--version` can help
+            inform what args are available)
         extra_deps: extra dependencies passed to pip-compile.
         generate_hashes: whether to put hashes in the requirements_txt file.
         py_binary: the py_binary rule to be used.
