PEP 832: Address feedback

peps/pep-0832.rst

@@ -93,8 +93,8 @@ represents an environment that is usable by the project and may be separated by
 and MUST be ignored.
 
 Lines in a :file:`.python-envs` file MAY be paths to an environment. Paths MAY
-be relative, and if they are, they MUST be relative to the
-:file:`.python-envs` file. IF a path is for a virtual environment, THEN the
+be relative, and if they are, they MUST be relative to the directory containing
+the :file:`.python-envs` file. IF a path is for a virtual environment, THEN the
 path MUST be to the directory of the virtual environment (i.e. the directory
 containing the :file:`pyvenv.cfg` file). A line MAY represent any type of an
 environment. Tools reading a :file:`.python-envs` MAY choose what sort of
@@ -137,6 +137,13 @@ by this PEP.
 Tools MAY use a file system locking mechanism to help guarantee no race
 conditions when reading or writing to a :`.python-envs` file.
 
+IF a tool can detect that an environment is already in use (e.g. the
+``VIRTUAL_ENV`` environment variable is set), THEN tools SHOULD respect the
+user's choice and use the activated/in-use environment over the default
+environment when no previous environment selection has occurred. Tools MAY
+choose to override even a previous environment selection if an environment is
+detected as activated/in use.
+
 
 Rationale
 =========
@@ -170,13 +177,21 @@ aspect of the project (environments themselves can be viewed as implementation
 details). The file name was chosen to make sure it didn't clash with any other
 tool using the same name while still being self-descriptive.
 
+Allowing for multiple environments came up multiple times during discussions of
+this PEP as people said they would switch between multiple environments during
+development. Listing all of the environments available instead of a single one
+allows for a better UX by allowing tools to present users a list of
+environments to choose from. It also helps avoid constant rewriting of the file
+recording the single environment that should be used.
+
 The :file:`.python-envs` file is specifically agnostic when it comes to what
 type of environment can be represented. This helps future-proof the file for
 unforeseen, future environments. As well, leaving the representation as loose
 as what a single line of a file can represent helps with allowing alternative
 environments that a tool may or may not support (which can include alternative
 representations for virtual environments, e.g. connecting over SSH). It does
-mean, though, that tools SHOULD check the line for appropriate use.
+mean, though, that tools SHOULD check the line for appropriate use to avoid
+using malicious inputs.
 
 The file format is simple to allow for easy manipulation. Having a
 line-delimited file format makes it easy to append a line to a
@@ -206,8 +221,29 @@ Having :file:`.venv` represent the last, and thus default, environment in a
 :file:`.python-envs` file is for practical reasons. Tools that predate this
 PEP may use the :file:`.venv` location, and so this is a
 backwards-compatibility consideration. And if a user is using such a tool that
-uses :file:`.venv`, then they likely already considered that virtual environment
-the default.
+uses :file:`.venv`, then they likely already considered that virtual
+environment the default.
+
+Suggesting tools respect any activate environment is so that users have a way
+to override any potential project-specific default location for an environment
+(e.g. a project checks in a :file:`.python-envs` file with a relative path
+while the user very much does not want that location used as they want all
+environments stored in a centralized location).
+
+
+Example
+=======
+
+If the following contents were in a :file:`.python-envs` file in the
+``/workspace`` directory::
+
+  /absolute/path/to/venv
+  /a/path/to/conda-env
+  ssh@example.com:custom-path
+  relative/path/venv
+
+The ``relative/path/venv`` directory should be resolved to
+``workspace/relative/path/venv``.
 
 
 Project Support for this PEP
@@ -222,6 +258,8 @@ Speaking to various tool maintainers about this PEP:
 - Supports
 
   1. VS Code
+  2. tox (Bernat Gabor; `PoC <https://github.com/tox-dev/tox/pull/4013>`__)
+  3. virtualenv (Bernat Gabor; `PoC <https://github.com/pypa/virtualenv/pull/3204>`__)
 
 
 Backwards Compatibility
@@ -244,6 +282,13 @@ Not checking the contents of a potentially malicious :file:`.python-envs` file
 and passing it to a shell process (e.g. ``subprocess.run(..., shell=True)``)
 would be a serious security concern.
 
+If tools blindly overwrite :file:`.venv`, that could be a denial of service
+attack if a user happened to use that directory for something else. The
+expectation, though, is that would occur very rarely due to the convention of
+:file:`.venv` being used for virtual environments. If tools are concerned about
+this issue then they can prompt the user before creating an environment at a
+location that already exists.
+
 
 How to Teach This
 =================
@@ -408,6 +453,18 @@ this PEP.
 Change History
 ==============
 
+- 10-Aug-2026
+
+  - Clarify that relative paths in :file:`.python-envs` are against the
+    directory containing the file
+  - Say that tools SHOULD respect any activated environment if the user has
+    not previously selected an environment to use, and allow completely
+    overriding any previous selection
+  - Give a rationale for supporting multiple environments
+  - Provide an example
+  - List tox and virtualenv support
+  - Mention DoS concern
+
 - 31-Jul-2026
 
   - Changed from :file:`.venv` redirect files to :file:`.python-envs`