classification
Title: venv documentation incorrect / misleading
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Graham.Oliver, docs@python, r.david.murray, steven.downum, willingc
Priority: normal Keywords: easy, patch

Created on 2015-06-01 22:21 by Graham.Oliver, last changed 2018-06-11 07:41 by taleinat.

Pull Requests
URL Status Linked Edit
PR 6589 open Elena.Oat, 2018-04-24 15:42
Messages (8)
msg244618 - (view) Author: Graham Oliver (Graham.Oliver) Date: 2015-06-01 22:21
See my question here
https://groups.google.com/forum/#!topic/comp.lang.python/BUmyc_hzAsA
In particular Carl Meyer's response
https://groups.google.com/d/msg/comp.lang.python/BUmyc_hzAsA/-cT-N-g_LL4J

I am not sure what is possible with venv but I would suggest that the statement 'allowing creation of environments with various Python versions' needs to be clarified and / or altered.

Thanks
Graham
msg244619 - (view) Author: Graham Oliver (Graham.Oliver) Date: 2015-06-01 22:25
See also
https://groups.google.com/d/msg/comp.lang.python/BUmyc_hzAsA/Nx5QgT1gzYEJ
msg244631 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-06-02 01:18
Hmm.  We don't in general mention 2.7 in the python3 docs (in fact I found only one mention of it, in the logging package docs).  I suppose this might be confusing enough to warrant it.  But it might be better to rewrite that sentence to make it clear that the python binary you get in your virtual environment is the one that the venv command comes from.  That should make it pretty clear you can't use it with 2.7, since 2.7 doesn't include venv.
msg244634 - (view) Author: Graham Oliver (Graham.Oliver) Date: 2015-06-02 02:06
ok current version
Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories.

Suggested Alternative
Each virtual environment has its own isolated Python binary (which matches the version used to create it) and can have its own independent set of installed Python packages in its site directories.
msg244639 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-06-02 02:30
Current version
Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories.

Another suggested revision
Since its introduction in Python 3.3, venv may be used to create a virtual environment with its own Python binary and optionally its own independent set of installed Python packages in its site directories. Multiple virtual environments permit various Python versions to exist on a system.

David and Graham,
Perhaps moving the "see also" box (see also Python Packaging User Guide: Creating and using virtual environments) closer to the top, perhaps under the pep reference, would be helpful for the user.

Virtual environments are confusing for those new to Python since there are many "env"s such as venv, pyvenv, virtualenv, virtualenvwrapper, pyenv tool, and myenv used in many examples.

Carol
msg244640 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-06-02 02:37
I think Graham's formulation provides more information.  venv already has a "new in python 3.3" at the top (just before that sentence), so putting that in the text feels redundant.

On the other hand, the current placement of the 'see also' box looks odd, unless the packaging authority doesn't mention virtual environments on Windows (and if it doesn't, it should!).  I agree that moving that up to just after the PEP reference is probably a good idea.
msg244642 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-06-02 02:41
David,

Sounds good to me. I'll submit a patch with Graham's suggested text and move the See also box up right after the PEP reference.

Thanks,
Carol
msg245062 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2015-06-09 13:24
See also the recent addition of a section on venv to the Tutorial section of the docs (Doc/tutorial/venv.rst, issue23891). The wording there and in the module docs should at least be consistent with each other.
History
Date User Action Args
2018-06-11 07:41:50taleinatsetnosy: - taleinat
2018-04-24 15:42:32Elena.Oatsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request6289
2018-03-26 15:57:26steven.downumsetnosy: + steven.downum
2018-03-25 16:55:14cheryl.sabellasetkeywords: + easy
stage: needs patch
type: enhancement
versions: + Python 3.7, Python 3.8, - Python 3.3
2015-06-09 13:24:58taleinatsetnosy: + taleinat
messages: + msg245062
2015-06-02 02:41:15willingcsetmessages: + msg244642
2015-06-02 02:37:47r.david.murraysetmessages: + msg244640
2015-06-02 02:30:31willingcsetnosy: + willingc
messages: + msg244639
2015-06-02 02:06:51Graham.Oliversetmessages: + msg244634
2015-06-02 01:18:15r.david.murraysetnosy: + r.david.murray
messages: + msg244631
2015-06-01 22:25:07Graham.Oliversetmessages: + msg244619
2015-06-01 22:21:33Graham.Olivercreate