Usage of venv specifies a python3 command not found in 3.11.2 on Windows

[Liturgist]

Documentation

The documentation on using venv at https://docs.python.org/3/library/venv.html for 3.11.2 specifies to use a python3 executable.

I do not find a python3 executable in the 3.11.2 installation for Windows 64-bit.

Linked PRs

• gh-102354: change python3 to python in docs examples #102696
• [3.11] gh-102354: change python3 to python in docs examples (GH-102696) #102697
• [3.10] gh-102354: change python3 to python in docs examples (GH-102696) #102698

[carljm]

A few lines later there are specific instructions for Windows:

On Windows, invoke the venv command as follows:

c:\>c:\Python35\python -m venv c:\path\to\myenv

Alternatively, if you configured the PATH and PATHEXT variables for your [Python installation] (https://docs.python.org/3/using/windows.html#using-on-windows):

c:\>python -m venv c:\path\to\myenv

Grepping the entire Doc/ directory, I see 156 occurrences of python -m and only 8 of python3 -m, so it seems like python -m is much more common in our documentation, despite the fact that a make install of Python 3 on most platforms doesn't install a python binary at all. So I'm not clear what the docs should prefer or standardize on here.

[Liturgist]

@carljm, yes, I see the later instructions for Windows. But, python3 -m... is the first example and it does not specify a platform.

If python -m... works on all platforms, perhaps that should be used.

[carljm]

python -m ... does not work on all platforms, unless you are in a venv, or your distro or someone else has decided to link python to python3. Just building and installing python on POSIX installs only bin/python3, there's no python.

I feel sure this is something that has been discussed before; I'll see if I can find out what the thinking has been.

[carljm]

Looks like the conclusion in #98761 was that python -m ... should be preferred in the docs. So @Liturgist, if you are interested in making a pull request to convert the few cases of python3 -m ... to python -m ... (including this one), it looks like that would be appropriate.

See also #102358 for providing bin/python in make install, so we are more consistent in our preference for python -m ....

[Liturgist]

@carljm, here are the mentions of python 3 -m I find. It would appear that this specific issue is about ./using/venv-create.inc. Is that the only change to be made? Should others be considered. Is this issue, #102354, the one to fix?

PS C:\src\cpython\Doc> dir -File -Recurse * | %{sls 'python3 -m' $_}

Makefile:157:           $(VENVDIR)/bin/python3 -m pip install -U pip setuptools; \
Makefile:158:           $(VENVDIR)/bin/python3 -m pip install -r requirements.txt; \
library\__main__.rst:262:   block. You can invoke it with ``python3 -m venv [directory]``.
library\importlib.metadata.rst:76:    $ python3 -m venv example
library\pdb.rst:61:   python3 -m pdb myscript.py
library\pdb.rst:75:   ``python3 -m`` does. As with a script, the debugger will pause execution just
tutorial\venv.rst:47:   python3 -m venv tutorial-env
using\venv-create.inc:4:    python3 -m venv /path/to/new/virtual/environment
whatsnew\3.10.rst:1542:  The ``python3 -m module-name`` command startup time is 1.4x faster in
whatsnew\3.6.rst:2060:The ``pyvenv`` script has been deprecated in favour of ``python3 -m venv``.

[carljm]

I think it makes sense to be consistent in our usage in the docs, so I think it would be fine to update all of the cases (other than the Makefile.) And yes, you can use this issue.

[Liturgist]

@carljm, I think I have made the changes and created a PR. Please let me know of anything I may have not done or done incorrectly.