classification
Title: Use the py launcher in venv Windows examples
Type: enhancement Stage:
Components: Documentation, Windows Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mariatta, docs@python, eryksun, ned.deily, paul.moore, pwatson, steve.dower, terry.reedy, tim.golden, zach.ware
Priority: normal Keywords:

Created on 2018-01-15 02:08 by pwatson, last changed 2021-03-17 05:18 by eryksun.

Messages (11)
msg309943 - (view) Author: Paul Watson (pwatson) Date: 2018-01-15 02:08
The 3.6.4 documentation on venv specifies using 'python3', but no python3 executable is in the 3.6.4 kit.

https://docs.python.org/3/library/venv.html?highlight=venv#module-venv
msg309949 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2018-01-15 05:26
People who has more than one Python versions installed will have python3.
msg310000 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-01-15 17:04
Unfortunately, it may depend on what environment and/or from which distributor you obtain Python 3.6 as to whether there is a "python3" link installed.  On Unix-like systems, the default Python installation built from source ("make install") does install both "python3.6" and "python3" links in the configured "bin" directory.  But that may not be true everywhere.  On what environment are you running Python 3.6 and from where was it installed?
msg310001 - (view) Author: Paul Watson (pwatson) Date: 2018-01-15 17:08
I am running 3.6.4 from a download on pythong.org yesterday.

Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:54:40) [MSC v.1900 64 bit (AMD64)] on win32

There is a python3.dll, but no python3 executable.
msg310002 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-01-15 17:09
Thanks! Pinging the Windows team.
msg310004 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2018-01-15 17:41
Actually, for Windows, the docs don't recommend "python3", they say:

"""
On Windows, invoke the venv command as follows:

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

This should probably be altered to say "py -m venv" (or maybe "py -3 -m venv", but I don't think that's really necessary), as using the launcher is less tied to having your PATH set, or using an explicit path.
msg310015 - (view) Author: Paul Watson (pwatson) Date: 2018-01-15 20:58
Ok, I do find later on where it says to do something different on Windows. However, the first "Note" box in "28.3. venv" specifies using "python3". It does not say that this is for non-Windows systems. This should be changed.

Also, the path specified, "c:\Python35\python", would not be the default location for a Windows install. "C:\Program Files\Python36\python" or "C:\Program Files (x86)\Python36\python" should be specified.

I detest that it is this complex and verbose, but it is. Glossing over it does not help the user.
msg310024 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2018-01-15 23:20
That's why I suggest using the launcher rather than absolute paths - there are far too many variations to enumerate with absolue paths (you didn't mention per-user Python 3.6 installations, for example).

If you have a suggested wording that you feel would explain things better, feel free to propose it. What's there at the moment seems relatively OK to me (aside from a minor tweak to use the launcher) so I'm not sure I could modify it in a way that would address your concerns.
msg310028 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2018-01-15 23:55
`PATHEXT` is irrelevant here, so that should be removed. As to the py launcher, it's optional and not always installed for all users, though that's the default. I'd prefer `python` that's found in PATH as the first example. Then add another example with `py -X.Y` to show how to create virtual environments for other versions.
msg310057 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2018-01-16 09:11
Agreed, the docs don't need to mention PATHEXT.

I don't have a machine to hand with Python 3.6 not installed, to check, but I believe the launcher is installed by default (although as you say it can be deselected - and it's definitely described as "recommended") whereas adding Python to PATH is deselected by default. So "py" is more likely to work on a typical installation than "python".

As I say, though, I have no feel here for the right level of detail. Maybe something like

"""
To execute the venv command, use

    python -m venv

Unix installations typically name the Python 3.x executable "python3", and on Windows the "py" launcher is generally available even if the Python interpreter is not on your PATH, so you may need to substitute the appropriate means of invoking Python in place of the "python" command above.
"""

But that's (to my mind) still wordy and complex - and the new users I've spoken to already find the docs too full of confusing detail.

Ideally, I'd prefer it if "Invoking Python" were described once and for all in a separate section of the docs (i.e., the "Python Setup and Usage" manual) and everywhere else in the official documentation we simply used "python", with no qualifications, on the understanding that this stands for "whatever you use on your PC to run Python". I suspect that would generate complaints from a lot of people, though, as most people hit the doc pages via direct links, not by reading the manuals in order...
msg310285 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-01-19 19:56
As far as I know, Windows binaries have only been named python.exe or pythonw.exe.  Before 3.5, I believe, "C:\Pythonxy", where x,y were major,minor, *was* the default Windows installation directory.  'Python35' must have been the result of a mechanical update.
History
Date User Action Args
2021-03-17 05:18:38eryksunsettitle: venv says to use python3 which does not exist in 3.6.4 -> Use the py launcher in venv Windows examples
versions: + Python 3.8, Python 3.9, Python 3.10, - Python 3.6
2018-01-19 19:56:08terry.reedysetnosy: + terry.reedy
messages: + msg310285
2018-01-16 09:11:12paul.mooresetmessages: + msg310057
2018-01-15 23:55:43eryksunsetnosy: + eryksun
messages: + msg310028
2018-01-15 23:20:02paul.mooresetmessages: + msg310024
2018-01-15 20:58:38pwatsonsetmessages: + msg310015
2018-01-15 17:41:44paul.mooresetmessages: + msg310004
2018-01-15 17:09:51ned.deilysetmessages: + msg310002
2018-01-15 17:09:20ned.deilysetnosy: + paul.moore, tim.golden, zach.ware, steve.dower
components: + Windows
2018-01-15 17:08:43pwatsonsetmessages: + msg310001
2018-01-15 17:04:47ned.deilysetnosy: + ned.deily
messages: + msg310000
2018-01-15 05:26:41Mariattasetnosy: + Mariatta
messages: + msg309949
2018-01-15 02:08:16pwatsoncreate