From 8e76d7e1a9592b24717204ad307b7493d593191f Mon Sep 17 00:00:00 2001 From: Susan Su Date: Sun, 17 Apr 2022 21:46:18 -0700 Subject: [PATCH] bpo-21150: Add quick link/summary table to the top of argparse documentation (GH-12005) No work has been done to move this forward. On the theory that perfect is the enemy of good, I'm going to push it and we can make minor edits as needed afterwards. --- Doc/library/argparse.rst | 98 +++++++++++++++++++ .../2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst | 1 + 2 files changed, 99 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index e050d6298b6ff6..425409db3cb751 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -26,6 +26,75 @@ 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: + +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='PROG', description='DESC', + ... 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 +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('-v', '--verbose', action='store_true', + ... help='Show various debugging information') + + +Basic Usage of :func:`add_argument` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +**Name or Flags Type** + +====================== =========================== +Type Example +====================== =========================== +Positional ``'foo'`` +Optional ``'-v'``, ``'--verbose'`` +====================== =========================== + + +**Basic Arguments:** + +====================== =========================================================== ========================================================================================================================= +Name Description Keywords +====================== =========================================================== ========================================================================================================================= +action_ Specifies how an argument should be handled ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``'append_const'``, ``'count'``, ``'help'``, ``'version'`` +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()`` +====================== =========================================================== ======================================================================================================================= + + + Example ------- @@ -196,6 +265,8 @@ ArgumentParser objects The following sections describe how each of these are used. +.. _prog: + prog ^^^^ @@ -293,6 +364,8 @@ The ``%(prog)s`` format specifier is available to fill in the program name in your usage messages. +.. _description: + description ^^^^^^^^^^^ @@ -373,6 +446,8 @@ and one in the child) and raise an error. not be reflected in the child. +.. _formatter_class: + formatter_class ^^^^^^^^^^^^^^^ @@ -716,6 +791,8 @@ The add_argument() method The following sections describe how each of these are used. +.. _name_or_flags: + name or flags ^^^^^^^^^^^^^ @@ -749,6 +826,8 @@ be positional:: PROG: error: the following arguments are required: bar +.. _action: + action ^^^^^^ @@ -884,6 +963,9 @@ An example of a custom action:: For more details, see :class:`Action`. + +.. _nargs: + nargs ^^^^^ @@ -971,6 +1053,8 @@ is determined by the action_. Generally this means a single command-line argume will be consumed and a single item (not a list) will be produced. +.. _const: + const ^^^^^ @@ -997,6 +1081,8 @@ the various :class:`ArgumentParser` actions. The two most common uses of it are ``const=None`` by default, including when ``action='append_const'`` or ``action='store_const'``. +.. _default: + default ^^^^^^^ @@ -1055,6 +1141,8 @@ command-line argument was not present:: Namespace(foo='1') +.. _type: + type ^^^^ @@ -1124,6 +1212,8 @@ For type checkers that simply check against a fixed set of values, consider using the choices_ keyword instead. +.. _choices: + choices ^^^^^^^ @@ -1166,6 +1256,8 @@ from *dest*. This is usually what you want because the user never sees the many choices), just specify an explicit metavar_. +.. _required: + required ^^^^^^^^ @@ -1192,6 +1284,8 @@ present at the command line. *options* to be *optional*, and thus they should be avoided when possible. +.. _help: + help ^^^^ @@ -1247,6 +1341,8 @@ setting the ``help`` value to ``argparse.SUPPRESS``:: -h, --help show this help message and exit +.. _metavar: + metavar ^^^^^^^ @@ -1311,6 +1407,8 @@ arguments:: --foo bar baz +.. _dest: + dest ^^^^ diff --git a/Misc/NEWS.d/next/Documentation/2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst b/Misc/NEWS.d/next/Documentation/2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst new file mode 100644 index 00000000000000..d1b5615a12e7fd --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst @@ -0,0 +1 @@ +Place summary/quick links table at the top of the documentation for the argparse module to benefit ease of use. \ No newline at end of file