From 82ef37b9e1ddabe3591f78fee668c0ee581ff95d Mon Sep 17 00:00:00 2001 From: Susan Su Date: Sat, 23 Feb 2019 18:55:05 -0800 Subject: [PATCH 1/7] added summary tables to argparse documentation --- Doc/library/argparse.rst | 86 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 85 insertions(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index cef197f3055581..94d1c9f6a38207 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -26,6 +26,61 @@ module also automatically generates help and usage messages and issues errors when users give the program invalid arguments. +Summary +------- + +Core Functionality +^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "Name", "Commonly Used Arguments", "Example" + + ":class:`argparse.ArgumentParser`", "`prog`_, `description`_, `formatter_class`_", "``parser = argparse.ArgumentParser(prog='PROG', description='DESC', formatter_class=argparse.RawDescriptionHelpFormatter)``" + ":func:`ArgumentParser.add_argument`", "`name or flags`_, `action`_, `default`_, `type`_, `required`_, `help`_", "``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 +240,8 @@ ArgumentParser objects The following sections describe how each of these are used. +.. _prog: + prog ^^^^ @@ -282,6 +339,8 @@ The ``%(prog)s`` format specifier is available to fill in the program name in your usage messages. +.. _description: + description ^^^^^^^^^^^ @@ -362,6 +421,8 @@ and one in the child) and raise an error. not be reflected in the child. +.. _formatter_class: + formatter_class ^^^^^^^^^^^^^^^ @@ -683,6 +744,8 @@ The add_argument() method The following sections describe how each of these are used. +.. _name or flags: + name or flags ^^^^^^^^^^^^^ @@ -715,6 +778,8 @@ be positional:: PROG: error: the following arguments are required: bar +.. _action: + action ^^^^^^ @@ -824,6 +889,9 @@ An example of a custom action:: For more details, see :class:`Action`. + +.. _nargs: + nargs ^^^^^ @@ -924,6 +992,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 +1017,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 +1069,8 @@ command-line argument was not present:: Namespace(foo='1') +.. _type: + type ^^^^ @@ -1059,6 +1133,8 @@ simply check against a range of values:: See the choices_ section for more details. +.. _choices: + choices ^^^^^^^ @@ -1093,7 +1169,9 @@ Any object that supports the ``in`` operator can be passed as the *choices* value, so :class:`dict` objects, :class:`set` objects, custom containers, etc. are all supported. - + +.. _required: + required ^^^^^^^^ @@ -1120,6 +1198,8 @@ present at the command line. *options* to be *optional*, and thus they should be avoided when possible. +.. _help: + help ^^^^ @@ -1175,6 +1255,8 @@ setting the ``help`` value to ``argparse.SUPPRESS``:: -h, --help show this help message and exit +.. _metavar: + metavar ^^^^^^^ @@ -1239,6 +1321,8 @@ arguments:: --foo bar baz +.. _dest: + dest ^^^^ From 5e75aa36015394479ee8a80719fc8ee4f1cbee84 Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" Date: Sun, 24 Feb 2019 03:07:00 +0000 Subject: [PATCH 2/7] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../next/Documentation/2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Documentation/2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst 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 From 427d6f61737a6227d3ca9d115215d6cf96459c68 Mon Sep 17 00:00:00 2001 From: Susan Su Date: Sat, 23 Feb 2019 19:19:13 -0800 Subject: [PATCH 3/7] removed whitespaces --- Doc/library/argparse.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 94d1c9f6a38207..42b31e9dcc3487 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -891,7 +891,7 @@ For more details, see :class:`Action`. .. _nargs: - + nargs ^^^^^ @@ -1169,9 +1169,9 @@ Any object that supports the ``in`` operator can be passed as the *choices* value, so :class:`dict` objects, :class:`set` objects, custom containers, etc. are all supported. - + .. _required: - + required ^^^^^^^^ From 2d96d8313decb030ea13123e0541c3ef4d209804 Mon Sep 17 00:00:00 2001 From: Susan Su Date: Sun, 24 Feb 2019 13:28:17 -0800 Subject: [PATCH 4/7] Changed core functionality table into sentences based on merwok's recommendation --- Doc/library/argparse.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 42b31e9dcc3487..11249d49b917d5 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -32,11 +32,17 @@ Summary Core Functionality ^^^^^^^^^^^^^^^^^^ -.. csv-table:: - :header: "Name", "Commonly Used Arguments", "Example" +The :mod:`argparse` module's support for command-line interfaces is built from the following: - ":class:`argparse.ArgumentParser`", "`prog`_, `description`_, `formatter_class`_", "``parser = argparse.ArgumentParser(prog='PROG', description='DESC', formatter_class=argparse.RawDescriptionHelpFormatter)``" - ":func:`ArgumentParser.add_argument`", "`name or flags`_, `action`_, `default`_, `type`_, `required`_, `help`_", "``parser.add_argument('-v', '--verbose', action='store_true', help='Show various debugging information')``" +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` @@ -744,7 +750,7 @@ The add_argument() method The following sections describe how each of these are used. -.. _name or flags: +.. ref:`name or flags` name or flags ^^^^^^^^^^^^^ From 95984c356e9128b6c33271b650dfd9bc9268ff85 Mon Sep 17 00:00:00 2001 From: Susan Su Date: Sun, 24 Feb 2019 13:34:55 -0800 Subject: [PATCH 5/7] removed tabs --- Doc/library/argparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 11249d49b917d5..c52dae25b55a74 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -37,12 +37,12 @@ The :mod:`argparse` module's support for command-line interfaces is built from t 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) + ... 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') + ... help='Show various debugging information') Basic Usage of :func:`add_argument` From da29e79224e9d86d56f1334bcba06f1b33541f7b Mon Sep 17 00:00:00 2001 From: Susan Su Date: Mon, 25 Feb 2019 13:04:42 -0800 Subject: [PATCH 6/7] reverted change from old commit --- Doc/library/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index c52dae25b55a74..afd4eec75a27df 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -750,7 +750,7 @@ The add_argument() method The following sections describe how each of these are used. -.. ref:`name or flags` +.. _name_or_flags: name or flags ^^^^^^^^^^^^^ From 8b35e391415d2025792a2f6eb85669ea5542a9f6 Mon Sep 17 00:00:00 2001 From: Susan Su Date: Mon, 25 Feb 2019 14:45:49 -0800 Subject: [PATCH 7/7] Wrapped long lines of paragraphs under Core functionality section and removed backtick marks around source links to maintain consistency throughout file --- Doc/library/argparse.rst | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index afd4eec75a27df..22bc9d4774392a 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -32,14 +32,22 @@ Summary Core Functionality ^^^^^^^^^^^^^^^^^^ -The :mod:`argparse` module's support for command-line interfaces is built from the following: +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:: +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:: +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') @@ -64,10 +72,10 @@ Optional ``'-v'``, ``'--verbose'`` ====================== =========================================================== ========================================================================================================================= 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 +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 ====================== =========================================================== ========================================================================================================================= @@ -77,12 +85,12 @@ Name Description ====================== =========================================================== ======================================================================================================================= 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()`` +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()`` ====================== =========================================================== =======================================================================================================================