From 484ca7f3845f9551ee92003c190be936ea1bb0b6 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Mon, 30 Sep 2024 21:20:52 -0700 Subject: [PATCH 01/20] Progress on paring things down --- Doc/library/argparse.rst | 232 ++------------------------------------- 1 file changed, 8 insertions(+), 224 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index a4683bccf651cd..aa59668add687a 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -25,29 +25,6 @@ will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse` module also automatically generates help and usage messages. The module will also issue errors when users give the program invalid arguments. -Quick Links for ArgumentParser ---------------------------------------- -========================= =========================================================================================================== ================================================================================== -Name Description Values -========================= =========================================================================================================== ================================================================================== -prog_ The name of the program Defaults to ``os.path.basename(sys.argv[0])`` -usage_ The string describing the program usage -description_ A brief description of what the program does -epilog_ Additional description of the program after the argument help -parents_ A list of :class:`ArgumentParser` objects whose arguments should also be included -formatter_class_ A class for customizing the help output ``argparse.HelpFormatter`` -prefix_chars_ The set of characters that prefix optional arguments Defaults to ``'-'`` -fromfile_prefix_chars_ The set of characters that prefix files to read additional arguments from Defaults to ``None`` (meaning arguments will never be treated as file references) -argument_default_ The global default value for arguments -allow_abbrev_ Allows long options to be abbreviated if the abbreviation is unambiguous ``True`` or ``False`` (default: ``True``) -conflict_handler_ The strategy for resolving conflicting optionals -add_help_ Add a ``-h/--help`` option to the parser ``True`` or ``False`` (default: ``True``) -exit_on_error_ Determines whether or not to exit with error info when an error occurs ``True`` or ``False`` (default: ``True``) -========================= =========================================================================================================== ================================================================================== - -Core Functionality ------------------- - The :mod:`argparse` module's support for command-line interfaces is built around an instance of :class:`argparse.ArgumentParser`. It is a container for argument specifications and has options that apply to the parser as whole:: @@ -73,133 +50,6 @@ the extracted data in a :class:`argparse.Namespace` object:: 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 a specific set of choices ``['foo', 'bar']``, ``range(1, 10)``, or :class:`~collections.abc.Container` instance -const_ Store a constant value -default_ Default value used when an argument is not provided Defaults to ``None`` -dest_ Specify the attribute name used in the 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 :class:`int`, ``'?'``, ``'*'``, or ``'+'`` -required_ Indicate whether an argument is required or optional ``True`` or ``False`` -:ref:`type ` Automatically convert an argument to the given type :class:`int`, :class:`float`, ``argparse.FileType('w')``, or callable function -============================ =========================================================== ========================================================================================================================== - - -Example -------- - -The following code is a Python program that takes a list of integers and -produces either the sum or the max:: - - import argparse - - parser = argparse.ArgumentParser(description='Process some integers.') - parser.add_argument('integers', metavar='N', type=int, nargs='+', - help='an integer for the accumulator') - parser.add_argument('--sum', dest='accumulate', action='store_const', - const=sum, default=max, - help='sum the integers (default: find the max)') - - args = parser.parse_args() - print(args.accumulate(args.integers)) - -Assuming the above Python code is saved into a file called ``prog.py``, it can -be run at the command line and it provides useful help messages: - -.. code-block:: shell-session - - $ python prog.py -h - usage: prog.py [-h] [--sum] N [N ...] - - Process some integers. - - positional arguments: - N an integer for the accumulator - - options: - -h, --help show this help message and exit - --sum sum the integers (default: find the max) - -When run with the appropriate arguments, it prints either the sum or the max of -the command-line integers: - -.. code-block:: shell-session - - $ python prog.py 1 2 3 4 - 4 - - $ python prog.py 1 2 3 4 --sum - 10 - -If invalid arguments are passed in, an error will be displayed: - -.. code-block:: shell-session - - $ python prog.py a b c - usage: prog.py [-h] [--sum] N [N ...] - prog.py: error: argument N: invalid int value: 'a' - -The following sections walk you through this example. - - -Creating a parser -^^^^^^^^^^^^^^^^^ - -The first step in using the :mod:`argparse` is creating an -:class:`ArgumentParser` object:: - - >>> parser = argparse.ArgumentParser(description='Process some integers.') - -The :class:`ArgumentParser` object will hold all the information necessary to -parse the command line into Python data types. - - -Adding arguments -^^^^^^^^^^^^^^^^ - -Filling an :class:`ArgumentParser` with information about program arguments is -done by making calls to the :meth:`~ArgumentParser.add_argument` method. -Generally, these calls tell the :class:`ArgumentParser` how to take the strings -on the command line and turn them into objects. This information is stored and -used when :meth:`~ArgumentParser.parse_args` is called. For example:: - - >>> parser.add_argument('integers', metavar='N', type=int, nargs='+', - ... help='an integer for the accumulator') - >>> parser.add_argument('--sum', dest='accumulate', action='store_const', - ... const=sum, default=max, - ... help='sum the integers (default: find the max)') - -Later, calling :meth:`~ArgumentParser.parse_args` will return an object with -two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute -will be a list of one or more integers, and the ``accumulate`` attribute will be -either the :func:`sum` function, if ``--sum`` was specified at the command line, -or the :func:`max` function if it was not. - - -Parsing arguments -^^^^^^^^^^^^^^^^^ - -:class:`ArgumentParser` parses arguments through the -:meth:`~ArgumentParser.parse_args` method. This will inspect the command line, -convert each argument to the appropriate type and then invoke the appropriate action. -In most cases, this means a simple :class:`Namespace` object will be built up from -attributes parsed out of the command line:: - - >>> parser.parse_args(['--sum', '7', '-1', '42']) - Namespace(accumulate=, integers=[7, -1, 42]) - -In a script, :meth:`~ArgumentParser.parse_args` will typically be called with no -arguments, and the :class:`ArgumentParser` will automatically determine the -command-line arguments from :data:`sys.argv`. - - ArgumentParser objects ---------------------- @@ -272,35 +122,9 @@ By default, :class:`ArgumentParser` objects use the base name (see :func:`os.path.basename`) of ``sys.argv[0]`` to determine how to display the name of the program in help messages. This default is almost always desirable because it will make the help messages match the name that was -used to invoke the program on the command line. For example, consider a file -named ``myprogram.py`` with the following code:: - - import argparse - parser = argparse.ArgumentParser() - parser.add_argument('--foo', help='foo help') - args = parser.parse_args() - -The help for this program will display ``myprogram.py`` as the program name -(regardless of where the program was invoked from): - -.. code-block:: shell-session - - $ python myprogram.py --help - usage: myprogram.py [-h] [--foo FOO] - - options: - -h, --help show this help message and exit - --foo FOO foo help - $ cd .. - $ python subdir/myprogram.py --help - usage: myprogram.py [-h] [--foo FOO] - - options: - -h, --help show this help message and exit - --foo FOO foo help - -To change this default behavior, another value can be supplied using the -``prog=`` argument to :class:`ArgumentParser`:: +used to invoke the program on the command line. However, to change this default +behavior, another value can be supplied using the ``prog=`` argument to +:class:`ArgumentParser`:: >>> parser = argparse.ArgumentParser(prog='myprogram') >>> parser.print_help() @@ -329,22 +153,8 @@ usage ^^^^^ By default, :class:`ArgumentParser` calculates the usage message from the -arguments it contains:: - - >>> parser = argparse.ArgumentParser(prog='PROG') - >>> parser.add_argument('--foo', nargs='?', help='foo help') - >>> parser.add_argument('bar', nargs='+', help='bar help') - >>> parser.print_help() - usage: PROG [-h] [--foo [FOO]] bar [bar ...] - - positional arguments: - bar bar help - - options: - -h, --help show this help message and exit - --foo [FOO] foo help - -The default message can be overridden with the ``usage=`` keyword argument:: +arguments it contains. The default message can be overridden with the +``usage=`` keyword argument:: >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]') >>> parser.add_argument('--foo', nargs='?', help='foo help') @@ -372,16 +182,7 @@ Most calls to the :class:`ArgumentParser` constructor will use the ``description=`` keyword argument. This argument gives a brief description of what the program does and how it works. In help messages, the description is displayed between the command-line usage string and the help messages for the -various arguments:: - - >>> parser = argparse.ArgumentParser(description='A foo that bars') - >>> parser.print_help() - usage: argparse.py [-h] - - A foo that bars - - options: - -h, --help show this help message and exit +various arguments. By default, the description will be line-wrapped so that it fits within the given space. To change this behavior, see the formatter_class_ argument. @@ -692,25 +493,8 @@ add_help ^^^^^^^^ By default, ArgumentParser objects add an option which simply displays -the parser's help message. For example, consider a file named -``myprogram.py`` containing the following code:: - - import argparse - parser = argparse.ArgumentParser() - parser.add_argument('--foo', help='foo help') - args = parser.parse_args() - -If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser -help will be printed: - -.. code-block:: shell-session - - $ python myprogram.py --help - usage: myprogram.py [-h] [--foo FOO] - - options: - -h, --help show this help message and exit - --foo FOO foo help +the parser's help message. If ``-h`` or ``--help`` is supplied at the command +line, the ArgumentParser help will be printed. Occasionally, it may be useful to disable the addition of this help option. This can be achieved by passing ``False`` as the ``add_help=`` argument to From 47a411a003b2a2aa851bf418d67872cc857f1ca0 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Mon, 30 Sep 2024 21:32:04 -0700 Subject: [PATCH 02/20] More deduping --- Doc/library/argparse.rst | 54 ++++------------------------------------ 1 file changed, 5 insertions(+), 49 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index aa59668add687a..21cc0ba9699936 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -633,12 +633,7 @@ them, though most actions simply add an attribute to the object returned by how the command-line arguments should be handled. The supplied actions are: * ``'store'`` - This just stores the argument's value. This is the default - action. For example:: - - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--foo') - >>> parser.parse_args('--foo 1'.split()) - Namespace(foo='1') + action. * ``'store_const'`` - This stores the value specified by the const_ keyword argument; note that the const_ keyword argument defaults to ``None``. The @@ -653,14 +648,7 @@ how the command-line arguments should be handled. The supplied actions are: * ``'store_true'`` and ``'store_false'`` - These are special cases of ``'store_const'`` used for storing the values ``True`` and ``False`` respectively. In addition, they create default values of ``False`` and - ``True`` respectively. For example:: - - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--foo', action='store_true') - >>> parser.add_argument('--bar', action='store_false') - >>> parser.add_argument('--baz', action='store_false') - >>> parser.parse_args('--foo --bar'.split()) - Namespace(foo=True, bar=False, baz=True) + ``True`` respectively. * ``'append'`` - This stores a list, and appends each argument value to the list. It is useful to allow an option to be specified multiple times. @@ -1021,28 +1009,11 @@ Some command-line arguments should be selected from a restricted set of values. These can be handled by passing a sequence object as the *choices* keyword argument to :meth:`~ArgumentParser.add_argument`. When the command line is parsed, argument values will be checked, and an error message will be displayed -if the argument was not one of the acceptable values:: - - >>> parser = argparse.ArgumentParser(prog='game.py') - >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors']) - >>> parser.parse_args(['rock']) - Namespace(move='rock') - >>> parser.parse_args(['fire']) - usage: game.py [-h] {rock,paper,scissors} - game.py: error: argument move: invalid choice: 'fire' (choose from 'rock', - 'paper', 'scissors') +if the argument was not one of the acceptable values. Note that inclusion in the *choices* sequence is checked after any type_ conversions have been performed, so the type of the objects in the *choices* -sequence should match the type_ specified:: - - >>> parser = argparse.ArgumentParser(prog='doors.py') - >>> parser.add_argument('door', type=int, choices=range(1, 4)) - >>> print(parser.parse_args(['3'])) - Namespace(door=3) - >>> parser.parse_args(['4']) - usage: doors.py [-h] {1,2,3} - doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3) +sequence should match the type_ specified. Any sequence can be passed as the *choices* value, so :class:`list` objects, :class:`tuple` objects, and custom sequences are all supported. @@ -1092,22 +1063,7 @@ help The ``help`` value is a string containing a brief description of the argument. When a user requests help (usually by using ``-h`` or ``--help`` at the command line), these ``help`` descriptions will be displayed with each -argument:: - - >>> parser = argparse.ArgumentParser(prog='frobble') - >>> parser.add_argument('--foo', action='store_true', - ... help='foo the bars before frobbling') - >>> parser.add_argument('bar', nargs='+', - ... help='one of the bars to be frobbled') - >>> parser.parse_args(['-h']) - usage: frobble [-h] [--foo] bar [bar ...] - - positional arguments: - bar one of the bars to be frobbled - - options: - -h, --help show this help message and exit - --foo foo the bars before frobbling +argument. The ``help`` strings can include various format specifiers to avoid repetition of things like the program name or the argument default_. The available From 9845e44dc4e1599637b1d47af5fd0887959ce8ed Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Mon, 30 Sep 2024 21:35:55 -0700 Subject: [PATCH 03/20] Move details about upgrading from optparse to a separate doc --- Doc/library/argparse-optparse.rst | 55 +++++++++++++++++++++++++++++++ Doc/library/argparse.rst | 50 ---------------------------- 2 files changed, 55 insertions(+), 50 deletions(-) create mode 100644 Doc/library/argparse-optparse.rst diff --git a/Doc/library/argparse-optparse.rst b/Doc/library/argparse-optparse.rst new file mode 100644 index 00000000000000..8b6720f8f9adaa --- /dev/null +++ b/Doc/library/argparse-optparse.rst @@ -0,0 +1,55 @@ +.. currentmodule:: argparse + +.. _upgrading-optparse-code: + +========================== +Upgrading optparse code +========================== + +Originally, the :mod:`argparse` module had attempted to maintain compatibility +with :mod:`optparse`. However, :mod:`optparse` was difficult to extend +transparently, particularly with the changes required to support the new +``nargs=`` specifiers and better usage messages. When most everything in +:mod:`optparse` had either been copy-pasted over or monkey-patched, it no +longer seemed practical to try to maintain the backwards compatibility. + +The :mod:`argparse` module improves on the standard library :mod:`optparse` +module in a number of ways including: + +* Handling positional arguments. +* Supporting sub-commands. +* Allowing alternative option prefixes like ``+`` and ``/``. +* Handling zero-or-more and one-or-more style arguments. +* Producing more informative usage messages. +* Providing a much simpler interface for custom ``type`` and ``action``. + +A partial upgrade path from :mod:`optparse` to :mod:`argparse`: + +* Replace all :meth:`optparse.OptionParser.add_option` calls with + :meth:`ArgumentParser.add_argument` calls. + +* Replace ``(options, args) = parser.parse_args()`` with ``args = + parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument` + calls for the positional arguments. Keep in mind that what was previously + called ``options``, now in the :mod:`argparse` context is called ``args``. + +* Replace :meth:`optparse.OptionParser.disable_interspersed_args` + by using :meth:`~ArgumentParser.parse_intermixed_args` instead of + :meth:`~ArgumentParser.parse_args`. + +* Replace callback actions and the ``callback_*`` keyword arguments with + ``type`` or ``action`` arguments. + +* Replace string names for ``type`` keyword arguments with the corresponding + type objects (e.g. int, float, complex, etc). + +* Replace :class:`optparse.Values` with :class:`Namespace` and + :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with + :exc:`ArgumentError`. + +* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with + the standard Python syntax to use dictionaries to format strings, that is, + ``%(default)s`` and ``%(prog)s``. + +* Replace the OptionParser constructor ``version`` argument with a call to + ``parser.add_argument('--version', action='version', version='')``. diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 21cc0ba9699936..31225afed83696 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -2053,56 +2053,6 @@ remaining unparsed argument strings. .. _upgrading-optparse-code: -Upgrading optparse code ------------------------ - -Originally, the :mod:`argparse` module had attempted to maintain compatibility -with :mod:`optparse`. However, :mod:`optparse` was difficult to extend -transparently, particularly with the changes required to support the new -``nargs=`` specifiers and better usage messages. When most everything in -:mod:`optparse` had either been copy-pasted over or monkey-patched, it no -longer seemed practical to try to maintain the backwards compatibility. - -The :mod:`argparse` module improves on the standard library :mod:`optparse` -module in a number of ways including: - -* Handling positional arguments. -* Supporting sub-commands. -* Allowing alternative option prefixes like ``+`` and ``/``. -* Handling zero-or-more and one-or-more style arguments. -* Producing more informative usage messages. -* Providing a much simpler interface for custom ``type`` and ``action``. - -A partial upgrade path from :mod:`optparse` to :mod:`argparse`: - -* Replace all :meth:`optparse.OptionParser.add_option` calls with - :meth:`ArgumentParser.add_argument` calls. - -* Replace ``(options, args) = parser.parse_args()`` with ``args = - parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument` - calls for the positional arguments. Keep in mind that what was previously - called ``options``, now in the :mod:`argparse` context is called ``args``. - -* Replace :meth:`optparse.OptionParser.disable_interspersed_args` - by using :meth:`~ArgumentParser.parse_intermixed_args` instead of - :meth:`~ArgumentParser.parse_args`. - -* Replace callback actions and the ``callback_*`` keyword arguments with - ``type`` or ``action`` arguments. - -* Replace string names for ``type`` keyword arguments with the corresponding - type objects (e.g. int, float, complex, etc). - -* Replace :class:`optparse.Values` with :class:`Namespace` and - :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with - :exc:`ArgumentError`. - -* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with - the standard Python syntax to use dictionaries to format strings, that is, - ``%(default)s`` and ``%(prog)s``. - -* Replace the OptionParser constructor ``version`` argument with a call to - ``parser.add_argument('--version', action='version', version='')``. Exceptions ---------- From 5aae0a08a8ed9e503506dcc24db2296b396c3a76 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:00:27 -0700 Subject: [PATCH 04/20] Updates --- Doc/library/argparse.rst | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 31225afed83696..504aedc7141079 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -49,6 +49,9 @@ the extracted data in a :class:`argparse.Namespace` object:: args = parser.parse_args() print(args.filename, args.count, args.verbose) +.. note:: + If you're looking a guide about how to upgrade optparse code + to argparse, see :ref:`Upgrading Optparse Code `. ArgumentParser objects ---------------------- @@ -124,7 +127,9 @@ how to display the name of the program in help messages. This default is almost always desirable because it will make the help messages match the name that was used to invoke the program on the command line. However, to change this default behavior, another value can be supplied using the ``prog=`` argument to -:class:`ArgumentParser`:: +:class:`ArgumentParser` + +:: >>> parser = argparse.ArgumentParser(prog='myprogram') >>> parser.print_help() @@ -1523,7 +1528,7 @@ Sub-commands Description of parameters: * title - title for the sub-parser group in help output; by default - "subcommands" if description is provided, otherwise uses title for + "sub-commands" if description is provided, otherwise uses title for positional arguments * description - description for the sub-parser group in help output, by @@ -1542,7 +1547,7 @@ Sub-commands * dest_ - name of the attribute under which sub-command name will be stored; by default ``None`` and no value is stored - * required_ - Whether or not a subcommand must be provided, by default + * required_ - Whether or not a sub-command must be provided, by default ``False`` (added in 3.7) * help_ - help for sub-parser group in help output, by default ``None`` @@ -1619,8 +1624,8 @@ Sub-commands appear in their own group in the help output. For example:: >>> parser = argparse.ArgumentParser() - >>> subparsers = parser.add_subparsers(title='subcommands', - ... description='valid subcommands', + >>> subparsers = parser.add_subparsers(title='sub-commands', + ... description='valid sub-commands', ... help='additional help') >>> subparsers.add_parser('foo') >>> subparsers.add_parser('bar') @@ -1630,8 +1635,8 @@ Sub-commands options: -h, --help show this help message and exit - subcommands: - valid subcommands + sub-commands: + valid sub-commands {foo,bar} additional help @@ -2051,8 +2056,6 @@ remaining unparsed argument strings. .. versionadded:: 3.7 -.. _upgrading-optparse-code: - Exceptions ---------- @@ -2067,3 +2070,15 @@ Exceptions .. exception:: ArgumentTypeError Raised when something goes wrong converting a command line string to a type. + +.. We use the "rubric" directive here to avoid creating + the "Reference" subsection in the TOC. + +.. rubric:: Reference + +.. toctree:: + :maxdepth: 1 + :caption: Guides and Tutorials + + ../howto/argparse.rst + argparse-optparse.rst \ No newline at end of file From 5f14ee3d6f463dcc04c0b1c1ed3946858e490baa Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:26:50 -0700 Subject: [PATCH 05/20] remove table --- Doc/library/argparse.rst | 26 -------------------------- 1 file changed, 26 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 6499b72cb4dd9e..568f1080bb35bf 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -25,32 +25,6 @@ will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse` module also automatically generates help and usage messages. The module will also issue errors when users give the program invalid arguments. -<<<<<<< HEAD -======= -Quick Links for ArgumentParser ---------------------------------------- -========================= =========================================================================================================== ================================================================================== -Name Description Values -========================= =========================================================================================================== ================================================================================== -prog_ The name of the program -usage_ The string describing the program usage -description_ A brief description of what the program does -epilog_ Additional description of the program after the argument help -parents_ A list of :class:`ArgumentParser` objects whose arguments should also be included -formatter_class_ A class for customizing the help output ``argparse.HelpFormatter`` -prefix_chars_ The set of characters that prefix optional arguments Defaults to ``'-'`` -fromfile_prefix_chars_ The set of characters that prefix files to read additional arguments from Defaults to ``None`` (meaning arguments will never be treated as file references) -argument_default_ The global default value for arguments -allow_abbrev_ Allows long options to be abbreviated if the abbreviation is unambiguous ``True`` or ``False`` (default: ``True``) -conflict_handler_ The strategy for resolving conflicting optionals -add_help_ Add a ``-h/--help`` option to the parser ``True`` or ``False`` (default: ``True``) -exit_on_error_ Determines whether or not to exit with error info when an error occurs ``True`` or ``False`` (default: ``True``) -========================= =========================================================================================================== ================================================================================== - -Core Functionality ------------------- - ->>>>>>> main The :mod:`argparse` module's support for command-line interfaces is built around an instance of :class:`argparse.ArgumentParser`. It is a container for argument specifications and has options that apply to the parser as whole:: From 3c055d4824fd18ec589874be5e664cffb5b32658 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:32:13 -0700 Subject: [PATCH 06/20] Apply suggestions from code review Co-authored-by: Jelle Zijlstra --- Doc/library/argparse-optparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/argparse-optparse.rst b/Doc/library/argparse-optparse.rst index 8b6720f8f9adaa..1554c255da8a0a 100644 --- a/Doc/library/argparse-optparse.rst +++ b/Doc/library/argparse-optparse.rst @@ -8,12 +8,12 @@ Upgrading optparse code Originally, the :mod:`argparse` module had attempted to maintain compatibility with :mod:`optparse`. However, :mod:`optparse` was difficult to extend -transparently, particularly with the changes required to support the new +transparently, particularly with the changes required to support ``nargs=`` specifiers and better usage messages. When most everything in :mod:`optparse` had either been copy-pasted over or monkey-patched, it no longer seemed practical to try to maintain the backwards compatibility. -The :mod:`argparse` module improves on the standard library :mod:`optparse` +The :mod:`argparse` module improves on the :mod:`optparse` module in a number of ways including: * Handling positional arguments. From 1cb7d1f8de72289fa9313c762082d19485ed535e Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:32:51 -0700 Subject: [PATCH 07/20] Move optparse to howto --- Doc/{library => howto}/argparse-optparse.rst | 0 Doc/library/argparse.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename Doc/{library => howto}/argparse-optparse.rst (100%) diff --git a/Doc/library/argparse-optparse.rst b/Doc/howto/argparse-optparse.rst similarity index 100% rename from Doc/library/argparse-optparse.rst rename to Doc/howto/argparse-optparse.rst diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 568f1080bb35bf..122ab08cb4a3ff 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -2091,4 +2091,4 @@ Exceptions :caption: Guides and Tutorials ../howto/argparse.rst - argparse-optparse.rst \ No newline at end of file + ../howto/argparse-optparse.rst \ No newline at end of file From bfb28afc8035aaafd5370643a44f465505bdfab1 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:35:05 -0700 Subject: [PATCH 08/20] Appease linter --- Doc/howto/argparse-optparse.rst | 2 +- Doc/library/argparse.rst | 15 ++++++++------- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/Doc/howto/argparse-optparse.rst b/Doc/howto/argparse-optparse.rst index 1554c255da8a0a..946e86130a2654 100644 --- a/Doc/howto/argparse-optparse.rst +++ b/Doc/howto/argparse-optparse.rst @@ -1,7 +1,7 @@ .. currentmodule:: argparse .. _upgrading-optparse-code: - + ========================== Upgrading optparse code ========================== diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 122ab08cb4a3ff..0f2ecc2aae8f7d 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -132,9 +132,9 @@ to display in help messages depending on the way the Python interpreter was run: * The Python interpreter name followed by ``-m`` followed by the module or package name if the :option:`-m` option was used. -This default is almost always desirable because it will make the help messages -match the string that was used to invoke the program on the command line. -However, to change this default behavior, another value can be supplied using +This default is almost always desirable because it will make the help messages +match the string that was used to invoke the program on the command line. +However, to change this default behavior, another value can be supplied using the ``prog=`` argument to :class:`ArgumentParser`:: >>> parser = argparse.ArgumentParser(prog='myprogram') @@ -168,7 +168,7 @@ usage ^^^^^ By default, :class:`ArgumentParser` calculates the usage message from the -arguments it contains. The default message can be overridden with the +arguments it contains. The default message can be overridden with the ``usage=`` keyword argument:: >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]') @@ -508,7 +508,7 @@ add_help ^^^^^^^^ By default, ArgumentParser objects add an option which simply displays -the parser's help message. If ``-h`` or ``--help`` is supplied at the command +the parser's help message. If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser help will be printed. Occasionally, it may be useful to disable the addition of this help option. @@ -648,7 +648,7 @@ them, though most actions simply add an attribute to the object returned by how the command-line arguments should be handled. The supplied actions are: * ``'store'`` - This just stores the argument's value. This is the default - action. + action. * ``'store_const'`` - This stores the value specified by the const_ keyword argument; note that the const_ keyword argument defaults to ``None``. The @@ -2091,4 +2091,5 @@ Exceptions :caption: Guides and Tutorials ../howto/argparse.rst - ../howto/argparse-optparse.rst \ No newline at end of file + ../howto/argparse-optparse.rst + \ No newline at end of file From 936c808f8626b72b9e1ba10fbbb2e1eba7ec9125 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:39:13 -0700 Subject: [PATCH 09/20] Address PR comments --- Doc/library/argparse.rst | 48 ++++++++++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 0f2ecc2aae8f7d..785d36d0bed317 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1,4 +1,4 @@ -:mod:`!argparse` --- Parser for command-line options, arguments and sub-commands +:mod:`!argparse` --- Parser for command-line options, arguments and subcommands ================================================================================ .. module:: argparse @@ -663,7 +663,13 @@ how the command-line arguments should be handled. The supplied actions are: * ``'store_true'`` and ``'store_false'`` - These are special cases of ``'store_const'`` used for storing the values ``True`` and ``False`` respectively. In addition, they create default values of ``False`` and - ``True`` respectively. + ``True`` respectively:: + + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo', action='store_true') + >>> parser.add_argument('--bar', action='store_false') + >>> parser.parse_args(['--foo', '--bar']) + Namespace(bar=False, foo=True) * ``'append'`` - This stores a list, and appends each argument value to the list. It is useful to allow an option to be specified multiple times. @@ -1024,7 +1030,15 @@ Some command-line arguments should be selected from a restricted set of values. These can be handled by passing a sequence object as the *choices* keyword argument to :meth:`~ArgumentParser.add_argument`. When the command line is parsed, argument values will be checked, and an error message will be displayed -if the argument was not one of the acceptable values. +if the argument was not one of the acceptable values:: + + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors']) + >>> parser.parse_args(['rock']) + Namespace(move='rock') + >>> parser.parse_args(['fire']) + usage: [-h] {rock,paper,scissors} + : error: argument move: invalid choice: 'fire' (choose from 'rock', 'paper', 'scissors') Note that inclusion in the *choices* sequence is checked after any type_ conversions have been performed, so the type of the objects in the *choices* @@ -1523,12 +1537,12 @@ Sub-commands [option_strings], [dest], [required], \ [help], [metavar]) - Many programs split up their functionality into a number of sub-commands, - for example, the ``svn`` program can invoke sub-commands like ``svn + Many programs split up their functionality into a number of subcommands, + for example, the ``svn`` program can invoke subcommands like ``svn checkout``, ``svn update``, and ``svn commit``. Splitting up functionality this way can be a particularly good idea when a program performs several different functions which require different kinds of command-line arguments. - :class:`ArgumentParser` supports the creation of such sub-commands with the + :class:`ArgumentParser` supports the creation of such subcommands with the :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally called with no arguments and returns a special action object. This object has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a @@ -1538,7 +1552,7 @@ Sub-commands Description of parameters: * title - title for the sub-parser group in help output; by default - "sub-commands" if description is provided, otherwise uses title for + "subcommands" if description is provided, otherwise uses title for positional arguments * description - description for the sub-parser group in help output, by @@ -1562,15 +1576,15 @@ Sub-commands * help_ - help for sub-parser group in help output, by default ``None`` - * metavar_ - string presenting available sub-commands in help; by default it - is ``None`` and presents sub-commands in form {cmd1, cmd2, ..} + * metavar_ - string presenting available subcommands in help; by default it + is ``None`` and presents subcommands in form {cmd1, cmd2, ..} Some example usage:: >>> # create the top-level parser >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--foo', action='store_true', help='foo help') - >>> subparsers = parser.add_subparsers(help='sub-command help') + >>> subparsers = parser.add_subparsers(help='subcommand help') >>> >>> # create the parser for the "a" command >>> parser_a = subparsers.add_parser('a', help='a help') @@ -1605,7 +1619,7 @@ Sub-commands usage: PROG [-h] [--foo] {a,b} ... positional arguments: - {a,b} sub-command help + {a,b} subcommand help a a help b b help @@ -1634,8 +1648,8 @@ Sub-commands appear in their own group in the help output. For example:: >>> parser = argparse.ArgumentParser() - >>> subparsers = parser.add_subparsers(title='sub-commands', - ... description='valid sub-commands', + >>> subparsers = parser.add_subparsers(title='subcommands', + ... description='valid subcommands', ... help='additional help') >>> subparsers.add_parser('foo') >>> subparsers.add_parser('bar') @@ -1645,8 +1659,8 @@ Sub-commands options: -h, --help show this help message and exit - sub-commands: - valid sub-commands + subcommands: + valid subcommands {foo,bar} additional help @@ -1676,12 +1690,12 @@ Sub-commands .. versionadded:: 3.13 - One particularly effective way of handling sub-commands is to combine the use + One particularly effective way of handling subcommands is to combine the use of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so that each subparser knows which Python function it should execute. For example:: - >>> # sub-command functions + >>> # subcommand functions >>> def foo(args): ... print(args.x * args.y) ... From a5baef9e4bac257644530c58ba706d7ca8f1cd75 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:40:01 -0700 Subject: [PATCH 10/20] Address PR comments --- Doc/library/argparse.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 785d36d0bed317..9a786849325ec8 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -668,8 +668,9 @@ how the command-line arguments should be handled. The supplied actions are: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='store_true') >>> parser.add_argument('--bar', action='store_false') - >>> parser.parse_args(['--foo', '--bar']) - Namespace(bar=False, foo=True) + >>> parser.add_argument('--baz', action='store_false') + >>> parser.parse_args('--foo --bar'.split()) + Namespace(foo=True, bar=False, baz=True) * ``'append'`` - This stores a list, and appends each argument value to the list. It is useful to allow an option to be specified multiple times. From 782a60105a021880d4808f4e6161af7b71e82036 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:41:48 -0700 Subject: [PATCH 11/20] Fix indentation --- Doc/library/argparse.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 9a786849325ec8..37dd54e1f5dc3a 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -665,12 +665,12 @@ how the command-line arguments should be handled. The supplied actions are: respectively. In addition, they create default values of ``False`` and ``True`` respectively:: - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--foo', action='store_true') - >>> parser.add_argument('--bar', action='store_false') - >>> parser.add_argument('--baz', action='store_false') - >>> parser.parse_args('--foo --bar'.split()) - Namespace(foo=True, bar=False, baz=True) + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo', action='store_true') + >>> parser.add_argument('--bar', action='store_false') + >>> parser.add_argument('--baz', action='store_false') + >>> parser.parse_args('--foo --bar'.split()) + Namespace(foo=True, bar=False, baz=True) * ``'append'`` - This stores a list, and appends each argument value to the list. It is useful to allow an option to be specified multiple times. @@ -1032,7 +1032,7 @@ These can be handled by passing a sequence object as the *choices* keyword argument to :meth:`~ArgumentParser.add_argument`. When the command line is parsed, argument values will be checked, and an error message will be displayed if the argument was not one of the acceptable values:: - + >>> parser = argparse.ArgumentParser() >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors']) >>> parser.parse_args(['rock']) @@ -2107,4 +2107,3 @@ Exceptions ../howto/argparse.rst ../howto/argparse-optparse.rst - \ No newline at end of file From 903c7024b30ae93197b6f350ccff6bce2b76d1d2 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:42:56 -0700 Subject: [PATCH 12/20] Fix indentation --- Doc/library/argparse.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 37dd54e1f5dc3a..3388dc81c53676 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -665,12 +665,12 @@ how the command-line arguments should be handled. The supplied actions are: respectively. In addition, they create default values of ``False`` and ``True`` respectively:: - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--foo', action='store_true') - >>> parser.add_argument('--bar', action='store_false') - >>> parser.add_argument('--baz', action='store_false') - >>> parser.parse_args('--foo --bar'.split()) - Namespace(foo=True, bar=False, baz=True) + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo', action='store_true') + >>> parser.add_argument('--bar', action='store_false') + >>> parser.add_argument('--baz', action='store_false') + >>> parser.parse_args('--foo --bar'.split()) + Namespace(foo=True, bar=False, baz=True) * ``'append'`` - This stores a list, and appends each argument value to the list. It is useful to allow an option to be specified multiple times. @@ -1033,13 +1033,13 @@ argument to :meth:`~ArgumentParser.add_argument`. When the command line is parsed, argument values will be checked, and an error message will be displayed if the argument was not one of the acceptable values:: - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors']) - >>> parser.parse_args(['rock']) - Namespace(move='rock') - >>> parser.parse_args(['fire']) - usage: [-h] {rock,paper,scissors} - : error: argument move: invalid choice: 'fire' (choose from 'rock', 'paper', 'scissors') + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors']) + >>> parser.parse_args(['rock']) + Namespace(move='rock') + >>> parser.parse_args(['fire']) + usage: [-h] {rock,paper,scissors} + : error: argument move: invalid choice: 'fire' (choose from 'rock', 'paper', 'scissors') Note that inclusion in the *choices* sequence is checked after any type_ conversions have been performed, so the type of the objects in the *choices* From db7adf384387b00fc47f435d3d9c67cb1b70cb90 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:43:47 -0700 Subject: [PATCH 13/20] Fix indentation --- Doc/library/argparse.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 3388dc81c53676..c742add796e463 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1033,13 +1033,14 @@ argument to :meth:`~ArgumentParser.add_argument`. When the command line is parsed, argument values will be checked, and an error message will be displayed if the argument was not one of the acceptable values:: - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors']) - >>> parser.parse_args(['rock']) - Namespace(move='rock') - >>> parser.parse_args(['fire']) - usage: [-h] {rock,paper,scissors} - : error: argument move: invalid choice: 'fire' (choose from 'rock', 'paper', 'scissors') + >>> parser = argparse.ArgumentParser(prog='game.py') + >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors']) + >>> parser.parse_args(['rock']) + Namespace(move='rock') + >>> parser.parse_args(['fire']) + usage: game.py [-h] {rock,paper,scissors} + game.py: error: argument move: invalid choice: 'fire' (choose from 'rock', + 'paper', 'scissors') Note that inclusion in the *choices* sequence is checked after any type_ conversions have been performed, so the type of the objects in the *choices* From 52f7bbe3d031e5b128f85f3bf683ad094a46895e Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 1 Oct 2024 20:46:07 -0700 Subject: [PATCH 14/20] Update TOC --- Doc/library/argparse.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index c742add796e463..1b8e3677c84d77 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -2097,14 +2097,11 @@ Exceptions Raised when something goes wrong converting a command line string to a type. -.. We use the "rubric" directive here to avoid creating - the "Reference" subsection in the TOC. -.. rubric:: Reference +.. rubric:: Guides and Tutorials .. toctree:: :maxdepth: 1 - :caption: Guides and Tutorials ../howto/argparse.rst ../howto/argparse-optparse.rst From 300ed649636cdf37c1aa41ecc95faa798aa13907 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Wed, 2 Oct 2024 08:30:23 -0700 Subject: [PATCH 15/20] Update argparse-optparse.rst Co-authored-by: Tomas R --- Doc/howto/argparse-optparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/argparse-optparse.rst b/Doc/howto/argparse-optparse.rst index 946e86130a2654..cef2d893b28a62 100644 --- a/Doc/howto/argparse-optparse.rst +++ b/Doc/howto/argparse-optparse.rst @@ -17,7 +17,7 @@ The :mod:`argparse` module improves on the :mod:`optparse` module in a number of ways including: * Handling positional arguments. -* Supporting sub-commands. +* Supporting subcommands. * Allowing alternative option prefixes like ``+`` and ``/``. * Handling zero-or-more and one-or-more style arguments. * Producing more informative usage messages. From 3273f031039f0d70cd6bb96101b5e3c341f6dec4 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Wed, 2 Oct 2024 08:30:29 -0700 Subject: [PATCH 16/20] Update argparse.rst Co-authored-by: Tomas R --- 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 1b8e3677c84d77..2142cc6c272a32 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1573,7 +1573,7 @@ Sub-commands * dest_ - name of the attribute under which sub-command name will be stored; by default ``None`` and no value is stored - * required_ - Whether or not a sub-command must be provided, by default + * required_ - Whether or not a subcommand must be provided, by default ``False`` (added in 3.7) * help_ - help for sub-parser group in help output, by default ``None`` From f4395d19d73bc543b73a264fe24ed9d5c16ae455 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Wed, 2 Oct 2024 19:37:21 -0700 Subject: [PATCH 17/20] Address feedback --- Doc/library/argparse.rst | 194 +++++++++++++++++++-------------------- 1 file changed, 97 insertions(+), 97 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 2142cc6c272a32..7b7038c3b422db 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -19,13 +19,13 @@ introduction to Python command-line parsing, have a look at the :ref:`argparse tutorial `. -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` +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. The module will also issue errors when users give the program invalid arguments. -The :mod:`argparse` module's support for command-line interfaces is built +The :mod:`!argparse` module's support for command-line interfaces is built around an instance of :class:`argparse.ArgumentParser`. It is a container for argument specifications and has options that apply to the parser as whole:: @@ -327,7 +327,7 @@ should not be line-wrapped:: -h, --help show this help message and exit :class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text, -including argument descriptions. However, multiple new lines are replaced with +including argument descriptions. However, multiple newlines are replaced with one. If you wish to preserve multiple blank lines, add spaces between the newlines. @@ -421,8 +421,8 @@ arguments will never be treated as file references. .. versionchanged:: 3.12 :class:`ArgumentParser` changed encoding and errors to read arguments files - from default (e.g. :func:`locale.getpreferredencoding(False) ` and - ``"strict"``) to :term:`filesystem encoding and error handler`. + from default (e.g. :func:`locale.getpreferredencoding(False) ` + and ``"strict"``) to the :term:`filesystem encoding and error handler`. Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows. @@ -908,7 +908,7 @@ was not present at the command line:: Namespace(foo=42) If the target namespace already has an attribute set, the action *default* -will not over write it:: +will not overwrite it:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default=42) @@ -982,7 +982,6 @@ Common built-in types and functions can be used as type converters: parser.add_argument('distance', type=float) parser.add_argument('street', type=ascii) parser.add_argument('code_point', type=ord) - parser.add_argument('source_file', type=open) parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1')) parser.add_argument('datapath', type=pathlib.Path) @@ -1275,40 +1274,41 @@ this API may be passed as the ``action`` parameter to type=None, choices=None, required=False, help=None, \ metavar=None) -Action objects are used by an ArgumentParser to represent the information -needed to parse a single argument from one or more strings from the -command line. The Action class must accept the two positional arguments -plus any keyword arguments passed to :meth:`ArgumentParser.add_argument` -except for the ``action`` itself. + Action objects are used by an ArgumentParser to represent the information + needed to parse a single argument from one or more strings from the + command line. The Action class must accept the two positional arguments + plus any keyword arguments passed to :meth:`ArgumentParser.add_argument` + except for the ``action`` itself. -Instances of Action (or return value of any callable to the ``action`` -parameter) should have attributes "dest", "option_strings", "default", "type", -"required", "help", etc. defined. The easiest way to ensure these attributes -are defined is to call ``Action.__init__``. + Instances of Action (or return value of any callable to the ``action`` + parameter) should have attributes "dest", "option_strings", "default", "type", + "required", "help", etc. defined. The easiest way to ensure these attributes + are defined is to call ``Action.__init__``. -Action instances should be callable, so subclasses must override the -``__call__`` method, which should accept four parameters: + Action instances should be callable, so subclasses must override the + ``__call__`` method, which should accept four parameters: -* ``parser`` - The ArgumentParser object which contains this action. + * ``parser`` - The ArgumentParser object which contains this action. -* ``namespace`` - The :class:`Namespace` object that will be returned by - :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this - object using :func:`setattr`. + * ``namespace`` - The :class:`Namespace` object that will be returned by + :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this + object using :func:`setattr`. -* ``values`` - The associated command-line arguments, with any type conversions - applied. Type conversions are specified with the type_ keyword argument to - :meth:`~ArgumentParser.add_argument`. + * ``values`` - The associated command-line arguments, with any type conversions + applied. Type conversions are specified with the type_ keyword argument to + :meth:`~ArgumentParser.add_argument`. -* ``option_string`` - The option string that was used to invoke this action. - The ``option_string`` argument is optional, and will be absent if the action - is associated with a positional argument. + * ``option_string`` - The option string that was used to invoke this action. + The ``option_string`` argument is optional, and will be absent if the action + is associated with a positional argument. + + The ``__call__`` method may perform arbitrary actions, but will typically set + attributes on the ``namespace`` based on ``dest`` and ``values``. -The ``__call__`` method may perform arbitrary actions, but will typically set -attributes on the ``namespace`` based on ``dest`` and ``values``. + Action subclasses can define a ``format_usage`` method that takes no argument + and return a string which will be used when printing the usage of the program. + If such method is not provided, a sensible default will be used. -Action subclasses can define a ``format_usage`` method that takes no argument -and return a string which will be used when printing the usage of the program. -If such method is not provided, a sensible default will be used. The parse_args() method ----------------------- @@ -1503,29 +1503,29 @@ The Namespace object Simple class used by default by :meth:`~ArgumentParser.parse_args` to create an object holding attributes and return it. -This class is deliberately simple, just an :class:`object` subclass with a -readable string representation. If you prefer to have dict-like view of the -attributes, you can use the standard Python idiom, :func:`vars`:: + This class is deliberately simple, just an :class:`object` subclass with a + readable string representation. If you prefer to have dict-like view of the + attributes, you can use the standard Python idiom, :func:`vars`:: - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--foo') - >>> args = parser.parse_args(['--foo', 'BAR']) - >>> vars(args) - {'foo': 'BAR'} - -It may also be useful to have an :class:`ArgumentParser` assign attributes to an -already existing object, rather than a new :class:`Namespace` object. This can -be achieved by specifying the ``namespace=`` keyword argument:: - - >>> class C: - ... pass - ... - >>> c = C() - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--foo') - >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c) - >>> c.foo - 'BAR' + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo') + >>> args = parser.parse_args(['--foo', 'BAR']) + >>> vars(args) + {'foo': 'BAR'} + + It may also be useful to have an :class:`ArgumentParser` assign attributes to an + already existing object, rather than a new :class:`Namespace` object. This can + be achieved by specifying the ``namespace=`` keyword argument:: + + >>> class C: + ... pass + ... + >>> c = C() + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo') + >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c) + >>> c.foo + 'BAR' Other utilities @@ -1979,20 +1979,20 @@ Partial parsing .. method:: ArgumentParser.parse_known_args(args=None, namespace=None) -Sometimes a script may only parse a few of the command-line arguments, passing -the remaining arguments on to another script or program. In these cases, the -:meth:`~ArgumentParser.parse_known_args` method can be useful. It works much like -:meth:`~ArgumentParser.parse_args` except that it does not produce an error when -extra arguments are present. Instead, it returns a two item tuple containing -the populated namespace and the list of remaining argument strings. + Sometimes a script may only parse a few of the command-line arguments, passing + the remaining arguments on to another script or program. In these cases, the + :meth:`~ArgumentParser.parse_known_args` method can be useful. It works much like + :meth:`~ArgumentParser.parse_args` except that it does not produce an error when + extra arguments are present. Instead, it returns a two item tuple containing + the populated namespace and the list of remaining argument strings. -:: + :: - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--foo', action='store_true') - >>> parser.add_argument('bar') - >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam']) - (Namespace(bar='BAR', foo=True), ['--badger', 'spam']) + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo', action='store_true') + >>> parser.add_argument('bar') + >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam']) + (Namespace(bar='BAR', foo=True), ['--badger', 'spam']) .. warning:: :ref:`Prefix matching ` rules apply to @@ -2050,37 +2050,37 @@ Intermixed parsing .. method:: ArgumentParser.parse_intermixed_args(args=None, namespace=None) .. method:: ArgumentParser.parse_known_intermixed_args(args=None, namespace=None) -A number of Unix commands allow the user to intermix optional arguments with -positional arguments. The :meth:`~ArgumentParser.parse_intermixed_args` -and :meth:`~ArgumentParser.parse_known_intermixed_args` methods -support this parsing style. + A number of Unix commands allow the user to intermix optional arguments with + positional arguments. The :meth:`~ArgumentParser.parse_intermixed_args` + and :meth:`~ArgumentParser.parse_known_intermixed_args` methods + support this parsing style. -These parsers do not support all the argparse features, and will raise -exceptions if unsupported features are used. In particular, subparsers, -and mutually exclusive groups that include both -optionals and positionals are not supported. + These parsers do not support all the argparse features, and will raise + exceptions if unsupported features are used. In particular, subparsers, + and mutually exclusive groups that include both + optionals and positionals are not supported. -The following example shows the difference between -:meth:`~ArgumentParser.parse_known_args` and -:meth:`~ArgumentParser.parse_intermixed_args`: the former returns ``['2', -'3']`` as unparsed arguments, while the latter collects all the positionals -into ``rest``. :: + The following example shows the difference between + :meth:`~ArgumentParser.parse_known_args` and + :meth:`~ArgumentParser.parse_intermixed_args`: the former returns ``['2', + '3']`` as unparsed arguments, while the latter collects all the positionals + into ``rest``. :: - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--foo') - >>> parser.add_argument('cmd') - >>> parser.add_argument('rest', nargs='*', type=int) - >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split()) - (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3']) - >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split()) - Namespace(cmd='doit', foo='bar', rest=[1, 2, 3]) - -:meth:`~ArgumentParser.parse_known_intermixed_args` returns a two item tuple -containing the populated namespace and the list of remaining argument strings. -:meth:`~ArgumentParser.parse_intermixed_args` raises an error if there are any -remaining unparsed argument strings. - -.. versionadded:: 3.7 + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo') + >>> parser.add_argument('cmd') + >>> parser.add_argument('rest', nargs='*', type=int) + >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split()) + (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3']) + >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split()) + Namespace(cmd='doit', foo='bar', rest=[1, 2, 3]) + + :meth:`~ArgumentParser.parse_known_intermixed_args` returns a two item tuple + containing the populated namespace and the list of remaining argument strings. + :meth:`~ArgumentParser.parse_intermixed_args` raises an error if there are any + remaining unparsed argument strings. + + .. versionadded:: 3.7 Exceptions From 537684bc1493bc1874f548f6e418a291d0c71d93 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Wed, 2 Oct 2024 19:38:24 -0700 Subject: [PATCH 18/20] Run pre-commit --- 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 7b7038c3b422db..87c272335f9296 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -421,7 +421,7 @@ arguments will never be treated as file references. .. versionchanged:: 3.12 :class:`ArgumentParser` changed encoding and errors to read arguments files - from default (e.g. :func:`locale.getpreferredencoding(False) ` + from default (e.g. :func:`locale.getpreferredencoding(False) ` and ``"strict"``) to the :term:`filesystem encoding and error handler`. Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows. @@ -1298,10 +1298,10 @@ this API may be passed as the ``action`` parameter to applied. Type conversions are specified with the type_ keyword argument to :meth:`~ArgumentParser.add_argument`. - * ``option_string`` - The option string that was used to invoke this action. + * ``option_string`` - The option string that was used to invoke this action. The ``option_string`` argument is optional, and will be absent if the action is associated with a positional argument. - + The ``__call__`` method may perform arbitrary actions, but will typically set attributes on the ``namespace`` based on ``dest`` and ``values``. From f1e5e71e9eb8383f9d1aac835da28b72d894274e Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Wed, 2 Oct 2024 19:43:16 -0700 Subject: [PATCH 19/20] Remove formatting on params --- Doc/library/argparse.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 87c272335f9296..86001868d2e63b 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1012,10 +1012,11 @@ better reporting than can be given by the ``type`` keyword. A :exc:`FileNotFoundError` exception would not be handled at all. Even :class:`~argparse.FileType` has its limitations for use with the ``type`` -keyword. If one argument uses *FileType* and then a subsequent argument fails, -an error is reported but the file is not automatically closed. In this case, it -would be better to wait until after the parser has run and then use the -:keyword:`with`-statement to manage the files. +keyword. If one argument uses :class:`~argparse.FileType` and then a +subsequent argument fails, an error is reported but the file is not +automatically closed. In this case, it would be better to wait until after +the parser has run and then use the :keyword:`with`-statement to manage the +files. For type checkers that simply check against a fixed set of values, consider using the choices_ keyword instead. @@ -1288,17 +1289,17 @@ this API may be passed as the ``action`` parameter to Action instances should be callable, so subclasses must override the ``__call__`` method, which should accept four parameters: - * ``parser`` - The ArgumentParser object which contains this action. + * parser - The ArgumentParser object which contains this action. - * ``namespace`` - The :class:`Namespace` object that will be returned by + * namespace - The :class:`Namespace` object that will be returned by :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this object using :func:`setattr`. - * ``values`` - The associated command-line arguments, with any type conversions + * values - The associated command-line arguments, with any type conversions applied. Type conversions are specified with the type_ keyword argument to :meth:`~ArgumentParser.add_argument`. - * ``option_string`` - The option string that was used to invoke this action. + * option_string - The option string that was used to invoke this action. The ``option_string`` argument is optional, and will be absent if the action is associated with a positional argument. From 1c465051ad05339cfab3cb6295ceac395a775656 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Mon, 7 Oct 2024 08:57:45 -0600 Subject: [PATCH 20/20] Formatting for parameters --- Doc/library/argparse.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 86001868d2e63b..e9a08984f77c3a 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1289,17 +1289,17 @@ this API may be passed as the ``action`` parameter to Action instances should be callable, so subclasses must override the ``__call__`` method, which should accept four parameters: - * parser - The ArgumentParser object which contains this action. + * *parser* - The ArgumentParser object which contains this action. - * namespace - The :class:`Namespace` object that will be returned by + * *namespace* - The :class:`Namespace` object that will be returned by :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this object using :func:`setattr`. - * values - The associated command-line arguments, with any type conversions + * *values* - The associated command-line arguments, with any type conversions applied. Type conversions are specified with the type_ keyword argument to :meth:`~ArgumentParser.add_argument`. - * option_string - The option string that was used to invoke this action. + * *option_string* - The option string that was used to invoke this action. The ``option_string`` argument is optional, and will be absent if the action is associated with a positional argument. @@ -1554,18 +1554,18 @@ Sub-commands Description of parameters: - * title - title for the sub-parser group in help output; by default + * *title* - title for the sub-parser group in help output; by default "subcommands" if description is provided, otherwise uses title for positional arguments - * description - description for the sub-parser group in help output, by + * *description* - description for the sub-parser group in help output, by default ``None`` - * prog - usage information that will be displayed with sub-command help, + * *prog* - usage information that will be displayed with sub-command help, by default the name of the program and any positional arguments before the subparser argument - * parser_class - class which will be used to create sub-parser instances, by + * *parser_class* - class which will be used to create sub-parser instances, by default the class of the current parser (e.g. ArgumentParser) * action_ - the basic type of action to be taken when this argument is