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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy