✨ feat(config): catalog environments in a PEP 832 .python-envs file

[gaborbernat]

Nothing tells an editor where tox put its environments. They live under .tox, a directory no editor searches, so picking one as your interpreter means running tox devenv, copying the path out of the output, pasting it into a settings dialog, and doing it again after the next recreate. 🔍

PEP 832 gives tools a place to publish that answer: a .python-envs file at the project root listing one environment directory per line, where the last line names the default. VS Code reads it today. tox now writes it at the end of a run, listing the environments that exist on disk, and orders them by how useful they are to someone editing code: an environment named dev takes the last line, then one that installs the project in development mode, then the earlier entries of env_list. Trimming lines off the bottom falls back to the next best choice rather than to whatever ran last.

Lines pointing outside the work dir came from another tool, so tox leaves them alone, including a claim on the last line. If you or another tool chose the default, tox writes its own block above it. An environment drops out of the catalog while -r rebuilds it and returns once the run finishes, so nothing sends a reader to a half-built interpreter. A .venv gets no line at all, since PEP 832 already treats it as the implicit final entry.

Writing into the project root is on by default, because a discovery convention only pays off when tools follow it without being asked. Set python_envs to false to opt out. The docs cover it across all four sections: a step in the tutorial, a recipe for pointing an editor at an environment, the config reference, and the reasoning in the concepts page.