✨ feat(config): add package = "deps-only" mode (#3774)

Many tox environments -- coverage combining, doc building, linting --
need a project's dependencies (and extras) but not the project itself.
Today the only option is `skip_install = true` plus manually duplicating
every dependency in `deps`, which drifts out of sync with
`pyproject.toml`. This adds `package = "deps-only"` so those
environments can declare `extras = ["docs"]` and get the right
dependencies automatically, just like a normal test environment, without
paying for a build step. 🎯

The implementation uses a two-tier resolution strategy. It first tries
to read dependencies statically from a PEP 621 `[project]` table in
`pyproject.toml` -- no packaging environment needed, same fast path as
`dependency_groups`. If that fails (dynamic deps, no `[project]` table,
`setup.cfg`-only projects), it falls back to the existing `.pkg` env and
`prepare_metadata_for_build_wheel` to extract metadata. A new
`load_deps_for_env` abstract method on `PythonPackageToxEnv` exposes
this fallback cleanly to the runner.

The `extras` config key works identically to other package modes,
including validation of unknown extra names. Existing configurations are
unaffected -- `deps-only` is purely opt-in alongside the existing
`wheel`, `sdist`, `sdist-wheel`, `editable`, `editable-legacy`, `skip`,
and `external` modes.

Fixes #2301

---------

Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>

Author: gaborbernat

docs/changelog/2301.feature.rst

@@ -0,0 +1,3 @@
+Add ``package = "deps-only"`` mode that installs the package's dependencies (including extras) without building or
+installing the package itself. For projects with static :PEP:`621` metadata, dependencies are read directly from
+``pyproject.toml`` without creating a packaging environment - by :user:`gaborbernat`.

docs/changelog/3774.bugfix.rst

@@ -0,0 +1,3 @@
+Fix PEP 517 backend crash detection to handle both ``ENOENT`` (missing interpreter) and runtime crashes without hanging,
+and fix flaky ``test_provision_install_pkg_pep517`` integration test by using a pre-built wheel instead of an sdist to
+avoid devpi mirror dependency on setuptools - by :user:`gaborjbernat`.

docs/how-to/usage.rst

@@ -516,6 +516,46 @@ environments via the :ref:`extras` configuration:
 This installs your package together with the specified extras, avoiding the need to duplicate dependency lists in both
 ``pyproject.toml`` and your tox configuration.
 
+************************************
+ Install extras without the package
+************************************
+
+Sometimes you need the package's dependencies (including extras) without installing the package itself. For example,
+coverage combining, documentation builds, or linting environments that share the same dependency set. Use ``package =
+"deps-only"`` instead of ``skip_install = true`` combined with manually duplicated ``deps``:
+
+.. tab:: TOML
+
+    .. code-block:: toml
+
+         # pyproject.toml
+         [project]
+         name = "myproject"
+         dependencies = ["httpx>=0.27"]
+
+         [project.optional-dependencies]
+         docs = ["sphinx>=7", "furo"]
+
+    .. code-block:: toml
+
+         # tox.toml
+         [env.docs]
+         package = "deps-only"
+         extras = ["docs"]
+         commands = [["sphinx-build", "-W", "docs", "docs/_build/html"]]
+
+.. tab:: INI
+
+    .. code-block:: ini
+
+         [testenv:docs]
+         package = deps-only
+         extras = docs
+         commands = sphinx-build -W docs docs/_build/html
+
+This reads your ``pyproject.toml`` directly (no build step) and installs ``httpx``, ``sphinx``, and ``furo`` into the
+environment. If your dependencies are dynamic, tox falls back to using the packaging environment to extract metadata.
+
 .. ------------------------------------------------------------------------------------------
 
 .. Environment Customization

docs/reference/config.rst

@@ -1400,9 +1400,16 @@ Python run
     :keys: package
     :version_added: 4.0
 
-    When option can be one of ``wheel``, ``sdist``, ``sdist-wheel``, ``editable``, ``editable-legacy``, ``skip``, or
-    ``external``. If :ref:`use_develop` is set this becomes a constant of ``editable``. If :ref:`skip_install` is set
-    this becomes a constant of ``skip``.
+    When option can be one of ``wheel``, ``sdist``, ``sdist-wheel``, ``editable``, ``editable-legacy``, ``deps-only``,
+    ``skip``, or ``external``. If :ref:`use_develop` is set this becomes a constant of ``editable``. If
+    :ref:`skip_install` is set this becomes a constant of ``skip``.
+
+    When ``deps-only`` is selected, tox installs the package's dependencies (including any requested :ref:`extras`) but
+    does **not** build or install the package itself. This is useful for environments that need the same dependencies as
+    the package without the package, such as coverage combining, documentation building, or linting. For projects with
+    static :pep:`621` metadata in ``pyproject.toml``, dependencies are read directly without creating a packaging
+    environment. For dynamic dependencies or non-PEP-621 projects, the packaging environment is used to extract
+    metadata.
 
     When ``sdist-wheel`` is selected, tox first builds a source distribution and then builds a wheel from that sdist
     (rather than directly from the source tree). This is useful for verifying that the sdist is complete and that the

pyproject.toml

@@ -96,7 +96,7 @@ test = [
   "pytest-timeout>=2.4",
   "pytest-xdist>=3.8",
   "re-assert>=1.1",
-  "setuptools>=80.10.2",
+  "setuptools>=80.10.2,<82",
   "time-machine>=3.2; implementation_name!='pypy'",
   "wheel>=0.46.3",
 ]

src/tox/execute/pep517_backend.py

@@ -57,11 +57,12 @@ def local_execute(self, options: ExecuteOptions) -> tuple[LocalSubProcessExecute
             )
             status = instance.__enter__()  # noqa: PLC2801
             self._local_execute = instance, status
+            process_exited = instance.process is None  # Popen failed (e.g. ENOENT)
             while True:
                 if b"started backend " in status.out:
                     self.is_alive = True
                     break
-                if b"failed to start backend" in status.err:
+                if b"failed to start backend" in status.err or process_exited:
                     from tox.tox_env.python.virtual_env.package.pyproject import ToxBackendFailed  # noqa: PLC0415
 
                     failure = BackendFailed(
@@ -75,6 +76,8 @@ def local_execute(self, options: ExecuteOptions) -> tuple[LocalSubProcessExecute
                     )
                     self._exc = ToxBackendFailed(failure)
                     raise self._exc
+                if instance.process is not None and instance.process.poll() is not None:
+                    process_exited = True  # give reader threads one more iteration to drain
                 time.sleep(0.01)  # wait a short while for the output to populate
         return self._local_execute
 

src/tox/pytest.py

@@ -144,7 +144,7 @@ def __init__(  # noqa: PLR0913
     @staticmethod
     def _setup_files(dest: Path, base: Path | None, content: dict[str, Any]) -> None:
         if base is not None:
-            shutil.copytree(str(base), str(dest))
+            shutil.copytree(str(base), str(dest), ignore=shutil.ignore_patterns(".tox"))
         dest.mkdir(exist_ok=True)
         for key, value in content.items():
             if not isinstance(key, str):

src/tox/tox.schema.json

@@ -352,7 +352,7 @@
         },
         "package": {
           "type": "string",
-          "description": "package installation mode - wheel | sdist | sdist-wheel | editable | editable-legacy | skip | external "
+          "description": "package installation mode - wheel | sdist | sdist-wheel | editable | editable-legacy | deps-only | skip | external "
         },
         "extras": {
           "type": "array",

src/tox/tox_env/python/extras.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from packaging.requirements import Requirement
+
+from .virtual_env.package.util import dependencies_with_extras_from_markers
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+if sys.version_info >= (3, 11):  # pragma: no cover (py311+)
+    import tomllib
+else:  # pragma: no cover (py311+)
+    import tomli as tomllib
+
+
+def resolve_extras_static(root: Path, extras: set[str]) -> list[Requirement] | None:
+    pyproject_file = root / "pyproject.toml"
+    if not pyproject_file.exists():
+        return None
+    with pyproject_file.open("rb") as file_handler:
+        pyproject = tomllib.load(file_handler)
+    if "project" not in pyproject:
+        return None
+    project = pyproject["project"]
+    for dynamic in project.get("dynamic", []):
+        if dynamic == "dependencies" or (extras and dynamic == "optional-dependencies"):
+            return None
+    deps_with_markers: list[tuple[Requirement, set[str | None]]] = [
+        (Requirement(i), {None}) for i in project.get("dependencies", [])
+    ]
+    optional_deps = project.get("optional-dependencies", {})
+    for extra, reqs in optional_deps.items():
+        deps_with_markers.extend((Requirement(req), {extra}) for req in (reqs or []))
+    return dependencies_with_extras_from_markers(
+        deps_with_markers=deps_with_markers,
+        extras=extras,
+        package_name=project.get("name", "."),
+        available_extras=set(optional_deps.keys()),
+    )
+
+
+__all__ = [
+    "resolve_extras_static",
+]

src/tox/tox_env/python/package.py

@@ -65,6 +65,10 @@ def _setup_env(self) -> None:
     def requires(self) -> tuple[Requirement, ...] | PythonDeps:
         raise NotImplementedError
 
+    @abstractmethod
+    def load_deps_for_env(self, for_env: EnvConfigSet) -> list[Requirement]:
+        raise NotImplementedError
+
     def register_run_env(self, run_env: RunToxEnv) -> Generator[tuple[str, str], PackageToxEnv, None]:
         yield from super().register_run_env(run_env)
         if run_env.conf["package"] != "skip" and "deps" not in self.conf: