From abd92ebdb97aa7cf9d7c4cd001930e1fe9f78649 Mon Sep 17 00:00:00 2001 From: mental Date: Wed, 31 Jul 2019 11:40:43 +0100 Subject: [PATCH 1/4] bpo-37726: prefer argparse over getopt --- Doc/tutorial/stdlib.rst | 31 +++++++++++++++++-- .../2019-07-31-11-40-06.bpo-37726.h-3o9a.rst | 2 ++ 2 files changed, 30 insertions(+), 3 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 e030f8f19b48de..9953dc80a2a083 100644 --- a/Doc/tutorial/stdlib.rst +++ b/Doc/tutorial/stdlib.rst @@ -72,10 +72,35 @@ 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 + >>> parser = argparse.ArgumentParser(description='An argparse example.') + >>> parser.add_argument('name', help='The name of someone to greet.') + >>> args = parser.parse_args() + >>> print(f'Hello, {args.name}!') + +The three lines of code needed for creating the command line argument formula +are simple to read and understand and are easy to extend in terms of your +applications functionality. + +What if you wanted to provide a default value? + +:: + + >>> from getpass import getuser + >>> parser.add_argument('name', nargs='?', default=getuser(), help='The name of someone to greet.') + +How about if you wanted to control how verbose you are with your output? + +:: + + >>> parser.add_argument('--verbose', '-v', action='count') + >>> greeting = ["Hi", "Hello", "Greetings! its very nice to meet you"][args.verbose % 3] + >>> print(f'{greeting}, {args.name}') .. _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 00000000000000..195e9755a43c6a --- /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. From e7656a27663a70e5d3ebbbfc9161ad66cfdf8bbd Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Wed, 31 Jul 2019 07:53:35 -0700 Subject: [PATCH 2/4] Punctuation --- Doc/tutorial/stdlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst index 9953dc80a2a083..aa9a305c1bf92e 100644 --- a/Doc/tutorial/stdlib.rst +++ b/Doc/tutorial/stdlib.rst @@ -72,7 +72,7 @@ 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, +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:: From 20b974dc0c4e369912b6a65df996784370e3cf6f Mon Sep 17 00:00:00 2001 From: mental Date: Thu, 1 Aug 2019 01:30:22 +0100 Subject: [PATCH 3/4] Make requested changes --- Doc/tutorial/stdlib.rst | 28 +++++++--------------------- 1 file changed, 7 insertions(+), 21 deletions(-) diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst index aa9a305c1bf92e..92be554a850d0a 100644 --- a/Doc/tutorial/stdlib.rst +++ b/Doc/tutorial/stdlib.rst @@ -78,29 +78,15 @@ It should always be preferred over directly processing ``sys.argv`` manually. Take, for example, the below snippet of code:: >>> import argparse - >>> parser = argparse.ArgumentParser(description='An argparse example.') - >>> parser.add_argument('name', help='The name of someone to greet.') - >>> args = parser.parse_args() - >>> print(f'Hello, {args.name}!') - -The three lines of code needed for creating the command line argument formula -are simple to read and understand and are easy to extend in terms of your -applications functionality. - -What if you wanted to provide a default value? - -:: - >>> 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.') - -How about if you wanted to control how verbose you are with your output? - -:: - - >>> parser.add_argument('--verbose', '-v', action='count') - >>> greeting = ["Hi", "Hello", "Greetings! its very nice to meet you"][args.verbose % 3] - >>> print(f'{greeting}, {args.name}') + >>> 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: From 43f4ce44938a3ad17cd566267cf15c7d6ef82483 Mon Sep 17 00:00:00 2001 From: mental Date: Thu, 1 Aug 2019 01:36:14 +0100 Subject: [PATCH 4/4] Replace backticks with double quotes --- Doc/tutorial/stdlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst index 92be554a850d0a..f32063e7f0960a 100644 --- a/Doc/tutorial/stdlib.rst +++ b/Doc/tutorial/stdlib.rst @@ -86,7 +86,7 @@ Take, for example, the below snippet of code:: >>> 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!') + >>> print('Try running this again with multiple "-v" flags!') .. _tut-stderr: