[doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (GH-98350) #98350

pelson · 2022-10-17T08:41:11Z

Refresh the venv introduction documentation, and correct the incorrect statement about the VIRTUAL_ENV environment variable mentioned in #21970 (comment) in discussion with @vsajip.

This is quite an extensive restructure of the venv introduction. The existing documentation has clearly been developed iteratively, and it therefore needed a bit of effort to ensure that the information is presented logically and consistently. I am happy to adapt/adjust as requested, but I believe the proposed change is simpler, shorter and more precise.

In practice this documentation can be back-ported fully (it doesn't refer to any new features).

cpython-cla-bot · 2022-10-17T08:41:39Z

All commit authors signed the Contributor License Agreement.

…orrect statement about the VIRTUAL_ENV environment variable

vsajip · 2022-10-17T10:15:32Z

Thanks, Phil, your changes look good to me. I'll ask for an additional reviewer to look at it, since I may be a bit too close to it to notice things from a newcomer's perspective.

vsajip

Just a minor whitespace change.

vsajip · 2022-10-17T10:18:29Z

Doc/library/venv.rst

+be optionally isolated from the base's site packages, meaning
+that packages installed in the base environment will not be accessible from
+the virtual environment.
+A virtual environment is therefore a powerful and convenient concept which


Perhaps insert a blank line here?

Sure thing. Done in 1ba4797

bedevere-bot · 2022-10-17T10:20:35Z

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 I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

…nments

vsajip · 2022-10-17T17:52:34Z

Phil, you need to sign the CLA using the button above.

CAM-Gerlach

This is a significant improvement overall in the structure, presentation and phrasing of these docs. Thanks for all your work, @pelson !

I did have a number of comments, all as suggestions, that fix/clarify some key details, use appropriate Sphinx syntax, update or remove some outdated or inapplicable passages, say the same thing more simply and concisely, avoid repetition and improve phrasing.

To easily apply some or all of them with one click, go to the Files tab, clicking Add to batch on each of the suggestions, and finally click Commit once you've selected all the ones you want. You can also reply with your own suggestions and add/apply those at the same time, if you want to fix something in mine. That will apply the specific suggestions and auto-resolve the review comments all in one go, which makes things a lot easier for both you and us.

Thanks, and looking forward to seeing this merged!

Doc/library/venv.rst

CAM-Gerlach · 2022-10-17T22:04:55Z

Doc/library/venv.rst

+.. note:: When a virtual environment is active, any options that change the
+   installation path will be ignored from all :mod:`distutils` configuration
+   files to prevent projects being inadvertently installed outside of the
+   virtual environment.
+
+
 .. _venv-api:


Suggested change

.. note:: When a virtual environment is active, any options that change the

installation path will be ignored from all :mod:`distutils` configuration

files to prevent projects being inadvertently installed outside of the

virtual environment.

.. _venv-api:

.. _venv-api:

Distutils has been officially deprecated since Python 3.10 (the oldest backportable version) and removed in this version, 3.12 (thus the link should not resolve). Furthermore, use of these config files and use of distutils as an installer directly has been deprecated for perhaps a decade. Therefore, this should just be removed.

The one thing that would make me hesitate with this one is that it would be good to get these improvements into older Python docs. The VIRTUAL_ENV environment variable documentation is wrong since Python 3.8 (by a commit that was backported that far 2 years ago).

But that snippet could be left out even in documentation for older Python versions, as it doesn't really add all that much information - for example, it's not clear which options might be meant in

any options that change the installation path

The one thing that would make me hesitate with this one is that it would be good to get these improvements into older Python docs.

Right, which is why I mentioned it has been deprecated since the oldest backportable version, Python 3.10, and discouraged for perhaps a decade (never mind "distutils configuration files"—I don't know if I've ever run into any modern mention of anything actually using them these days; I'm involved with a fair bit of packaging stuff and I'd never even heard of them until now). Ergo, this is likely to cause more confusion than anything, if even packaging experts like @vsajip aren't even sure what it is intended to mean. And if worst comes to worse, this one change can always be dropped in a backport (though it seems very unnecessary).

The VIRTUAL_ENV environment variable documentation is wrong since Python 3.8 (by a commit that was backported that far 2 years ago).

I'm not entirely sure what you intend to mean here, sorry.

I'm not entirely sure what you intend to mean here, sorry.

Simply stating that there is a factually incorrect statement in the documenation relating to VIRTUAL_ENV environment use (it claims: "This can be used to check if one is running inside a virtual environment.", which is wrong), which it would be great to remove from as many backported versions as possible to avoid incorrect usage in the wild.

Ah, gotcha 👍 I was confused and wasn't sure the connection.

CAM-Gerlach · 2022-10-17T22:19:39Z

As a quick reminder, to easily apply some or all of them with one click, go to the Files tab, clicking Add to batch on each of the suggestions, and finally click Commit once you've selected all the ones you want. You can also reply with your own suggestions and add/apply those at the same time, if you want to fix something in mine. That will apply the specific suggestions and auto-resolve the review comments all in one go, which makes things a lot easier for both you and us.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

miss-islington · 2022-10-19T14:49:46Z

Sorry, @pelson and @vsajip, I could not cleanly backport this to 3.10 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 1a6bacb31f7b49c244a6cc3ff0fa7f71a82412ef 3.10

CAM-Gerlach · 2022-10-19T19:09:36Z

Thanks @pelson for your hard work and putting up with me, and @vsajip for reviewing, inviting me to and merging!

@vsajip @pelson were either of you planning to do the manual cherry picking for the backport? If not, I can help take care of it, though I'm also pretty busy finishing #95913 before the 3.11 release Monday so it might not happen right away.

…atement about VIRTUAL_ENV (pythonGH-98350) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> (cherry picked from commit 1a6bacb)

… the statement about VIRTUAL_ENV (pythonGH-98350) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> (cherry picked from commit 1a6bacb)

bedevere-bot · 2022-10-19T21:26:11Z

GH-98465 is a backport of this pull request to the 3.11 branch.

bedevere-bot · 2022-10-19T21:27:15Z

GH-98466 is a backport of this pull request to the 3.10 branch.

vsajip · 2022-10-19T21:33:48Z

were either of you planning to do the manual cherry picking for the backport?

Yes, I've had a stab at it 🙂

CAM-Gerlach · 2022-10-20T00:18:57Z

Thanks @vsajip !

vsajip · 2022-10-20T08:11:20Z

I just looked at the built documentation and noticed something a bit odd.

I'm not familiar with the use of exclamation marks in this markup - :program:`!fish` and :program:`!csh` activation scripts. @CAM-Gerlach what do they do? I couldn't see anything in the Sphinx docs.

* main: (40 commits) pythongh-98461: Fix source location in comprehensions bytecode (pythonGH-98464) pythongh-98421: Clean Up PyObject_Print (pythonGH-98422) pythongh-98360: multiprocessing now spawns children on Windows with correct argv[0] in virtual environments (pythonGH-98462) CODEOWNERS: Become a typing code owner (python#98480) [doc] Improve logging cookbook example. (pythonGH-98481) Add more tkinter.Canvas tests (pythonGH-98475) pythongh-95023: Added os.setns and os.unshare functions (python#95046) pythonGH-98363: Presize the list for batched() (pythonGH-98419) pythongh-98374: Suppress ImportError for invalid query for help() command. (pythongh-98450) typing tests: `_overload_dummy` raises `NotImplementedError`, not `RuntimeError` (python#98351) pythongh-98354: Add unicode check for 'name' attribute in _imp_create_builtin (pythonGH-98412) pythongh-98257: Make _PyEval_SetTrace() reentrant (python#98258) pythongh-98414: py.exe launcher does not use defaults for -V:company/ option (pythonGH-98460) pythongh-98417: Store int_max_str_digits on the Interpreter State (pythonGH-98418) Doc: Remove title text from internal links (python#98409) [doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (pythonGH-98350) Docs: Bump sphinx-lint and fix unbalanced inline literal markup (python#98441) pythongh-92886: Replace assertion statements in `handlers.BaseHandler` to support running with optimizations (`-O`) (pythonGH-93231) pythongh-92886: Fix tests that fail when running with optimizations (`-O`) in `_test_multiprocessing.py` (pythonGH-93233) pythongh-92886: Fix tests that fail when running with optimizations (`-O`) in `test_py_compile.py` (pythonGH-93235) ...

CAM-Gerlach · 2022-10-20T18:22:55Z

As documented in at the top of the Sphinx Roles doc and in the Python devguide, for any Sphinx role that creates a cross-reference (which are most of them), most domain-specific Sphinx roles) prefixing the content of with ! disables resolving the reference.

This is used in the CPython docs when the target is already referenced within the same paragraph/information unit to not link the same thing multiple times, when referring to a class, function etc. within its own description to avoid linking to itself, and when either the target intentionally doesn't exist (e.g. example class, removed from Python, not part of CPython, deliberately undocumented, etc) to skip wasting time looking it up and silence the resulting spurious warning.

I had naturally assumed that :program: was a cross-reference role that referenced programs defined by the .. program:: directive, just like :option: does for the .. option:: directive (that can be embedded inside .. program::, and I needed a ! since those programs weren't defined within the Python docs. However, it seems the role is in fact currently only for semantics/formatting purposes, and it does not support cross referencing. Therefore, the ! can simply be elided.

vsajip · 2022-10-21T00:04:14Z

TIL - thanks! I'll look at updating those at some point.

CAM-Gerlach · 2022-10-21T02:58:40Z

Thanks! Since its my fault, I'll also look to take care of it at some point soon if you don't get to it first.

Also, I talked to Adam about adding cross-reference support to future Sphinx versions for :program:, so this might eventually work as intended.

Remove the exclamation mark from :program:`!foo` in .rst files because it inadvertently shows up in the rendered HTML. (Sphinx's cross-referencing roles use a '!' prefix to suppress hyperlinking[1], but :program: is not a cross-referencing role so the '!' is displayed verbatim.) The exclamation marks in venv.rst were introduced in #98350. See comments [2] and [3] for additional discussion. [1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax [2]: #98350 (comment) [3]: #98350 (comment) Reported-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>

Remove the exclamation mark from :program:`!foo` in .rst files because it inadvertently shows up in the rendered HTML. (Sphinx's cross-referencing roles use a '!' prefix to suppress hyperlinking[1], but :program: is not a cross-referencing role so the '!' is displayed verbatim.) The exclamation marks in venv.rst were introduced in python#98350. See comments [2] and [3] for additional discussion. [1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax [2]: python#98350 (comment) [3]: python#98350 (comment) Reported-by: Vinay Sajip <vinay_sajip@yahoo.co.uk> (cherry picked from commit 8647ba4)

Remove the exclamation mark from :program:`!foo` in .rst files because it inadvertently shows up in the rendered HTML. (Sphinx's cross-referencing roles use a '!' prefix to suppress hyperlinking[1], but :program: is not a cross-referencing role so the '!' is displayed verbatim.) The exclamation marks in venv.rst were introduced in pythonGH-98350. See comments [2] and [3] for additional discussion. [1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.htmlGH-cross-referencing-syntax [2]: https://github.com/python/cpython/pull/98350GH-issuecomment-1285965759 [3]: https://github.com/python/cpython/pull/98350GH-issuecomment-1286394047 Reported-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>. (cherry picked from commit 8647ba4) Co-authored-by: Tom Levy <tomlevy93@gmail.com>

tom93 · 2023-03-15T07:18:15Z

Therefore, the ! can simply be elided.

Done in #102694.

…2716) Remove the exclamation mark from :program:`!foo` in .rst files because it inadvertently shows up in the rendered HTML. (Sphinx's cross-referencing roles use a '!' prefix to suppress hyperlinking[1], but :program: is not a cross-referencing role so the '!' is displayed verbatim.) The exclamation marks in venv.rst were introduced in #98350. See comments [2] and [3] for additional discussion. [1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax [2]: #98350 (comment) [3]: #98350 (comment) Reported-by: Vinay Sajip <vinay_sajip@yahoo.co.uk> Co-authored-by: Tom Levy <tomlevy93@gmail.com>

…2717) Remove the exclamation mark from :program:`!foo` in .rst files because it inadvertently shows up in the rendered HTML. (Sphinx's cross-referencing roles use a '!' prefix to suppress hyperlinking[1], but :program: is not a cross-referencing role so the '!' is displayed verbatim.) The exclamation marks in venv.rst were introduced in #98350. See comments [2] and [3] for additional discussion. [1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax [2]: #98350 (comment) [3]: #98350 (comment) Reported-by: Vinay Sajip <vinay_sajip@yahoo.co.uk> Co-authored-by: Tom Levy <tomlevy93@gmail.com>

Remove the exclamation mark from :program:`!foo` in .rst files because it inadvertently shows up in the rendered HTML. (Sphinx's cross-referencing roles use a '!' prefix to suppress hyperlinking[1], but :program: is not a cross-referencing role so the '!' is displayed verbatim.) The exclamation marks in venv.rst were introduced in python#98350. See comments [2] and [3] for additional discussion. [1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax [2]: python#98350 (comment) [3]: python#98350 (comment) Reported-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>

pelson requested a review from vsajip as a code owner October 17, 2022 08:41

bedevere-bot added the awaiting review label Oct 17, 2022

pelson force-pushed the enh/venv-docs branch from 8c08a07 to b234ddc Compare October 17, 2022 08:41

pelson force-pushed the enh/venv-docs branch 2 times, most recently from c11acb4 to 54259a2 Compare October 17, 2022 08:45

Doc: Refresh the venv introduction documentation, and correct the inc…

ea6ccbe

…orrect statement about the VIRTUAL_ENV environment variable

pelson force-pushed the enh/venv-docs branch from 54259a2 to ea6ccbe Compare October 17, 2022 08:47

vsajip requested a review from CAM-Gerlach October 17, 2022 10:15

vsajip added docs Documentation in the Doc dir skip issue skip news labels Oct 17, 2022

vsajip requested changes Oct 17, 2022

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting review labels Oct 17, 2022

Review action to add newline into the documentation of virtual enviro…

1ba4797

…nments

pelson force-pushed the enh/venv-docs branch from 27de904 to 1ba4797 Compare October 17, 2022 11:16

vsajip approved these changes Oct 17, 2022

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting changes labels Oct 17, 2022

vsajip added awaiting review and removed awaiting merge labels Oct 17, 2022

CAM-Gerlach added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels Oct 17, 2022

CAM-Gerlach reviewed Oct 17, 2022

View reviewed changes

Apply suggestions from code review

f3d13f3

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

vsajip mentioned this pull request Oct 19, 2022

[3.11] [doc] Refresh the venv introduction documentation, and correct the st… (GH-98465) #98465

Merged

bedevere-bot removed the needs backport to 3.11 only security fixes label Oct 19, 2022

vsajip mentioned this pull request Oct 19, 2022

[3.10] [doc] Refresh the venv introduction documentation, and correct… (GH-98466) #98466

Merged

bedevere-bot removed the needs backport to 3.10 only security fixes label Oct 19, 2022

pelson deleted the enh/venv-docs branch October 30, 2022 21:07

pelson mentioned this pull request Nov 17, 2022

Implement config file location 'base' to config all environments of an interpreter pypa/pip#11487

Merged

hugovk mentioned this pull request Mar 14, 2023

Remove misformatted exclamation marks in docs #102694

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (GH-98350) #98350

[doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (GH-98350) #98350

pelson commented Oct 17, 2022

cpython-cla-bot bot commented Oct 17, 2022 •

edited

Loading

vsajip commented Oct 17, 2022

vsajip left a comment

vsajip Oct 17, 2022

pelson Oct 17, 2022

bedevere-bot commented Oct 17, 2022

vsajip commented Oct 17, 2022

CAM-Gerlach left a comment

CAM-Gerlach Oct 17, 2022

pelson Oct 18, 2022

vsajip Oct 18, 2022

CAM-Gerlach Oct 18, 2022

pelson Oct 19, 2022

CAM-Gerlach Oct 19, 2022

CAM-Gerlach commented Oct 17, 2022

miss-islington commented Oct 19, 2022

CAM-Gerlach commented Oct 19, 2022 •

edited

Loading

bedevere-bot commented Oct 19, 2022

bedevere-bot commented Oct 19, 2022

vsajip commented Oct 19, 2022

CAM-Gerlach commented Oct 20, 2022

vsajip commented Oct 20, 2022

CAM-Gerlach commented Oct 20, 2022

vsajip commented Oct 21, 2022

CAM-Gerlach commented Oct 21, 2022

tom93 commented Mar 15, 2023

[doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (GH-98350) #98350

[doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (GH-98350) #98350

Conversation

pelson commented Oct 17, 2022

cpython-cla-bot bot commented Oct 17, 2022 • edited Loading

vsajip commented Oct 17, 2022

vsajip left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bedevere-bot commented Oct 17, 2022

vsajip commented Oct 17, 2022

CAM-Gerlach left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CAM-Gerlach commented Oct 17, 2022

miss-islington commented Oct 19, 2022

CAM-Gerlach commented Oct 19, 2022 • edited Loading

bedevere-bot commented Oct 19, 2022

bedevere-bot commented Oct 19, 2022

vsajip commented Oct 19, 2022

CAM-Gerlach commented Oct 20, 2022

vsajip commented Oct 20, 2022

CAM-Gerlach commented Oct 20, 2022

vsajip commented Oct 21, 2022

CAM-Gerlach commented Oct 21, 2022

tom93 commented Mar 15, 2023

cpython-cla-bot bot commented Oct 17, 2022 •

edited

Loading

CAM-Gerlach commented Oct 19, 2022 •

edited

Loading