devguide
devguide copied to clipboard
python
python or python3 in the documentation
Hi,
Sometimes, I can read python or python3 in the documentation and in the devguide.
Maybe we could take a decision and indicate which term we should use for the documentation.
For me, just my humble opinion, we should use python, because:
-
pythonis the name of the binary when we compile Python - name of the executable when we use a
venv - starts to become the default name of Python 3 in the majority of the distributions
- for Python 2, there is python2 with some distributions.
- python.exe on Windows
I agree with the conclusion, but not entirely with the rationale. As per https://www.python.org/dev/peps/pep-0394/ an unqualified "python" still refers to the system Python 2 installation in most Linux installations.
What's changed is that folks are being more strongly encouraged to not use the system Python installation directly unless they're specifically scripting the operating system, or working on an operating system component.
So python3 is only the correct command when folks are working in a way that we don't generally recommend, and the folks that have a good reason for ignoring that default recommendation will also know to make the python -> python3 adjustment.
On Windows, there is only 'python', so use of 'python3' would have to be qualified.
@terryjreedy just updated the description of my issue with python.exe on Windows
@ncoghlan thanks for your explanation
on cpython/master, about python -m, we have 43 references and for python3 -m , only 7.
on devguide/master, python -m -> 7 references, python3 -m -> 0 references.
in this case, we could change the 7 references of python3 -m in cpython/master.
do you agree?
Do you not like the situation on Windows? There is no system python (too bad, in a way). A single version can be run with 'py'. Multiple versions are run with 'py -2', 'py -3', with 'py' then defaulting to 'py -3'.
@terryjreedy I don't use Python on Windows and Windows and in this case, your feedback is really important. I just want to find a good solution for this issue with python or python3 in the documentation.
I was implying that general docs should use 'python' consistently. At some place, say that we are using 'python' generically, and that 'python' may be replaced by OS-specific terms, as given in OS sections of Python Setup and Usage. (There may even by distribution specifics.) Have system experts check that specifics and recommendations are up to date. (For instance, Windows 'py' once defaulted to 'py -2' instead of 'py -3'.)
It's also true on the Linux distros that /usr/bin has the more qualified python3.5 or python3.6 binaries too, and those are sometimes the preferred way of invoking scripts.
Several concepts have long been conflated, so it may be worth teasing them out. There are the shebang lines (on *nix) which for system scripts should point to a system Python, but for user scripts would point to a "user Python". Often the shebang lines use /usr/bin/env python or some such so that the user's $PATH gets involved. This is a bad idea for system scripts.
Then there's the thing we use at the CLI to invoke the REPL. On *nix that's always going to invoke the $PATH. It's what we want to tell people to run if they want to start typing interactive Python. What this thing is called depends on their operating system, any active virtualenvs, etc.
The second thing may also be what they call to run a script that isn't shebanged, e.g. python foo.py.
I think that the devguide should largely describe the user interface for the CLI, i.e. what folks sitting at a shell prompt would type. Not that that gives a lot of clarity ;). But we need a separate discussion about what to shebang scripts on *nix, and what the system Python should be called.
I agree, the docs should consistently use python. Operating systems and users may have different details, but in the abstract the Python interpreter is started using the python command. Operating system specific documentation (and/or "Python Setup and Usage") can provide the details, but the convention outside of those documents should be to use python.
The Windows section of "Python Setup and Usage" goes into some detail about setting PATH and/or using the launcher, but the Unix section seems pretty limited in this respect. Maybe that section should be expanded to give an overview of the versioned commands, why distributions typically have python and python3, etc?
https://docs.python.org/3/installing/#installing-into-the-system-python-on-linux should continue to use python3 in the appropriate location, but other than that I'd expected us to be using the generic python.
As we near End of Life for Python 2, it will be important to clarify terms in the devguide and point out where existing docs may differ from these and why.
With my distro maintainer hat on: If the docs use python everywhere, I think it would be a disservice to users if python was not the latest available stable version. But PEP 394 says it should be Python 2 (or missing) :(
Users don't read docs in order. Mentioning it in place solves nothing.
What's changed is that folks are being more strongly encouraged to not use the system Python installation directly unless they're specifically scripting the operating system, or working on an operating system component.
I disagree.
When you pip install a package, you should do that in a venv (and you can use python inside a venv, but need a proper command to create it). But if the included batteries are enough, system Python (if there is one) should be perfectly fine.
I'm going to close this devguide issue since there is not consensus and usage varies based on "how" and "where" Python is being used.