Implement a --group option for installing from [dependency-groups] found in pyproject.toml files

news/12963.feature.rst

@@ -0,0 +1,3 @@
+- Add a ``--group`` option which allows installation from PEP 735 Dependency
+  Groups. Only ``pyproject.toml`` files in the current working directory are
+  supported.

src/pip/_internal/cli/cmdoptions.py

@@ -733,6 +733,17 @@ def _handle_no_cache_dir(
     help="Don't install package dependencies.",
 )
 
+dependency_groups: Callable[..., Option] = partial(
+    Option,
+    "--group",
+    dest="dependency_groups",
+    default=[],
+    action="append",
+    metavar="group",
+    help="Install a named dependency-group from `pyproject.toml` "
+    "in the current directory.",
+)
+
 ignore_requires_python: Callable[..., Option] = partial(
     Option,
     "--ignore-requires-python",

src/pip/_internal/cli/req_command.py

@@ -28,6 +28,7 @@
     install_req_from_parsed_requirement,
     install_req_from_req_string,
 )
+from pip._internal.req.req_dependency_group import parse_dependency_groups
 from pip._internal.req.req_file import parse_requirements
 from pip._internal.req.req_install import InstallRequirement
 from pip._internal.resolution.base import BaseResolver
@@ -240,6 +241,16 @@ def get_requirements(
             )
             requirements.append(req_to_add)
 
