classification
Title: venv documentation doesn't tell you how to specify a particular version of python
Type: behavior Stage: resolved
Components: Distutils, Documentation Versions: Python 3.7, Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: brett.cannon Nosy List: Mariatta, brett.cannon, docs@python, dstufft, eric.araujo, lac, matrixise, python-dev, r.david.murray, serhiy.storchaka, zach.ware
Priority: normal Keywords: patch

Created on 2015-09-17 14:13 by lac, last changed 2016-10-28 17:57 by zach.ware. This issue is now closed.

Files
File name Uploaded Description Edit
issue25152.patch Mariatta, 2016-10-23 15:42 review
Messages (17)
msg250891 - (view) Author: Laura Creighton (lac) Date: 2015-09-17 14:13
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).
msg250892 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-09-17 14:24
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).
msg250896 - (view) Author: Laura Creighton (lac) Date: 2015-09-17 16:36
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.
msg250897 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-09-17 16:40
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.
msg250899 - (view) Author: Laura Creighton (lac) Date: 2015-09-17 16:51
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.
msg250902 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2015-09-17 17:28
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.
msg250906 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-09-17 17:55
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).
msg250907 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2015-09-17 18:14
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.
msg250908 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2015-09-17 18:16
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.
msg278380 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-10-09 17:27
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.
msg279148 - (view) Author: Roundup Robot (python-dev) Date: 2016-10-21 19:54
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
msg279263 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-10-23 14:42
http://buildbot.python.org/all/builders/Docs%203.x/builds/2710/steps/lint/logs/stdio
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
msg279266 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2016-10-23 15:42
> [2] library/venv.rst:27: default role used
> 1 problem with severity 2 found.

I made a patch to address it. Please review. Thanks :)
msg279267 - (view) Author: St├ęphane Wirtel (matrixise) * Date: 2016-10-23 16:01
we can merge the patch of Mariatta
msg279318 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2016-10-24 16:31
Thanks, St├ęphane :)
Perhaps this can be updated into patch review stage?
msg279619 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-10-28 17:26
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.
msg279621 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2016-10-28 17:57
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!
History
Date User Action Args
2016-10-28 17:57:44zach.waresetnosy: + zach.ware
messages: + msg279621
2016-10-28 17:26:33brett.cannonsetstatus: open -> closed

messages: + msg279619
stage: commit review -> resolved
2016-10-24 16:31:50Mariattasetmessages: + msg279318
2016-10-23 16:01:24matrixisesetnosy: + matrixise

messages: + msg279267
stage: resolved -> commit review
2016-10-23 15:42:03Mariattasetfiles: + issue25152.patch

nosy: + Mariatta
messages: + msg279266

keywords: + patch
2016-10-23 14:42:10serhiy.storchakasetstatus: closed -> open
nosy: + serhiy.storchaka
messages: + msg279263

2016-10-21 19:55:29brett.cannonsetstatus: open -> closed
resolution: fixed
stage: needs patch -> resolved
2016-10-21 19:54:41python-devsetnosy: + python-dev
messages: + msg279148
2016-10-14 19:54:49brett.cannonsetassignee: docs@python -> brett.cannon
2016-10-09 17:27:34r.david.murraysettype: behavior
stage: needs patch
messages: + msg278380
versions: + Python 3.7, - Python 3.4
2015-09-17 18:16:04brett.cannonsetmessages: + msg250908
2015-09-17 18:14:12brett.cannonsetmessages: + msg250907
2015-09-17 17:55:57r.david.murraysetmessages: + msg250906
2015-09-17 17:28:07brett.cannonsetnosy: + brett.cannon
messages: + msg250902
2015-09-17 16:51:34lacsetmessages: + msg250899
2015-09-17 16:40:02r.david.murraysetmessages: + msg250897
2015-09-17 16:36:15lacsetmessages: + msg250896
2015-09-17 14:24:38r.david.murraysetnosy: + r.david.murray

messages: + msg250892
versions: - Python 3.3
2015-09-17 14:13:32laccreate