From 0499cc56b67ca3751691ddfc141543d98ab588c9 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Wed, 20 Apr 2022 00:24:33 -0500 Subject: [PATCH 1/2] Clean-up the argparse docs quick links table --- Doc/library/argparse.rst | 53 +++++++++++----------------------------- 1 file changed, 14 insertions(+), 39 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 425409db3cb751..6e2828d92ce0c5 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -26,11 +26,8 @@ module also automatically generates help and usage messages and issues errors when users give the program invalid arguments. -Summary -------- - Core Functionality -^^^^^^^^^^^^^^^^^^ +------------------ The :mod:`argparse` module's support for command-line interfaces is built from the following: @@ -44,7 +41,7 @@ formatter_class_. For example, the user can create an instance of ... formatter_class=argparse.RawDescriptionHelpFormatter) The :func:`ArgumentParser.add_argument` is a function that is used -to define how a single command-line argument should be parsed. Commonly used +to define each command-line argument should be parsed. Commonly used arguments include `name or flags`_, action_, default_, type_, required_, and help_. An example of the function :func:`ArgumentParser.add_argument` is as follows:: @@ -53,44 +50,22 @@ is as follows:: ... help='Show various debugging information') -Basic Usage of :func:`add_argument` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - -**Name or Flags Type** - -====================== =========================== -Type Example -====================== =========================== -Positional ``'foo'`` -Optional ``'-v'``, ``'--verbose'`` -====================== =========================== - - -**Basic Arguments:** +Quick Links for add_argument() +------------------------------ ====================== =========================================================== ========================================================================================================================= -Name Description Keywords +Name Description Values ====================== =========================================================== ========================================================================================================================= -action_ Specifies how an argument should be handled ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``'append_const'``, ``'count'``, ``'help'``, ``'version'`` +action_ Specify how an argument should be handled ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``'append_const'``, ``'count'``, ``'help'``, ``'version'`` +choices_ Limit values to specific set of choices ``['foo', 'bar']``, ``range(1, 10)``, or an object that supports ``in`` operator +const_ Store a constant value default_ Default value used when an argument is not provided -type_ Automatically converts an argument to the given type :class:`int`, :class:`float`, :class:`bool`, ``argparse.FileType('w')``, ``callable function`` -help_ Help message of an argument -====================== =========================================================== ========================================================================================================================= - - - -**Advanced Arguments:** - -====================== =========================================================== ======================================================================================================================= -Name Description Keywords -====================== =========================================================== ======================================================================================================================= -nargs_ Associates a single action with the number of arguments ``N`` (:class:`int`), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER`` -const_ Stores constant values of names or flags -choices_ A container that lists the possible values ``['foo', 'bar']``, ``range(1, 10)``, Any object that supports ``in`` operator -required_ Indicates if an optional argument is required or not ``True``, ``False`` -metavar_ An alternative display name for the argument -dest_ Specifies name of attribute to be used in ``parse_args()`` +dest_ Specify the attribute name in result namespace +help_ Help message for an argument +metavar_ Alternate display name for the argument as shown in help +nargs_ Number of times the argument can be used ``N`` (:class:`int`), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER`` +required_ Indicate whether an optional argument is required or not ``True``, ``False`` +type_ Automatically convert an argument to the given type :class:`int`, :class:`float`, ``argparse.FileType('w')``, or any callable function ====================== =========================================================== ======================================================================================================================= From 6418ad442302e4d763ed53012350c13fb6f1acaa Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Wed, 20 Apr 2022 00:57:37 -0500 Subject: [PATCH 2/2] Fix table and make the core functionality summary more focused --- Doc/library/argparse.rst | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 6e2828d92ce0c5..7c206370f54325 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -30,32 +30,36 @@ Core Functionality ------------------ The :mod:`argparse` module's support for command-line interfaces is built -from the following: +around an instance of :class:`argparse.ArgumentParser`. It is a container for +argument specifications and has options that apply the parser as whole:: -The :class:`argparse.ArgumentParser` creates a new :class:`ArgumentParser` -object. Commonly used arguments include prog_, description_, and -formatter_class_. For example, the user can create an instance of -:class:`ArgumentParser` through the following:: + parser = argparse.ArgumentParser( + prog = 'ProgramName', + description = 'What the program does', + epilog = 'Text at the bottom of help') - >>> parser = argparse.ArgumentParser(prog='PROG', description='DESC', - ... formatter_class=argparse.RawDescriptionHelpFormatter) +The :func:`ArgumentParser.add_argument` function attaches individual argument +specifications to the parser. It supports positional arguments, options that +accept values, and on/off flags:: -The :func:`ArgumentParser.add_argument` is a function that is used -to define each command-line argument should be parsed. Commonly used -arguments include `name or flags`_, action_, default_, type_, required_, -and help_. An example of the function :func:`ArgumentParser.add_argument` -is as follows:: + parser.add_argument('filename') # positional argument + parser.add_argument('-c', '--count') # option that takes value + parser.add_argument('-v', '--verbose', + action='store_true') # on/off flag - >>> parser.add_argument('-v', '--verbose', action='store_true', - ... help='Show various debugging information') +The :func:`ArgumentParser.parse_args` function runs the parser and puts +the extracted data in a :class:`argparse.Namespace` object:: + + args = parser.parse_args() + print(args.filename, args.count, args.verbose) Quick Links for add_argument() ------------------------------ -====================== =========================================================== ========================================================================================================================= +====================== =========================================================== ========================================================================================================================== Name Description Values -====================== =========================================================== ========================================================================================================================= +====================== =========================================================== ========================================================================================================================== action_ Specify how an argument should be handled ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``'append_const'``, ``'count'``, ``'help'``, ``'version'`` choices_ Limit values to specific set of choices ``['foo', 'bar']``, ``range(1, 10)``, or an object that supports ``in`` operator const_ Store a constant value @@ -66,8 +70,7 @@ metavar_ Alternate display name for the argument as shown in help nargs_ Number of times the argument can be used ``N`` (:class:`int`), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER`` required_ Indicate whether an optional argument is required or not ``True``, ``False`` type_ Automatically convert an argument to the given type :class:`int`, :class:`float`, ``argparse.FileType('w')``, or any callable function -====================== =========================================================== ======================================================================================================================= - +====================== =========================================================== ========================================================================================================================== Example