Implement Dependency Group option: --group

`--group` is supported on `download` and `install` commands.
The option is parsed into the more verbose and explicit
`dependency_groups` name on the parsed args.

Both of these commands invoke the same processor for resolving
dependency groups, which loads `pyproject.toml` and resolves the list
of provided groups against the `[dependency-groups]` table.

A small alteration is made to `pip wheel` to initialize
`dependency_groups = []`, as this allows for some lower-level
consistency in the handling of the commands.

Author: sirosen

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,18 @@ def get_requirements(
             )
             requirements.append(req_to_add)
 
+        if options.dependency_groups:
+            for req in parse_dependency_groups(
+                options.dependency_groups, session, finder=finder, options=options
+            ):
+                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 +285,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

@@ -84,6 +84,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,59 @@
+import optparse
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from pip._vendor import tomli
+from pip._vendor.dependency_groups import resolve as resolve_dependency_group
+
+from pip._internal.exceptions import InstallationError
+from pip._internal.network.session import PipSession
+
+if TYPE_CHECKING:
+    from pip._internal.index.package_finder import PackageFinder
+
+
+def parse_dependency_groups(
+    groups: List[str],
+    session: PipSession,
+    finder: Optional["PackageFinder"] = None,
+    options: Optional[optparse.Values] = None,
+) -> 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("[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