From 07ac215c8233dd02404932e5e61d48511e193d69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Wirtel?= Date: Wed, 27 Feb 2019 14:48:28 +0100 Subject: [PATCH] bpo-13850: Add summary tables for argparse add_argument options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Xavier Morel Co-authored-by: Tina Zhang Co-authored-by: Stéphane Wirtel --- Doc/library/argparse.rst | 42 ++++++++++++++++++- .../2019-02-27-14-48-15.bpo-13850.EykSI5.rst | 3 ++ 2 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 Misc/NEWS.d/next/Documentation/2019-02-27-14-48-15.bpo-13850.EykSI5.rst diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index cef197f3055581..d4824f67e71840 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -23,8 +23,48 @@ The :mod:`argparse` module makes it easy to write user-friendly command-line interfaces. The program defines what arguments it requires, and :mod:`argparse` will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse` module also automatically generates help and usage messages and issues errors -when users give the program invalid arguments. +when users give the program invalid arguments. See the `Quick Reference`_ for a +summary table of applicable parameters for each action_ in +:meth:`~ArgumentParser.add_argument`. +Quick Reference +--------------- + +The table below provides a summary of applicable parameters (columns) of the +add_argument() method for each functional action_ (rows). + ++-----------------+---------+----------------+-----------+--------+-----------+------------+--------+-----------+--------+-----------+ +| |``nargs``|``const`` |``default``|``type``|``choices``|``required``|``help``|``metavar``|``dest``|``version``| ++=================+=========+================+===========+========+===========+============+========+===========+========+===========+ +|``store`` |x |if ``nargs='?'``|x |x |x |x |x |x |x | | ++-----------------+---------+----------------+-----------+--------+-----------+------------+--------+-----------+--------+-----------+ +|``store_const`` | |x |x | | |x |x |x |x | | ++-----------------+---------+----------------+-----------+--------+-----------+------------+--------+-----------+--------+-----------+ +|``store_true`` | |x |x | | |x |x |x |x | | ++-----------------+---------+----------------+-----------+--------+-----------+------------+--------+-----------+--------+-----------+ +|``store_false`` | |x |x | | |x |x |x |x | | ++-----------------+---------+----------------+-----------+--------+-----------+------------+--------+-----------+--------+-----------+ +|``append`` |x |if ``nargs='?'``|x |x |x |x |x |x |x | | ++-----------------+---------+----------------+-----------+--------+-----------+------------+--------+-----------+--------+-----------+ +|``append_const`` | |x |x | | |x |x |x |x | | ++-----------------+---------+----------------+-----------+--------+-----------+------------+--------+-----------+--------+-----------+ +|``count`` | | | | | | |x |x |x | | ++-----------------+---------+----------------+-----------+--------+-----------+------------+--------+-----------+--------+-----------+ +|``version`` | | | | | | | | | |x | ++-----------------+---------+----------------+-----------+--------+-----------+------------+--------+-----------+--------+-----------+ + +.. note:: + + * ``default`` can be set to ``argparse.SUPPRESS`` to prevent the + attribute from being added + + * ``nargs='?'`` will use ``default`` if the argument is not + specified, but ``const`` if the argument is specified with no + value provided + + * list-type ``nargs`` (an ``int``, ``'*'`` or ``'+'``) causes a + list to be used: ``store`` becomes a list and ``append`` becomes + a list of lists Example ------- diff --git a/Misc/NEWS.d/next/Documentation/2019-02-27-14-48-15.bpo-13850.EykSI5.rst b/Misc/NEWS.d/next/Documentation/2019-02-27-14-48-15.bpo-13850.EykSI5.rst new file mode 100644 index 00000000000000..f727d921b113fa --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2019-02-27-14-48-15.bpo-13850.EykSI5.rst @@ -0,0 +1,3 @@ +Add asummary of applicable parameters of the +:meth:`~ArgumentParser.add_argument`. Original patch by Xavier Morel, +updated by Tina Zhang. Contributed by Stéphane Wirtel.