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

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 9a1cf3a53c4427612e2e25f83abbf0105f79b286..f8e39189686208fa896d8922b1a1e89576fba8d5 100644 (file)
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -810,10 +810,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 f32063e7f0960a50027d1b6b7867cd7f7efc9e61..a52653b94a32535a92265178453415ed22b3523a 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: