Skip to content

PEP 796: Relative Virtual Environments #4476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 38 commits into
base: main
Choose a base branch
from
Open

PEP 796: Relative Virtual Environments #4476

wants to merge 38 commits into from

Conversation

rickeylev
Copy link

@rickeylev rickeylev commented Jun 30, 2025 •
edited
Loading

Basic requirements (all PEP Types)

  • Read and followed PEP 1 & PEP 12
  • File created from the latest PEP template
  • PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header
  • Title clearly, accurately and concisely describes the content in 79 characters or less
  • Core dev/PEP editor listed as Author or Sponsor, and formally confirmed their approval
  • Author, Status (Draft), Type and Created headers filled out correctly
  • PEP-Delegate, Topic, Requires and Replaces headers completed if appropriate
  • Required sections included
    • Abstract (first section)
    • Copyright (last section; exact wording from template required)
  • Code is well-formatted (PEP 7/PEP 8) and is in code blocks, with the right lexer names if non-Python
  • PEP builds with no warnings, pre-commit checks pass and content displays as intended in the rendered HTML
  • Authors/sponsor added to .github/CODEOWNERS for the PEP

Standards Track requirements

  • PEP topic discussed in a suitable venue with general agreement that a PEP is appropriate
  • Suggested sections included (unless not applicable)
    • Motivation
    • Rationale
    • Specification
    • Backwards Compatibility
    • Security Implications
    • How to Teach This
    • Reference Implementation
    • Rejected Ideas
    • Open Issues
  • Python-Version set to valid (pre-beta) future Python version, if relevant
  • Any project stated in the PEP as supporting/endorsing/benefiting from the PEP formally confirmed such
  • Right before or after initial merging, PEP discussion thread created and linked to in Discussions-To and Post-History

Work towards python/cpython#136051

📚 Documentation preview 📚: https://pep-previews--4476.org.readthedocs.build/

@rickeylev rickeylev mentioned this pull request Jun 30, 2025
Open
StanFromIreland
StanFromIreland reviewed Jun 30, 2025
View reviewed changes
@hugovk
Copy link
Member

hugovk commented Jun 30, 2025

Hello, before we go any further with this PR, has the idea been discussed on Discourse?

And after that we'll need a sponsor before assigning the PEP number, do you have one yet? Let's unassign 796 for now.

Please see:

@hugovk hugovk changed the title PEP 796: relative virtual environments, initial draft PEP xxx: relative virtual environments, initial draft Jun 30, 2025
@rickeylev
Copy link
Author

Thanks @hugovk and @StanFromIreland for the early review. I used a draft PR to see the CI results to further clean it up -- my apologies for wasting some of your time, but thank you regardless.

discussed on Discourse?

Yes: https://discuss.python.org/t/making-venvs-relocatable-friendly/96177

The criteria of "discussed enough with enough support" is vague, but what gave me enough confidence to begin a PEP and start a (draft) PR at this point was:

Sponsor needed to assign number

Thanks for clarifying that part! Yes, finding a sponsor is my next big step.

@hugovk
Copy link
Member

hugovk commented Jun 30, 2025

I used a draft PR to see the CI results to further clean it up

Tip: you can enable GitHub Actions at https://github.com/rickeylev/peps/actions and run the CI on your fork.

Yes, finding a sponsor is my next big step.

Good luck!

zanieb
zanieb reviewed Jul 6, 2025
View reviewed changes
hugovk
hugovk reviewed Jul 11, 2025
View reviewed changes
@aignas aignas mentioned this pull request Jul 24, 2025
Open
1 task
@Vigilans Vigilans mentioned this pull request Jul 28, 2025
Open
@paveldikov

This comment has been minimized.

Sign in to view
@AA-Turner
Copy link
Member

@paveldikov thank you for the comment, please could you re-post it on Discourse? The peps repo / PR discussion is mainly for editorial discussion, rather than substantive comment on the proposal itself.

A

rickeylev and others added 4 commits August 17, 2025 13:02
rickeylev
rickeylev commented Aug 17, 2025
View reviewed changes
Copy link
Author

@rickeylev rickeylev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the reviews! I'm out from under $dayJob and vacation backlogs a bit now and addressed comments.

StanFromIreland
StanFromIreland reviewed Aug 18, 2025
View reviewed changes
Copy link
Member

@StanFromIreland StanFromIreland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some little notes

@ncoghlan
Copy link
Contributor

Belatedly removed the DO-NOT-MERGE label (that was added pending the Discourse discussion and sponsorship of the PEP)

AA-Turner
AA-Turner requested changes Aug 18, 2025
View reviewed changes
Copy link
Member

@AA-Turner AA-Turner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PEP is currently missing a Security Implications section, which I think should be added given that arbitrary directory traversal is permitted -- at the very least explaining why this is fine.

Several editorial notes, I think the Motivation & Rationale sections should be strengthened to focus on the benefits from relative environments, there is currently (I believe) a lot of assumed context.

The PEP also discusses at some length a broader proposal for reloacatable venvs. Is it worth considering making that the proposal here? I don't know the specifics, so it might be that the changes needed for 'relocatable' are too large to tackle in one go.

