Prefer "python" over "python3" for command line examples in docs.

[felixxm]

Documentation

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

Linked PRs

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

[AlexWaygood]

I agree it would be nice to be more consistent here.

Here's the results of `git grep "$ python"` in the `Doc/` directory:

extending/newtypes_tutorial.rst:   $ python setup.py build
howto/logging-cookbook.rst:    ~/logging-contextual-webapp$ python main.py
howto/logging-cookbook.rst:    $ python logctx.py
howto/logging-cookbook.rst:    $ python logctx.py 2>/dev/null
howto/logging-cookbook.rst:    $ python logctx.py >/dev/null
howto/logging-cookbook.rst:    $ python app.py start foo
howto/logging-cookbook.rst:    $ python app.py stop foo bar
howto/logging-cookbook.rst:    $ python app.py restart foo bar baz
howto/logging-cookbook.rst:    $ python app.py --log-level DEBUG start foo
howto/logging-cookbook.rst:    $ python app.py --log-level DEBUG stop foo bar
howto/logging-cookbook.rst:    $ python app.py --log-level DEBUG restart foo bar baz
howto/logging-cookbook.rst:    $ python app.py --log-level WARNING start foo
howto/logging-cookbook.rst:    $ python app.py --log-level WARNING stop foo bar
howto/logging-cookbook.rst:    $ python app.py --log-level WARNING restart foo bar baz
howto/logging.rst:    $ python simple_logging_module.py
howto/logging.rst:    $ python simple_logging_config.py
howto/perf_profiling.rst:    $ python -Xperf my_script.py
howto/perf_profiling.rst:    $ python -m sysconfig | grep 'no-omit-frame-pointer'
howto/unicode.rst:   $ python listdir-test.py
library/argparse.rst:   $ python prog.py -h
library/argparse.rst:   $ python prog.py 1 2 3 4
library/argparse.rst:   $ python prog.py 1 2 3 4 --sum
library/argparse.rst:   $ python prog.py a b c
library/argparse.rst:   $ python myprogram.py --help
library/argparse.rst:   $ python subdir/myprogram.py --help
library/argparse.rst:   $ python myprogram.py --help
library/doctest.rst:   $ python example.py
library/doctest.rst:   $ python example.py -v
library/importlib.metadata.rst:    (example) $ python -m pip install wheel
library/json.rst:      $ python -m json.tool mp_films.json
library/pickletools.rst:    $ python -m pickle x.pickle
library/pickletools.rst:    $ python -m pickletools x.pickle
library/shutil.rst:    $ python -m tarfile -l /Users/tarek/myarchive.tar
library/socketserver.rst:   $ python TCPServer.py
library/socketserver.rst:   $ python TCPClient.py hello world with TCP
library/socketserver.rst:   $ python TCPClient.py python is nice
library/socketserver.rst:   $ python ThreadedTCPServer.py
library/sysconfig.rst:    $ python -m sysconfig
library/tarfile.rst:    $ python -m tarfile -c monty.tar  spam.txt eggs.txt
library/tarfile.rst:    $ python -m tarfile -c monty.tar life-of-brian_1979/
library/tarfile.rst:    $ python -m tarfile -e monty.tar
library/tarfile.rst:    $ python -m tarfile -e monty.tar  other-dir/
library/tarfile.rst:    $ python -m tarfile -l monty.tar
library/timeit.rst:   $ python -m timeit -s 'text = "sample string"; char = "g"'  'char in text'
library/timeit.rst:   $ python -m timeit -s 'text = "sample string"; char = "g"'  'text.find(char)'
library/timeit.rst:   $ python -m timeit 'try:' '  str.__bool__' 'except AttributeError:' '  pass'
library/timeit.rst:   $ python -m timeit 'if hasattr(str, "__bool__"): pass'
library/timeit.rst:   $ python -m timeit 'try:' '  int.__bool__' 'except AttributeError:' '  pass'
library/timeit.rst:   $ python -m timeit 'if hasattr(int, "__bool__"): pass'
library/tokenize.rst:    $ python -m tokenize hello.py
library/tokenize.rst:    $ python -m tokenize -e hello.py
library/zipapp.rst:   $ python -m zipapp myapp -m "myapp:main"
library/zipapp.rst:   $ python myapp.pyz
library/zipapp.rst:   $ python -m zipapp source [options]
library/zipapp.rst:   $ python -m zipapp myapp
library/zipapp.rst:   $ python myapp.pyz
library/zipapp.rst:   $ python -m zipapp myapp -p "/usr/bin/env python"
library/zipapp.rst:      $ python -m pip install -r requirements.txt --target myapp
library/zipapp.rst:      $ python -m zipapp -p "interpreter" myapp
library/zipfile.rst:    $ python -m zipfile -c monty.zip spam.txt eggs.txt
library/zipfile.rst:    $ python -m zipfile -c monty.zip life-of-brian_1979/
library/zipfile.rst:    $ python -m zipfile -e monty.zip target-dir/
library/zipfile.rst:    $ python -m zipfile -l monty.zip
tutorial/modules.rst:   $ python fibo.py 50
tutorial/venv.rst:  (tutorial-env) $ python -m pip install novas
tutorial/venv.rst:  (tutorial-env) $ python -m pip install requests==2.6.0
tutorial/venv.rst:  (tutorial-env) $ python -m pip install --upgrade requests
tutorial/venv.rst:  (tutorial-env) $ python -m pip show requests
tutorial/venv.rst:  (tutorial-env) $ python -m pip list
tutorial/venv.rst:  (tutorial-env) $ python -m pip freeze > requirements.txt
tutorial/venv.rst:  (tutorial-env) $ python -m pip install -r requirements.txt
whatsnew/3.2.rst:    $ python -q
whatsnew/3.2.rst:      $ python -q -Wdefault
whatsnew/3.2.rst:    $ python -m unittest discover -s my_proj_dir -p _test.py
whatsnew/3.2.rst:    $ python -m site --user-base
whatsnew/3.2.rst:    $ python -m site --user-site
whatsnew/3.2.rst:    $ python -m turtledemo
whatsnew/3.3.rst:    $ python -q -X faulthandler
whatsnew/3.5.rst:    $ python -m zipapp myapp
whatsnew/3.5.rst:    $ python myapp.pyz
whatsnew/3.8.rst:    $ python -m asyncio

