From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Thu, 1 Aug 2019 14:34:57 +0000 (-0700)
Subject: bpo-37726: Prefer argparse over getopt in stdlib tutorial (GH-15052) (#15070)
X-Git-Tag: v3.8.0b4~143
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=dcc53ebbff384076b0763c1f842966c189417071;p=thirdparty%2FPython%2Fcpython.git

bpo-37726: Prefer argparse over getopt in stdlib tutorial (GH-15052) (#15070)

(cherry picked from commit 2491134029b195d3159a489e1803ee22a7839b41)

Co-authored-by: mental <m3nta1@yahoo.com>
---

diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst
index 82261a651348..20ad3563ca05 100644
--- a/Doc/tutorial/stdlib.rst
+++ b/Doc/tutorial/stdlib.rst
@@ -72,10 +72,21 @@ three`` at the command line::
    >>> print(sys.argv)
    ['demo.py', 'one', 'two', 'three']
 
-The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix
-:func:`getopt` function.  More powerful and flexible command line processing is
-provided by the :mod:`argparse` module.
-
+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!')
 
 .. _tut-stderr:
 
diff --git a/Misc/NEWS.d/next/Documentation/2019-07-31-11-40-06.bpo-37726.h-3o9a.rst b/Misc/NEWS.d/next/Documentation/2019-07-31-11-40-06.bpo-37726.h-3o9a.rst
new file mode 100644
index 000000000000..195e9755a43c
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-07-31-11-40-06.bpo-37726.h-3o9a.rst
@@ -0,0 +1,2 @@
+Stop recommending getopt in the tutorial for command line argument parsing
+and promote argparse.