bpo-38678: Improve argparse example in tutorial (GH-17207) (GH-17213)

(cherry picked from commit 04c79d6088a22d467f04dbe438050c26de22fa85)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index a2baa077cd890f2df1fb1f02c937c1e3dcd1de74..4a24c267ec79f4232b498a3585e85c4968c99bbf 100644 (file)
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -778,10 +778,12 @@ how the command-line arguments should be handled. The supplied actions are:
   example, this is useful for increasing verbosity levels::
 
     >>> parser = argparse.ArgumentParser()
-    >>> parser.add_argument('--verbose', '-v', action='count')
+    >>> parser.add_argument('--verbose', '-v', action='count', default=0)
     >>> parser.parse_args(['-vvv'])
     Namespace(verbose=3)
 
+  Note, the *default* will be ``None`` unless explicitly set to *0*.
+
 * ``'help'`` - This prints a complete help message for all the options in the
   current parser and then exits. By default a help action is automatically
   added to the parser. See :class:`ArgumentParser` for details of how the

diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst
index 26f11950e79e765114749b5b9c57e6f0105a40ff..a1b8c23b7bbae0a16a5efab76ca0cb0e53ee9318 100644 (file)
--- a/Doc/tutorial/stdlib.rst
+++ b/Doc/tutorial/stdlib.rst
@@ -72,21 +72,23 @@ three`` at the command line::
    >>> print(sys.argv)
    ['demo.py', 'one', 'two', 'three']
 
-The :mod:`argparse` module provides a mechanism to process command line arguments.
-It should always be preferred over directly processing ``sys.argv`` manually.
-
-Take, for example, the below snippet of code::
-
-   >>> import argparse
-   >>> from getpass import getuser
-   >>> parser = argparse.ArgumentParser(description='An argparse example.')
-   >>> parser.add_argument('name', nargs='?', default=getuser(), help='The name of someone to greet.')
-   >>> parser.add_argument('--verbose', '-v', action='count')
-   >>> args = parser.parse_args()
-   >>> greeting = ["Hi", "Hello", "Greetings! its very nice to meet you"][args.verbose % 3]
-   >>> print(f'{greeting}, {args.name}')
-   >>> if not args.verbose:
-   >>>     print('Try running this again with multiple "-v" flags!')
+The :mod:`argparse` module provides a more sophisticated mechanism to process
+command line arguments.  The following script extracts one or more filenames
+and an optional number of lines to be displayed::
+
+    import argparse
+
+    parser = argparse.ArgumentParser(prog = 'top',
+        description = 'Show top lines from each file')
+    parser.add_argument('filenames', nargs='+')
+    parser.add_argument('-l', '--lines', type=int, default=10)
+    args = parser.parse_args()
+    print(args)
+
+When run at the command line with ``python top.py --lines=5 alpha.txt
+beta.txt``, the script sets ``args.lines`` to ``5`` and ``args.filenames``
+to ``['alpha.txt', 'beta.txt']``.
+
 
 .. _tut-stderr: