diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index cef197f3055581..22bc9d4774392a 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 ------- @@ -185,6 +254,8 @@ ArgumentParser objects The following sections describe how each of these are used. +.. _prog: + prog ^^^^ @@ -282,6 +353,8 @@ The ``%(prog)s`` format specifier is available to fill in the program name in your usage messages. +.. _description: + description ^^^^^^^^^^^ @@ -362,6 +435,8 @@ and one in the child) and raise an error. not be reflected in the child. +.. _formatter_class: + formatter_class ^^^^^^^^^^^^^^^ @@ -683,6 +758,8 @@ The add_argument() method The following sections describe how each of these are used. +.. _name_or_flags: + name or flags ^^^^^^^^^^^^^ @@ -715,6 +792,8 @@ be positional:: PROG: error: the following arguments are required: bar +.. _action: + action ^^^^^^ @@ -824,6 +903,9 @@ An example of a custom action:: For more details, see :class:`Action`. + +.. _nargs: + nargs ^^^^^ @@ -924,6 +1006,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 ^^^^^ @@ -947,6 +1031,8 @@ With the ``'store_const'`` and ``'append_const'`` actions, the ``const`` keyword argument must be given. For other actions, it defaults to ``None``. +.. _default: + default ^^^^^^^ @@ -997,6 +1083,8 @@ command-line argument was not present:: Namespace(foo='1') +.. _type: + type ^^^^ @@ -1059,6 +1147,8 @@ simply check against a range of values:: See the choices_ section for more details. +.. _choices: + choices ^^^^^^^ @@ -1094,6 +1184,8 @@ value, so :class:`dict` objects, :class:`set` objects, custom containers, etc. are all supported. +.. _required: + required ^^^^^^^^ @@ -1120,6 +1212,8 @@ present at the command line. *options* to be *optional*, and thus they should be avoided when possible. +.. _help: + help ^^^^ @@ -1175,6 +1269,8 @@ setting the ``help`` value to ``argparse.SUPPRESS``:: -h, --help show this help message and exit +.. _metavar: + metavar ^^^^^^^ @@ -1239,6 +1335,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