Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
felixxm opened this issue Oct 27, 2022 · 6 comments
Open

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

felixxm opened this issue Oct 27, 2022 · 6 comments
Labels
docs Documentation in the Doc dir

Comments

@felixxm
Copy link
Contributor

felixxm commented Oct 27, 2022 •
edited by bedevere-bot

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

Tasks

No tasks being tracked yet.

Linked PRs
@felixxm felixxm added the docs Documentation in the Doc dir label Oct 27, 2022
felixxm added a commit to felixxm/cpython that referenced this issue Oct 27, 2022
@felixxm
pythongh-98763: Prefer "python" over "python3" for command line examp…
81e0988 
…les in docs.

See https://peps.python.org/pep-0394/#for-end-users-of-python
@bedevere-bot bedevere-bot mentioned this issue Oct 27, 2022
Merged
@AlexWaygood
Copy link
Member

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
Copy link

sc68cal commented Nov 20, 2022 •
edited

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.

@hugovk hugovk added the easy label Nov 20, 2022
@AlexWaygood
Copy link
Member

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

@AlexWaygood AlexWaygood removed the easy label Nov 20, 2022
felixxm added a commit to felixxm/cpython that referenced this issue Jan 3, 2023
@felixxm
pythongh-98763: Prefer "python" over "python3" for command line examp…
cb27624 
…les in docs.

See https://peps.python.org/pep-0394/#for-end-users-of-python
felixxm added a commit to felixxm/cpython that referenced this issue Jan 11, 2023
@felixxm
pythongh-98763: Prefer "python" over "python3" for command line examp…
d89202c 
…les in docs.

See https://peps.python.org/pep-0394/#for-end-users-of-python
kumaraditya303 pushed a commit that referenced this issue Jan 11, 2023
@felixxm
gh-98763: Prefer "python" over "python3" for command line examples in…
847d770 
… docs. (#98761)
@hugovk hugovk mentioned this issue Jan 12, 2023
Open
@hugovk
Copy link
Member

hugovk commented Jan 12, 2023

See issue #100972 and PR #100973 for more.

@rhettinger
Copy link
Contributor

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.

@rhettinger rhettinger reopened this Jan 14, 2023
@AlexWaygood
Copy link
Member

AlexWaygood commented Jan 14, 2023 •
edited

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.

On my Windows machine, only python works. python3 takes me to a page on the Windows Store inviting me to download Python (I obviously have it downloaded, but downloaded it from python.org instead of the Windows Store).

I think it's unlikely that there's anything that works for everybody, sadly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@sc68cal @hugovk @rhettinger @felixxm @kumaraditya303 @AlexWaygood