From c93ba66aef1eb2c5e120f48cee8c7310b5622ba6 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 10 Aug 2026 12:22:00 -0700 Subject: [PATCH] PEP 832: Address feedback --- peps/pep-0832.rst | 67 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 5 deletions(-) diff --git a/peps/pep-0832.rst b/peps/pep-0832.rst index c9e735fbdce..64454e11116 100644 --- a/peps/pep-0832.rst +++ b/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 `__) + 3. virtualenv (Bernat Gabor; `PoC `__) 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`