From 2491134029b195d3159a489e1803ee22a7839b41 Mon Sep 17 00:00:00 2001 From: mental Date: Thu, 1 Aug 2019 15:17:30 +0100 Subject: bpo-37726: Prefer argparse over getopt in stdlib tutorial (#15052) --- Doc/tutorial/stdlib.rst | 19 +++++++++++++++---- .../2019-07-31-11-40-06.bpo-37726.h-3o9a.rst | 2 ++ 2 files changed, 17 insertions(+), 4 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2019-07-31-11-40-06.bpo-37726.h-3o9a.rst diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst index e030f8f..f32063e 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 0000000..195e975 --- /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. -- cgit v0.12