+        if options.dependency_groups:
+            for req in parse_dependency_groups(options.dependency_groups):
+                req_to_add = install_req_from_req_string(
+                    req,
+                    isolated=options.isolated_mode,
+                    use_pep517=options.use_pep517,
+                    user_supplied=True,
+                )
+                requirements.append(req_to_add)
+
         for req in options.editables:
             req_to_add = install_req_from_editable(
                 req,
@@ -272,7 +283,12 @@ def get_requirements(
         if any(req.has_hash_options for req in requirements):
             options.require_hashes = True
 
-        if not (args or options.editables or options.requirements):
+        if not (
+            args
+            or options.editables
+            or options.requirements
+            or options.dependency_groups
+        ):
             opts = {"name": self.name}
             if options.find_links:
                 raise CommandError(

src/pip/_internal/commands/download.py

@@ -38,6 +38,7 @@ class DownloadCommand(RequirementCommand):
     def add_options(self) -> None:
         self.cmd_opts.add_option(cmdoptions.constraints())
         self.cmd_opts.add_option(cmdoptions.requirements())
+        self.cmd_opts.add_option(cmdoptions.dependency_groups())
         self.cmd_opts.add_option(cmdoptions.no_deps())
         self.cmd_opts.add_option(cmdoptions.global_options())
         self.cmd_opts.add_option(cmdoptions.no_binary())

src/pip/_internal/commands/install.py

@@ -77,6 +77,7 @@ def add_options(self) -> None:
         self.cmd_opts.add_option(cmdoptions.pre())
 
         self.cmd_opts.add_option(cmdoptions.editable())
+        self.cmd_opts.add_option(cmdoptions.dependency_groups())
         self.cmd_opts.add_option(
             "--dry-run",
             action="store_true",

src/pip/_internal/commands/wheel.py

@@ -102,6 +102,10 @@ def add_options(self) -> None:
 
     @with_cleanup
     def run(self, options: Values, args: List[str]) -> int:
+        # dependency-groups aren't desirable with `pip wheel`, but providing it
+        # consistently allows RequirementCommand to expect it to be present
+        options.dependency_groups = []
+
         session = self.get_default_session(options)
 
         finder = self._build_package_finder(options, session)

src/pip/_internal/req/req_dependency_group.py

@@ -0,0 +1,49 @@
+from typing import Any, Dict, List
+
+from pip._vendor import tomli
+from pip._vendor.dependency_groups import resolve as resolve_dependency_group
+
+from pip._internal.exceptions import InstallationError
+
+
+def parse_dependency_groups(groups: List[str]) -> List[str]:
+    """
+    Parse dependency groups data in a way which is sensitive to the `pip` context and
+    raises InstallationErrors if anything goes wrong.
+    """
+    pyproject = _load_pyproject()
+
+    if "dependency-groups" not in pyproject:
+        raise InstallationError(
+            "[dependency-groups] table was missing. Cannot resolve '--group' options."
+        )
+    raw_dependency_groups = pyproject["dependency-groups"]
+    if not isinstance(raw_dependency_groups, dict):
+        raise InstallationError(
+            "[dependency-groups] table was malformed. Cannot resolve '--group' options."
+        )
+
+    try:
+        return list(resolve_dependency_group(raw_dependency_groups, *groups))
+    except (ValueError, TypeError, LookupError) as e:
+        raise InstallationError(f"[dependency-groups] resolution failed: {e}") from e
+
+
+def _load_pyproject() -> Dict[str, Any]:
+    """
+    This helper loads pyproject.toml from the current working directory.
+
+    It does not allow specification of the path to be used and raises an
+    InstallationError if the operation fails.
+    """
+    try:
+        with open("pyproject.toml", "rb") as fp:
+            return tomli.load(fp)
+    except FileNotFoundError:
+        raise InstallationError(
+            "pyproject.toml not found. Cannot resolve '--group' options."
+        )
+    except tomli.TOMLDecodeError as e:
+        raise InstallationError(f"Error parsing pyproject.toml: {e}") from e
+    except OSError as e:
+        raise InstallationError(f"Error reading pyproject.toml: {e}") from e

src/pip/_vendor/__init__.py

@@ -60,6 +60,7 @@ def vendored(modulename):
     # Actually alias all of our vendored dependencies.
     vendored("cachecontrol")
     vendored("certifi")
+    vendored("dependency-groups")
     vendored("distlib")
     vendored("distro")
     vendored("packaging")

src/pip/_vendor/dependency_groups/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024-present Stephen Rosen <sirosen0@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

src/pip/_vendor/dependency_groups/__init__.py

@@ -0,0 +1,13 @@
+from ._implementation import (
+    CyclicDependencyError,
+    DependencyGroupInclude,
+    DependencyGroupResolver,
+    resolve,
+)
+
+__all__ = (
+    "CyclicDependencyError",
+    "DependencyGroupInclude",
+    "DependencyGroupResolver",
+    "resolve",
+)

src/pip/_vendor/dependency_groups/__main__.py

@@ -0,0 +1,65 @@
+import argparse
+import sys
+
+from ._implementation import resolve
+from ._toml_compat import tomllib
+
+
+def main() -> None:
+    if tomllib is None:
+        print(
+            "Usage error: dependency-groups CLI requires tomli or Python 3.11+",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+
+    parser = argparse.ArgumentParser(
+        description=(
+            "A dependency-groups CLI. Prints out a resolved group, newline-delimited."
+        )
+    )
+    parser.add_argument(
+        "GROUP_NAME", nargs="*", help="The dependency group(s) to resolve."
+    )
+    parser.add_argument(
+        "-f",
+        "--pyproject-file",
+        default="pyproject.toml",
+        help="The pyproject.toml file. Defaults to trying in the current directory.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="An output file. Defaults to stdout.",
+    )
+    parser.add_argument(
+        "-l",
+        "--list",
+        action="store_true",
+        help="List the available dependency groups",
+    )
+    args = parser.parse_args()
+
+    with open(args.pyproject_file, "rb") as fp:
+        pyproject = tomllib.load(fp)
+
+    dependency_groups_raw = pyproject.get("dependency-groups", {})
+
+    if args.list:
+        print(*dependency_groups_raw.keys())
+        return
+    if not args.GROUP_NAME:
+        print("A GROUP_NAME is required", file=sys.stderr)
+        raise SystemExit(3)
+
+    content = "\n".join(resolve(dependency_groups_raw, *args.GROUP_NAME))
+
+    if args.output is None or args.output == "-":
+        print(content)
+    else:
+        with open(args.output, "w", encoding="utf-8") as fp:
+            print(content, file=fp)
+
+
+if __name__ == "__main__":
+    main()