Here's the results of `git grep "$ python3"` in the `Doc/` directory:

howto/argparse.rst:   $ python3 prog.py
howto/argparse.rst:   $ python3 prog.py --help
howto/argparse.rst:   $ python3 prog.py --verbose
howto/argparse.rst:   $ python3 prog.py foo
howto/argparse.rst:   $ python3 prog.py
howto/argparse.rst:   $ python3 prog.py --help
howto/argparse.rst:   $ python3 prog.py foo
howto/argparse.rst:   $ python3 prog.py -h
howto/argparse.rst:   $ python3 prog.py 4
howto/argparse.rst:   $ python3 prog.py 4
howto/argparse.rst:   $ python3 prog.py four
howto/argparse.rst:   $ python3 prog.py --verbosity 1
howto/argparse.rst:   $ python3 prog.py
howto/argparse.rst:   $ python3 prog.py --help
howto/argparse.rst:   $ python3 prog.py --verbosity
howto/argparse.rst:   $ python3 prog.py --verbose
howto/argparse.rst:   $ python3 prog.py --verbose 1
howto/argparse.rst:   $ python3 prog.py --help
howto/argparse.rst:   $ python3 prog.py -v
howto/argparse.rst:   $ python3 prog.py --help
howto/argparse.rst:   $ python3 prog.py
howto/argparse.rst:   $ python3 prog.py 4
howto/argparse.rst:   $ python3 prog.py 4 --verbose
howto/argparse.rst:   $ python3 prog.py --verbose 4
howto/argparse.rst:   $ python3 prog.py 4
howto/argparse.rst:   $ python3 prog.py 4 -v
howto/argparse.rst:   $ python3 prog.py 4 -v 1
howto/argparse.rst:   $ python3 prog.py 4 -v 2
howto/argparse.rst:   $ python3 prog.py 4 -v 3
howto/argparse.rst:   $ python3 prog.py 4 -v 3
howto/argparse.rst:   $ python3 prog.py 4 -h
howto/argparse.rst:   $ python3 prog.py 4
howto/argparse.rst:   $ python3 prog.py 4 -v
howto/argparse.rst:   $ python3 prog.py 4 -vv
howto/argparse.rst:   $ python3 prog.py 4 --verbosity --verbosity
howto/argparse.rst:   $ python3 prog.py 4 -v 1
howto/argparse.rst:   $ python3 prog.py 4 -h
howto/argparse.rst:   $ python3 prog.py 4 -vvv
howto/argparse.rst:   $ python3 prog.py 4 -vvv
howto/argparse.rst:   $ python3 prog.py 4 -vvvv
howto/argparse.rst:   $ python3 prog.py 4
howto/argparse.rst:   $ python3 prog.py 4
howto/argparse.rst:   $ python3 prog.py
howto/argparse.rst:   $ python3 prog.py -h
howto/argparse.rst:   $ python3 prog.py 4 2 -v
howto/argparse.rst:   $ python3 prog.py 4 2
howto/argparse.rst:   $ python3 prog.py 4 2 -v
howto/argparse.rst:   $ python3 prog.py 4 2 -vv
howto/argparse.rst:   $ python3 prog.py 4 2
howto/argparse.rst:   $ python3 prog.py 4 2 -q
howto/argparse.rst:   $ python3 prog.py 4 2 -v
howto/argparse.rst:   $ python3 prog.py 4 2 -vq
howto/argparse.rst:   $ python3 prog.py 4 2 -v --quiet
howto/argparse.rst:   $ python3 prog.py --help
howto/clinic.rst:    $ python3 Tools/clinic/clinic.py foo.c
howto/unicode.rst:    $ python3 compare-strs.py
library/__main__.rst:       $ python3 helloworld.py
library/__main__.rst:       $ python3 -m tarfile
library/__main__.rst:       $ python3 -c "import this"
library/__main__.rst:   $ python3 -m bandclass
library/__main__.rst:   $ python3 start.py
library/__main__.rst:   $ python3 start.py
library/devmode.rst:    $ python3 script.py README.txt
library/devmode.rst:    $ python3 -X dev script.py README.txt
library/devmode.rst:    $ python3 -X dev -X tracemalloc=5 script.py README.rst
library/devmode.rst:    $ python3 script.py
library/devmode.rst:    $ python3 script.py
library/faulthandler.rst:    $ python3 -c "import ctypes; ctypes.string_at(0)"
library/faulthandler.rst:    $ python3 -q -X faulthandler
library/importlib.metadata.rst:    $ python3 -m venv example
library/site.rst:   $ python3 -m site --user-site
library/timeit.rst:   $ python3 -m timeit '"-".join(str(n) for n in range(100))'
library/timeit.rst:   $ python3 -m timeit '"-".join([str(n) for n in range(100)])'
library/timeit.rst:   $ python3 -m timeit '"-".join(map(str, range(100)))'

In particular, it's pretty strange that the argparse reference doc uses python very consistently, while the argparse HOWTO uses python3 very consistently.

[sc68cal]

Homebrew still installs and links python as python3. Ubuntu 20.04 LTS (at least via Windows Subsystem for Linux) does not have a python binary, but instead has python3. So, I think the issue is that until the OS distros start consistently installing python3.x interpreters as python in $PATH, we will have this issue. I think this means maybe everything needs to be explicitly python3 until that happens? Until we then have to change it back?

The referenced PEP says

The python command should always invoke Python 2 (to prevent hard-to-diagnose errors when Python 2 code is run on Python 3).

Which argues that it should be python3 - although that's not to say things haven't changed since the PEP was written.

[AlexWaygood]

I'm removing the "easy" label since we already have a PR here, it just needs to be reviewed :)

[hugovk]

See issue #100972 and PR #100973 for more.

[rhettinger]

On my Mac, python no longer refers to an executable. Only python3 works. So, at least for Mac Users, the status quo is better. With the proposed substitutions, the examples won't work any more.