✨ feat(config): catalog environments per PEP 832

Editors have no way to find the environments tox builds under .tox, so
using one means copying a path out of tox devenv and pasting it into a
settings dialog, again after every recreate. PEP 832 fixes that with a
.python-envs file at the project root that any tool can write and any
editor can read, with the last line naming the default environment.

tox now writes that file at the end of a run. The ordering puts the
environment a developer edits code against last: one named dev, then a
develop install, then the earlier entries of env_list, so trimming lines
from the bottom falls back to the next best choice. Lines outside the
work dir belong to another tool and survive untouched, including their
claim on the last line. A recreated environment leaves the catalog while
it rebuilds so nothing points at a half-built interpreter.

Writing into the project root is on by default, since the convention
only pays off when tools follow it without being asked; python_envs
turns it off.

Author: gaborbernat

.gitignore

@@ -12,3 +12,4 @@ __pycache__
 /tests/demo_pkg_setuptools/build/lib/demo_pkg_setuptools/__init__.py
 /tests/demo_pkg_inline.lock
 /tests/demo_pkg_inline/.tox/
+.python-envs

docs/changelog/4013.feature.rst

@@ -0,0 +1,6 @@
+Catalog the created tox environments in a :PEP:`832` ``.python-envs`` file next to the configuration file, so that
+editors such as VS Code or PyCharm offer them as interpreters instead of asking you for a path under ``.tox``. The
+default environment comes last, and tox prefers one named ``dev`` for that spot, then one that installs the project in
+development mode, then the first of :ref:`env_list`. tox leaves the lines other tools wrote alone, and takes an
+environment out of the catalog while it recreates it. Set :ref:`python_envs` to ``false`` to skip the file - by
+:user:`gaborbernat`. (:issue:`4013`)

docs/explanation.rst

@@ -721,6 +721,31 @@ upgrade that changes the derived value) triggers automatic recreation.
 This design mirrors tox's own auto-provisioning mechanism (``requires`` / ``min_version``), where tox bootstraps itself
 into a separate environment when the running installation doesn't meet the declared requirements.
 
+***********************
+ Environment discovery
+***********************
+
+Editors need an interpreter path before they can offer completion, navigation or a debugger. tox keeps its environments
+under ``.tox``, a directory editors have no reason to search, so for years the answer was to copy a path out of ``tox
+devenv`` output and paste it into a settings dialog, then repeat it after every recreate.
+
+:PEP:`832` standardizes where tools publish that answer. A project may hold a virtual environment at ``.venv``, and a
+``.python-envs`` file at the project root lists any further environments, one directory per line. The last line is the
+default, so a reader that supports only one environment still knows which to take. VS Code reads the file today and
+PyCharm honors the ``.venv`` half of the convention.
+
+tox writes ``.python-envs`` at the end of a run, listing every environment that exists on disk. Ordering follows how
+useful an environment is to an editor rather than how tox happens to schedule it: an environment named ``dev`` wins,
+then one installing the project in development mode, then the earlier entries of :ref:`env_list`. Since the catalog
+lists the preferred environment last, removing lines from the bottom degrades to the next best choice.
+
+Two rules keep the file honest. tox owns the lines under :ref:`work_dir` and rewrites them wholesale, while lines
+pointing elsewhere came from another tool and survive untouched, including the last line and the default it claims. And
+because a recreated environment is unusable between the moment tox empties the directory and the moment the new
+interpreter lands, tox takes the environment out of the catalog first and puts it back once the run ends.
+
+Set :ref:`python_envs` to ``false`` if you would rather tox left the project root alone.
+
 *******************
  Known limitations
 *******************

docs/how-to/usage.rst

@@ -162,6 +162,44 @@ The ``tox exec`` subcommand runs an arbitrary command inside a tox environment w
 The command must be in the environment's ``PATH`` or listed in :ref:`allowlist_externals`. ``tox exec`` is useful for
 debugging, running one-off scripts, or interactively exploring an environment without modifying your configuration.
 
+.. _howto_editor_env:
+
+***************************************
+ Open a tox environment in your editor
+***************************************
+
+Editors pick up interpreters through the :PEP:`832` ``.python-envs`` file, which tox writes next to your configuration
+file after each run. Name the environment you develop against ``dev`` and tox puts it on the last line, the one readers
+treat as the default:
+
+.. code-block:: toml
+
+    [env.dev]
+    description = "development environment"
+    package = "editable"
+    dependency_groups = [ "dev" ]
+
+Create it, then reload your editor window:
+
+.. code-block:: bash
+
+    tox run -e dev --notest
+
+The file lists one directory per line, so you can check what an editor will see:
+
+.. code-block:: bash
+
+    $ cat .python-envs
+    .tox/3.13
+    .tox/dev
+
+Commit the file when your team keeps environments in the same place, otherwise add it to your ``.gitignore``. To keep
+tox from writing it at all, set :ref:`python_envs` in the core section:
+
+.. code-block:: toml
+
+    python_envs = false
+
 .. ------------------------------------------------------------------------------------------
 
 .. Configuration (frequently needed)

docs/reference/config.rst

@@ -539,6 +539,21 @@ the top level of ``tox.toml``. Placing these options in an environment section (
     this directory for the project package. This ensures tox works correctly when having parallel runs (as each session
     will have its own copy of the project package - e.g. the source distribution).
 
+.. conf::
+    :keys: python_envs
+    :default: true
+    :version_added: 4.59.0
+
+    Catalog the created tox environments in a :pep:`832` ``.python-envs`` file next to the configuration file, so that
+    editors such as VS Code or PyCharm offer them as interpreters. The file holds one environment directory per line,
+    with the default one last. tox prefers an environment named ``dev`` for that spot, then one that installs the
+    project in development mode, then the first entry of :ref:`env_list`. It lists only environments that exist, and
+    takes one out of the catalog while it recreates it.
+
+    Lines pointing outside the :ref:`work_dir` come from another tool, so tox keeps them, including their claim on the
+    last line. Commit the file when everyone working on the project has their environments in the same place, otherwise
+    ignore it.
+
 .. conf::
     :keys: no_package, skipsdist
     :default: false

docs/tutorial/getting-started.rst

@@ -287,6 +287,23 @@ has changed), use ``--skip-env-install``:
 
     tox run -e 3.13 --skip-env-install
 
+******************************
+ Using an environment at hand
+******************************
+
+After a run, tox records the environments it created in a ``.python-envs`` file next to your configuration, following
+:PEP:`832`. Editors such as VS Code read it and offer those interpreters, so you can pick one instead of hunting for a
+path under ``.tox``:
+
+.. code-block:: bash
+
+    $ tox run -e 3.13
+    $ cat .python-envs
+    .tox/3.13
+
+The last line is the default. Name an environment ``dev`` and tox puts it there, which is what you want for the
+environment you edit code against - see :ref:`howto_editor_env`.
+
 ********************************
  Listing available environments
 ********************************

src/tox/config/sets.py

@@ -315,6 +315,12 @@ def register_config(self) -> None:
             default=self._default_temp_dir,
             desc="a folder for temporary files (is not cleaned at start)",
         )
+        self.add_config(
+            keys=["python_envs"],
+            of_type=bool,
+            default=True,
+            desc="catalog the created tox environments in a PEP-832 .python-envs file, so editors can discover them",
+        )
         self.add_constant("host_python", "the host python executable path", sys.executable)
 
     def _on_duplicate_conf(self, key: str, definition: ConfigDefinition[V]) -> None:

src/tox/pytest.py

@@ -147,7 +147,7 @@ def __init__(  # ruff:ignore[too-many-arguments]
     @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), ignore=shutil.ignore_patterns(".tox"))
+            shutil.copytree(str(base), str(dest), ignore=shutil.ignore_patterns(".tox", ".python-envs"))
         dest.mkdir(exist_ok=True)
         for key, value in content.items():
             if not isinstance(key, str):

src/tox/session/cmd/run/common.py

@@ -9,6 +9,7 @@
 from concurrent.futures import FIRST_COMPLETED, CancelledError, Future, ThreadPoolExecutor
 from concurrent.futures import wait as wait_futures
 from fnmatch import fnmatchcase
+from operator import itemgetter
 from pathlib import Path
 from signal import SIGINT, Handlers, signal
 from threading import Event, Thread
@@ -25,6 +26,7 @@
 from tox.session.cmd.run.single import ToxEnvRunResult, run_one
 from tox.tox_env.errors import Fail
 from tox.util.graph import stable_topological_sort
+from tox.util.python_envs import record_python_envs
 from tox.util.spinner import MISS_DURATION, Spinner
 
 if TYPE_CHECKING:
@@ -282,6 +284,8 @@ def _run_thread() -> tuple[Callable[[int, FrameType | None], Any] | int | Handle
         ordered_results = _order_results(state, results, to_run_list)
         # write the journal
         write_journal(state.conf.options.result_json, state._journal)  # ruff:ignore[private-member-access]
+        # let editors discover the environments
+        _record_python_envs(state)
         # warn about unused config keys
         _warn_unused_config(state)
         # report the outcome
@@ -313,6 +317,22 @@ def _order_results(state: State, results: list[ToxEnvRunResult], to_run_list: li
     return ordered
 
 
+def _record_python_envs(state: State) -> None:
+    core = state.conf.core
+    if not core["python_envs"]:
+        return
+    ranked: list[tuple[tuple[bool, bool, int], Path]] = []
+    for at, name in enumerate(state.envs.iter(only_active=False)):
+        env = state.envs[name]
+        if not (env.env_dir / "pyvenv.cfg").exists():  # not a Python environment a reader could use
+            continue
+        develop = "package" in env.conf and env.conf["package"] in {"editable", "editable-legacy"}
+        # the default environment goes last: prefer one named dev, then a develop install, then the env list order
+        ranked.append(((name == "dev", develop, -at), env.env_dir))
+    envs = [env_dir for _, env_dir in sorted(ranked, key=itemgetter(0))]
+    record_python_envs(cast("Path", core["tox_root"]), cast("Path", core["work_dir"]), envs)
+
+
 class ToxSpinner(Spinner):
     def __init__(self, enabled: bool, state: State, total: int) -> None:  # ruff:ignore[boolean-type-hint-positional-argument]
         stream = state._options.log_handler.stdout  # ruff:ignore[private-member-access]

src/tox/tox.schema.json

@@ -32,6 +32,10 @@
       "type": "string",
       "description": "a folder for temporary files (is not cleaned at start)"
     },
+    "python_envs": {
+      "type": "boolean",
+      "description": "catalog the created tox environments in a PEP-832 .python-envs file, so editors can discover them"
+    },
     "env_list": {
       "type": "array",
       "items": {