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

news/12963.feature.rst

@@ -0,0 +1,4 @@
+- Add a ``--group`` option which allows installation from PEP 735 Dependency
+  Groups. ``--group`` accepts arguments of the form ``group`` or
+  ``path:group``, where the default path is ``pyproject.toml``, and installs
+  the named Dependency Group from the provided ``pyproject.toml`` file.

src/pip/_internal/cli/cmdoptions.py

@@ -13,6 +13,7 @@
 import importlib.util
 import logging
 import os
+import pathlib
 import textwrap
 from functools import partial
 from optparse import SUPPRESS_HELP, Option, OptionGroup, OptionParser, Values
@@ -733,6 +734,46 @@ def _handle_no_cache_dir(
     help="Don't install package dependencies.",
 )
 
+
+def _handle_dependency_group(
+    option: Option, opt: str, value: str, parser: OptionParser
+) -> None:
+    """
+    Process a value provided for the --group option.
+
+    Splits on the rightmost ":", and validates that the path (if present) ends
+    in `pyproject.toml`. Defaults the path to `pyproject.toml` when one is not given.
+
+    `:` cannot appear in dependency group names, so this is a safe and simple parse.
+
+    This is an optparse.Option callback for the dependency_groups option.
+    """
+    path, sep, groupname = value.rpartition(":")
+    if not sep:
+        path = "pyproject.toml"
+    else:
+        # check for 'pyproject.toml' filenames using pathlib
+        if pathlib.PurePath(path).name != "pyproject.toml":
+            msg = "group paths use 'pyproject.toml' filenames"
+            raise_option_error(parser, option=option, msg=msg)
+
+    parser.values.dependency_groups.append((path, groupname))
+
+
+dependency_groups: Callable[..., Option] = partial(
+    Option,
+    "--group",
+    dest="dependency_groups",
+    default=[],
+    type=str,
+    action="callback",
+    callback=_handle_dependency_group,
+    metavar="[path:]group",
+    help='Install a named dependency-group from a "pyproject.toml" file. '
+    'If a path is given, it must end in "pyproject.toml:". '
+    'Defaults to using "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
@@ -79,6 +80,7 @@ class RequirementCommand(IndexGroupCommand):
     def __init__(self, *args: Any, **kw: Any) -> None:
         super().__init__(*args, **kw)
 
+        self.cmd_opts.add_option(cmdoptions.dependency_groups())
         self.cmd_opts.add_option(cmdoptions.no_clean())
 
     @staticmethod
@@ -240,6 +242,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 +284,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/req/req_dependency_group.py

@@ -0,0 +1,74 @@
+from typing import Any, Dict, Iterable, Iterator, List, Tuple
+
+from pip._vendor import tomli
+from pip._vendor.dependency_groups import DependencyGroupResolver
+
+from pip._internal.exceptions import InstallationError
+
+
+def parse_dependency_groups(groups: List[Tuple[str, str]]) -> List[str]:
+    """
+    Parse dependency groups data as provided via the CLI, in a `[path:]group` syntax.
+
+    Raises InstallationErrors if anything goes wrong.
+    """
+    resolvers = _build_resolvers(path for (path, _) in groups)
+    return list(_resolve_all_groups(resolvers, groups))
+
+
+def _resolve_all_groups(
+    resolvers: Dict[str, DependencyGroupResolver], groups: List[Tuple[str, str]]
+) -> Iterator[str]:
+    """
+    Run all resolution, converting any error from `DependencyGroupResolver` into
+    an InstallationError.
+    """
+    for path, groupname in groups:
+        resolver = resolvers[path]
+        try:
+            yield from (str(req) for req in resolver.resolve(groupname))
+        except (ValueError, TypeError, LookupError) as e:
+            raise InstallationError(
+                f"[dependency-groups] resolution failed for '{groupname}' "
+                f"from '{path}': {e}"
+            ) from e
+
+
+def _build_resolvers(paths: Iterable[str]) -> Dict[str, Any]:
+    resolvers = {}
+    for path in paths:
+        if path in resolvers:
+            continue
+
+        pyproject = _load_pyproject(path)
+        if "dependency-groups" not in pyproject:
+            raise InstallationError(
+                f"[dependency-groups] table was missing from '{path}'. "
+                "Cannot resolve '--group' option."
+            )
+        raw_dependency_groups = pyproject["dependency-groups"]
+        if not isinstance(raw_dependency_groups, dict):
+            raise InstallationError(
+                f"[dependency-groups] table was malformed in {path}. "
+                "Cannot resolve '--group' option."
+            )
+
+        resolvers[path] = DependencyGroupResolver(raw_dependency_groups)
+    return resolvers
+
+
+def _load_pyproject(path: str) -> Dict[str, Any]:
+    """
+    This helper loads a pyproject.toml as TOML.
+
+    It raises an InstallationError if the operation fails.
+    """
+    try:
+        with open(path, "rb") as fp:
+            return tomli.load(fp)
+    except FileNotFoundError:
+        raise InstallationError(f"{path} not found. Cannot resolve '--group' option.")
+    except tomli.TOMLDecodeError as e:
+        raise InstallationError(f"Error parsing {path}: {e}") from e
+    except OSError as e:
+        raise InstallationError(f"Error reading {path}: {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()