[issue25152] venv documentation doesn't tell you how to specify a particular version of python
New submission from Laura Creighton: https://docs.python.org/3/library/venv.html nowhere explicitly states how you are supposed to get a venv with a particular python version. Users of virtualenv will be looking for a -p option. The doc says: "Creation of virtual environments is done by executing the pyvenv script:" which undoubtably works if you _have_ a pyenv script, but I don't have one. It is nowhere stated where I should find one. Fortunately, I can also run things as some_python_version -m venv myvenv This, everybody is able to do. (However, it may not work, see issue 25151 -- but forget that for now.) This is something that everybody ought to be able to do. Thus I propose either deleting the mention of pyenv, (if it is exactly equivalent to running python -m venv) or expanding the section, indicating where the script lives, and why you might want to run it instead of python -m venv. Then, before the line: The command, if run with -h, will show the available options: add the line: The version of python used in the venv is determined at this time. If the default version of python is not the one desired, use: /path/to/the/python/I/want -m venv myenv instead. (Plus, if there is a way to do this with pyenv, then list that part here). ---------- assignee: docs@python components: Distutils, Documentation messages: 250891 nosy: docs@python, dstufft, eric.araujo, lac priority: normal severity: normal status: open title: venv documentation doesn't tell you how to specify a particular version of python versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
R. David Murray added the comment: Our documentation describes what you get if you install Python using our distribution of python. If you do that, you (by default) get a pyvenv script, and it points to the version of python that you just (last) installed. Distributions change this. We can't document what every distribution does. That said, I think it would be a good idea to move the description of calling it via 'python -m venv' to be the *first* mention, and *then* describing pyvenv (and noting that it is installed by our installers but a vendor install may do something different, including omit it). ---------- nosy: +r.david.murray versions: -Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Laura Creighton added the comment: On thinking things over, I think that venv is, as it stands now, only able to work with python3.3 and greater. If you want to build a virtualenv for python 2.7, then I think venv is not for you. I think this needs to be mentioned. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
R. David Murray added the comment: Not in the python3 docs, it doesn't. The python3 docs are documenting python3. But, this is another reason the -m venv description should be first, to make it clear it is *part* of the python version, not a standalone package that might work with multiple python versions. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Laura Creighton added the comment: The problem is that people who run into venv will think that it is virtualenv made into part of the standard library. Thus they will have a great expectation that there will be a -p option to specify the python version that they want and that they can get 2.7. As Josh Billings (American humourist) wrote: "It ain't ignorance causes so much trouble; it's folks knowing so much that ain't so." A 'this is not virtualenv' message would be useful. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Brett Cannon added the comment: Maybe we should consider dropping the generic pyvenv script or at least only install it with a full version suffix like pyvenv3.6 to prevent this kind of confusion (I have this issue all the time with pip and it drives me nuts). At the very minimum we should do as David suggests and bump up the `python -m` suggestion up as the first one. ---------- nosy: +brett.cannon _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
R. David Murray added the comment: I was surprised myself that pyvenv wasn't at least named pyvenv3. I think I've only ever used it once, mostly I use the -m because then I *know* what version of python I'm getting. I'd be in favor of dropping the script except that that would be a backward compatibility break. (Gentoo at least would probably recreate it so that 'pyvenv' continued to work no matter which version of python you had selected as your system default). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Brett Cannon added the comment: It would break backwards-compatibility, but the fix is to simply switch to `python3 -m venv` which still gives you the same semantics of using the newest Python 3 installation you have so the work to change is minimal. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Brett Cannon added the comment: Actually, I like the idea of dropping pyvenv enough that I'm going to create an issue for it and bring it up on python-dev. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
R. David Murray added the comment: Issue 25154 has deprecated pyvenv in 3.6. The docs, however, still need updating. The updated docs should mention pyvenv only to say that it is deprecated, I think. This change could be applied to 3.5 if we get it in before 3.5 final. ---------- stage: -> needs patch type: -> behavior versions: +Python 3.7 -Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Changes by Brett Cannon <brett@python.org>: ---------- assignee: docs@python -> brett.cannon _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Roundup Robot added the comment: New changeset 9feff7ba89b2 by Brett Cannon in branch '3.5': Issue #25152: Mention the deprecation of pyvenv https://hg.python.org/cpython/rev/9feff7ba89b2 New changeset 126ff1f3b6cd by Brett Cannon in branch '3.6': Merge (issue #25152) https://hg.python.org/cpython/rev/126ff1f3b6cd New changeset 53bee4ef1d0a by Brett Cannon in branch 'default': Merge (issue #25152) https://hg.python.org/cpython/rev/53bee4ef1d0a ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Changes by Brett Cannon <brett@python.org>: ---------- resolution: -> fixed stage: needs patch -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Serhiy Storchaka added the comment: http://buildbot.python.org/all/builders/Docs%203.x/builds/2710/steps/lint/lo... python3 tools/rstlint.py -i tools -i venv [2] library/venv.rst:27: default role used 1 problem with severity 2 found. Makefile:156: recipe for target 'check' failed ---------- nosy: +serhiy.storchaka status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Mariatta Wijaya added the comment:
[2] library/venv.rst:27: default role used 1 problem with severity 2 found.
I made a patch to address it. Please review. Thanks :) ---------- keywords: +patch nosy: +Mariatta Added file: http://bugs.python.org/file45196/issue25152.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Stéphane Wirtel added the comment: we can merge the patch of Mariatta ---------- nosy: +matrixise stage: resolved -> commit review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Mariatta Wijaya added the comment: Thanks, Stéphane :) Perhaps this can be updated into patch review stage? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Brett Cannon added the comment: It looks like Zachary beat me to fixing this: https://hg.python.org/cpython/rev/5d1934c27137. Thanks for the patch, Mariatta, even if Zachary didn't use it. ---------- stage: commit review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
Zachary Ware added the comment: Ah ha, I thought I'd seen it mentioned in an issue somewhere, but I didn't go looking when I noticed my Docs bots were all red. Thanks for the patch anyway, Mariatta! ---------- nosy: +zach.ware _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________
participants (8)
-
Brett Cannon -
Laura Creighton
-
Mariatta Wijaya
-
R. David Murray
-
Roundup Robot
-
Serhiy Storchaka
-
Stéphane Wirtel
-
Zachary Ware