gh-98763: Prefer "python" over "python3" for command line examples in docs.

[felixxm]

Currently docs are not consistent in using python vs. python3 for command line examples. As far as I'm aware, we should prefer python, see https://peps.python.org/pep-0394/#for-end-users-of-python

I can create a new issue, if required for such cleanup.

• Issue: Prefer "python" over "python3" for command line examples in docs. #98763

[AlexWaygood]

Thanks! We generally create issues for everything except the most trivial changes, to ensure visibility -- would you mind creating an issue for this?

[felixxm]

Thanks! We generally create issues for everything except the most trivial changes, to ensure visibility -- would you mind creating an issue for this?

Created 👍

[hauntsaninja]

Thank you!

I'm in favour of merging, given:

• the https://peps.python.org/pep-0394/#for-end-users-of-python section that you link
• the fact that three years on, Python 2 is finally mostly dead
• that any eventual Python 4 is unlikely to break any of these examples

cc @JelleZijlstra

[JelleZijlstra]

I agree but it's probably good to get some more opinions. @warsaw as one of the authors of PEP 394, what do you think?

[warsaw]

Gah! GH lost the long comment I was composing.

I think it's worth revisiting PEP 394 in light of Python 2's EOL, but I am not involved in distro maintenance these days. @doko42 and @encukou might have relevant input here. On modern macOS, there's no python command and Homebrew doesn't install it, so the documentation will be broken for some folks. If it didn't touch so many files, I'd recommend including a note that these examples are only guaranteed to work in a virtualenv and if they don't work, try substituting python3 for python. Then there's also the py launcher to consider (@brettcannon).

3 years on, I think it's time to reclaim python for Python 3. Python 4 is still vaporware (wishware?) so I wouldn't worry about it.

[felixxm]

Then there's also the py launcher to consider (@brettcannon).

In Django docs, we have a custom extension for the console directive which renders two-tab code blocks, 1st for Linux/MacOs with $ python, and the 2nd for Windows with ...\> py (see an example page):

I could prepare a similar solution for Python docs and the shell-session directive.

[warsaw]

@felixxm That's nice, although the distinction between the tab labels may not always be correct (i.e. install py in Homebrew and it'll work on macOS, but also python doesn't work out of the box on standard macOS, afaict).

[brettcannon]

python doesn't work out of the box on standard macOS, afaict

Apple dropped Python from the macOS install, so the closest you get to Python being automatically installed now on an OS is some Linux distros and Windows and it's python3 shim (I don't know if it also covers python).

[AlexWaygood]

Windows and it's python3 shim (I don't know if it also covers python).

As a Windows user, I'd personally much prefer "python" in the docs to "python3". I tried installing it from the Windows Store once, and it didn't work (can't remember why not, I don't think I ever dug too deeply). Since then I've always installed it from python.org because, well, it's never not worked.

Unfortunately, because I installed it from python.org rather than the Windows Store, python3 on the command line takes me straight to the Windows Store every time rather than executing Python. python, on the other hand, works every time.

[encukou]

I can't speak for all Linux distros, let alone other platforms, but as far as I know it'd be best to follow the ”For end users of Python” section of PEP 394:

While far from being universally available, python remains the preferred spelling for explicitly invoking Python.

While a lot of the PEP's reasoning is outdated nowadays, I think the actual recommendations have aged pretty well.

[warsaw]

@encukou Does that mean that the modern Fedora ecosystem provides python executable that invokes Python 3?

(I haven't been a user or contributor to Debuntu in years so I haven't kept up.)

[encukou]

@encukou Does that mean that the modern Fedora ecosystem provides python executable that invokes Python 3?

Yes. Back in 2019 we updated PEP 394 so we could do that :)

The “unversioned” python command is packaged separately, so it's not present in some environments (like minimal / non-Python containers). But even there, dnf install python or dnf install /usr/bin/python will install a 3.x python command.
(Python 2 is still available, because Gimp needs it, but that's always explicitly named python2.)

[felixxm]

As far as I'm aware, we reached a consensus to use python for command line examples 🥳 Thanks to everyone 🥇

[kumaraditya303]

LGTM, time to get this in!