Skip to content

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

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Jan 11, 2023
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 54 additions & 54 deletions Doc/howto/argparse.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,16 +79,16 @@ Following is a result of running the code:

.. code-block:: shell-session

$ python3 prog.py
$ python3 prog.py --help
$ python prog.py
$ python prog.py --help
usage: prog.py [-h]

options:
-h, --help show this help message and exit
$ python3 prog.py --verbose
$ python prog.py --verbose
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --verbose
$ python3 prog.py foo
$ python prog.py foo
usage: prog.py [-h]
prog.py: error: unrecognized arguments: foo

Expand Down Expand Up @@ -121,18 +121,18 @@ And running the code:

.. code-block:: shell-session

$ python3 prog.py
$ python prog.py
usage: prog.py [-h] echo
prog.py: error: the following arguments are required: echo
$ python3 prog.py --help
$ python prog.py --help
usage: prog.py [-h] echo

positional arguments:
echo

options:
-h, --help show this help message and exit
$ python3 prog.py foo
$ python prog.py foo
foo

Here is what's happening:
Expand Down Expand Up @@ -166,7 +166,7 @@ And we get:

.. code-block:: shell-session

$ python3 prog.py -h
$ python prog.py -h
usage: prog.py [-h] echo

positional arguments:
Expand All @@ -187,7 +187,7 @@ Following is a result of running the code:

.. code-block:: shell-session

$ python3 prog.py 4
$ python prog.py 4
Traceback (most recent call last):
File "prog.py", line 5, in <module>
print(args.square**2)
Expand All @@ -208,9 +208,9 @@ Following is a result of running the code:

.. code-block:: shell-session

$ python3 prog.py 4
$ python prog.py 4
16
$ python3 prog.py four
$ python prog.py four
usage: prog.py [-h] square
prog.py: error: argument square: invalid int value: 'four'

Expand All @@ -235,17 +235,17 @@ And the output:

.. code-block:: shell-session

$ python3 prog.py --verbosity 1
$ python prog.py --verbosity 1
verbosity turned on
$ python3 prog.py
$ python3 prog.py --help
$ python prog.py
$ python prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]

options:
-h, --help show this help message and exit
--verbosity VERBOSITY
increase output verbosity
$ python3 prog.py --verbosity
$ python prog.py --verbosity
usage: prog.py [-h] [--verbosity VERBOSITY]
prog.py: error: argument --verbosity: expected one argument

Expand Down Expand Up @@ -281,12 +281,12 @@ And the output:

.. code-block:: shell-session

$ python3 prog.py --verbose
$ python prog.py --verbose
verbosity turned on
$ python3 prog.py --verbose 1
$ python prog.py --verbose 1
usage: prog.py [-h] [--verbose]
prog.py: error: unrecognized arguments: 1
$ python3 prog.py --help
$ python prog.py --help
usage: prog.py [-h] [--verbose]

options:
Expand Down Expand Up @@ -327,9 +327,9 @@ And here goes:

.. code-block:: shell-session

$ python3 prog.py -v
$ python prog.py -v
verbosity turned on
$ python3 prog.py --help
$ python prog.py --help
usage: prog.py [-h] [-v]

options:
Expand Down Expand Up @@ -361,14 +361,14 @@ And now the output:

.. code-block:: shell-session

$ python3 prog.py
$ python prog.py
usage: prog.py [-h] [-v] square
prog.py: error: the following arguments are required: square
$ python3 prog.py 4
$ python prog.py 4
16
$ python3 prog.py 4 --verbose
$ python prog.py 4 --verbose
the square of 4 equals 16
$ python3 prog.py --verbose 4
$ python prog.py --verbose 4
the square of 4 equals 16

* We've brought back a positional argument, hence the complaint.
Expand Down Expand Up @@ -397,16 +397,16 @@ And the output:

.. code-block:: shell-session

$ python3 prog.py 4
$ python prog.py 4
16
$ python3 prog.py 4 -v
$ python prog.py 4 -v
usage: prog.py [-h] [-v VERBOSITY] square
prog.py: error: argument -v/--verbosity: expected one argument
$ python3 prog.py 4 -v 1
$ python prog.py 4 -v 1
4^2 == 16
$ python3 prog.py 4 -v 2
$ python prog.py 4 -v 2
the square of 4 equals 16
$ python3 prog.py 4 -v 3
$ python prog.py 4 -v 3
16

These all look good except the last one, which exposes a bug in our program.
Expand All @@ -431,10 +431,10 @@ And the output:

.. code-block:: shell-session

$ python3 prog.py 4 -v 3
$ python prog.py 4 -v 3
usage: prog.py [-h] [-v {0,1,2}] square
prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)
$ python3 prog.py 4 -h
$ python prog.py 4 -h
usage: prog.py [-h] [-v {0,1,2}] square

positional arguments:
Expand Down Expand Up @@ -473,18 +473,18 @@ to count the number of occurrences of specific options.

.. code-block:: shell-session

$ python3 prog.py 4
$ python prog.py 4
16
$ python3 prog.py 4 -v
$ python prog.py 4 -v
4^2 == 16
$ python3 prog.py 4 -vv
$ python prog.py 4 -vv
the square of 4 equals 16
$ python3 prog.py 4 --verbosity --verbosity
$ python prog.py 4 --verbosity --verbosity
the square of 4 equals 16
$ python3 prog.py 4 -v 1
$ python prog.py 4 -v 1
usage: prog.py [-h] [-v] square
prog.py: error: unrecognized arguments: 1
$ python3 prog.py 4 -h
$ python prog.py 4 -h
usage: prog.py [-h] [-v] square

positional arguments:
Expand All @@ -493,7 +493,7 @@ to count the number of occurrences of specific options.
options:
-h, --help show this help message and exit
-v, --verbosity increase output verbosity
$ python3 prog.py 4 -vvv
$ python prog.py 4 -vvv
16

* Yes, it's now more of a flag (similar to ``action="store_true"``) in the
Expand Down Expand Up @@ -540,11 +540,11 @@ And this is what it gives:

.. code-block:: shell-session

$ python3 prog.py 4 -vvv
$ python prog.py 4 -vvv
the square of 4 equals 16
$ python3 prog.py 4 -vvvv
$ python prog.py 4 -vvvv
the square of 4 equals 16
$ python3 prog.py 4
$ python prog.py 4
Traceback (most recent call last):
File "prog.py", line 11, in <module>
if args.verbosity >= 2:
Expand Down Expand Up @@ -584,7 +584,7 @@ And:

.. code-block:: shell-session

$ python3 prog.py 4
$ python prog.py 4
16

You can go quite far just with what we've learned so far,
Expand Down Expand Up @@ -617,10 +617,10 @@ Output:

.. code-block:: shell-session

$ python3 prog.py
$ python prog.py
usage: prog.py [-h] [-v] x y
prog.py: error: the following arguments are required: x, y
$ python3 prog.py -h
$ python prog.py -h
usage: prog.py [-h] [-v] x y

positional arguments:
Expand All @@ -630,7 +630,7 @@ Output:
options:
-h, --help show this help message and exit
-v, --verbosity
$ python3 prog.py 4 2 -v
$ python prog.py 4 2 -v
4^2 == 16


Expand All @@ -655,11 +655,11 @@ Output:

.. code-block:: shell-session

$ python3 prog.py 4 2
$ python prog.py 4 2
16
$ python3 prog.py 4 2 -v
$ python prog.py 4 2 -v
4^2 == 16
$ python3 prog.py 4 2 -vv
$ python prog.py 4 2 -vv
Running 'prog.py'
4^2 == 16

Expand Down Expand Up @@ -727,16 +727,16 @@ demonstration. Anyways, here's the output:

.. code-block:: shell-session

$ python3 prog.py 4 2
$ python prog.py 4 2
4^2 == 16
$ python3 prog.py 4 2 -q
$ python prog.py 4 2 -q
16
$ python3 prog.py 4 2 -v
$ python prog.py 4 2 -v
4 to the power 2 equals 16
$ python3 prog.py 4 2 -vq
$ python prog.py 4 2 -vq
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
$ python3 prog.py 4 2 -v --quiet
$ python prog.py 4 2 -v --quiet
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose

Expand Down Expand Up @@ -771,7 +771,7 @@ but not both at the same time:

.. code-block:: shell-session

$ python3 prog.py --help
$ python prog.py --help
usage: prog.py [-h] [-v | -q] x y

calculate X to the power of Y
Expand Down
2 changes: 1 addition & 1 deletion Doc/howto/clinic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ If you run that script, specifying a C file as an argument:

.. code-block:: shell-session

$ python3 Tools/clinic/clinic.py foo.c
$ python Tools/clinic/clinic.py foo.c

Argument Clinic will scan over the file looking for lines that
look exactly like this:
Expand Down
2 changes: 1 addition & 1 deletion Doc/howto/unicode.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,7 +449,7 @@ When run, this outputs:

.. code-block:: shell-session

$ python3 compare-strs.py
$ python compare-strs.py
length of first string= 1
length of second string= 2
True
Expand Down
16 changes: 8 additions & 8 deletions Doc/library/__main__.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,22 +61,22 @@ The top-level code environment can be:

.. code-block:: shell-session

$ python3 helloworld.py
$ python helloworld.py
Hello, world!

* the Python module or package passed to the Python interpreter with the
:option:`-m` argument:

.. code-block:: shell-session

$ python3 -m tarfile
$ python -m tarfile
usage: tarfile.py [-h] [-v] (...)

* Python code read by the Python interpreter from standard input:

.. code-block:: shell-session

$ echo "import this" | python3
$ echo "import this" | python
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Expand All @@ -87,7 +87,7 @@ The top-level code environment can be:

.. code-block:: shell-session

$ python3 -c "import this"
$ python -c "import this"
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Expand Down Expand Up @@ -178,7 +178,7 @@ that your function will return some value acceptable as an input to
returned if your function does not have a return statement).

By proactively following this convention ourselves, our module will have the
same behavior when run directly (i.e. ``python3 echo.py``) as it will have if
same behavior when run directly (i.e. ``python echo.py``) as it will have if
we later package it as a console script entry-point in a pip-installable
package.

Expand Down Expand Up @@ -215,7 +215,7 @@ directly from the command line using the :option:`-m` flag. For example:

.. code-block:: shell-session

$ python3 -m bandclass
$ python -m bandclass

This command will cause ``__main__.py`` to run. How you utilize this mechanism
will depend on the nature of the package you are writing, but in this
Expand Down Expand Up @@ -320,7 +320,7 @@ Now, if we started our program, the result would look like this:

.. code-block:: shell-session

$ python3 start.py
$ python start.py
Define the variable `my_name`!

The exit code of the program would be 1, indicating an error. Uncommenting the
Expand All @@ -329,7 +329,7 @@ status code 0, indicating success:

.. code-block:: shell-session

$ python3 start.py
$ python start.py
Dinsdale found in file /path/to/start.py

Note that importing ``__main__`` doesn't cause any issues with unintentionally
Expand Down
Loading