A

@AA-Turner AA-Turner changed the title PEP 796: relative virtual environments, initial draft PEP 796: Relative Virtual Environments [initial draft] Aug 18, 2025
rickeylev and others added 2 commits August 20, 2025 22:12
@rickeylev @ncoghlan
@AA-Turner @StanFromIreland
Apply AA-Turner suggestions
0af0eea 
Co-authored-by: Alyssa Coghlan <ncoghlan@gmail.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@rickeylev
add refs, remove CWD acronym, fix grammar
68dd5e0
rickeylev
rickeylev commented Aug 21, 2025
View reviewed changes
Copy link
Author

@rickeylev rickeylev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied suggestions and addressed a few comments; didn't have time to address everything, though.

rickeylev
rickeylev commented Aug 24, 2025
View reviewed changes
Copy link
Author

@rickeylev rickeylev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, all pending comments addressed (I think. The Github UI frequently tricks me 😂 )

PTAL

re: security section: added. At least, insofar as I understand your concern correctly.

re: motivation and rationale strengthening: Thanks! Yeah, honestly, a big issue I've had writing this that "Motivation" and "Rationale" are, to me at least, practically synonyms. I did my best to better separate "Why do this change at all?" (motivation) and "Implementation decision and why that decision" (rationale).

re: proposing relocatable venv in this pep: I added a section about why this pep limits its scope to just the core interpreter.

@rickeylev rickeylev mentioned this pull request Sep 6, 2025
Open
@AA-Turner AA-Turner added the new-pep A new draft PEP submitted for initial review label Sep 29, 2025
ncoghlan
ncoghlan approved these changes Sep 30, 2025
View reviewed changes
Copy link
Contributor

@ncoghlan ncoghlan left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few editorial comments inline, but I think this is essentially ready for publication.

peps/pep-0796.rst
During interpreter startup (i.e. :file:`getpath.py`), the relative path is joined to the
directory containing ``pyvenv.cfg`` to form an absolute path.
Parent-directory references (``../``) and current
directory references (``./``) are resolved syntactically (i.e. not resolving
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
directory references (``./``) are resolved syntactically (i.e. not resolving
directory references (``./``) are resolved lexically (i.e. not resolving

(I don't mind if this isn't accepted, I've just always referred to this style of resolution as lexical rather than as syntactic: python/cpython#124825

peps/pep-0796.rst

This PEP does not specify how to create a ``pyvenv.cfg`` with a relative path,
nor how downstream tools (e.g. installers) should identify them or process
them. These questions are best addressed separately by tool owners.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't an open issue, but rather than intentional omission. Perhaps just include a variant of this paragraph in the rationale subsection about not fully specifying portable virtual environments?

@hugovk hugovk changed the title PEP 796: Relative Virtual Environments [initial draft] PEP 796: Relative Virtual Environments Sep 30, 2025
hugovk
hugovk reviewed Sep 30, 2025
View reviewed changes
peps/pep-0796.rst Outdated
machines do so either by relying on undocumented interpreter behaviour
(Bazel, omitting the ``home`` key entirely to trigger an implementation
dependent fallback to resolving via a symlinked interpreter binary on
non-Windows systems, see `gh-135773`) or by requiring a post-installation script to be executed
Copy link
Member

@hugovk hugovk Sep 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lint fix:

Alyssa's suggestion below is better.

peps/pep-0796.rst
Comment on lines +210 to +216
How to Teach This
=================

Teaching this should be straightforward: if you use a relative path in
``pyvenv.cfg``, then it's relative to the directory containing the
``pyvenv.cfg`` file. This is simple to explain and easy to understand for
anyone that is already familiar with handling relative filesystem paths.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be useful to say where you will teach this. What docs will you update?

peps/pep-0796.rst Outdated
paths.

A proof-of-concept of this is implemented in the author's branch,
`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.
`rickeylev/feat.relative.pyvenv.home
<https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.

Please could you also wrap some of the other long lines to 79 chars?

https://peps.python.org/pep-0012/#general

ncoghlan
ncoghlan reviewed Sep 30, 2025
View reviewed changes
Copy link
Contributor

@ncoghlan ncoghlan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these are the two items the PEP linter is picking up.

@ncoghlan @hugovk
Apply markup and simple grammar fixes from code review
ae5a67f 
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
@ncoghlan
Copy link
Contributor

ncoghlan commented Oct 7, 2025

@rickeylev I went ahead and applied the straightforward markup & grammar fixes in ae5a67f, so the remaining comments are the ones that aren't as simple to address.

@AA-Turner This will need a re-review from you at some point for the "Changes requested" flag.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ncoghlan ncoghlan ncoghlan approved these changes

@hugovk hugovk hugovk left review comments

@zanieb zanieb zanieb left review comments

@StanFromIreland StanFromIreland StanFromIreland left review comments

@AA-Turner AA-Turner AA-Turner requested changes

Assignees
No one assigned
Labels
new-pep A new draft PEP submitted for initial review
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@rickeylev @hugovk @ncoghlan @paveldikov @AA-Turner @zanieb @StanFromIreland