✨ feat(create): record created environments per PEP 832 - #3204
Draft
gaborbernat wants to merge 5 commits into
Draft
✨ feat(create): record created environments per PEP 832#3204gaborbernat wants to merge 5 commits into
gaborbernat wants to merge 5 commits into
Conversation
gaborbernat
marked this pull request as draft
August 5, 2026 00:54
gaborbernat
force-pushed
the
832
branch
2 times, most recently
from
August 5, 2026 01:09
2f01549 to
af89bd8
Compare
gaborbernat
force-pushed
the
832
branch
2 times, most recently
from
August 28, 2026 19:19
720f524 to
9611c5c
Compare
Bind version_info once instead of repeating self.interpreter.version_info across the python-version, version_info, and version fields. Assert the written python-version against sys.version_info rather than the interpreter object the code just read, so the test fails if the field value is wrong.
The key had no home in the docs, since virtualenv documented no `pyvenv.cfg` key anywhere. A reference page now covers the file, and a table sets `python-version` against `version` and `version_info`, which carry one number at three precisions and gave callers no reason to prefer one over another. The tutorial reads the key out of an environment it just made, the usage guide parses it without spawning the interpreter, and the explanation of why environments borrow from the base install says why `pyvenv.cfg` became the place tools look. The version assertion compared against the running interpreter while the code reads the target one, so it passed for the wrong reason whenever the two agree.
Editors and type checkers have no standard way to find a project's environments without an activated shell, so each one hard-codes a search per tool that creates environments. PEP 832 replaces that with a .python-envs file whose last line names the default environment. virtualenv creates environments, so it covers the write half. After creation it records the destination in the .python-envs file of the parent folder and moves any existing entry for it to the end, making the fresh environment the default. A destination named .venv is left alone, since the PEP counts it as the implicit last line. A read or write failure warns and leaves the environment usable. Pass --no-python-envs to opt out. Recording rewrites the whole file, which loses entries when several environments land in one folder at once: eight concurrent creations dropped between one and four of them on every attempt. The read-modify-write therefore runs under a .python-envs.lock file next to the recorded one. Locking beside the resource rather than inside the app data folder holds the guarantee when the app data is read-only or disabled, and gives any other PEP 832 writer a location to agree on. Documented across all four Diataxis dimensions, including a new reference page cataloguing every file virtualenv writes inside and beside an environment.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Editors and type checkers have no standard way to find a project's environments without an activated shell, so each one hard-codes a search per tool that creates environments. PEP 832 addresses that with a
.python-envsfile listing one environment per line, where the last line names the default environment and a.venvfolder alongside counts as the implicit last line.virtualenv creates environments, so this covers the write half. After creation it records the destination in the
.python-envsfile of the parent folder and moves any existing entry for it to the end, making the fresh environment the default. It leaves a destination named.venvalone, since the PEP treats it as the implicit last line. A read or write failure warns and leaves the environment usable. Pass--no-python-envsto opt out.Rewriting the whole file loses entries when several environments land in one folder at once. Eight concurrent creations dropped between one and four of them on every attempt, so the read-modify-write runs under a
.python-envs.lockfile next to the recorded one. 🔒 Locking beside the resource rather than inside the app data folder holds the guarantee when the app data is read-only or disabled, and gives any other PEP 832 writer a location to agree on.