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).

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).

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.

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.

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.

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.

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).

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.

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.

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.

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

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

> [2] library/venv.rst:27: default role used
> 1 problem with severity 2 found.

I made a patch to address it. Please review. Thanks :)

we can merge the patch of Mariatta

Thanks, Stéphane :)
Perhaps this can be updated into patch review stage?

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.

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!