DOC: clarify and expand documentation about PYTHONUSERBASE and PYTHONNOUSERSITE#144637
DOC: clarify and expand documentation about PYTHONUSERBASE and PYTHONNOUSERSITE#144637tacaswell wants to merge 7 commits intopython:mainfrom
Conversation
Otherwise it is not clear how to disable user site-packages. Even though it is directly above, the link from the search results put the top of the page on PYHONUSERBASE and the user may not think to scroll up for critical context.
Now matches both site.rst and the actual implementation.
It is not otherwise documented that this implicitly disables user site-packages.
tacaswell
force-pushed
the
doc/usersite_details
branch
from
69f8de3 to
9cde670
Compare
There was a problem hiding this comment.
Thanks for working on this @tacaswell!
It overall looks good, and corrects some incorrect information, which is very helpful. I just have a couple comments.
| There are other ways how "virtual environments" could be implemented, this | ||
| documentation refers implementations based on the ``pyvenv.cfg`` mechanism, | ||
| such as :mod:`venv`. Most virtual environment implementations follow the | ||
| model set by :mod:`venv`, but there may be exotic implementations that | ||
| diverge from it. | ||
| There are many ways how "virtual environments" could be implemented. | ||
| This documentation refers to implementations based on the ``pyvenv.cfg`` | ||
| mechanism, such as :mod:`venv`, that many virtual environment implementations | ||
| follow. |
There was a problem hiding this comment.
I honestly don't think this paragraph needs a change. In fact, I think the new version removes some information that I think is helpful to the user.
There was a problem hiding this comment.
I do not think this edit removes any factual information, but agree it could be word smithed a bit.
There was a problem hiding this comment.
The old text points out that most virtual environment implementations use pyvenv.cfg, and reminds the user that there are still other implementations. The new text removes emphasis on pyvenv.cfg being the main mechanism used in most virtual environment implementations. That's what I meant, sorry!
There was a problem hiding this comment.
"virtual environments" is a bit of a slippery term as it can both mean the very specific family of implementations that rely on pyvenv.cfg and a generic "isolated user space Python". Neither pixi nor conda currently drop this file in their environments (how I got started down this path was an issue at work on a shared system where some had done pip install --user and it was then leaking into and breaking pixi environments).
I consider those mainstream tools for the looser meaning the term and in that context the previous text was at best misleading.
I tweaked the first sentence a bit.
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
|
Friendly ping @tacaswell 😊 |
|
I have made the requested changes; please review again |
|
Thanks for making the requested changes! @FFY00: please review the changes made to this pull request. |
2 participants
I erred on this not needing an issue to say "the docs could be improved" as that is always a true statement ;).
The changes are split up into individual commits for ease of review. The primary changes are:
include-system-site-packagesinpyvenv.cfgimplicitly also controls user site-packagessite.pydocstring (looks like it has always been wrong)📚 Documentation preview 📚: https://cpython-previews--144637.org.readthedocs.build/