17db96d56Sopenharmony_ci:mod:`argparse` --- Parser for command-line options, arguments and sub-commands
27db96d56Sopenharmony_ci===============================================================================
37db96d56Sopenharmony_ci
47db96d56Sopenharmony_ci.. module:: argparse
57db96d56Sopenharmony_ci   :synopsis: Command-line option and argument parsing library.
67db96d56Sopenharmony_ci
77db96d56Sopenharmony_ci.. moduleauthor:: Steven Bethard <steven.bethard@gmail.com>
87db96d56Sopenharmony_ci.. sectionauthor:: Steven Bethard <steven.bethard@gmail.com>
97db96d56Sopenharmony_ci
107db96d56Sopenharmony_ci.. versionadded:: 3.2
117db96d56Sopenharmony_ci
127db96d56Sopenharmony_ci**Source code:** :source:`Lib/argparse.py`
137db96d56Sopenharmony_ci
147db96d56Sopenharmony_ci--------------
157db96d56Sopenharmony_ci
167db96d56Sopenharmony_ci.. sidebar:: Tutorial
177db96d56Sopenharmony_ci
187db96d56Sopenharmony_ci   This page contains the API reference information. For a more gentle
197db96d56Sopenharmony_ci   introduction to Python command-line parsing, have a look at the
207db96d56Sopenharmony_ci   :ref:`argparse tutorial <argparse-tutorial>`.
217db96d56Sopenharmony_ci
227db96d56Sopenharmony_ciThe :mod:`argparse` module makes it easy to write user-friendly command-line
237db96d56Sopenharmony_ciinterfaces. The program defines what arguments it requires, and :mod:`argparse`
247db96d56Sopenharmony_ciwill figure out how to parse those out of :data:`sys.argv`.  The :mod:`argparse`
257db96d56Sopenharmony_cimodule also automatically generates help and usage messages.  The module
267db96d56Sopenharmony_ciwill also issue errors when users give the program invalid arguments.
277db96d56Sopenharmony_ci
287db96d56Sopenharmony_ci
297db96d56Sopenharmony_ciCore Functionality
307db96d56Sopenharmony_ci------------------
317db96d56Sopenharmony_ci
327db96d56Sopenharmony_ciThe :mod:`argparse` module's support for command-line interfaces is built
337db96d56Sopenharmony_ciaround an instance of :class:`argparse.ArgumentParser`.  It is a container for
347db96d56Sopenharmony_ciargument specifications and has options that apply the parser as whole::
357db96d56Sopenharmony_ci
367db96d56Sopenharmony_ci   parser = argparse.ArgumentParser(
377db96d56Sopenharmony_ci                       prog='ProgramName',
387db96d56Sopenharmony_ci                       description='What the program does',
397db96d56Sopenharmony_ci                       epilog='Text at the bottom of help')
407db96d56Sopenharmony_ci
417db96d56Sopenharmony_ciThe :meth:`ArgumentParser.add_argument` method attaches individual argument
427db96d56Sopenharmony_cispecifications to the parser.  It supports positional arguments, options that
437db96d56Sopenharmony_ciaccept values, and on/off flags::
447db96d56Sopenharmony_ci
457db96d56Sopenharmony_ci   parser.add_argument('filename')           # positional argument
467db96d56Sopenharmony_ci   parser.add_argument('-c', '--count')      # option that takes a value
477db96d56Sopenharmony_ci   parser.add_argument('-v', '--verbose',
487db96d56Sopenharmony_ci                       action='store_true')  # on/off flag
497db96d56Sopenharmony_ci
507db96d56Sopenharmony_ciThe :meth:`ArgumentParser.parse_args` method runs the parser and places
517db96d56Sopenharmony_cithe extracted data in a :class:`argparse.Namespace` object::
527db96d56Sopenharmony_ci
537db96d56Sopenharmony_ci   args = parser.parse_args()
547db96d56Sopenharmony_ci   print(args.filename, args.count, args.verbose)
557db96d56Sopenharmony_ci
567db96d56Sopenharmony_ci
577db96d56Sopenharmony_ciQuick Links for add_argument()
587db96d56Sopenharmony_ci------------------------------
597db96d56Sopenharmony_ci
607db96d56Sopenharmony_ci====================== =========================================================== ==========================================================================================================================
617db96d56Sopenharmony_ciName                   Description                                                 Values
627db96d56Sopenharmony_ci====================== =========================================================== ==========================================================================================================================
637db96d56Sopenharmony_ciaction_                Specify how an argument should be handled                   ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``'append_const'``, ``'count'``, ``'help'``, ``'version'``
647db96d56Sopenharmony_cichoices_               Limit values to a specific set of choices                   ``['foo', 'bar']``, ``range(1, 10)``, or :class:`~collections.abc.Container` instance
657db96d56Sopenharmony_ciconst_                 Store a constant value
667db96d56Sopenharmony_cidefault_               Default value used when an argument is not provided         Defaults to ``None``
677db96d56Sopenharmony_cidest_                  Specify the attribute name used in the result namespace
687db96d56Sopenharmony_cihelp_                  Help message for an argument
697db96d56Sopenharmony_cimetavar_               Alternate display name for the argument as shown in help
707db96d56Sopenharmony_cinargs_                 Number of times the argument can be used                    :class:`int`, ``'?'``, ``'*'``, or ``'+'``
717db96d56Sopenharmony_cirequired_              Indicate whether an argument is required or optional        ``True`` or ``False``
727db96d56Sopenharmony_citype_                  Automatically convert an argument to the given type         :class:`int`, :class:`float`, ``argparse.FileType('w')``, or callable function
737db96d56Sopenharmony_ci====================== =========================================================== ==========================================================================================================================
747db96d56Sopenharmony_ci
757db96d56Sopenharmony_ci
767db96d56Sopenharmony_ciExample
777db96d56Sopenharmony_ci-------
787db96d56Sopenharmony_ci
797db96d56Sopenharmony_ciThe following code is a Python program that takes a list of integers and
807db96d56Sopenharmony_ciproduces either the sum or the max::
817db96d56Sopenharmony_ci
827db96d56Sopenharmony_ci   import argparse
837db96d56Sopenharmony_ci
847db96d56Sopenharmony_ci   parser = argparse.ArgumentParser(description='Process some integers.')
857db96d56Sopenharmony_ci   parser.add_argument('integers', metavar='N', type=int, nargs='+',
867db96d56Sopenharmony_ci                       help='an integer for the accumulator')
877db96d56Sopenharmony_ci   parser.add_argument('--sum', dest='accumulate', action='store_const',
887db96d56Sopenharmony_ci                       const=sum, default=max,
897db96d56Sopenharmony_ci                       help='sum the integers (default: find the max)')
907db96d56Sopenharmony_ci
917db96d56Sopenharmony_ci   args = parser.parse_args()
927db96d56Sopenharmony_ci   print(args.accumulate(args.integers))
937db96d56Sopenharmony_ci
947db96d56Sopenharmony_ciAssuming the above Python code is saved into a file called ``prog.py``, it can
957db96d56Sopenharmony_cibe run at the command line and it provides useful help messages:
967db96d56Sopenharmony_ci
977db96d56Sopenharmony_ci.. code-block:: shell-session
987db96d56Sopenharmony_ci
997db96d56Sopenharmony_ci   $ python prog.py -h
1007db96d56Sopenharmony_ci   usage: prog.py [-h] [--sum] N [N ...]
1017db96d56Sopenharmony_ci
1027db96d56Sopenharmony_ci   Process some integers.
1037db96d56Sopenharmony_ci
1047db96d56Sopenharmony_ci   positional arguments:
1057db96d56Sopenharmony_ci    N           an integer for the accumulator
1067db96d56Sopenharmony_ci
1077db96d56Sopenharmony_ci   options:
1087db96d56Sopenharmony_ci    -h, --help  show this help message and exit
1097db96d56Sopenharmony_ci    --sum       sum the integers (default: find the max)
1107db96d56Sopenharmony_ci
1117db96d56Sopenharmony_ciWhen run with the appropriate arguments, it prints either the sum or the max of
1127db96d56Sopenharmony_cithe command-line integers:
1137db96d56Sopenharmony_ci
1147db96d56Sopenharmony_ci.. code-block:: shell-session
1157db96d56Sopenharmony_ci
1167db96d56Sopenharmony_ci   $ python prog.py 1 2 3 4
1177db96d56Sopenharmony_ci   4
1187db96d56Sopenharmony_ci
1197db96d56Sopenharmony_ci   $ python prog.py 1 2 3 4 --sum
1207db96d56Sopenharmony_ci   10
1217db96d56Sopenharmony_ci
1227db96d56Sopenharmony_ciIf invalid arguments are passed in, an error will be displayed:
1237db96d56Sopenharmony_ci
1247db96d56Sopenharmony_ci.. code-block:: shell-session
1257db96d56Sopenharmony_ci
1267db96d56Sopenharmony_ci   $ python prog.py a b c
1277db96d56Sopenharmony_ci   usage: prog.py [-h] [--sum] N [N ...]
1287db96d56Sopenharmony_ci   prog.py: error: argument N: invalid int value: 'a'
1297db96d56Sopenharmony_ci
1307db96d56Sopenharmony_ciThe following sections walk you through this example.
1317db96d56Sopenharmony_ci
1327db96d56Sopenharmony_ci
1337db96d56Sopenharmony_ciCreating a parser
1347db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^
1357db96d56Sopenharmony_ci
1367db96d56Sopenharmony_ciThe first step in using the :mod:`argparse` is creating an
1377db96d56Sopenharmony_ci:class:`ArgumentParser` object::
1387db96d56Sopenharmony_ci
1397db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(description='Process some integers.')
1407db96d56Sopenharmony_ci
1417db96d56Sopenharmony_ciThe :class:`ArgumentParser` object will hold all the information necessary to
1427db96d56Sopenharmony_ciparse the command line into Python data types.
1437db96d56Sopenharmony_ci
1447db96d56Sopenharmony_ci
1457db96d56Sopenharmony_ciAdding arguments
1467db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^
1477db96d56Sopenharmony_ci
1487db96d56Sopenharmony_ciFilling an :class:`ArgumentParser` with information about program arguments is
1497db96d56Sopenharmony_cidone by making calls to the :meth:`~ArgumentParser.add_argument` method.
1507db96d56Sopenharmony_ciGenerally, these calls tell the :class:`ArgumentParser` how to take the strings
1517db96d56Sopenharmony_cion the command line and turn them into objects.  This information is stored and
1527db96d56Sopenharmony_ciused when :meth:`~ArgumentParser.parse_args` is called. For example::
1537db96d56Sopenharmony_ci
1547db96d56Sopenharmony_ci   >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
1557db96d56Sopenharmony_ci   ...                     help='an integer for the accumulator')
1567db96d56Sopenharmony_ci   >>> parser.add_argument('--sum', dest='accumulate', action='store_const',
1577db96d56Sopenharmony_ci   ...                     const=sum, default=max,
1587db96d56Sopenharmony_ci   ...                     help='sum the integers (default: find the max)')
1597db96d56Sopenharmony_ci
1607db96d56Sopenharmony_ciLater, calling :meth:`~ArgumentParser.parse_args` will return an object with
1617db96d56Sopenharmony_citwo attributes, ``integers`` and ``accumulate``.  The ``integers`` attribute
1627db96d56Sopenharmony_ciwill be a list of one or more integers, and the ``accumulate`` attribute will be
1637db96d56Sopenharmony_cieither the :func:`sum` function, if ``--sum`` was specified at the command line,
1647db96d56Sopenharmony_cior the :func:`max` function if it was not.
1657db96d56Sopenharmony_ci
1667db96d56Sopenharmony_ci
1677db96d56Sopenharmony_ciParsing arguments
1687db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^
1697db96d56Sopenharmony_ci
1707db96d56Sopenharmony_ci:class:`ArgumentParser` parses arguments through the
1717db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_args` method.  This will inspect the command line,
1727db96d56Sopenharmony_ciconvert each argument to the appropriate type and then invoke the appropriate action.
1737db96d56Sopenharmony_ciIn most cases, this means a simple :class:`Namespace` object will be built up from
1747db96d56Sopenharmony_ciattributes parsed out of the command line::
1757db96d56Sopenharmony_ci
1767db96d56Sopenharmony_ci   >>> parser.parse_args(['--sum', '7', '-1', '42'])
1777db96d56Sopenharmony_ci   Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
1787db96d56Sopenharmony_ci
1797db96d56Sopenharmony_ciIn a script, :meth:`~ArgumentParser.parse_args` will typically be called with no
1807db96d56Sopenharmony_ciarguments, and the :class:`ArgumentParser` will automatically determine the
1817db96d56Sopenharmony_cicommand-line arguments from :data:`sys.argv`.
1827db96d56Sopenharmony_ci
1837db96d56Sopenharmony_ci
1847db96d56Sopenharmony_ciArgumentParser objects
1857db96d56Sopenharmony_ci----------------------
1867db96d56Sopenharmony_ci
1877db96d56Sopenharmony_ci.. class:: ArgumentParser(prog=None, usage=None, description=None, \
1887db96d56Sopenharmony_ci                          epilog=None, parents=[], \
1897db96d56Sopenharmony_ci                          formatter_class=argparse.HelpFormatter, \
1907db96d56Sopenharmony_ci                          prefix_chars='-', fromfile_prefix_chars=None, \
1917db96d56Sopenharmony_ci                          argument_default=None, conflict_handler='error', \
1927db96d56Sopenharmony_ci                          add_help=True, allow_abbrev=True, exit_on_error=True)
1937db96d56Sopenharmony_ci
1947db96d56Sopenharmony_ci   Create a new :class:`ArgumentParser` object. All parameters should be passed
1957db96d56Sopenharmony_ci   as keyword arguments. Each parameter has its own more detailed description
1967db96d56Sopenharmony_ci   below, but in short they are:
1977db96d56Sopenharmony_ci
1987db96d56Sopenharmony_ci   * prog_ - The name of the program (default:
1997db96d56Sopenharmony_ci     ``os.path.basename(sys.argv[0])``)
2007db96d56Sopenharmony_ci
2017db96d56Sopenharmony_ci   * usage_ - The string describing the program usage (default: generated from
2027db96d56Sopenharmony_ci     arguments added to parser)
2037db96d56Sopenharmony_ci
2047db96d56Sopenharmony_ci   * description_ - Text to display before the argument help
2057db96d56Sopenharmony_ci     (by default, no text)
2067db96d56Sopenharmony_ci
2077db96d56Sopenharmony_ci   * epilog_ - Text to display after the argument help (by default, no text)
2087db96d56Sopenharmony_ci
2097db96d56Sopenharmony_ci   * parents_ - A list of :class:`ArgumentParser` objects whose arguments should
2107db96d56Sopenharmony_ci     also be included
2117db96d56Sopenharmony_ci
2127db96d56Sopenharmony_ci   * formatter_class_ - A class for customizing the help output
2137db96d56Sopenharmony_ci
2147db96d56Sopenharmony_ci   * prefix_chars_ - The set of characters that prefix optional arguments
2157db96d56Sopenharmony_ci     (default: '-')
2167db96d56Sopenharmony_ci
2177db96d56Sopenharmony_ci   * fromfile_prefix_chars_ - The set of characters that prefix files from
2187db96d56Sopenharmony_ci     which additional arguments should be read (default: ``None``)
2197db96d56Sopenharmony_ci
2207db96d56Sopenharmony_ci   * argument_default_ - The global default value for arguments
2217db96d56Sopenharmony_ci     (default: ``None``)
2227db96d56Sopenharmony_ci
2237db96d56Sopenharmony_ci   * conflict_handler_ - The strategy for resolving conflicting optionals
2247db96d56Sopenharmony_ci     (usually unnecessary)
2257db96d56Sopenharmony_ci
2267db96d56Sopenharmony_ci   * add_help_ - Add a ``-h/--help`` option to the parser (default: ``True``)
2277db96d56Sopenharmony_ci
2287db96d56Sopenharmony_ci   * allow_abbrev_ - Allows long options to be abbreviated if the
2297db96d56Sopenharmony_ci     abbreviation is unambiguous. (default: ``True``)
2307db96d56Sopenharmony_ci
2317db96d56Sopenharmony_ci   * exit_on_error_ - Determines whether or not ArgumentParser exits with
2327db96d56Sopenharmony_ci     error info when an error occurs. (default: ``True``)
2337db96d56Sopenharmony_ci
2347db96d56Sopenharmony_ci   .. versionchanged:: 3.5
2357db96d56Sopenharmony_ci      *allow_abbrev* parameter was added.
2367db96d56Sopenharmony_ci
2377db96d56Sopenharmony_ci   .. versionchanged:: 3.8
2387db96d56Sopenharmony_ci      In previous versions, *allow_abbrev* also disabled grouping of short
2397db96d56Sopenharmony_ci      flags such as ``-vv`` to mean ``-v -v``.
2407db96d56Sopenharmony_ci
2417db96d56Sopenharmony_ci   .. versionchanged:: 3.9
2427db96d56Sopenharmony_ci      *exit_on_error* parameter was added.
2437db96d56Sopenharmony_ci
2447db96d56Sopenharmony_ciThe following sections describe how each of these are used.
2457db96d56Sopenharmony_ci
2467db96d56Sopenharmony_ci
2477db96d56Sopenharmony_ci.. _prog:
2487db96d56Sopenharmony_ci
2497db96d56Sopenharmony_ciprog
2507db96d56Sopenharmony_ci^^^^
2517db96d56Sopenharmony_ci
2527db96d56Sopenharmony_ciBy default, :class:`ArgumentParser` objects use ``sys.argv[0]`` to determine
2537db96d56Sopenharmony_cihow to display the name of the program in help messages.  This default is almost
2547db96d56Sopenharmony_cialways desirable because it will make the help messages match how the program was
2557db96d56Sopenharmony_ciinvoked on the command line.  For example, consider a file named
2567db96d56Sopenharmony_ci``myprogram.py`` with the following code::
2577db96d56Sopenharmony_ci
2587db96d56Sopenharmony_ci   import argparse
2597db96d56Sopenharmony_ci   parser = argparse.ArgumentParser()
2607db96d56Sopenharmony_ci   parser.add_argument('--foo', help='foo help')
2617db96d56Sopenharmony_ci   args = parser.parse_args()
2627db96d56Sopenharmony_ci
2637db96d56Sopenharmony_ciThe help for this program will display ``myprogram.py`` as the program name
2647db96d56Sopenharmony_ci(regardless of where the program was invoked from):
2657db96d56Sopenharmony_ci
2667db96d56Sopenharmony_ci.. code-block:: shell-session
2677db96d56Sopenharmony_ci
2687db96d56Sopenharmony_ci   $ python myprogram.py --help
2697db96d56Sopenharmony_ci   usage: myprogram.py [-h] [--foo FOO]
2707db96d56Sopenharmony_ci
2717db96d56Sopenharmony_ci   options:
2727db96d56Sopenharmony_ci    -h, --help  show this help message and exit
2737db96d56Sopenharmony_ci    --foo FOO   foo help
2747db96d56Sopenharmony_ci   $ cd ..
2757db96d56Sopenharmony_ci   $ python subdir/myprogram.py --help
2767db96d56Sopenharmony_ci   usage: myprogram.py [-h] [--foo FOO]
2777db96d56Sopenharmony_ci
2787db96d56Sopenharmony_ci   options:
2797db96d56Sopenharmony_ci    -h, --help  show this help message and exit
2807db96d56Sopenharmony_ci    --foo FOO   foo help
2817db96d56Sopenharmony_ci
2827db96d56Sopenharmony_ciTo change this default behavior, another value can be supplied using the
2837db96d56Sopenharmony_ci``prog=`` argument to :class:`ArgumentParser`::
2847db96d56Sopenharmony_ci
2857db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='myprogram')
2867db96d56Sopenharmony_ci   >>> parser.print_help()
2877db96d56Sopenharmony_ci   usage: myprogram [-h]
2887db96d56Sopenharmony_ci
2897db96d56Sopenharmony_ci   options:
2907db96d56Sopenharmony_ci    -h, --help  show this help message and exit
2917db96d56Sopenharmony_ci
2927db96d56Sopenharmony_ciNote that the program name, whether determined from ``sys.argv[0]`` or from the
2937db96d56Sopenharmony_ci``prog=`` argument, is available to help messages using the ``%(prog)s`` format
2947db96d56Sopenharmony_cispecifier.
2957db96d56Sopenharmony_ci
2967db96d56Sopenharmony_ci::
2977db96d56Sopenharmony_ci
2987db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='myprogram')
2997db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
3007db96d56Sopenharmony_ci   >>> parser.print_help()
3017db96d56Sopenharmony_ci   usage: myprogram [-h] [--foo FOO]
3027db96d56Sopenharmony_ci
3037db96d56Sopenharmony_ci   options:
3047db96d56Sopenharmony_ci    -h, --help  show this help message and exit
3057db96d56Sopenharmony_ci    --foo FOO   foo of the myprogram program
3067db96d56Sopenharmony_ci
3077db96d56Sopenharmony_ci
3087db96d56Sopenharmony_ciusage
3097db96d56Sopenharmony_ci^^^^^
3107db96d56Sopenharmony_ci
3117db96d56Sopenharmony_ciBy default, :class:`ArgumentParser` calculates the usage message from the
3127db96d56Sopenharmony_ciarguments it contains::
3137db96d56Sopenharmony_ci
3147db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
3157db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', nargs='?', help='foo help')
3167db96d56Sopenharmony_ci   >>> parser.add_argument('bar', nargs='+', help='bar help')
3177db96d56Sopenharmony_ci   >>> parser.print_help()
3187db96d56Sopenharmony_ci   usage: PROG [-h] [--foo [FOO]] bar [bar ...]
3197db96d56Sopenharmony_ci
3207db96d56Sopenharmony_ci   positional arguments:
3217db96d56Sopenharmony_ci    bar          bar help
3227db96d56Sopenharmony_ci
3237db96d56Sopenharmony_ci   options:
3247db96d56Sopenharmony_ci    -h, --help   show this help message and exit
3257db96d56Sopenharmony_ci    --foo [FOO]  foo help
3267db96d56Sopenharmony_ci
3277db96d56Sopenharmony_ciThe default message can be overridden with the ``usage=`` keyword argument::
3287db96d56Sopenharmony_ci
3297db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
3307db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', nargs='?', help='foo help')
3317db96d56Sopenharmony_ci   >>> parser.add_argument('bar', nargs='+', help='bar help')
3327db96d56Sopenharmony_ci   >>> parser.print_help()
3337db96d56Sopenharmony_ci   usage: PROG [options]
3347db96d56Sopenharmony_ci
3357db96d56Sopenharmony_ci   positional arguments:
3367db96d56Sopenharmony_ci    bar          bar help
3377db96d56Sopenharmony_ci
3387db96d56Sopenharmony_ci   options:
3397db96d56Sopenharmony_ci    -h, --help   show this help message and exit
3407db96d56Sopenharmony_ci    --foo [FOO]  foo help
3417db96d56Sopenharmony_ci
3427db96d56Sopenharmony_ciThe ``%(prog)s`` format specifier is available to fill in the program name in
3437db96d56Sopenharmony_ciyour usage messages.
3447db96d56Sopenharmony_ci
3457db96d56Sopenharmony_ci
3467db96d56Sopenharmony_ci.. _description:
3477db96d56Sopenharmony_ci
3487db96d56Sopenharmony_cidescription
3497db96d56Sopenharmony_ci^^^^^^^^^^^
3507db96d56Sopenharmony_ci
3517db96d56Sopenharmony_ciMost calls to the :class:`ArgumentParser` constructor will use the
3527db96d56Sopenharmony_ci``description=`` keyword argument.  This argument gives a brief description of
3537db96d56Sopenharmony_ciwhat the program does and how it works.  In help messages, the description is
3547db96d56Sopenharmony_cidisplayed between the command-line usage string and the help messages for the
3557db96d56Sopenharmony_civarious arguments::
3567db96d56Sopenharmony_ci
3577db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(description='A foo that bars')
3587db96d56Sopenharmony_ci   >>> parser.print_help()
3597db96d56Sopenharmony_ci   usage: argparse.py [-h]
3607db96d56Sopenharmony_ci
3617db96d56Sopenharmony_ci   A foo that bars
3627db96d56Sopenharmony_ci
3637db96d56Sopenharmony_ci   options:
3647db96d56Sopenharmony_ci    -h, --help  show this help message and exit
3657db96d56Sopenharmony_ci
3667db96d56Sopenharmony_ciBy default, the description will be line-wrapped so that it fits within the
3677db96d56Sopenharmony_cigiven space.  To change this behavior, see the formatter_class_ argument.
3687db96d56Sopenharmony_ci
3697db96d56Sopenharmony_ci
3707db96d56Sopenharmony_ciepilog
3717db96d56Sopenharmony_ci^^^^^^
3727db96d56Sopenharmony_ci
3737db96d56Sopenharmony_ciSome programs like to display additional description of the program after the
3747db96d56Sopenharmony_cidescription of the arguments.  Such text can be specified using the ``epilog=``
3757db96d56Sopenharmony_ciargument to :class:`ArgumentParser`::
3767db96d56Sopenharmony_ci
3777db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(
3787db96d56Sopenharmony_ci   ...     description='A foo that bars',
3797db96d56Sopenharmony_ci   ...     epilog="And that's how you'd foo a bar")
3807db96d56Sopenharmony_ci   >>> parser.print_help()
3817db96d56Sopenharmony_ci   usage: argparse.py [-h]
3827db96d56Sopenharmony_ci
3837db96d56Sopenharmony_ci   A foo that bars
3847db96d56Sopenharmony_ci
3857db96d56Sopenharmony_ci   options:
3867db96d56Sopenharmony_ci    -h, --help  show this help message and exit
3877db96d56Sopenharmony_ci
3887db96d56Sopenharmony_ci   And that's how you'd foo a bar
3897db96d56Sopenharmony_ci
3907db96d56Sopenharmony_ciAs with the description_ argument, the ``epilog=`` text is by default
3917db96d56Sopenharmony_ciline-wrapped, but this behavior can be adjusted with the formatter_class_
3927db96d56Sopenharmony_ciargument to :class:`ArgumentParser`.
3937db96d56Sopenharmony_ci
3947db96d56Sopenharmony_ci
3957db96d56Sopenharmony_ciparents
3967db96d56Sopenharmony_ci^^^^^^^
3977db96d56Sopenharmony_ci
3987db96d56Sopenharmony_ciSometimes, several parsers share a common set of arguments. Rather than
3997db96d56Sopenharmony_cirepeating the definitions of these arguments, a single parser with all the
4007db96d56Sopenharmony_cishared arguments and passed to ``parents=`` argument to :class:`ArgumentParser`
4017db96d56Sopenharmony_cican be used.  The ``parents=`` argument takes a list of :class:`ArgumentParser`
4027db96d56Sopenharmony_ciobjects, collects all the positional and optional actions from them, and adds
4037db96d56Sopenharmony_cithese actions to the :class:`ArgumentParser` object being constructed::
4047db96d56Sopenharmony_ci
4057db96d56Sopenharmony_ci   >>> parent_parser = argparse.ArgumentParser(add_help=False)
4067db96d56Sopenharmony_ci   >>> parent_parser.add_argument('--parent', type=int)
4077db96d56Sopenharmony_ci
4087db96d56Sopenharmony_ci   >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
4097db96d56Sopenharmony_ci   >>> foo_parser.add_argument('foo')
4107db96d56Sopenharmony_ci   >>> foo_parser.parse_args(['--parent', '2', 'XXX'])
4117db96d56Sopenharmony_ci   Namespace(foo='XXX', parent=2)
4127db96d56Sopenharmony_ci
4137db96d56Sopenharmony_ci   >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
4147db96d56Sopenharmony_ci   >>> bar_parser.add_argument('--bar')
4157db96d56Sopenharmony_ci   >>> bar_parser.parse_args(['--bar', 'YYY'])
4167db96d56Sopenharmony_ci   Namespace(bar='YYY', parent=None)
4177db96d56Sopenharmony_ci
4187db96d56Sopenharmony_ciNote that most parent parsers will specify ``add_help=False``.  Otherwise, the
4197db96d56Sopenharmony_ci:class:`ArgumentParser` will see two ``-h/--help`` options (one in the parent
4207db96d56Sopenharmony_ciand one in the child) and raise an error.
4217db96d56Sopenharmony_ci
4227db96d56Sopenharmony_ci.. note::
4237db96d56Sopenharmony_ci   You must fully initialize the parsers before passing them via ``parents=``.
4247db96d56Sopenharmony_ci   If you change the parent parsers after the child parser, those changes will
4257db96d56Sopenharmony_ci   not be reflected in the child.
4267db96d56Sopenharmony_ci
4277db96d56Sopenharmony_ci
4287db96d56Sopenharmony_ci.. _formatter_class:
4297db96d56Sopenharmony_ci
4307db96d56Sopenharmony_ciformatter_class
4317db96d56Sopenharmony_ci^^^^^^^^^^^^^^^
4327db96d56Sopenharmony_ci
4337db96d56Sopenharmony_ci:class:`ArgumentParser` objects allow the help formatting to be customized by
4347db96d56Sopenharmony_cispecifying an alternate formatting class.  Currently, there are four such
4357db96d56Sopenharmony_ciclasses:
4367db96d56Sopenharmony_ci
4377db96d56Sopenharmony_ci.. class:: RawDescriptionHelpFormatter
4387db96d56Sopenharmony_ci           RawTextHelpFormatter
4397db96d56Sopenharmony_ci           ArgumentDefaultsHelpFormatter
4407db96d56Sopenharmony_ci           MetavarTypeHelpFormatter
4417db96d56Sopenharmony_ci
4427db96d56Sopenharmony_ci:class:`RawDescriptionHelpFormatter` and :class:`RawTextHelpFormatter` give
4437db96d56Sopenharmony_cimore control over how textual descriptions are displayed.
4447db96d56Sopenharmony_ciBy default, :class:`ArgumentParser` objects line-wrap the description_ and
4457db96d56Sopenharmony_ciepilog_ texts in command-line help messages::
4467db96d56Sopenharmony_ci
4477db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(
4487db96d56Sopenharmony_ci   ...     prog='PROG',
4497db96d56Sopenharmony_ci   ...     description='''this description
4507db96d56Sopenharmony_ci   ...         was indented weird
4517db96d56Sopenharmony_ci   ...             but that is okay''',
4527db96d56Sopenharmony_ci   ...     epilog='''
4537db96d56Sopenharmony_ci   ...             likewise for this epilog whose whitespace will
4547db96d56Sopenharmony_ci   ...         be cleaned up and whose words will be wrapped
4557db96d56Sopenharmony_ci   ...         across a couple lines''')
4567db96d56Sopenharmony_ci   >>> parser.print_help()
4577db96d56Sopenharmony_ci   usage: PROG [-h]
4587db96d56Sopenharmony_ci
4597db96d56Sopenharmony_ci   this description was indented weird but that is okay
4607db96d56Sopenharmony_ci
4617db96d56Sopenharmony_ci   options:
4627db96d56Sopenharmony_ci    -h, --help  show this help message and exit
4637db96d56Sopenharmony_ci
4647db96d56Sopenharmony_ci   likewise for this epilog whose whitespace will be cleaned up and whose words
4657db96d56Sopenharmony_ci   will be wrapped across a couple lines
4667db96d56Sopenharmony_ci
4677db96d56Sopenharmony_ciPassing :class:`RawDescriptionHelpFormatter` as ``formatter_class=``
4687db96d56Sopenharmony_ciindicates that description_ and epilog_ are already correctly formatted and
4697db96d56Sopenharmony_cishould not be line-wrapped::
4707db96d56Sopenharmony_ci
4717db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(
4727db96d56Sopenharmony_ci   ...     prog='PROG',
4737db96d56Sopenharmony_ci   ...     formatter_class=argparse.RawDescriptionHelpFormatter,
4747db96d56Sopenharmony_ci   ...     description=textwrap.dedent('''\
4757db96d56Sopenharmony_ci   ...         Please do not mess up this text!
4767db96d56Sopenharmony_ci   ...         --------------------------------
4777db96d56Sopenharmony_ci   ...             I have indented it
4787db96d56Sopenharmony_ci   ...             exactly the way
4797db96d56Sopenharmony_ci   ...             I want it
4807db96d56Sopenharmony_ci   ...         '''))
4817db96d56Sopenharmony_ci   >>> parser.print_help()
4827db96d56Sopenharmony_ci   usage: PROG [-h]
4837db96d56Sopenharmony_ci
4847db96d56Sopenharmony_ci   Please do not mess up this text!
4857db96d56Sopenharmony_ci   --------------------------------
4867db96d56Sopenharmony_ci      I have indented it
4877db96d56Sopenharmony_ci      exactly the way
4887db96d56Sopenharmony_ci      I want it
4897db96d56Sopenharmony_ci
4907db96d56Sopenharmony_ci   options:
4917db96d56Sopenharmony_ci    -h, --help  show this help message and exit
4927db96d56Sopenharmony_ci
4937db96d56Sopenharmony_ci:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
4947db96d56Sopenharmony_ciincluding argument descriptions. However, multiple new lines are replaced with
4957db96d56Sopenharmony_cione. If you wish to preserve multiple blank lines, add spaces between the
4967db96d56Sopenharmony_cinewlines.
4977db96d56Sopenharmony_ci
4987db96d56Sopenharmony_ci:class:`ArgumentDefaultsHelpFormatter` automatically adds information about
4997db96d56Sopenharmony_cidefault values to each of the argument help messages::
5007db96d56Sopenharmony_ci
5017db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(
5027db96d56Sopenharmony_ci   ...     prog='PROG',
5037db96d56Sopenharmony_ci   ...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
5047db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
5057db96d56Sopenharmony_ci   >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
5067db96d56Sopenharmony_ci   >>> parser.print_help()
5077db96d56Sopenharmony_ci   usage: PROG [-h] [--foo FOO] [bar ...]
5087db96d56Sopenharmony_ci
5097db96d56Sopenharmony_ci   positional arguments:
5107db96d56Sopenharmony_ci    bar         BAR! (default: [1, 2, 3])
5117db96d56Sopenharmony_ci
5127db96d56Sopenharmony_ci   options:
5137db96d56Sopenharmony_ci    -h, --help  show this help message and exit
5147db96d56Sopenharmony_ci    --foo FOO   FOO! (default: 42)
5157db96d56Sopenharmony_ci
5167db96d56Sopenharmony_ci:class:`MetavarTypeHelpFormatter` uses the name of the type_ argument for each
5177db96d56Sopenharmony_ciargument as the display name for its values (rather than using the dest_
5187db96d56Sopenharmony_cias the regular formatter does)::
5197db96d56Sopenharmony_ci
5207db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(
5217db96d56Sopenharmony_ci   ...     prog='PROG',
5227db96d56Sopenharmony_ci   ...     formatter_class=argparse.MetavarTypeHelpFormatter)
5237db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', type=int)
5247db96d56Sopenharmony_ci   >>> parser.add_argument('bar', type=float)
5257db96d56Sopenharmony_ci   >>> parser.print_help()
5267db96d56Sopenharmony_ci   usage: PROG [-h] [--foo int] float
5277db96d56Sopenharmony_ci
5287db96d56Sopenharmony_ci   positional arguments:
5297db96d56Sopenharmony_ci     float
5307db96d56Sopenharmony_ci
5317db96d56Sopenharmony_ci   options:
5327db96d56Sopenharmony_ci     -h, --help  show this help message and exit
5337db96d56Sopenharmony_ci     --foo int
5347db96d56Sopenharmony_ci
5357db96d56Sopenharmony_ci
5367db96d56Sopenharmony_ciprefix_chars
5377db96d56Sopenharmony_ci^^^^^^^^^^^^
5387db96d56Sopenharmony_ci
5397db96d56Sopenharmony_ciMost command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
5407db96d56Sopenharmony_ciParsers that need to support different or additional prefix
5417db96d56Sopenharmony_cicharacters, e.g. for options
5427db96d56Sopenharmony_cilike ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
5437db96d56Sopenharmony_cito the ArgumentParser constructor::
5447db96d56Sopenharmony_ci
5457db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
5467db96d56Sopenharmony_ci   >>> parser.add_argument('+f')
5477db96d56Sopenharmony_ci   >>> parser.add_argument('++bar')
5487db96d56Sopenharmony_ci   >>> parser.parse_args('+f X ++bar Y'.split())
5497db96d56Sopenharmony_ci   Namespace(bar='Y', f='X')
5507db96d56Sopenharmony_ci
5517db96d56Sopenharmony_ciThe ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of
5527db96d56Sopenharmony_cicharacters that does not include ``-`` will cause ``-f/--foo`` options to be
5537db96d56Sopenharmony_cidisallowed.
5547db96d56Sopenharmony_ci
5557db96d56Sopenharmony_ci
5567db96d56Sopenharmony_cifromfile_prefix_chars
5577db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^
5587db96d56Sopenharmony_ci
5597db96d56Sopenharmony_ciSometimes, when dealing with a particularly long argument list, it
5607db96d56Sopenharmony_cimay make sense to keep the list of arguments in a file rather than typing it out
5617db96d56Sopenharmony_ciat the command line.  If the ``fromfile_prefix_chars=`` argument is given to the
5627db96d56Sopenharmony_ci:class:`ArgumentParser` constructor, then arguments that start with any of the
5637db96d56Sopenharmony_cispecified characters will be treated as files, and will be replaced by the
5647db96d56Sopenharmony_ciarguments they contain.  For example::
5657db96d56Sopenharmony_ci
5667db96d56Sopenharmony_ci   >>> with open('args.txt', 'w') as fp:
5677db96d56Sopenharmony_ci   ...     fp.write('-f\nbar')
5687db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
5697db96d56Sopenharmony_ci   >>> parser.add_argument('-f')
5707db96d56Sopenharmony_ci   >>> parser.parse_args(['-f', 'foo', '@args.txt'])
5717db96d56Sopenharmony_ci   Namespace(f='bar')
5727db96d56Sopenharmony_ci
5737db96d56Sopenharmony_ciArguments read from a file must by default be one per line (but see also
5747db96d56Sopenharmony_ci:meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they
5757db96d56Sopenharmony_ciwere in the same place as the original file referencing argument on the command
5767db96d56Sopenharmony_ciline.  So in the example above, the expression ``['-f', 'foo', '@args.txt']``
5777db96d56Sopenharmony_ciis considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
5787db96d56Sopenharmony_ci
5797db96d56Sopenharmony_ciThe ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
5807db96d56Sopenharmony_ciarguments will never be treated as file references.
5817db96d56Sopenharmony_ci
5827db96d56Sopenharmony_ci
5837db96d56Sopenharmony_ciargument_default
5847db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^
5857db96d56Sopenharmony_ci
5867db96d56Sopenharmony_ciGenerally, argument defaults are specified either by passing a default to
5877db96d56Sopenharmony_ci:meth:`~ArgumentParser.add_argument` or by calling the
5887db96d56Sopenharmony_ci:meth:`~ArgumentParser.set_defaults` methods with a specific set of name-value
5897db96d56Sopenharmony_cipairs.  Sometimes however, it may be useful to specify a single parser-wide
5907db96d56Sopenharmony_cidefault for arguments.  This can be accomplished by passing the
5917db96d56Sopenharmony_ci``argument_default=`` keyword argument to :class:`ArgumentParser`.  For example,
5927db96d56Sopenharmony_cito globally suppress attribute creation on :meth:`~ArgumentParser.parse_args`
5937db96d56Sopenharmony_cicalls, we supply ``argument_default=SUPPRESS``::
5947db96d56Sopenharmony_ci
5957db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
5967db96d56Sopenharmony_ci   >>> parser.add_argument('--foo')
5977db96d56Sopenharmony_ci   >>> parser.add_argument('bar', nargs='?')
5987db96d56Sopenharmony_ci   >>> parser.parse_args(['--foo', '1', 'BAR'])
5997db96d56Sopenharmony_ci   Namespace(bar='BAR', foo='1')
6007db96d56Sopenharmony_ci   >>> parser.parse_args([])
6017db96d56Sopenharmony_ci   Namespace()
6027db96d56Sopenharmony_ci
6037db96d56Sopenharmony_ci.. _allow_abbrev:
6047db96d56Sopenharmony_ci
6057db96d56Sopenharmony_ciallow_abbrev
6067db96d56Sopenharmony_ci^^^^^^^^^^^^
6077db96d56Sopenharmony_ci
6087db96d56Sopenharmony_ciNormally, when you pass an argument list to the
6097db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_args` method of an :class:`ArgumentParser`,
6107db96d56Sopenharmony_ciit :ref:`recognizes abbreviations <prefix-matching>` of long options.
6117db96d56Sopenharmony_ci
6127db96d56Sopenharmony_ciThis feature can be disabled by setting ``allow_abbrev`` to ``False``::
6137db96d56Sopenharmony_ci
6147db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
6157db96d56Sopenharmony_ci   >>> parser.add_argument('--foobar', action='store_true')
6167db96d56Sopenharmony_ci   >>> parser.add_argument('--foonley', action='store_false')
6177db96d56Sopenharmony_ci   >>> parser.parse_args(['--foon'])
6187db96d56Sopenharmony_ci   usage: PROG [-h] [--foobar] [--foonley]
6197db96d56Sopenharmony_ci   PROG: error: unrecognized arguments: --foon
6207db96d56Sopenharmony_ci
6217db96d56Sopenharmony_ci.. versionadded:: 3.5
6227db96d56Sopenharmony_ci
6237db96d56Sopenharmony_ci
6247db96d56Sopenharmony_ciconflict_handler
6257db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^
6267db96d56Sopenharmony_ci
6277db96d56Sopenharmony_ci:class:`ArgumentParser` objects do not allow two actions with the same option
6287db96d56Sopenharmony_cistring.  By default, :class:`ArgumentParser` objects raise an exception if an
6297db96d56Sopenharmony_ciattempt is made to create an argument with an option string that is already in
6307db96d56Sopenharmony_ciuse::
6317db96d56Sopenharmony_ci
6327db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
6337db96d56Sopenharmony_ci   >>> parser.add_argument('-f', '--foo', help='old foo help')
6347db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', help='new foo help')
6357db96d56Sopenharmony_ci   Traceback (most recent call last):
6367db96d56Sopenharmony_ci    ..
6377db96d56Sopenharmony_ci   ArgumentError: argument --foo: conflicting option string(s): --foo
6387db96d56Sopenharmony_ci
6397db96d56Sopenharmony_ciSometimes (e.g. when using parents_) it may be useful to simply override any
6407db96d56Sopenharmony_ciolder arguments with the same option string.  To get this behavior, the value
6417db96d56Sopenharmony_ci``'resolve'`` can be supplied to the ``conflict_handler=`` argument of
6427db96d56Sopenharmony_ci:class:`ArgumentParser`::
6437db96d56Sopenharmony_ci
6447db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
6457db96d56Sopenharmony_ci   >>> parser.add_argument('-f', '--foo', help='old foo help')
6467db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', help='new foo help')
6477db96d56Sopenharmony_ci   >>> parser.print_help()
6487db96d56Sopenharmony_ci   usage: PROG [-h] [-f FOO] [--foo FOO]
6497db96d56Sopenharmony_ci
6507db96d56Sopenharmony_ci   options:
6517db96d56Sopenharmony_ci    -h, --help  show this help message and exit
6527db96d56Sopenharmony_ci    -f FOO      old foo help
6537db96d56Sopenharmony_ci    --foo FOO   new foo help
6547db96d56Sopenharmony_ci
6557db96d56Sopenharmony_ciNote that :class:`ArgumentParser` objects only remove an action if all of its
6567db96d56Sopenharmony_cioption strings are overridden.  So, in the example above, the old ``-f/--foo``
6577db96d56Sopenharmony_ciaction is retained as the ``-f`` action, because only the ``--foo`` option
6587db96d56Sopenharmony_cistring was overridden.
6597db96d56Sopenharmony_ci
6607db96d56Sopenharmony_ci
6617db96d56Sopenharmony_ciadd_help
6627db96d56Sopenharmony_ci^^^^^^^^
6637db96d56Sopenharmony_ci
6647db96d56Sopenharmony_ciBy default, ArgumentParser objects add an option which simply displays
6657db96d56Sopenharmony_cithe parser's help message. For example, consider a file named
6667db96d56Sopenharmony_ci``myprogram.py`` containing the following code::
6677db96d56Sopenharmony_ci
6687db96d56Sopenharmony_ci   import argparse
6697db96d56Sopenharmony_ci   parser = argparse.ArgumentParser()
6707db96d56Sopenharmony_ci   parser.add_argument('--foo', help='foo help')
6717db96d56Sopenharmony_ci   args = parser.parse_args()
6727db96d56Sopenharmony_ci
6737db96d56Sopenharmony_ciIf ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
6747db96d56Sopenharmony_cihelp will be printed:
6757db96d56Sopenharmony_ci
6767db96d56Sopenharmony_ci.. code-block:: shell-session
6777db96d56Sopenharmony_ci
6787db96d56Sopenharmony_ci   $ python myprogram.py --help
6797db96d56Sopenharmony_ci   usage: myprogram.py [-h] [--foo FOO]
6807db96d56Sopenharmony_ci
6817db96d56Sopenharmony_ci   options:
6827db96d56Sopenharmony_ci    -h, --help  show this help message and exit
6837db96d56Sopenharmony_ci    --foo FOO   foo help
6847db96d56Sopenharmony_ci
6857db96d56Sopenharmony_ciOccasionally, it may be useful to disable the addition of this help option.
6867db96d56Sopenharmony_ciThis can be achieved by passing ``False`` as the ``add_help=`` argument to
6877db96d56Sopenharmony_ci:class:`ArgumentParser`::
6887db96d56Sopenharmony_ci
6897db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
6907db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', help='foo help')
6917db96d56Sopenharmony_ci   >>> parser.print_help()
6927db96d56Sopenharmony_ci   usage: PROG [--foo FOO]
6937db96d56Sopenharmony_ci
6947db96d56Sopenharmony_ci   options:
6957db96d56Sopenharmony_ci    --foo FOO  foo help
6967db96d56Sopenharmony_ci
6977db96d56Sopenharmony_ciThe help option is typically ``-h/--help``. The exception to this is
6987db96d56Sopenharmony_ciif the ``prefix_chars=`` is specified and does not include ``-``, in
6997db96d56Sopenharmony_ciwhich case ``-h`` and ``--help`` are not valid options.  In
7007db96d56Sopenharmony_cithis case, the first character in ``prefix_chars`` is used to prefix
7017db96d56Sopenharmony_cithe help options::
7027db96d56Sopenharmony_ci
7037db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
7047db96d56Sopenharmony_ci   >>> parser.print_help()
7057db96d56Sopenharmony_ci   usage: PROG [+h]
7067db96d56Sopenharmony_ci
7077db96d56Sopenharmony_ci   options:
7087db96d56Sopenharmony_ci     +h, ++help  show this help message and exit
7097db96d56Sopenharmony_ci
7107db96d56Sopenharmony_ci
7117db96d56Sopenharmony_ciexit_on_error
7127db96d56Sopenharmony_ci^^^^^^^^^^^^^
7137db96d56Sopenharmony_ci
7147db96d56Sopenharmony_ciNormally, when you pass an invalid argument list to the :meth:`~ArgumentParser.parse_args`
7157db96d56Sopenharmony_cimethod of an :class:`ArgumentParser`, it will exit with error info.
7167db96d56Sopenharmony_ci
7177db96d56Sopenharmony_ciIf the user would like to catch errors manually, the feature can be enabled by setting
7187db96d56Sopenharmony_ci``exit_on_error`` to ``False``::
7197db96d56Sopenharmony_ci
7207db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(exit_on_error=False)
7217db96d56Sopenharmony_ci   >>> parser.add_argument('--integers', type=int)
7227db96d56Sopenharmony_ci   _StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
7237db96d56Sopenharmony_ci   >>> try:
7247db96d56Sopenharmony_ci   ...     parser.parse_args('--integers a'.split())
7257db96d56Sopenharmony_ci   ... except argparse.ArgumentError:
7267db96d56Sopenharmony_ci   ...     print('Catching an argumentError')
7277db96d56Sopenharmony_ci   ...
7287db96d56Sopenharmony_ci   Catching an argumentError
7297db96d56Sopenharmony_ci
7307db96d56Sopenharmony_ci.. versionadded:: 3.9
7317db96d56Sopenharmony_ci
7327db96d56Sopenharmony_ci
7337db96d56Sopenharmony_ciThe add_argument() method
7347db96d56Sopenharmony_ci-------------------------
7357db96d56Sopenharmony_ci
7367db96d56Sopenharmony_ci.. method:: ArgumentParser.add_argument(name or flags..., [action], [nargs], \
7377db96d56Sopenharmony_ci                           [const], [default], [type], [choices], [required], \
7387db96d56Sopenharmony_ci                           [help], [metavar], [dest])
7397db96d56Sopenharmony_ci
7407db96d56Sopenharmony_ci   Define how a single command-line argument should be parsed.  Each parameter
7417db96d56Sopenharmony_ci   has its own more detailed description below, but in short they are:
7427db96d56Sopenharmony_ci
7437db96d56Sopenharmony_ci   * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo``
7447db96d56Sopenharmony_ci     or ``-f, --foo``.
7457db96d56Sopenharmony_ci
7467db96d56Sopenharmony_ci   * action_ - The basic type of action to be taken when this argument is
7477db96d56Sopenharmony_ci     encountered at the command line.
7487db96d56Sopenharmony_ci
7497db96d56Sopenharmony_ci   * nargs_ - The number of command-line arguments that should be consumed.
7507db96d56Sopenharmony_ci
7517db96d56Sopenharmony_ci   * const_ - A constant value required by some action_ and nargs_ selections.
7527db96d56Sopenharmony_ci
7537db96d56Sopenharmony_ci   * default_ - The value produced if the argument is absent from the
7547db96d56Sopenharmony_ci     command line and if it is absent from the namespace object.
7557db96d56Sopenharmony_ci
7567db96d56Sopenharmony_ci   * type_ - The type to which the command-line argument should be converted.
7577db96d56Sopenharmony_ci
7587db96d56Sopenharmony_ci   * choices_ - A sequence of the allowable values for the argument.
7597db96d56Sopenharmony_ci
7607db96d56Sopenharmony_ci   * required_ - Whether or not the command-line option may be omitted
7617db96d56Sopenharmony_ci     (optionals only).
7627db96d56Sopenharmony_ci
7637db96d56Sopenharmony_ci   * help_ - A brief description of what the argument does.
7647db96d56Sopenharmony_ci
7657db96d56Sopenharmony_ci   * metavar_ - A name for the argument in usage messages.
7667db96d56Sopenharmony_ci
7677db96d56Sopenharmony_ci   * dest_ - The name of the attribute to be added to the object returned by
7687db96d56Sopenharmony_ci     :meth:`parse_args`.
7697db96d56Sopenharmony_ci
7707db96d56Sopenharmony_ciThe following sections describe how each of these are used.
7717db96d56Sopenharmony_ci
7727db96d56Sopenharmony_ci
7737db96d56Sopenharmony_ci.. _name_or_flags:
7747db96d56Sopenharmony_ci
7757db96d56Sopenharmony_ciname or flags
7767db96d56Sopenharmony_ci^^^^^^^^^^^^^
7777db96d56Sopenharmony_ci
7787db96d56Sopenharmony_ciThe :meth:`~ArgumentParser.add_argument` method must know whether an optional
7797db96d56Sopenharmony_ciargument, like ``-f`` or ``--foo``, or a positional argument, like a list of
7807db96d56Sopenharmony_cifilenames, is expected.  The first arguments passed to
7817db96d56Sopenharmony_ci:meth:`~ArgumentParser.add_argument` must therefore be either a series of
7827db96d56Sopenharmony_ciflags, or a simple argument name.
7837db96d56Sopenharmony_ci
7847db96d56Sopenharmony_ciFor example, an optional argument could be created like::
7857db96d56Sopenharmony_ci
7867db96d56Sopenharmony_ci   >>> parser.add_argument('-f', '--foo')
7877db96d56Sopenharmony_ci
7887db96d56Sopenharmony_ciwhile a positional argument could be created like::
7897db96d56Sopenharmony_ci
7907db96d56Sopenharmony_ci   >>> parser.add_argument('bar')
7917db96d56Sopenharmony_ci
7927db96d56Sopenharmony_ciWhen :meth:`~ArgumentParser.parse_args` is called, optional arguments will be
7937db96d56Sopenharmony_ciidentified by the ``-`` prefix, and the remaining arguments will be assumed to
7947db96d56Sopenharmony_cibe positional::
7957db96d56Sopenharmony_ci
7967db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
7977db96d56Sopenharmony_ci   >>> parser.add_argument('-f', '--foo')
7987db96d56Sopenharmony_ci   >>> parser.add_argument('bar')
7997db96d56Sopenharmony_ci   >>> parser.parse_args(['BAR'])
8007db96d56Sopenharmony_ci   Namespace(bar='BAR', foo=None)
8017db96d56Sopenharmony_ci   >>> parser.parse_args(['BAR', '--foo', 'FOO'])
8027db96d56Sopenharmony_ci   Namespace(bar='BAR', foo='FOO')
8037db96d56Sopenharmony_ci   >>> parser.parse_args(['--foo', 'FOO'])
8047db96d56Sopenharmony_ci   usage: PROG [-h] [-f FOO] bar
8057db96d56Sopenharmony_ci   PROG: error: the following arguments are required: bar
8067db96d56Sopenharmony_ci
8077db96d56Sopenharmony_ci
8087db96d56Sopenharmony_ci.. _action:
8097db96d56Sopenharmony_ci
8107db96d56Sopenharmony_ciaction
8117db96d56Sopenharmony_ci^^^^^^
8127db96d56Sopenharmony_ci
8137db96d56Sopenharmony_ci:class:`ArgumentParser` objects associate command-line arguments with actions.  These
8147db96d56Sopenharmony_ciactions can do just about anything with the command-line arguments associated with
8157db96d56Sopenharmony_cithem, though most actions simply add an attribute to the object returned by
8167db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_args`.  The ``action`` keyword argument specifies
8177db96d56Sopenharmony_cihow the command-line arguments should be handled. The supplied actions are:
8187db96d56Sopenharmony_ci
8197db96d56Sopenharmony_ci* ``'store'`` - This just stores the argument's value.  This is the default
8207db96d56Sopenharmony_ci  action. For example::
8217db96d56Sopenharmony_ci
8227db96d56Sopenharmony_ci    >>> parser = argparse.ArgumentParser()
8237db96d56Sopenharmony_ci    >>> parser.add_argument('--foo')
8247db96d56Sopenharmony_ci    >>> parser.parse_args('--foo 1'.split())
8257db96d56Sopenharmony_ci    Namespace(foo='1')
8267db96d56Sopenharmony_ci
8277db96d56Sopenharmony_ci* ``'store_const'`` - This stores the value specified by the const_ keyword
8287db96d56Sopenharmony_ci  argument; note that the const_ keyword argument defaults to ``None``.  The
8297db96d56Sopenharmony_ci  ``'store_const'`` action is most commonly used with optional arguments that
8307db96d56Sopenharmony_ci  specify some sort of flag.  For example::
8317db96d56Sopenharmony_ci
8327db96d56Sopenharmony_ci    >>> parser = argparse.ArgumentParser()
8337db96d56Sopenharmony_ci    >>> parser.add_argument('--foo', action='store_const', const=42)
8347db96d56Sopenharmony_ci    >>> parser.parse_args(['--foo'])
8357db96d56Sopenharmony_ci    Namespace(foo=42)
8367db96d56Sopenharmony_ci
8377db96d56Sopenharmony_ci* ``'store_true'`` and ``'store_false'`` - These are special cases of
8387db96d56Sopenharmony_ci  ``'store_const'`` used for storing the values ``True`` and ``False``
8397db96d56Sopenharmony_ci  respectively.  In addition, they create default values of ``False`` and
8407db96d56Sopenharmony_ci  ``True`` respectively.  For example::
8417db96d56Sopenharmony_ci
8427db96d56Sopenharmony_ci    >>> parser = argparse.ArgumentParser()
8437db96d56Sopenharmony_ci    >>> parser.add_argument('--foo', action='store_true')
8447db96d56Sopenharmony_ci    >>> parser.add_argument('--bar', action='store_false')
8457db96d56Sopenharmony_ci    >>> parser.add_argument('--baz', action='store_false')
8467db96d56Sopenharmony_ci    >>> parser.parse_args('--foo --bar'.split())
8477db96d56Sopenharmony_ci    Namespace(foo=True, bar=False, baz=True)
8487db96d56Sopenharmony_ci
8497db96d56Sopenharmony_ci* ``'append'`` - This stores a list, and appends each argument value to the
8507db96d56Sopenharmony_ci  list. It is useful to allow an option to be specified multiple times.
8517db96d56Sopenharmony_ci  If the default value is non-empty, the default elements will be present
8527db96d56Sopenharmony_ci  in the parsed value for the option, with any values from the
8537db96d56Sopenharmony_ci  command line appended after those default values. Example usage::
8547db96d56Sopenharmony_ci
8557db96d56Sopenharmony_ci    >>> parser = argparse.ArgumentParser()
8567db96d56Sopenharmony_ci    >>> parser.add_argument('--foo', action='append')
8577db96d56Sopenharmony_ci    >>> parser.parse_args('--foo 1 --foo 2'.split())
8587db96d56Sopenharmony_ci    Namespace(foo=['1', '2'])
8597db96d56Sopenharmony_ci
8607db96d56Sopenharmony_ci* ``'append_const'`` - This stores a list, and appends the value specified by
8617db96d56Sopenharmony_ci  the const_ keyword argument to the list; note that the const_ keyword
8627db96d56Sopenharmony_ci  argument defaults to ``None``. The ``'append_const'`` action is typically
8637db96d56Sopenharmony_ci  useful when multiple arguments need to store constants to the same list. For
8647db96d56Sopenharmony_ci  example::
8657db96d56Sopenharmony_ci
8667db96d56Sopenharmony_ci    >>> parser = argparse.ArgumentParser()
8677db96d56Sopenharmony_ci    >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
8687db96d56Sopenharmony_ci    >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
8697db96d56Sopenharmony_ci    >>> parser.parse_args('--str --int'.split())
8707db96d56Sopenharmony_ci    Namespace(types=[<class 'str'>, <class 'int'>])
8717db96d56Sopenharmony_ci
8727db96d56Sopenharmony_ci* ``'count'`` - This counts the number of times a keyword argument occurs. For
8737db96d56Sopenharmony_ci  example, this is useful for increasing verbosity levels::
8747db96d56Sopenharmony_ci
8757db96d56Sopenharmony_ci    >>> parser = argparse.ArgumentParser()
8767db96d56Sopenharmony_ci    >>> parser.add_argument('--verbose', '-v', action='count', default=0)
8777db96d56Sopenharmony_ci    >>> parser.parse_args(['-vvv'])
8787db96d56Sopenharmony_ci    Namespace(verbose=3)
8797db96d56Sopenharmony_ci
8807db96d56Sopenharmony_ci  Note, the *default* will be ``None`` unless explicitly set to *0*.
8817db96d56Sopenharmony_ci
8827db96d56Sopenharmony_ci* ``'help'`` - This prints a complete help message for all the options in the
8837db96d56Sopenharmony_ci  current parser and then exits. By default a help action is automatically
8847db96d56Sopenharmony_ci  added to the parser. See :class:`ArgumentParser` for details of how the
8857db96d56Sopenharmony_ci  output is created.
8867db96d56Sopenharmony_ci
8877db96d56Sopenharmony_ci* ``'version'`` - This expects a ``version=`` keyword argument in the
8887db96d56Sopenharmony_ci  :meth:`~ArgumentParser.add_argument` call, and prints version information
8897db96d56Sopenharmony_ci  and exits when invoked::
8907db96d56Sopenharmony_ci
8917db96d56Sopenharmony_ci    >>> import argparse
8927db96d56Sopenharmony_ci    >>> parser = argparse.ArgumentParser(prog='PROG')
8937db96d56Sopenharmony_ci    >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
8947db96d56Sopenharmony_ci    >>> parser.parse_args(['--version'])
8957db96d56Sopenharmony_ci    PROG 2.0
8967db96d56Sopenharmony_ci
8977db96d56Sopenharmony_ci* ``'extend'`` - This stores a list, and extends each argument value to the
8987db96d56Sopenharmony_ci  list.
8997db96d56Sopenharmony_ci  Example usage::
9007db96d56Sopenharmony_ci
9017db96d56Sopenharmony_ci    >>> parser = argparse.ArgumentParser()
9027db96d56Sopenharmony_ci    >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
9037db96d56Sopenharmony_ci    >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
9047db96d56Sopenharmony_ci    Namespace(foo=['f1', 'f2', 'f3', 'f4'])
9057db96d56Sopenharmony_ci
9067db96d56Sopenharmony_ci  .. versionadded:: 3.8
9077db96d56Sopenharmony_ci
9087db96d56Sopenharmony_ciYou may also specify an arbitrary action by passing an Action subclass or
9097db96d56Sopenharmony_ciother object that implements the same interface. The ``BooleanOptionalAction``
9107db96d56Sopenharmony_ciis available in ``argparse`` and adds support for boolean actions such as
9117db96d56Sopenharmony_ci``--foo`` and ``--no-foo``::
9127db96d56Sopenharmony_ci
9137db96d56Sopenharmony_ci    >>> import argparse
9147db96d56Sopenharmony_ci    >>> parser = argparse.ArgumentParser()
9157db96d56Sopenharmony_ci    >>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
9167db96d56Sopenharmony_ci    >>> parser.parse_args(['--no-foo'])
9177db96d56Sopenharmony_ci    Namespace(foo=False)
9187db96d56Sopenharmony_ci
9197db96d56Sopenharmony_ci.. versionadded:: 3.9
9207db96d56Sopenharmony_ci
9217db96d56Sopenharmony_ciThe recommended way to create a custom action is to extend :class:`Action`,
9227db96d56Sopenharmony_cioverriding the ``__call__`` method and optionally the ``__init__`` and
9237db96d56Sopenharmony_ci``format_usage`` methods.
9247db96d56Sopenharmony_ci
9257db96d56Sopenharmony_ciAn example of a custom action::
9267db96d56Sopenharmony_ci
9277db96d56Sopenharmony_ci   >>> class FooAction(argparse.Action):
9287db96d56Sopenharmony_ci   ...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
9297db96d56Sopenharmony_ci   ...         if nargs is not None:
9307db96d56Sopenharmony_ci   ...             raise ValueError("nargs not allowed")
9317db96d56Sopenharmony_ci   ...         super().__init__(option_strings, dest, **kwargs)
9327db96d56Sopenharmony_ci   ...     def __call__(self, parser, namespace, values, option_string=None):
9337db96d56Sopenharmony_ci   ...         print('%r %r %r' % (namespace, values, option_string))
9347db96d56Sopenharmony_ci   ...         setattr(namespace, self.dest, values)
9357db96d56Sopenharmony_ci   ...
9367db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
9377db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', action=FooAction)
9387db96d56Sopenharmony_ci   >>> parser.add_argument('bar', action=FooAction)
9397db96d56Sopenharmony_ci   >>> args = parser.parse_args('1 --foo 2'.split())
9407db96d56Sopenharmony_ci   Namespace(bar=None, foo=None) '1' None
9417db96d56Sopenharmony_ci   Namespace(bar='1', foo=None) '2' '--foo'
9427db96d56Sopenharmony_ci   >>> args
9437db96d56Sopenharmony_ci   Namespace(bar='1', foo='2')
9447db96d56Sopenharmony_ci
9457db96d56Sopenharmony_ciFor more details, see :class:`Action`.
9467db96d56Sopenharmony_ci
9477db96d56Sopenharmony_ci
9487db96d56Sopenharmony_ci.. _nargs:
9497db96d56Sopenharmony_ci
9507db96d56Sopenharmony_cinargs
9517db96d56Sopenharmony_ci^^^^^
9527db96d56Sopenharmony_ci
9537db96d56Sopenharmony_ciArgumentParser objects usually associate a single command-line argument with a
9547db96d56Sopenharmony_cisingle action to be taken.  The ``nargs`` keyword argument associates a
9557db96d56Sopenharmony_cidifferent number of command-line arguments with a single action.  The supported
9567db96d56Sopenharmony_civalues are:
9577db96d56Sopenharmony_ci
9587db96d56Sopenharmony_ci* ``N`` (an integer).  ``N`` arguments from the command line will be gathered
9597db96d56Sopenharmony_ci  together into a list.  For example::
9607db96d56Sopenharmony_ci
9617db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
9627db96d56Sopenharmony_ci     >>> parser.add_argument('--foo', nargs=2)
9637db96d56Sopenharmony_ci     >>> parser.add_argument('bar', nargs=1)
9647db96d56Sopenharmony_ci     >>> parser.parse_args('c --foo a b'.split())
9657db96d56Sopenharmony_ci     Namespace(bar=['c'], foo=['a', 'b'])
9667db96d56Sopenharmony_ci
9677db96d56Sopenharmony_ci  Note that ``nargs=1`` produces a list of one item.  This is different from
9687db96d56Sopenharmony_ci  the default, in which the item is produced by itself.
9697db96d56Sopenharmony_ci
9707db96d56Sopenharmony_ci.. index:: single: ? (question mark); in argparse module
9717db96d56Sopenharmony_ci
9727db96d56Sopenharmony_ci* ``'?'``. One argument will be consumed from the command line if possible, and
9737db96d56Sopenharmony_ci  produced as a single item.  If no command-line argument is present, the value from
9747db96d56Sopenharmony_ci  default_ will be produced.  Note that for optional arguments, there is an
9757db96d56Sopenharmony_ci  additional case - the option string is present but not followed by a
9767db96d56Sopenharmony_ci  command-line argument.  In this case the value from const_ will be produced.  Some
9777db96d56Sopenharmony_ci  examples to illustrate this::
9787db96d56Sopenharmony_ci
9797db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
9807db96d56Sopenharmony_ci     >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
9817db96d56Sopenharmony_ci     >>> parser.add_argument('bar', nargs='?', default='d')
9827db96d56Sopenharmony_ci     >>> parser.parse_args(['XX', '--foo', 'YY'])
9837db96d56Sopenharmony_ci     Namespace(bar='XX', foo='YY')
9847db96d56Sopenharmony_ci     >>> parser.parse_args(['XX', '--foo'])
9857db96d56Sopenharmony_ci     Namespace(bar='XX', foo='c')
9867db96d56Sopenharmony_ci     >>> parser.parse_args([])
9877db96d56Sopenharmony_ci     Namespace(bar='d', foo='d')
9887db96d56Sopenharmony_ci
9897db96d56Sopenharmony_ci  One of the more common uses of ``nargs='?'`` is to allow optional input and
9907db96d56Sopenharmony_ci  output files::
9917db96d56Sopenharmony_ci
9927db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
9937db96d56Sopenharmony_ci     >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
9947db96d56Sopenharmony_ci     ...                     default=sys.stdin)
9957db96d56Sopenharmony_ci     >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
9967db96d56Sopenharmony_ci     ...                     default=sys.stdout)
9977db96d56Sopenharmony_ci     >>> parser.parse_args(['input.txt', 'output.txt'])
9987db96d56Sopenharmony_ci     Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
9997db96d56Sopenharmony_ci               outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
10007db96d56Sopenharmony_ci     >>> parser.parse_args([])
10017db96d56Sopenharmony_ci     Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
10027db96d56Sopenharmony_ci               outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
10037db96d56Sopenharmony_ci
10047db96d56Sopenharmony_ci.. index:: single: * (asterisk); in argparse module
10057db96d56Sopenharmony_ci
10067db96d56Sopenharmony_ci* ``'*'``.  All command-line arguments present are gathered into a list.  Note that
10077db96d56Sopenharmony_ci  it generally doesn't make much sense to have more than one positional argument
10087db96d56Sopenharmony_ci  with ``nargs='*'``, but multiple optional arguments with ``nargs='*'`` is
10097db96d56Sopenharmony_ci  possible.  For example::
10107db96d56Sopenharmony_ci
10117db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
10127db96d56Sopenharmony_ci     >>> parser.add_argument('--foo', nargs='*')
10137db96d56Sopenharmony_ci     >>> parser.add_argument('--bar', nargs='*')
10147db96d56Sopenharmony_ci     >>> parser.add_argument('baz', nargs='*')
10157db96d56Sopenharmony_ci     >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
10167db96d56Sopenharmony_ci     Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
10177db96d56Sopenharmony_ci
10187db96d56Sopenharmony_ci.. index:: single: + (plus); in argparse module
10197db96d56Sopenharmony_ci
10207db96d56Sopenharmony_ci* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
10217db96d56Sopenharmony_ci  list.  Additionally, an error message will be generated if there wasn't at
10227db96d56Sopenharmony_ci  least one command-line argument present.  For example::
10237db96d56Sopenharmony_ci
10247db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser(prog='PROG')
10257db96d56Sopenharmony_ci     >>> parser.add_argument('foo', nargs='+')
10267db96d56Sopenharmony_ci     >>> parser.parse_args(['a', 'b'])
10277db96d56Sopenharmony_ci     Namespace(foo=['a', 'b'])
10287db96d56Sopenharmony_ci     >>> parser.parse_args([])
10297db96d56Sopenharmony_ci     usage: PROG [-h] foo [foo ...]
10307db96d56Sopenharmony_ci     PROG: error: the following arguments are required: foo
10317db96d56Sopenharmony_ci
10327db96d56Sopenharmony_ciIf the ``nargs`` keyword argument is not provided, the number of arguments consumed
10337db96d56Sopenharmony_ciis determined by the action_.  Generally this means a single command-line argument
10347db96d56Sopenharmony_ciwill be consumed and a single item (not a list) will be produced.
10357db96d56Sopenharmony_ci
10367db96d56Sopenharmony_ci
10377db96d56Sopenharmony_ci.. _const:
10387db96d56Sopenharmony_ci
10397db96d56Sopenharmony_ciconst
10407db96d56Sopenharmony_ci^^^^^
10417db96d56Sopenharmony_ci
10427db96d56Sopenharmony_ciThe ``const`` argument of :meth:`~ArgumentParser.add_argument` is used to hold
10437db96d56Sopenharmony_ciconstant values that are not read from the command line but are required for
10447db96d56Sopenharmony_cithe various :class:`ArgumentParser` actions.  The two most common uses of it are:
10457db96d56Sopenharmony_ci
10467db96d56Sopenharmony_ci* When :meth:`~ArgumentParser.add_argument` is called with
10477db96d56Sopenharmony_ci  ``action='store_const'`` or ``action='append_const'``.  These actions add the
10487db96d56Sopenharmony_ci  ``const`` value to one of the attributes of the object returned by
10497db96d56Sopenharmony_ci  :meth:`~ArgumentParser.parse_args`. See the action_ description for examples.
10507db96d56Sopenharmony_ci  If ``const`` is not provided to :meth:`~ArgumentParser.add_argument`, it will
10517db96d56Sopenharmony_ci  receive a default value of ``None``.
10527db96d56Sopenharmony_ci
10537db96d56Sopenharmony_ci
10547db96d56Sopenharmony_ci* When :meth:`~ArgumentParser.add_argument` is called with option strings
10557db96d56Sopenharmony_ci  (like ``-f`` or ``--foo``) and ``nargs='?'``.  This creates an optional
10567db96d56Sopenharmony_ci  argument that can be followed by zero or one command-line arguments.
10577db96d56Sopenharmony_ci  When parsing the command line, if the option string is encountered with no
10587db96d56Sopenharmony_ci  command-line argument following it, the value of ``const`` will be assumed to
10597db96d56Sopenharmony_ci  be ``None`` instead.  See the nargs_ description for examples.
10607db96d56Sopenharmony_ci
10617db96d56Sopenharmony_ci.. versionchanged:: 3.11
10627db96d56Sopenharmony_ci   ``const=None`` by default, including when ``action='append_const'`` or
10637db96d56Sopenharmony_ci   ``action='store_const'``.
10647db96d56Sopenharmony_ci
10657db96d56Sopenharmony_ci.. _default:
10667db96d56Sopenharmony_ci
10677db96d56Sopenharmony_cidefault
10687db96d56Sopenharmony_ci^^^^^^^
10697db96d56Sopenharmony_ci
10707db96d56Sopenharmony_ciAll optional arguments and some positional arguments may be omitted at the
10717db96d56Sopenharmony_cicommand line.  The ``default`` keyword argument of
10727db96d56Sopenharmony_ci:meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,
10737db96d56Sopenharmony_cispecifies what value should be used if the command-line argument is not present.
10747db96d56Sopenharmony_ciFor optional arguments, the ``default`` value is used when the option string
10757db96d56Sopenharmony_ciwas not present at the command line::
10767db96d56Sopenharmony_ci
10777db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
10787db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', default=42)
10797db96d56Sopenharmony_ci   >>> parser.parse_args(['--foo', '2'])
10807db96d56Sopenharmony_ci   Namespace(foo='2')
10817db96d56Sopenharmony_ci   >>> parser.parse_args([])
10827db96d56Sopenharmony_ci   Namespace(foo=42)
10837db96d56Sopenharmony_ci
10847db96d56Sopenharmony_ciIf the target namespace already has an attribute set, the action *default*
10857db96d56Sopenharmony_ciwill not over write it::
10867db96d56Sopenharmony_ci
10877db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
10887db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', default=42)
10897db96d56Sopenharmony_ci   >>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
10907db96d56Sopenharmony_ci   Namespace(foo=101)
10917db96d56Sopenharmony_ci
10927db96d56Sopenharmony_ciIf the ``default`` value is a string, the parser parses the value as if it
10937db96d56Sopenharmony_ciwere a command-line argument.  In particular, the parser applies any type_
10947db96d56Sopenharmony_ciconversion argument, if provided, before setting the attribute on the
10957db96d56Sopenharmony_ci:class:`Namespace` return value.  Otherwise, the parser uses the value as is::
10967db96d56Sopenharmony_ci
10977db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
10987db96d56Sopenharmony_ci   >>> parser.add_argument('--length', default='10', type=int)
10997db96d56Sopenharmony_ci   >>> parser.add_argument('--width', default=10.5, type=int)
11007db96d56Sopenharmony_ci   >>> parser.parse_args()
11017db96d56Sopenharmony_ci   Namespace(length=10, width=10.5)
11027db96d56Sopenharmony_ci
11037db96d56Sopenharmony_ciFor positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value
11047db96d56Sopenharmony_ciis used when no command-line argument was present::
11057db96d56Sopenharmony_ci
11067db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
11077db96d56Sopenharmony_ci   >>> parser.add_argument('foo', nargs='?', default=42)
11087db96d56Sopenharmony_ci   >>> parser.parse_args(['a'])
11097db96d56Sopenharmony_ci   Namespace(foo='a')
11107db96d56Sopenharmony_ci   >>> parser.parse_args([])
11117db96d56Sopenharmony_ci   Namespace(foo=42)
11127db96d56Sopenharmony_ci
11137db96d56Sopenharmony_ci
11147db96d56Sopenharmony_ciProviding ``default=argparse.SUPPRESS`` causes no attribute to be added if the
11157db96d56Sopenharmony_cicommand-line argument was not present::
11167db96d56Sopenharmony_ci
11177db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
11187db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
11197db96d56Sopenharmony_ci   >>> parser.parse_args([])
11207db96d56Sopenharmony_ci   Namespace()
11217db96d56Sopenharmony_ci   >>> parser.parse_args(['--foo', '1'])
11227db96d56Sopenharmony_ci   Namespace(foo='1')
11237db96d56Sopenharmony_ci
11247db96d56Sopenharmony_ci
11257db96d56Sopenharmony_ci.. _type:
11267db96d56Sopenharmony_ci
11277db96d56Sopenharmony_citype
11287db96d56Sopenharmony_ci^^^^
11297db96d56Sopenharmony_ci
11307db96d56Sopenharmony_ciBy default, the parser reads command-line arguments in as simple
11317db96d56Sopenharmony_cistrings. However, quite often the command-line string should instead be
11327db96d56Sopenharmony_ciinterpreted as another type, such as a :class:`float` or :class:`int`.  The
11337db96d56Sopenharmony_ci``type`` keyword for :meth:`~ArgumentParser.add_argument` allows any
11347db96d56Sopenharmony_cinecessary type-checking and type conversions to be performed.
11357db96d56Sopenharmony_ci
11367db96d56Sopenharmony_ciIf the type_ keyword is used with the default_ keyword, the type converter
11377db96d56Sopenharmony_ciis only applied if the default is a string.
11387db96d56Sopenharmony_ci
11397db96d56Sopenharmony_ciThe argument to ``type`` can be any callable that accepts a single string.
11407db96d56Sopenharmony_ciIf the function raises :exc:`ArgumentTypeError`, :exc:`TypeError`, or
11417db96d56Sopenharmony_ci:exc:`ValueError`, the exception is caught and a nicely formatted error
11427db96d56Sopenharmony_cimessage is displayed.  No other exception types are handled.
11437db96d56Sopenharmony_ci
11447db96d56Sopenharmony_ciCommon built-in types and functions can be used as type converters:
11457db96d56Sopenharmony_ci
11467db96d56Sopenharmony_ci.. testcode::
11477db96d56Sopenharmony_ci
11487db96d56Sopenharmony_ci   import argparse
11497db96d56Sopenharmony_ci   import pathlib
11507db96d56Sopenharmony_ci
11517db96d56Sopenharmony_ci   parser = argparse.ArgumentParser()
11527db96d56Sopenharmony_ci   parser.add_argument('count', type=int)
11537db96d56Sopenharmony_ci   parser.add_argument('distance', type=float)
11547db96d56Sopenharmony_ci   parser.add_argument('street', type=ascii)
11557db96d56Sopenharmony_ci   parser.add_argument('code_point', type=ord)
11567db96d56Sopenharmony_ci   parser.add_argument('source_file', type=open)
11577db96d56Sopenharmony_ci   parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
11587db96d56Sopenharmony_ci   parser.add_argument('datapath', type=pathlib.Path)
11597db96d56Sopenharmony_ci
11607db96d56Sopenharmony_ciUser defined functions can be used as well:
11617db96d56Sopenharmony_ci
11627db96d56Sopenharmony_ci.. doctest::
11637db96d56Sopenharmony_ci
11647db96d56Sopenharmony_ci   >>> def hyphenated(string):
11657db96d56Sopenharmony_ci   ...     return '-'.join([word[:4] for word in string.casefold().split()])
11667db96d56Sopenharmony_ci   ...
11677db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
11687db96d56Sopenharmony_ci   >>> _ = parser.add_argument('short_title', type=hyphenated)
11697db96d56Sopenharmony_ci   >>> parser.parse_args(['"The Tale of Two Cities"'])
11707db96d56Sopenharmony_ci   Namespace(short_title='"the-tale-of-two-citi')
11717db96d56Sopenharmony_ci
11727db96d56Sopenharmony_ciThe :func:`bool` function is not recommended as a type converter.  All it does
11737db96d56Sopenharmony_ciis convert empty strings to ``False`` and non-empty strings to ``True``.
11747db96d56Sopenharmony_ciThis is usually not what is desired.
11757db96d56Sopenharmony_ci
11767db96d56Sopenharmony_ciIn general, the ``type`` keyword is a convenience that should only be used for
11777db96d56Sopenharmony_cisimple conversions that can only raise one of the three supported exceptions.
11787db96d56Sopenharmony_ciAnything with more interesting error-handling or resource management should be
11797db96d56Sopenharmony_cidone downstream after the arguments are parsed.
11807db96d56Sopenharmony_ci
11817db96d56Sopenharmony_ciFor example, JSON or YAML conversions have complex error cases that require
11827db96d56Sopenharmony_cibetter reporting than can be given by the ``type`` keyword.  A
11837db96d56Sopenharmony_ci:exc:`~json.JSONDecodeError` would not be well formatted and a
11847db96d56Sopenharmony_ci:exc:`FileNotFoundError` exception would not be handled at all.
11857db96d56Sopenharmony_ci
11867db96d56Sopenharmony_ciEven :class:`~argparse.FileType` has its limitations for use with the ``type``
11877db96d56Sopenharmony_cikeyword.  If one argument uses *FileType* and then a subsequent argument fails,
11887db96d56Sopenharmony_cian error is reported but the file is not automatically closed.  In this case, it
11897db96d56Sopenharmony_ciwould be better to wait until after the parser has run and then use the
11907db96d56Sopenharmony_ci:keyword:`with`-statement to manage the files.
11917db96d56Sopenharmony_ci
11927db96d56Sopenharmony_ciFor type checkers that simply check against a fixed set of values, consider
11937db96d56Sopenharmony_ciusing the choices_ keyword instead.
11947db96d56Sopenharmony_ci
11957db96d56Sopenharmony_ci
11967db96d56Sopenharmony_ci.. _choices:
11977db96d56Sopenharmony_ci
11987db96d56Sopenharmony_cichoices
11997db96d56Sopenharmony_ci^^^^^^^
12007db96d56Sopenharmony_ci
12017db96d56Sopenharmony_ciSome command-line arguments should be selected from a restricted set of values.
12027db96d56Sopenharmony_ciThese can be handled by passing a sequence object as the *choices* keyword
12037db96d56Sopenharmony_ciargument to :meth:`~ArgumentParser.add_argument`.  When the command line is
12047db96d56Sopenharmony_ciparsed, argument values will be checked, and an error message will be displayed
12057db96d56Sopenharmony_ciif the argument was not one of the acceptable values::
12067db96d56Sopenharmony_ci
12077db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='game.py')
12087db96d56Sopenharmony_ci   >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
12097db96d56Sopenharmony_ci   >>> parser.parse_args(['rock'])
12107db96d56Sopenharmony_ci   Namespace(move='rock')
12117db96d56Sopenharmony_ci   >>> parser.parse_args(['fire'])
12127db96d56Sopenharmony_ci   usage: game.py [-h] {rock,paper,scissors}
12137db96d56Sopenharmony_ci   game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
12147db96d56Sopenharmony_ci   'paper', 'scissors')
12157db96d56Sopenharmony_ci
12167db96d56Sopenharmony_ciNote that inclusion in the *choices* sequence is checked after any type_
12177db96d56Sopenharmony_ciconversions have been performed, so the type of the objects in the *choices*
12187db96d56Sopenharmony_cisequence should match the type_ specified::
12197db96d56Sopenharmony_ci
12207db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='doors.py')
12217db96d56Sopenharmony_ci   >>> parser.add_argument('door', type=int, choices=range(1, 4))
12227db96d56Sopenharmony_ci   >>> print(parser.parse_args(['3']))
12237db96d56Sopenharmony_ci   Namespace(door=3)
12247db96d56Sopenharmony_ci   >>> parser.parse_args(['4'])
12257db96d56Sopenharmony_ci   usage: doors.py [-h] {1,2,3}
12267db96d56Sopenharmony_ci   doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)
12277db96d56Sopenharmony_ci
12287db96d56Sopenharmony_ciAny sequence can be passed as the *choices* value, so :class:`list` objects,
12297db96d56Sopenharmony_ci:class:`tuple` objects, and custom sequences are all supported.
12307db96d56Sopenharmony_ci
12317db96d56Sopenharmony_ciUse of :class:`enum.Enum` is not recommended because it is difficult to
12327db96d56Sopenharmony_cicontrol its appearance in usage, help, and error messages.
12337db96d56Sopenharmony_ci
12347db96d56Sopenharmony_ciFormatted choices override the default *metavar* which is normally derived
12357db96d56Sopenharmony_cifrom *dest*.  This is usually what you want because the user never sees the
12367db96d56Sopenharmony_ci*dest* parameter.  If this display isn't desirable (perhaps because there are
12377db96d56Sopenharmony_cimany choices), just specify an explicit metavar_.
12387db96d56Sopenharmony_ci
12397db96d56Sopenharmony_ci
12407db96d56Sopenharmony_ci.. _required:
12417db96d56Sopenharmony_ci
12427db96d56Sopenharmony_cirequired
12437db96d56Sopenharmony_ci^^^^^^^^
12447db96d56Sopenharmony_ci
12457db96d56Sopenharmony_ciIn general, the :mod:`argparse` module assumes that flags like ``-f`` and ``--bar``
12467db96d56Sopenharmony_ciindicate *optional* arguments, which can always be omitted at the command line.
12477db96d56Sopenharmony_ciTo make an option *required*, ``True`` can be specified for the ``required=``
12487db96d56Sopenharmony_cikeyword argument to :meth:`~ArgumentParser.add_argument`::
12497db96d56Sopenharmony_ci
12507db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
12517db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', required=True)
12527db96d56Sopenharmony_ci   >>> parser.parse_args(['--foo', 'BAR'])
12537db96d56Sopenharmony_ci   Namespace(foo='BAR')
12547db96d56Sopenharmony_ci   >>> parser.parse_args([])
12557db96d56Sopenharmony_ci   usage: [-h] --foo FOO
12567db96d56Sopenharmony_ci   : error: the following arguments are required: --foo
12577db96d56Sopenharmony_ci
12587db96d56Sopenharmony_ciAs the example shows, if an option is marked as ``required``,
12597db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_args` will report an error if that option is not
12607db96d56Sopenharmony_cipresent at the command line.
12617db96d56Sopenharmony_ci
12627db96d56Sopenharmony_ci.. note::
12637db96d56Sopenharmony_ci
12647db96d56Sopenharmony_ci    Required options are generally considered bad form because users expect
12657db96d56Sopenharmony_ci    *options* to be *optional*, and thus they should be avoided when possible.
12667db96d56Sopenharmony_ci
12677db96d56Sopenharmony_ci
12687db96d56Sopenharmony_ci.. _help:
12697db96d56Sopenharmony_ci
12707db96d56Sopenharmony_cihelp
12717db96d56Sopenharmony_ci^^^^
12727db96d56Sopenharmony_ci
12737db96d56Sopenharmony_ciThe ``help`` value is a string containing a brief description of the argument.
12747db96d56Sopenharmony_ciWhen a user requests help (usually by using ``-h`` or ``--help`` at the
12757db96d56Sopenharmony_cicommand line), these ``help`` descriptions will be displayed with each
12767db96d56Sopenharmony_ciargument::
12777db96d56Sopenharmony_ci
12787db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='frobble')
12797db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', action='store_true',
12807db96d56Sopenharmony_ci   ...                     help='foo the bars before frobbling')
12817db96d56Sopenharmony_ci   >>> parser.add_argument('bar', nargs='+',
12827db96d56Sopenharmony_ci   ...                     help='one of the bars to be frobbled')
12837db96d56Sopenharmony_ci   >>> parser.parse_args(['-h'])
12847db96d56Sopenharmony_ci   usage: frobble [-h] [--foo] bar [bar ...]
12857db96d56Sopenharmony_ci
12867db96d56Sopenharmony_ci   positional arguments:
12877db96d56Sopenharmony_ci    bar     one of the bars to be frobbled
12887db96d56Sopenharmony_ci
12897db96d56Sopenharmony_ci   options:
12907db96d56Sopenharmony_ci    -h, --help  show this help message and exit
12917db96d56Sopenharmony_ci    --foo   foo the bars before frobbling
12927db96d56Sopenharmony_ci
12937db96d56Sopenharmony_ciThe ``help`` strings can include various format specifiers to avoid repetition
12947db96d56Sopenharmony_ciof things like the program name or the argument default_.  The available
12957db96d56Sopenharmony_cispecifiers include the program name, ``%(prog)s`` and most keyword arguments to
12967db96d56Sopenharmony_ci:meth:`~ArgumentParser.add_argument`, e.g. ``%(default)s``, ``%(type)s``, etc.::
12977db96d56Sopenharmony_ci
12987db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='frobble')
12997db96d56Sopenharmony_ci   >>> parser.add_argument('bar', nargs='?', type=int, default=42,
13007db96d56Sopenharmony_ci   ...                     help='the bar to %(prog)s (default: %(default)s)')
13017db96d56Sopenharmony_ci   >>> parser.print_help()
13027db96d56Sopenharmony_ci   usage: frobble [-h] [bar]
13037db96d56Sopenharmony_ci
13047db96d56Sopenharmony_ci   positional arguments:
13057db96d56Sopenharmony_ci    bar     the bar to frobble (default: 42)
13067db96d56Sopenharmony_ci
13077db96d56Sopenharmony_ci   options:
13087db96d56Sopenharmony_ci    -h, --help  show this help message and exit
13097db96d56Sopenharmony_ci
13107db96d56Sopenharmony_ciAs the help string supports %-formatting, if you want a literal ``%`` to appear
13117db96d56Sopenharmony_ciin the help string, you must escape it as ``%%``.
13127db96d56Sopenharmony_ci
13137db96d56Sopenharmony_ci:mod:`argparse` supports silencing the help entry for certain options, by
13147db96d56Sopenharmony_cisetting the ``help`` value to ``argparse.SUPPRESS``::
13157db96d56Sopenharmony_ci
13167db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='frobble')
13177db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
13187db96d56Sopenharmony_ci   >>> parser.print_help()
13197db96d56Sopenharmony_ci   usage: frobble [-h]
13207db96d56Sopenharmony_ci
13217db96d56Sopenharmony_ci   options:
13227db96d56Sopenharmony_ci     -h, --help  show this help message and exit
13237db96d56Sopenharmony_ci
13247db96d56Sopenharmony_ci
13257db96d56Sopenharmony_ci.. _metavar:
13267db96d56Sopenharmony_ci
13277db96d56Sopenharmony_cimetavar
13287db96d56Sopenharmony_ci^^^^^^^
13297db96d56Sopenharmony_ci
13307db96d56Sopenharmony_ciWhen :class:`ArgumentParser` generates help messages, it needs some way to refer
13317db96d56Sopenharmony_cito each expected argument.  By default, ArgumentParser objects use the dest_
13327db96d56Sopenharmony_civalue as the "name" of each object.  By default, for positional argument
13337db96d56Sopenharmony_ciactions, the dest_ value is used directly, and for optional argument actions,
13347db96d56Sopenharmony_cithe dest_ value is uppercased.  So, a single positional argument with
13357db96d56Sopenharmony_ci``dest='bar'`` will be referred to as ``bar``. A single
13367db96d56Sopenharmony_cioptional argument ``--foo`` that should be followed by a single command-line argument
13377db96d56Sopenharmony_ciwill be referred to as ``FOO``.  An example::
13387db96d56Sopenharmony_ci
13397db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
13407db96d56Sopenharmony_ci   >>> parser.add_argument('--foo')
13417db96d56Sopenharmony_ci   >>> parser.add_argument('bar')
13427db96d56Sopenharmony_ci   >>> parser.parse_args('X --foo Y'.split())
13437db96d56Sopenharmony_ci   Namespace(bar='X', foo='Y')
13447db96d56Sopenharmony_ci   >>> parser.print_help()
13457db96d56Sopenharmony_ci   usage:  [-h] [--foo FOO] bar
13467db96d56Sopenharmony_ci
13477db96d56Sopenharmony_ci   positional arguments:
13487db96d56Sopenharmony_ci    bar
13497db96d56Sopenharmony_ci
13507db96d56Sopenharmony_ci   options:
13517db96d56Sopenharmony_ci    -h, --help  show this help message and exit
13527db96d56Sopenharmony_ci    --foo FOO
13537db96d56Sopenharmony_ci
13547db96d56Sopenharmony_ciAn alternative name can be specified with ``metavar``::
13557db96d56Sopenharmony_ci
13567db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
13577db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', metavar='YYY')
13587db96d56Sopenharmony_ci   >>> parser.add_argument('bar', metavar='XXX')
13597db96d56Sopenharmony_ci   >>> parser.parse_args('X --foo Y'.split())
13607db96d56Sopenharmony_ci   Namespace(bar='X', foo='Y')
13617db96d56Sopenharmony_ci   >>> parser.print_help()
13627db96d56Sopenharmony_ci   usage:  [-h] [--foo YYY] XXX
13637db96d56Sopenharmony_ci
13647db96d56Sopenharmony_ci   positional arguments:
13657db96d56Sopenharmony_ci    XXX
13667db96d56Sopenharmony_ci
13677db96d56Sopenharmony_ci   options:
13687db96d56Sopenharmony_ci    -h, --help  show this help message and exit
13697db96d56Sopenharmony_ci    --foo YYY
13707db96d56Sopenharmony_ci
13717db96d56Sopenharmony_ciNote that ``metavar`` only changes the *displayed* name - the name of the
13727db96d56Sopenharmony_ciattribute on the :meth:`~ArgumentParser.parse_args` object is still determined
13737db96d56Sopenharmony_ciby the dest_ value.
13747db96d56Sopenharmony_ci
13757db96d56Sopenharmony_ciDifferent values of ``nargs`` may cause the metavar to be used multiple times.
13767db96d56Sopenharmony_ciProviding a tuple to ``metavar`` specifies a different display for each of the
13777db96d56Sopenharmony_ciarguments::
13787db96d56Sopenharmony_ci
13797db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
13807db96d56Sopenharmony_ci   >>> parser.add_argument('-x', nargs=2)
13817db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
13827db96d56Sopenharmony_ci   >>> parser.print_help()
13837db96d56Sopenharmony_ci   usage: PROG [-h] [-x X X] [--foo bar baz]
13847db96d56Sopenharmony_ci
13857db96d56Sopenharmony_ci   options:
13867db96d56Sopenharmony_ci    -h, --help     show this help message and exit
13877db96d56Sopenharmony_ci    -x X X
13887db96d56Sopenharmony_ci    --foo bar baz
13897db96d56Sopenharmony_ci
13907db96d56Sopenharmony_ci
13917db96d56Sopenharmony_ci.. _dest:
13927db96d56Sopenharmony_ci
13937db96d56Sopenharmony_cidest
13947db96d56Sopenharmony_ci^^^^
13957db96d56Sopenharmony_ci
13967db96d56Sopenharmony_ciMost :class:`ArgumentParser` actions add some value as an attribute of the
13977db96d56Sopenharmony_ciobject returned by :meth:`~ArgumentParser.parse_args`.  The name of this
13987db96d56Sopenharmony_ciattribute is determined by the ``dest`` keyword argument of
13997db96d56Sopenharmony_ci:meth:`~ArgumentParser.add_argument`.  For positional argument actions,
14007db96d56Sopenharmony_ci``dest`` is normally supplied as the first argument to
14017db96d56Sopenharmony_ci:meth:`~ArgumentParser.add_argument`::
14027db96d56Sopenharmony_ci
14037db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
14047db96d56Sopenharmony_ci   >>> parser.add_argument('bar')
14057db96d56Sopenharmony_ci   >>> parser.parse_args(['XXX'])
14067db96d56Sopenharmony_ci   Namespace(bar='XXX')
14077db96d56Sopenharmony_ci
14087db96d56Sopenharmony_ciFor optional argument actions, the value of ``dest`` is normally inferred from
14097db96d56Sopenharmony_cithe option strings.  :class:`ArgumentParser` generates the value of ``dest`` by
14107db96d56Sopenharmony_citaking the first long option string and stripping away the initial ``--``
14117db96d56Sopenharmony_cistring.  If no long option strings were supplied, ``dest`` will be derived from
14127db96d56Sopenharmony_cithe first short option string by stripping the initial ``-`` character.  Any
14137db96d56Sopenharmony_ciinternal ``-`` characters will be converted to ``_`` characters to make sure
14147db96d56Sopenharmony_cithe string is a valid attribute name.  The examples below illustrate this
14157db96d56Sopenharmony_cibehavior::
14167db96d56Sopenharmony_ci
14177db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
14187db96d56Sopenharmony_ci   >>> parser.add_argument('-f', '--foo-bar', '--foo')
14197db96d56Sopenharmony_ci   >>> parser.add_argument('-x', '-y')
14207db96d56Sopenharmony_ci   >>> parser.parse_args('-f 1 -x 2'.split())
14217db96d56Sopenharmony_ci   Namespace(foo_bar='1', x='2')
14227db96d56Sopenharmony_ci   >>> parser.parse_args('--foo 1 -y 2'.split())
14237db96d56Sopenharmony_ci   Namespace(foo_bar='1', x='2')
14247db96d56Sopenharmony_ci
14257db96d56Sopenharmony_ci``dest`` allows a custom attribute name to be provided::
14267db96d56Sopenharmony_ci
14277db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
14287db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', dest='bar')
14297db96d56Sopenharmony_ci   >>> parser.parse_args('--foo XXX'.split())
14307db96d56Sopenharmony_ci   Namespace(bar='XXX')
14317db96d56Sopenharmony_ci
14327db96d56Sopenharmony_ciAction classes
14337db96d56Sopenharmony_ci^^^^^^^^^^^^^^
14347db96d56Sopenharmony_ci
14357db96d56Sopenharmony_ciAction classes implement the Action API, a callable which returns a callable
14367db96d56Sopenharmony_ciwhich processes arguments from the command-line. Any object which follows
14377db96d56Sopenharmony_cithis API may be passed as the ``action`` parameter to
14387db96d56Sopenharmony_ci:meth:`~ArgumentParser.add_argument`.
14397db96d56Sopenharmony_ci
14407db96d56Sopenharmony_ci.. class:: Action(option_strings, dest, nargs=None, const=None, default=None, \
14417db96d56Sopenharmony_ci                  type=None, choices=None, required=False, help=None, \
14427db96d56Sopenharmony_ci                  metavar=None)
14437db96d56Sopenharmony_ci
14447db96d56Sopenharmony_ciAction objects are used by an ArgumentParser to represent the information
14457db96d56Sopenharmony_cineeded to parse a single argument from one or more strings from the
14467db96d56Sopenharmony_cicommand line. The Action class must accept the two positional arguments
14477db96d56Sopenharmony_ciplus any keyword arguments passed to :meth:`ArgumentParser.add_argument`
14487db96d56Sopenharmony_ciexcept for the ``action`` itself.
14497db96d56Sopenharmony_ci
14507db96d56Sopenharmony_ciInstances of Action (or return value of any callable to the ``action``
14517db96d56Sopenharmony_ciparameter) should have attributes "dest", "option_strings", "default", "type",
14527db96d56Sopenharmony_ci"required", "help", etc. defined. The easiest way to ensure these attributes
14537db96d56Sopenharmony_ciare defined is to call ``Action.__init__``.
14547db96d56Sopenharmony_ci
14557db96d56Sopenharmony_ciAction instances should be callable, so subclasses must override the
14567db96d56Sopenharmony_ci``__call__`` method, which should accept four parameters:
14577db96d56Sopenharmony_ci
14587db96d56Sopenharmony_ci* ``parser`` - The ArgumentParser object which contains this action.
14597db96d56Sopenharmony_ci
14607db96d56Sopenharmony_ci* ``namespace`` - The :class:`Namespace` object that will be returned by
14617db96d56Sopenharmony_ci  :meth:`~ArgumentParser.parse_args`.  Most actions add an attribute to this
14627db96d56Sopenharmony_ci  object using :func:`setattr`.
14637db96d56Sopenharmony_ci
14647db96d56Sopenharmony_ci* ``values`` - The associated command-line arguments, with any type conversions
14657db96d56Sopenharmony_ci  applied.  Type conversions are specified with the type_ keyword argument to
14667db96d56Sopenharmony_ci  :meth:`~ArgumentParser.add_argument`.
14677db96d56Sopenharmony_ci
14687db96d56Sopenharmony_ci* ``option_string`` - The option string that was used to invoke this action.
14697db96d56Sopenharmony_ci  The ``option_string`` argument is optional, and will be absent if the action
14707db96d56Sopenharmony_ci  is associated with a positional argument.
14717db96d56Sopenharmony_ci
14727db96d56Sopenharmony_ciThe ``__call__`` method may perform arbitrary actions, but will typically set
14737db96d56Sopenharmony_ciattributes on the ``namespace`` based on ``dest`` and ``values``.
14747db96d56Sopenharmony_ci
14757db96d56Sopenharmony_ciAction subclasses can define a ``format_usage`` method that takes no argument
14767db96d56Sopenharmony_ciand return a string which will be used when printing the usage of the program.
14777db96d56Sopenharmony_ciIf such method is not provided, a sensible default will be used.
14787db96d56Sopenharmony_ci
14797db96d56Sopenharmony_ciThe parse_args() method
14807db96d56Sopenharmony_ci-----------------------
14817db96d56Sopenharmony_ci
14827db96d56Sopenharmony_ci.. method:: ArgumentParser.parse_args(args=None, namespace=None)
14837db96d56Sopenharmony_ci
14847db96d56Sopenharmony_ci   Convert argument strings to objects and assign them as attributes of the
14857db96d56Sopenharmony_ci   namespace.  Return the populated namespace.
14867db96d56Sopenharmony_ci
14877db96d56Sopenharmony_ci   Previous calls to :meth:`add_argument` determine exactly what objects are
14887db96d56Sopenharmony_ci   created and how they are assigned. See the documentation for
14897db96d56Sopenharmony_ci   :meth:`add_argument` for details.
14907db96d56Sopenharmony_ci
14917db96d56Sopenharmony_ci   * args_ - List of strings to parse.  The default is taken from
14927db96d56Sopenharmony_ci     :data:`sys.argv`.
14937db96d56Sopenharmony_ci
14947db96d56Sopenharmony_ci   * namespace_ - An object to take the attributes.  The default is a new empty
14957db96d56Sopenharmony_ci     :class:`Namespace` object.
14967db96d56Sopenharmony_ci
14977db96d56Sopenharmony_ci
14987db96d56Sopenharmony_ciOption value syntax
14997db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^^
15007db96d56Sopenharmony_ci
15017db96d56Sopenharmony_ciThe :meth:`~ArgumentParser.parse_args` method supports several ways of
15027db96d56Sopenharmony_cispecifying the value of an option (if it takes one).  In the simplest case, the
15037db96d56Sopenharmony_cioption and its value are passed as two separate arguments::
15047db96d56Sopenharmony_ci
15057db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
15067db96d56Sopenharmony_ci   >>> parser.add_argument('-x')
15077db96d56Sopenharmony_ci   >>> parser.add_argument('--foo')
15087db96d56Sopenharmony_ci   >>> parser.parse_args(['-x', 'X'])
15097db96d56Sopenharmony_ci   Namespace(foo=None, x='X')
15107db96d56Sopenharmony_ci   >>> parser.parse_args(['--foo', 'FOO'])
15117db96d56Sopenharmony_ci   Namespace(foo='FOO', x=None)
15127db96d56Sopenharmony_ci
15137db96d56Sopenharmony_ciFor long options (options with names longer than a single character), the option
15147db96d56Sopenharmony_ciand value can also be passed as a single command-line argument, using ``=`` to
15157db96d56Sopenharmony_ciseparate them::
15167db96d56Sopenharmony_ci
15177db96d56Sopenharmony_ci   >>> parser.parse_args(['--foo=FOO'])
15187db96d56Sopenharmony_ci   Namespace(foo='FOO', x=None)
15197db96d56Sopenharmony_ci
15207db96d56Sopenharmony_ciFor short options (options only one character long), the option and its value
15217db96d56Sopenharmony_cican be concatenated::
15227db96d56Sopenharmony_ci
15237db96d56Sopenharmony_ci   >>> parser.parse_args(['-xX'])
15247db96d56Sopenharmony_ci   Namespace(foo=None, x='X')
15257db96d56Sopenharmony_ci
15267db96d56Sopenharmony_ciSeveral short options can be joined together, using only a single ``-`` prefix,
15277db96d56Sopenharmony_cias long as only the last option (or none of them) requires a value::
15287db96d56Sopenharmony_ci
15297db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
15307db96d56Sopenharmony_ci   >>> parser.add_argument('-x', action='store_true')
15317db96d56Sopenharmony_ci   >>> parser.add_argument('-y', action='store_true')
15327db96d56Sopenharmony_ci   >>> parser.add_argument('-z')
15337db96d56Sopenharmony_ci   >>> parser.parse_args(['-xyzZ'])
15347db96d56Sopenharmony_ci   Namespace(x=True, y=True, z='Z')
15357db96d56Sopenharmony_ci
15367db96d56Sopenharmony_ci
15377db96d56Sopenharmony_ciInvalid arguments
15387db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^
15397db96d56Sopenharmony_ci
15407db96d56Sopenharmony_ciWhile parsing the command line, :meth:`~ArgumentParser.parse_args` checks for a
15417db96d56Sopenharmony_civariety of errors, including ambiguous options, invalid types, invalid options,
15427db96d56Sopenharmony_ciwrong number of positional arguments, etc.  When it encounters such an error,
15437db96d56Sopenharmony_ciit exits and prints the error along with a usage message::
15447db96d56Sopenharmony_ci
15457db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
15467db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', type=int)
15477db96d56Sopenharmony_ci   >>> parser.add_argument('bar', nargs='?')
15487db96d56Sopenharmony_ci
15497db96d56Sopenharmony_ci   >>> # invalid type
15507db96d56Sopenharmony_ci   >>> parser.parse_args(['--foo', 'spam'])
15517db96d56Sopenharmony_ci   usage: PROG [-h] [--foo FOO] [bar]
15527db96d56Sopenharmony_ci   PROG: error: argument --foo: invalid int value: 'spam'
15537db96d56Sopenharmony_ci
15547db96d56Sopenharmony_ci   >>> # invalid option
15557db96d56Sopenharmony_ci   >>> parser.parse_args(['--bar'])
15567db96d56Sopenharmony_ci   usage: PROG [-h] [--foo FOO] [bar]
15577db96d56Sopenharmony_ci   PROG: error: no such option: --bar
15587db96d56Sopenharmony_ci
15597db96d56Sopenharmony_ci   >>> # wrong number of arguments
15607db96d56Sopenharmony_ci   >>> parser.parse_args(['spam', 'badger'])
15617db96d56Sopenharmony_ci   usage: PROG [-h] [--foo FOO] [bar]
15627db96d56Sopenharmony_ci   PROG: error: extra arguments found: badger
15637db96d56Sopenharmony_ci
15647db96d56Sopenharmony_ci
15657db96d56Sopenharmony_ciArguments containing ``-``
15667db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^^^
15677db96d56Sopenharmony_ci
15687db96d56Sopenharmony_ciThe :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever
15697db96d56Sopenharmony_cithe user has clearly made a mistake, but some situations are inherently
15707db96d56Sopenharmony_ciambiguous.  For example, the command-line argument ``-1`` could either be an
15717db96d56Sopenharmony_ciattempt to specify an option or an attempt to provide a positional argument.
15727db96d56Sopenharmony_ciThe :meth:`~ArgumentParser.parse_args` method is cautious here: positional
15737db96d56Sopenharmony_ciarguments may only begin with ``-`` if they look like negative numbers and
15747db96d56Sopenharmony_cithere are no options in the parser that look like negative numbers::
15757db96d56Sopenharmony_ci
15767db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
15777db96d56Sopenharmony_ci   >>> parser.add_argument('-x')
15787db96d56Sopenharmony_ci   >>> parser.add_argument('foo', nargs='?')
15797db96d56Sopenharmony_ci
15807db96d56Sopenharmony_ci   >>> # no negative number options, so -1 is a positional argument
15817db96d56Sopenharmony_ci   >>> parser.parse_args(['-x', '-1'])
15827db96d56Sopenharmony_ci   Namespace(foo=None, x='-1')
15837db96d56Sopenharmony_ci
15847db96d56Sopenharmony_ci   >>> # no negative number options, so -1 and -5 are positional arguments
15857db96d56Sopenharmony_ci   >>> parser.parse_args(['-x', '-1', '-5'])
15867db96d56Sopenharmony_ci   Namespace(foo='-5', x='-1')
15877db96d56Sopenharmony_ci
15887db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
15897db96d56Sopenharmony_ci   >>> parser.add_argument('-1', dest='one')
15907db96d56Sopenharmony_ci   >>> parser.add_argument('foo', nargs='?')
15917db96d56Sopenharmony_ci
15927db96d56Sopenharmony_ci   >>> # negative number options present, so -1 is an option
15937db96d56Sopenharmony_ci   >>> parser.parse_args(['-1', 'X'])
15947db96d56Sopenharmony_ci   Namespace(foo=None, one='X')
15957db96d56Sopenharmony_ci
15967db96d56Sopenharmony_ci   >>> # negative number options present, so -2 is an option
15977db96d56Sopenharmony_ci   >>> parser.parse_args(['-2'])
15987db96d56Sopenharmony_ci   usage: PROG [-h] [-1 ONE] [foo]
15997db96d56Sopenharmony_ci   PROG: error: no such option: -2
16007db96d56Sopenharmony_ci
16017db96d56Sopenharmony_ci   >>> # negative number options present, so both -1s are options
16027db96d56Sopenharmony_ci   >>> parser.parse_args(['-1', '-1'])
16037db96d56Sopenharmony_ci   usage: PROG [-h] [-1 ONE] [foo]
16047db96d56Sopenharmony_ci   PROG: error: argument -1: expected one argument
16057db96d56Sopenharmony_ci
16067db96d56Sopenharmony_ciIf you have positional arguments that must begin with ``-`` and don't look
16077db96d56Sopenharmony_cilike negative numbers, you can insert the pseudo-argument ``'--'`` which tells
16087db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_args` that everything after that is a positional
16097db96d56Sopenharmony_ciargument::
16107db96d56Sopenharmony_ci
16117db96d56Sopenharmony_ci   >>> parser.parse_args(['--', '-f'])
16127db96d56Sopenharmony_ci   Namespace(foo='-f', one=None)
16137db96d56Sopenharmony_ci
16147db96d56Sopenharmony_ci.. _prefix-matching:
16157db96d56Sopenharmony_ci
16167db96d56Sopenharmony_ciArgument abbreviations (prefix matching)
16177db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16187db96d56Sopenharmony_ci
16197db96d56Sopenharmony_ciThe :meth:`~ArgumentParser.parse_args` method :ref:`by default <allow_abbrev>`
16207db96d56Sopenharmony_ciallows long options to be abbreviated to a prefix, if the abbreviation is
16217db96d56Sopenharmony_ciunambiguous (the prefix matches a unique option)::
16227db96d56Sopenharmony_ci
16237db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser(prog='PROG')
16247db96d56Sopenharmony_ci   >>> parser.add_argument('-bacon')
16257db96d56Sopenharmony_ci   >>> parser.add_argument('-badger')
16267db96d56Sopenharmony_ci   >>> parser.parse_args('-bac MMM'.split())
16277db96d56Sopenharmony_ci   Namespace(bacon='MMM', badger=None)
16287db96d56Sopenharmony_ci   >>> parser.parse_args('-bad WOOD'.split())
16297db96d56Sopenharmony_ci   Namespace(bacon=None, badger='WOOD')
16307db96d56Sopenharmony_ci   >>> parser.parse_args('-ba BA'.split())
16317db96d56Sopenharmony_ci   usage: PROG [-h] [-bacon BACON] [-badger BADGER]
16327db96d56Sopenharmony_ci   PROG: error: ambiguous option: -ba could match -badger, -bacon
16337db96d56Sopenharmony_ci
16347db96d56Sopenharmony_ciAn error is produced for arguments that could produce more than one options.
16357db96d56Sopenharmony_ciThis feature can be disabled by setting :ref:`allow_abbrev` to ``False``.
16367db96d56Sopenharmony_ci
16377db96d56Sopenharmony_ci.. _args:
16387db96d56Sopenharmony_ci
16397db96d56Sopenharmony_ciBeyond ``sys.argv``
16407db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^^
16417db96d56Sopenharmony_ci
16427db96d56Sopenharmony_ciSometimes it may be useful to have an ArgumentParser parse arguments other than those
16437db96d56Sopenharmony_ciof :data:`sys.argv`.  This can be accomplished by passing a list of strings to
16447db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_args`.  This is useful for testing at the
16457db96d56Sopenharmony_ciinteractive prompt::
16467db96d56Sopenharmony_ci
16477db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
16487db96d56Sopenharmony_ci   >>> parser.add_argument(
16497db96d56Sopenharmony_ci   ...     'integers', metavar='int', type=int, choices=range(10),
16507db96d56Sopenharmony_ci   ...     nargs='+', help='an integer in the range 0..9')
16517db96d56Sopenharmony_ci   >>> parser.add_argument(
16527db96d56Sopenharmony_ci   ...     '--sum', dest='accumulate', action='store_const', const=sum,
16537db96d56Sopenharmony_ci   ...     default=max, help='sum the integers (default: find the max)')
16547db96d56Sopenharmony_ci   >>> parser.parse_args(['1', '2', '3', '4'])
16557db96d56Sopenharmony_ci   Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
16567db96d56Sopenharmony_ci   >>> parser.parse_args(['1', '2', '3', '4', '--sum'])
16577db96d56Sopenharmony_ci   Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
16587db96d56Sopenharmony_ci
16597db96d56Sopenharmony_ci.. _namespace:
16607db96d56Sopenharmony_ci
16617db96d56Sopenharmony_ciThe Namespace object
16627db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^
16637db96d56Sopenharmony_ci
16647db96d56Sopenharmony_ci.. class:: Namespace
16657db96d56Sopenharmony_ci
16667db96d56Sopenharmony_ci   Simple class used by default by :meth:`~ArgumentParser.parse_args` to create
16677db96d56Sopenharmony_ci   an object holding attributes and return it.
16687db96d56Sopenharmony_ci
16697db96d56Sopenharmony_ciThis class is deliberately simple, just an :class:`object` subclass with a
16707db96d56Sopenharmony_cireadable string representation. If you prefer to have dict-like view of the
16717db96d56Sopenharmony_ciattributes, you can use the standard Python idiom, :func:`vars`::
16727db96d56Sopenharmony_ci
16737db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
16747db96d56Sopenharmony_ci   >>> parser.add_argument('--foo')
16757db96d56Sopenharmony_ci   >>> args = parser.parse_args(['--foo', 'BAR'])
16767db96d56Sopenharmony_ci   >>> vars(args)
16777db96d56Sopenharmony_ci   {'foo': 'BAR'}
16787db96d56Sopenharmony_ci
16797db96d56Sopenharmony_ciIt may also be useful to have an :class:`ArgumentParser` assign attributes to an
16807db96d56Sopenharmony_cialready existing object, rather than a new :class:`Namespace` object.  This can
16817db96d56Sopenharmony_cibe achieved by specifying the ``namespace=`` keyword argument::
16827db96d56Sopenharmony_ci
16837db96d56Sopenharmony_ci   >>> class C:
16847db96d56Sopenharmony_ci   ...     pass
16857db96d56Sopenharmony_ci   ...
16867db96d56Sopenharmony_ci   >>> c = C()
16877db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
16887db96d56Sopenharmony_ci   >>> parser.add_argument('--foo')
16897db96d56Sopenharmony_ci   >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
16907db96d56Sopenharmony_ci   >>> c.foo
16917db96d56Sopenharmony_ci   'BAR'
16927db96d56Sopenharmony_ci
16937db96d56Sopenharmony_ci
16947db96d56Sopenharmony_ciOther utilities
16957db96d56Sopenharmony_ci---------------
16967db96d56Sopenharmony_ci
16977db96d56Sopenharmony_ciSub-commands
16987db96d56Sopenharmony_ci^^^^^^^^^^^^
16997db96d56Sopenharmony_ci
17007db96d56Sopenharmony_ci.. method:: ArgumentParser.add_subparsers([title], [description], [prog], \
17017db96d56Sopenharmony_ci                                          [parser_class], [action], \
17027db96d56Sopenharmony_ci                                          [option_strings], [dest], [required], \
17037db96d56Sopenharmony_ci                                          [help], [metavar])
17047db96d56Sopenharmony_ci
17057db96d56Sopenharmony_ci   Many programs split up their functionality into a number of sub-commands,
17067db96d56Sopenharmony_ci   for example, the ``svn`` program can invoke sub-commands like ``svn
17077db96d56Sopenharmony_ci   checkout``, ``svn update``, and ``svn commit``.  Splitting up functionality
17087db96d56Sopenharmony_ci   this way can be a particularly good idea when a program performs several
17097db96d56Sopenharmony_ci   different functions which require different kinds of command-line arguments.
17107db96d56Sopenharmony_ci   :class:`ArgumentParser` supports the creation of such sub-commands with the
17117db96d56Sopenharmony_ci   :meth:`add_subparsers` method.  The :meth:`add_subparsers` method is normally
17127db96d56Sopenharmony_ci   called with no arguments and returns a special action object.  This object
17137db96d56Sopenharmony_ci   has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a
17147db96d56Sopenharmony_ci   command name and any :class:`ArgumentParser` constructor arguments, and
17157db96d56Sopenharmony_ci   returns an :class:`ArgumentParser` object that can be modified as usual.
17167db96d56Sopenharmony_ci
17177db96d56Sopenharmony_ci   Description of parameters:
17187db96d56Sopenharmony_ci
17197db96d56Sopenharmony_ci   * title - title for the sub-parser group in help output; by default
17207db96d56Sopenharmony_ci     "subcommands" if description is provided, otherwise uses title for
17217db96d56Sopenharmony_ci     positional arguments
17227db96d56Sopenharmony_ci
17237db96d56Sopenharmony_ci   * description - description for the sub-parser group in help output, by
17247db96d56Sopenharmony_ci     default ``None``
17257db96d56Sopenharmony_ci
17267db96d56Sopenharmony_ci   * prog - usage information that will be displayed with sub-command help,
17277db96d56Sopenharmony_ci     by default the name of the program and any positional arguments before the
17287db96d56Sopenharmony_ci     subparser argument
17297db96d56Sopenharmony_ci
17307db96d56Sopenharmony_ci   * parser_class - class which will be used to create sub-parser instances, by
17317db96d56Sopenharmony_ci     default the class of the current parser (e.g. ArgumentParser)
17327db96d56Sopenharmony_ci
17337db96d56Sopenharmony_ci   * action_ - the basic type of action to be taken when this argument is
17347db96d56Sopenharmony_ci     encountered at the command line
17357db96d56Sopenharmony_ci
17367db96d56Sopenharmony_ci   * dest_ - name of the attribute under which sub-command name will be
17377db96d56Sopenharmony_ci     stored; by default ``None`` and no value is stored
17387db96d56Sopenharmony_ci
17397db96d56Sopenharmony_ci   * required_ - Whether or not a subcommand must be provided, by default
17407db96d56Sopenharmony_ci     ``False`` (added in 3.7)
17417db96d56Sopenharmony_ci
17427db96d56Sopenharmony_ci   * help_ - help for sub-parser group in help output, by default ``None``
17437db96d56Sopenharmony_ci
17447db96d56Sopenharmony_ci   * metavar_ - string presenting available sub-commands in help; by default it
17457db96d56Sopenharmony_ci     is ``None`` and presents sub-commands in form {cmd1, cmd2, ..}
17467db96d56Sopenharmony_ci
17477db96d56Sopenharmony_ci   Some example usage::
17487db96d56Sopenharmony_ci
17497db96d56Sopenharmony_ci     >>> # create the top-level parser
17507db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser(prog='PROG')
17517db96d56Sopenharmony_ci     >>> parser.add_argument('--foo', action='store_true', help='foo help')
17527db96d56Sopenharmony_ci     >>> subparsers = parser.add_subparsers(help='sub-command help')
17537db96d56Sopenharmony_ci     >>>
17547db96d56Sopenharmony_ci     >>> # create the parser for the "a" command
17557db96d56Sopenharmony_ci     >>> parser_a = subparsers.add_parser('a', help='a help')
17567db96d56Sopenharmony_ci     >>> parser_a.add_argument('bar', type=int, help='bar help')
17577db96d56Sopenharmony_ci     >>>
17587db96d56Sopenharmony_ci     >>> # create the parser for the "b" command
17597db96d56Sopenharmony_ci     >>> parser_b = subparsers.add_parser('b', help='b help')
17607db96d56Sopenharmony_ci     >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
17617db96d56Sopenharmony_ci     >>>
17627db96d56Sopenharmony_ci     >>> # parse some argument lists
17637db96d56Sopenharmony_ci     >>> parser.parse_args(['a', '12'])
17647db96d56Sopenharmony_ci     Namespace(bar=12, foo=False)
17657db96d56Sopenharmony_ci     >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
17667db96d56Sopenharmony_ci     Namespace(baz='Z', foo=True)
17677db96d56Sopenharmony_ci
17687db96d56Sopenharmony_ci   Note that the object returned by :meth:`parse_args` will only contain
17697db96d56Sopenharmony_ci   attributes for the main parser and the subparser that was selected by the
17707db96d56Sopenharmony_ci   command line (and not any other subparsers).  So in the example above, when
17717db96d56Sopenharmony_ci   the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are
17727db96d56Sopenharmony_ci   present, and when the ``b`` command is specified, only the ``foo`` and
17737db96d56Sopenharmony_ci   ``baz`` attributes are present.
17747db96d56Sopenharmony_ci
17757db96d56Sopenharmony_ci   Similarly, when a help message is requested from a subparser, only the help
17767db96d56Sopenharmony_ci   for that particular parser will be printed.  The help message will not
17777db96d56Sopenharmony_ci   include parent parser or sibling parser messages.  (A help message for each
17787db96d56Sopenharmony_ci   subparser command, however, can be given by supplying the ``help=`` argument
17797db96d56Sopenharmony_ci   to :meth:`~_SubParsersAction.add_parser` as above.)
17807db96d56Sopenharmony_ci
17817db96d56Sopenharmony_ci   ::
17827db96d56Sopenharmony_ci
17837db96d56Sopenharmony_ci     >>> parser.parse_args(['--help'])
17847db96d56Sopenharmony_ci     usage: PROG [-h] [--foo] {a,b} ...
17857db96d56Sopenharmony_ci
17867db96d56Sopenharmony_ci     positional arguments:
17877db96d56Sopenharmony_ci       {a,b}   sub-command help
17887db96d56Sopenharmony_ci         a     a help
17897db96d56Sopenharmony_ci         b     b help
17907db96d56Sopenharmony_ci
17917db96d56Sopenharmony_ci     options:
17927db96d56Sopenharmony_ci       -h, --help  show this help message and exit
17937db96d56Sopenharmony_ci       --foo   foo help
17947db96d56Sopenharmony_ci
17957db96d56Sopenharmony_ci     >>> parser.parse_args(['a', '--help'])
17967db96d56Sopenharmony_ci     usage: PROG a [-h] bar
17977db96d56Sopenharmony_ci
17987db96d56Sopenharmony_ci     positional arguments:
17997db96d56Sopenharmony_ci       bar     bar help
18007db96d56Sopenharmony_ci
18017db96d56Sopenharmony_ci     options:
18027db96d56Sopenharmony_ci       -h, --help  show this help message and exit
18037db96d56Sopenharmony_ci
18047db96d56Sopenharmony_ci     >>> parser.parse_args(['b', '--help'])
18057db96d56Sopenharmony_ci     usage: PROG b [-h] [--baz {X,Y,Z}]
18067db96d56Sopenharmony_ci
18077db96d56Sopenharmony_ci     options:
18087db96d56Sopenharmony_ci       -h, --help     show this help message and exit
18097db96d56Sopenharmony_ci       --baz {X,Y,Z}  baz help
18107db96d56Sopenharmony_ci
18117db96d56Sopenharmony_ci   The :meth:`add_subparsers` method also supports ``title`` and ``description``
18127db96d56Sopenharmony_ci   keyword arguments.  When either is present, the subparser's commands will
18137db96d56Sopenharmony_ci   appear in their own group in the help output.  For example::
18147db96d56Sopenharmony_ci
18157db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
18167db96d56Sopenharmony_ci     >>> subparsers = parser.add_subparsers(title='subcommands',
18177db96d56Sopenharmony_ci     ...                                    description='valid subcommands',
18187db96d56Sopenharmony_ci     ...                                    help='additional help')
18197db96d56Sopenharmony_ci     >>> subparsers.add_parser('foo')
18207db96d56Sopenharmony_ci     >>> subparsers.add_parser('bar')
18217db96d56Sopenharmony_ci     >>> parser.parse_args(['-h'])
18227db96d56Sopenharmony_ci     usage:  [-h] {foo,bar} ...
18237db96d56Sopenharmony_ci
18247db96d56Sopenharmony_ci     options:
18257db96d56Sopenharmony_ci       -h, --help  show this help message and exit
18267db96d56Sopenharmony_ci
18277db96d56Sopenharmony_ci     subcommands:
18287db96d56Sopenharmony_ci       valid subcommands
18297db96d56Sopenharmony_ci
18307db96d56Sopenharmony_ci       {foo,bar}   additional help
18317db96d56Sopenharmony_ci
18327db96d56Sopenharmony_ci   Furthermore, ``add_parser`` supports an additional ``aliases`` argument,
18337db96d56Sopenharmony_ci   which allows multiple strings to refer to the same subparser. This example,
18347db96d56Sopenharmony_ci   like ``svn``, aliases ``co`` as a shorthand for ``checkout``::
18357db96d56Sopenharmony_ci
18367db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
18377db96d56Sopenharmony_ci     >>> subparsers = parser.add_subparsers()
18387db96d56Sopenharmony_ci     >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
18397db96d56Sopenharmony_ci     >>> checkout.add_argument('foo')
18407db96d56Sopenharmony_ci     >>> parser.parse_args(['co', 'bar'])
18417db96d56Sopenharmony_ci     Namespace(foo='bar')
18427db96d56Sopenharmony_ci
18437db96d56Sopenharmony_ci   One particularly effective way of handling sub-commands is to combine the use
18447db96d56Sopenharmony_ci   of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so
18457db96d56Sopenharmony_ci   that each subparser knows which Python function it should execute.  For
18467db96d56Sopenharmony_ci   example::
18477db96d56Sopenharmony_ci
18487db96d56Sopenharmony_ci     >>> # sub-command functions
18497db96d56Sopenharmony_ci     >>> def foo(args):
18507db96d56Sopenharmony_ci     ...     print(args.x * args.y)
18517db96d56Sopenharmony_ci     ...
18527db96d56Sopenharmony_ci     >>> def bar(args):
18537db96d56Sopenharmony_ci     ...     print('((%s))' % args.z)
18547db96d56Sopenharmony_ci     ...
18557db96d56Sopenharmony_ci     >>> # create the top-level parser
18567db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
18577db96d56Sopenharmony_ci     >>> subparsers = parser.add_subparsers(required=True)
18587db96d56Sopenharmony_ci     >>>
18597db96d56Sopenharmony_ci     >>> # create the parser for the "foo" command
18607db96d56Sopenharmony_ci     >>> parser_foo = subparsers.add_parser('foo')
18617db96d56Sopenharmony_ci     >>> parser_foo.add_argument('-x', type=int, default=1)
18627db96d56Sopenharmony_ci     >>> parser_foo.add_argument('y', type=float)
18637db96d56Sopenharmony_ci     >>> parser_foo.set_defaults(func=foo)
18647db96d56Sopenharmony_ci     >>>
18657db96d56Sopenharmony_ci     >>> # create the parser for the "bar" command
18667db96d56Sopenharmony_ci     >>> parser_bar = subparsers.add_parser('bar')
18677db96d56Sopenharmony_ci     >>> parser_bar.add_argument('z')
18687db96d56Sopenharmony_ci     >>> parser_bar.set_defaults(func=bar)
18697db96d56Sopenharmony_ci     >>>
18707db96d56Sopenharmony_ci     >>> # parse the args and call whatever function was selected
18717db96d56Sopenharmony_ci     >>> args = parser.parse_args('foo 1 -x 2'.split())
18727db96d56Sopenharmony_ci     >>> args.func(args)
18737db96d56Sopenharmony_ci     2.0
18747db96d56Sopenharmony_ci     >>>
18757db96d56Sopenharmony_ci     >>> # parse the args and call whatever function was selected
18767db96d56Sopenharmony_ci     >>> args = parser.parse_args('bar XYZYX'.split())
18777db96d56Sopenharmony_ci     >>> args.func(args)
18787db96d56Sopenharmony_ci     ((XYZYX))
18797db96d56Sopenharmony_ci
18807db96d56Sopenharmony_ci   This way, you can let :meth:`parse_args` do the job of calling the
18817db96d56Sopenharmony_ci   appropriate function after argument parsing is complete.  Associating
18827db96d56Sopenharmony_ci   functions with actions like this is typically the easiest way to handle the
18837db96d56Sopenharmony_ci   different actions for each of your subparsers.  However, if it is necessary
18847db96d56Sopenharmony_ci   to check the name of the subparser that was invoked, the ``dest`` keyword
18857db96d56Sopenharmony_ci   argument to the :meth:`add_subparsers` call will work::
18867db96d56Sopenharmony_ci
18877db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
18887db96d56Sopenharmony_ci     >>> subparsers = parser.add_subparsers(dest='subparser_name')
18897db96d56Sopenharmony_ci     >>> subparser1 = subparsers.add_parser('1')
18907db96d56Sopenharmony_ci     >>> subparser1.add_argument('-x')
18917db96d56Sopenharmony_ci     >>> subparser2 = subparsers.add_parser('2')
18927db96d56Sopenharmony_ci     >>> subparser2.add_argument('y')
18937db96d56Sopenharmony_ci     >>> parser.parse_args(['2', 'frobble'])
18947db96d56Sopenharmony_ci     Namespace(subparser_name='2', y='frobble')
18957db96d56Sopenharmony_ci
18967db96d56Sopenharmony_ci   .. versionchanged:: 3.7
18977db96d56Sopenharmony_ci      New *required* keyword argument.
18987db96d56Sopenharmony_ci
18997db96d56Sopenharmony_ci
19007db96d56Sopenharmony_ciFileType objects
19017db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^
19027db96d56Sopenharmony_ci
19037db96d56Sopenharmony_ci.. class:: FileType(mode='r', bufsize=-1, encoding=None, errors=None)
19047db96d56Sopenharmony_ci
19057db96d56Sopenharmony_ci   The :class:`FileType` factory creates objects that can be passed to the type
19067db96d56Sopenharmony_ci   argument of :meth:`ArgumentParser.add_argument`.  Arguments that have
19077db96d56Sopenharmony_ci   :class:`FileType` objects as their type will open command-line arguments as
19087db96d56Sopenharmony_ci   files with the requested modes, buffer sizes, encodings and error handling
19097db96d56Sopenharmony_ci   (see the :func:`open` function for more details)::
19107db96d56Sopenharmony_ci
19117db96d56Sopenharmony_ci      >>> parser = argparse.ArgumentParser()
19127db96d56Sopenharmony_ci      >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
19137db96d56Sopenharmony_ci      >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
19147db96d56Sopenharmony_ci      >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
19157db96d56Sopenharmony_ci      Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)
19167db96d56Sopenharmony_ci
19177db96d56Sopenharmony_ci   FileType objects understand the pseudo-argument ``'-'`` and automatically
19187db96d56Sopenharmony_ci   convert this into :data:`sys.stdin` for readable :class:`FileType` objects and
19197db96d56Sopenharmony_ci   :data:`sys.stdout` for writable :class:`FileType` objects::
19207db96d56Sopenharmony_ci
19217db96d56Sopenharmony_ci      >>> parser = argparse.ArgumentParser()
19227db96d56Sopenharmony_ci      >>> parser.add_argument('infile', type=argparse.FileType('r'))
19237db96d56Sopenharmony_ci      >>> parser.parse_args(['-'])
19247db96d56Sopenharmony_ci      Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)
19257db96d56Sopenharmony_ci
19267db96d56Sopenharmony_ci   .. versionadded:: 3.4
19277db96d56Sopenharmony_ci      The *encodings* and *errors* keyword arguments.
19287db96d56Sopenharmony_ci
19297db96d56Sopenharmony_ci
19307db96d56Sopenharmony_ciArgument groups
19317db96d56Sopenharmony_ci^^^^^^^^^^^^^^^
19327db96d56Sopenharmony_ci
19337db96d56Sopenharmony_ci.. method:: ArgumentParser.add_argument_group(title=None, description=None)
19347db96d56Sopenharmony_ci
19357db96d56Sopenharmony_ci   By default, :class:`ArgumentParser` groups command-line arguments into
19367db96d56Sopenharmony_ci   "positional arguments" and "options" when displaying help
19377db96d56Sopenharmony_ci   messages. When there is a better conceptual grouping of arguments than this
19387db96d56Sopenharmony_ci   default one, appropriate groups can be created using the
19397db96d56Sopenharmony_ci   :meth:`add_argument_group` method::
19407db96d56Sopenharmony_ci
19417db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
19427db96d56Sopenharmony_ci     >>> group = parser.add_argument_group('group')
19437db96d56Sopenharmony_ci     >>> group.add_argument('--foo', help='foo help')
19447db96d56Sopenharmony_ci     >>> group.add_argument('bar', help='bar help')
19457db96d56Sopenharmony_ci     >>> parser.print_help()
19467db96d56Sopenharmony_ci     usage: PROG [--foo FOO] bar
19477db96d56Sopenharmony_ci
19487db96d56Sopenharmony_ci     group:
19497db96d56Sopenharmony_ci       bar    bar help
19507db96d56Sopenharmony_ci       --foo FOO  foo help
19517db96d56Sopenharmony_ci
19527db96d56Sopenharmony_ci   The :meth:`add_argument_group` method returns an argument group object which
19537db96d56Sopenharmony_ci   has an :meth:`~ArgumentParser.add_argument` method just like a regular
19547db96d56Sopenharmony_ci   :class:`ArgumentParser`.  When an argument is added to the group, the parser
19557db96d56Sopenharmony_ci   treats it just like a normal argument, but displays the argument in a
19567db96d56Sopenharmony_ci   separate group for help messages.  The :meth:`add_argument_group` method
19577db96d56Sopenharmony_ci   accepts *title* and *description* arguments which can be used to
19587db96d56Sopenharmony_ci   customize this display::
19597db96d56Sopenharmony_ci
19607db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
19617db96d56Sopenharmony_ci     >>> group1 = parser.add_argument_group('group1', 'group1 description')
19627db96d56Sopenharmony_ci     >>> group1.add_argument('foo', help='foo help')
19637db96d56Sopenharmony_ci     >>> group2 = parser.add_argument_group('group2', 'group2 description')
19647db96d56Sopenharmony_ci     >>> group2.add_argument('--bar', help='bar help')
19657db96d56Sopenharmony_ci     >>> parser.print_help()
19667db96d56Sopenharmony_ci     usage: PROG [--bar BAR] foo
19677db96d56Sopenharmony_ci
19687db96d56Sopenharmony_ci     group1:
19697db96d56Sopenharmony_ci       group1 description
19707db96d56Sopenharmony_ci
19717db96d56Sopenharmony_ci       foo    foo help
19727db96d56Sopenharmony_ci
19737db96d56Sopenharmony_ci     group2:
19747db96d56Sopenharmony_ci       group2 description
19757db96d56Sopenharmony_ci
19767db96d56Sopenharmony_ci       --bar BAR  bar help
19777db96d56Sopenharmony_ci
19787db96d56Sopenharmony_ci   Note that any arguments not in your user-defined groups will end up back
19797db96d56Sopenharmony_ci   in the usual "positional arguments" and "optional arguments" sections.
19807db96d56Sopenharmony_ci
19817db96d56Sopenharmony_ci   .. versionchanged:: 3.11
19827db96d56Sopenharmony_ci    Calling :meth:`add_argument_group` on an argument group is deprecated.
19837db96d56Sopenharmony_ci    This feature was never supported and does not always work correctly.
19847db96d56Sopenharmony_ci    The function exists on the API by accident through inheritance and
19857db96d56Sopenharmony_ci    will be removed in the future.
19867db96d56Sopenharmony_ci
19877db96d56Sopenharmony_ci
19887db96d56Sopenharmony_ciMutual exclusion
19897db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^
19907db96d56Sopenharmony_ci
19917db96d56Sopenharmony_ci.. method:: ArgumentParser.add_mutually_exclusive_group(required=False)
19927db96d56Sopenharmony_ci
19937db96d56Sopenharmony_ci   Create a mutually exclusive group. :mod:`argparse` will make sure that only
19947db96d56Sopenharmony_ci   one of the arguments in the mutually exclusive group was present on the
19957db96d56Sopenharmony_ci   command line::
19967db96d56Sopenharmony_ci
19977db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser(prog='PROG')
19987db96d56Sopenharmony_ci     >>> group = parser.add_mutually_exclusive_group()
19997db96d56Sopenharmony_ci     >>> group.add_argument('--foo', action='store_true')
20007db96d56Sopenharmony_ci     >>> group.add_argument('--bar', action='store_false')
20017db96d56Sopenharmony_ci     >>> parser.parse_args(['--foo'])
20027db96d56Sopenharmony_ci     Namespace(bar=True, foo=True)
20037db96d56Sopenharmony_ci     >>> parser.parse_args(['--bar'])
20047db96d56Sopenharmony_ci     Namespace(bar=False, foo=False)
20057db96d56Sopenharmony_ci     >>> parser.parse_args(['--foo', '--bar'])
20067db96d56Sopenharmony_ci     usage: PROG [-h] [--foo | --bar]
20077db96d56Sopenharmony_ci     PROG: error: argument --bar: not allowed with argument --foo
20087db96d56Sopenharmony_ci
20097db96d56Sopenharmony_ci   The :meth:`add_mutually_exclusive_group` method also accepts a *required*
20107db96d56Sopenharmony_ci   argument, to indicate that at least one of the mutually exclusive arguments
20117db96d56Sopenharmony_ci   is required::
20127db96d56Sopenharmony_ci
20137db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser(prog='PROG')
20147db96d56Sopenharmony_ci     >>> group = parser.add_mutually_exclusive_group(required=True)
20157db96d56Sopenharmony_ci     >>> group.add_argument('--foo', action='store_true')
20167db96d56Sopenharmony_ci     >>> group.add_argument('--bar', action='store_false')
20177db96d56Sopenharmony_ci     >>> parser.parse_args([])
20187db96d56Sopenharmony_ci     usage: PROG [-h] (--foo | --bar)
20197db96d56Sopenharmony_ci     PROG: error: one of the arguments --foo --bar is required
20207db96d56Sopenharmony_ci
20217db96d56Sopenharmony_ci   Note that currently mutually exclusive argument groups do not support the
20227db96d56Sopenharmony_ci   *title* and *description* arguments of
20237db96d56Sopenharmony_ci   :meth:`~ArgumentParser.add_argument_group`.
20247db96d56Sopenharmony_ci
20257db96d56Sopenharmony_ci   .. versionchanged:: 3.11
20267db96d56Sopenharmony_ci    Calling :meth:`add_argument_group` or :meth:`add_mutually_exclusive_group`
20277db96d56Sopenharmony_ci    on a mutually exclusive group is deprecated. These features were never
20287db96d56Sopenharmony_ci    supported and do not always work correctly. The functions exist on the
20297db96d56Sopenharmony_ci    API by accident through inheritance and will be removed in the future.
20307db96d56Sopenharmony_ci
20317db96d56Sopenharmony_ci
20327db96d56Sopenharmony_ciParser defaults
20337db96d56Sopenharmony_ci^^^^^^^^^^^^^^^
20347db96d56Sopenharmony_ci
20357db96d56Sopenharmony_ci.. method:: ArgumentParser.set_defaults(**kwargs)
20367db96d56Sopenharmony_ci
20377db96d56Sopenharmony_ci   Most of the time, the attributes of the object returned by :meth:`parse_args`
20387db96d56Sopenharmony_ci   will be fully determined by inspecting the command-line arguments and the argument
20397db96d56Sopenharmony_ci   actions.  :meth:`set_defaults` allows some additional
20407db96d56Sopenharmony_ci   attributes that are determined without any inspection of the command line to
20417db96d56Sopenharmony_ci   be added::
20427db96d56Sopenharmony_ci
20437db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
20447db96d56Sopenharmony_ci     >>> parser.add_argument('foo', type=int)
20457db96d56Sopenharmony_ci     >>> parser.set_defaults(bar=42, baz='badger')
20467db96d56Sopenharmony_ci     >>> parser.parse_args(['736'])
20477db96d56Sopenharmony_ci     Namespace(bar=42, baz='badger', foo=736)
20487db96d56Sopenharmony_ci
20497db96d56Sopenharmony_ci   Note that parser-level defaults always override argument-level defaults::
20507db96d56Sopenharmony_ci
20517db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
20527db96d56Sopenharmony_ci     >>> parser.add_argument('--foo', default='bar')
20537db96d56Sopenharmony_ci     >>> parser.set_defaults(foo='spam')
20547db96d56Sopenharmony_ci     >>> parser.parse_args([])
20557db96d56Sopenharmony_ci     Namespace(foo='spam')
20567db96d56Sopenharmony_ci
20577db96d56Sopenharmony_ci   Parser-level defaults can be particularly useful when working with multiple
20587db96d56Sopenharmony_ci   parsers.  See the :meth:`~ArgumentParser.add_subparsers` method for an
20597db96d56Sopenharmony_ci   example of this type.
20607db96d56Sopenharmony_ci
20617db96d56Sopenharmony_ci.. method:: ArgumentParser.get_default(dest)
20627db96d56Sopenharmony_ci
20637db96d56Sopenharmony_ci   Get the default value for a namespace attribute, as set by either
20647db96d56Sopenharmony_ci   :meth:`~ArgumentParser.add_argument` or by
20657db96d56Sopenharmony_ci   :meth:`~ArgumentParser.set_defaults`::
20667db96d56Sopenharmony_ci
20677db96d56Sopenharmony_ci     >>> parser = argparse.ArgumentParser()
20687db96d56Sopenharmony_ci     >>> parser.add_argument('--foo', default='badger')
20697db96d56Sopenharmony_ci     >>> parser.get_default('foo')
20707db96d56Sopenharmony_ci     'badger'
20717db96d56Sopenharmony_ci
20727db96d56Sopenharmony_ci
20737db96d56Sopenharmony_ciPrinting help
20747db96d56Sopenharmony_ci^^^^^^^^^^^^^
20757db96d56Sopenharmony_ci
20767db96d56Sopenharmony_ciIn most typical applications, :meth:`~ArgumentParser.parse_args` will take
20777db96d56Sopenharmony_cicare of formatting and printing any usage or error messages.  However, several
20787db96d56Sopenharmony_ciformatting methods are available:
20797db96d56Sopenharmony_ci
20807db96d56Sopenharmony_ci.. method:: ArgumentParser.print_usage(file=None)
20817db96d56Sopenharmony_ci
20827db96d56Sopenharmony_ci   Print a brief description of how the :class:`ArgumentParser` should be
20837db96d56Sopenharmony_ci   invoked on the command line.  If *file* is ``None``, :data:`sys.stdout` is
20847db96d56Sopenharmony_ci   assumed.
20857db96d56Sopenharmony_ci
20867db96d56Sopenharmony_ci.. method:: ArgumentParser.print_help(file=None)
20877db96d56Sopenharmony_ci
20887db96d56Sopenharmony_ci   Print a help message, including the program usage and information about the
20897db96d56Sopenharmony_ci   arguments registered with the :class:`ArgumentParser`.  If *file* is
20907db96d56Sopenharmony_ci   ``None``, :data:`sys.stdout` is assumed.
20917db96d56Sopenharmony_ci
20927db96d56Sopenharmony_ciThere are also variants of these methods that simply return a string instead of
20937db96d56Sopenharmony_ciprinting it:
20947db96d56Sopenharmony_ci
20957db96d56Sopenharmony_ci.. method:: ArgumentParser.format_usage()
20967db96d56Sopenharmony_ci
20977db96d56Sopenharmony_ci   Return a string containing a brief description of how the
20987db96d56Sopenharmony_ci   :class:`ArgumentParser` should be invoked on the command line.
20997db96d56Sopenharmony_ci
21007db96d56Sopenharmony_ci.. method:: ArgumentParser.format_help()
21017db96d56Sopenharmony_ci
21027db96d56Sopenharmony_ci   Return a string containing a help message, including the program usage and
21037db96d56Sopenharmony_ci   information about the arguments registered with the :class:`ArgumentParser`.
21047db96d56Sopenharmony_ci
21057db96d56Sopenharmony_ci
21067db96d56Sopenharmony_ciPartial parsing
21077db96d56Sopenharmony_ci^^^^^^^^^^^^^^^
21087db96d56Sopenharmony_ci
21097db96d56Sopenharmony_ci.. method:: ArgumentParser.parse_known_args(args=None, namespace=None)
21107db96d56Sopenharmony_ci
21117db96d56Sopenharmony_ciSometimes a script may only parse a few of the command-line arguments, passing
21127db96d56Sopenharmony_cithe remaining arguments on to another script or program. In these cases, the
21137db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_known_args` method can be useful.  It works much like
21147db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_args` except that it does not produce an error when
21157db96d56Sopenharmony_ciextra arguments are present.  Instead, it returns a two item tuple containing
21167db96d56Sopenharmony_cithe populated namespace and the list of remaining argument strings.
21177db96d56Sopenharmony_ci
21187db96d56Sopenharmony_ci::
21197db96d56Sopenharmony_ci
21207db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
21217db96d56Sopenharmony_ci   >>> parser.add_argument('--foo', action='store_true')
21227db96d56Sopenharmony_ci   >>> parser.add_argument('bar')
21237db96d56Sopenharmony_ci   >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
21247db96d56Sopenharmony_ci   (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])
21257db96d56Sopenharmony_ci
21267db96d56Sopenharmony_ci.. warning::
21277db96d56Sopenharmony_ci   :ref:`Prefix matching <prefix-matching>` rules apply to
21287db96d56Sopenharmony_ci   :meth:`~ArgumentParser.parse_known_args`. The parser may consume an option even if it's just
21297db96d56Sopenharmony_ci   a prefix of one of its known options, instead of leaving it in the remaining
21307db96d56Sopenharmony_ci   arguments list.
21317db96d56Sopenharmony_ci
21327db96d56Sopenharmony_ci
21337db96d56Sopenharmony_ciCustomizing file parsing
21347db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^
21357db96d56Sopenharmony_ci
21367db96d56Sopenharmony_ci.. method:: ArgumentParser.convert_arg_line_to_args(arg_line)
21377db96d56Sopenharmony_ci
21387db96d56Sopenharmony_ci   Arguments that are read from a file (see the *fromfile_prefix_chars*
21397db96d56Sopenharmony_ci   keyword argument to the :class:`ArgumentParser` constructor) are read one
21407db96d56Sopenharmony_ci   argument per line. :meth:`convert_arg_line_to_args` can be overridden for
21417db96d56Sopenharmony_ci   fancier reading.
21427db96d56Sopenharmony_ci
21437db96d56Sopenharmony_ci   This method takes a single argument *arg_line* which is a string read from
21447db96d56Sopenharmony_ci   the argument file.  It returns a list of arguments parsed from this string.
21457db96d56Sopenharmony_ci   The method is called once per line read from the argument file, in order.
21467db96d56Sopenharmony_ci
21477db96d56Sopenharmony_ci   A useful override of this method is one that treats each space-separated word
21487db96d56Sopenharmony_ci   as an argument.  The following example demonstrates how to do this::
21497db96d56Sopenharmony_ci
21507db96d56Sopenharmony_ci    class MyArgumentParser(argparse.ArgumentParser):
21517db96d56Sopenharmony_ci        def convert_arg_line_to_args(self, arg_line):
21527db96d56Sopenharmony_ci            return arg_line.split()
21537db96d56Sopenharmony_ci
21547db96d56Sopenharmony_ci
21557db96d56Sopenharmony_ciExiting methods
21567db96d56Sopenharmony_ci^^^^^^^^^^^^^^^
21577db96d56Sopenharmony_ci
21587db96d56Sopenharmony_ci.. method:: ArgumentParser.exit(status=0, message=None)
21597db96d56Sopenharmony_ci
21607db96d56Sopenharmony_ci   This method terminates the program, exiting with the specified *status*
21617db96d56Sopenharmony_ci   and, if given, it prints a *message* before that. The user can override
21627db96d56Sopenharmony_ci   this method to handle these steps differently::
21637db96d56Sopenharmony_ci
21647db96d56Sopenharmony_ci    class ErrorCatchingArgumentParser(argparse.ArgumentParser):
21657db96d56Sopenharmony_ci        def exit(self, status=0, message=None):
21667db96d56Sopenharmony_ci            if status:
21677db96d56Sopenharmony_ci                raise Exception(f'Exiting because of an error: {message}')
21687db96d56Sopenharmony_ci            exit(status)
21697db96d56Sopenharmony_ci
21707db96d56Sopenharmony_ci.. method:: ArgumentParser.error(message)
21717db96d56Sopenharmony_ci
21727db96d56Sopenharmony_ci   This method prints a usage message including the *message* to the
21737db96d56Sopenharmony_ci   standard error and terminates the program with a status code of 2.
21747db96d56Sopenharmony_ci
21757db96d56Sopenharmony_ci
21767db96d56Sopenharmony_ciIntermixed parsing
21777db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^
21787db96d56Sopenharmony_ci
21797db96d56Sopenharmony_ci.. method:: ArgumentParser.parse_intermixed_args(args=None, namespace=None)
21807db96d56Sopenharmony_ci.. method:: ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)
21817db96d56Sopenharmony_ci
21827db96d56Sopenharmony_ciA number of Unix commands allow the user to intermix optional arguments with
21837db96d56Sopenharmony_cipositional arguments.  The :meth:`~ArgumentParser.parse_intermixed_args`
21847db96d56Sopenharmony_ciand :meth:`~ArgumentParser.parse_known_intermixed_args` methods
21857db96d56Sopenharmony_cisupport this parsing style.
21867db96d56Sopenharmony_ci
21877db96d56Sopenharmony_ciThese parsers do not support all the argparse features, and will raise
21887db96d56Sopenharmony_ciexceptions if unsupported features are used.  In particular, subparsers,
21897db96d56Sopenharmony_ciand mutually exclusive groups that include both
21907db96d56Sopenharmony_cioptionals and positionals are not supported.
21917db96d56Sopenharmony_ci
21927db96d56Sopenharmony_ciThe following example shows the difference between
21937db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_known_args` and
21947db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_intermixed_args`: the former returns ``['2',
21957db96d56Sopenharmony_ci'3']`` as unparsed arguments, while the latter collects all the positionals
21967db96d56Sopenharmony_ciinto ``rest``.  ::
21977db96d56Sopenharmony_ci
21987db96d56Sopenharmony_ci   >>> parser = argparse.ArgumentParser()
21997db96d56Sopenharmony_ci   >>> parser.add_argument('--foo')
22007db96d56Sopenharmony_ci   >>> parser.add_argument('cmd')
22017db96d56Sopenharmony_ci   >>> parser.add_argument('rest', nargs='*', type=int)
22027db96d56Sopenharmony_ci   >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
22037db96d56Sopenharmony_ci   (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
22047db96d56Sopenharmony_ci   >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
22057db96d56Sopenharmony_ci   Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])
22067db96d56Sopenharmony_ci
22077db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_known_intermixed_args` returns a two item tuple
22087db96d56Sopenharmony_cicontaining the populated namespace and the list of remaining argument strings.
22097db96d56Sopenharmony_ci:meth:`~ArgumentParser.parse_intermixed_args` raises an error if there are any
22107db96d56Sopenharmony_ciremaining unparsed argument strings.
22117db96d56Sopenharmony_ci
22127db96d56Sopenharmony_ci.. versionadded:: 3.7
22137db96d56Sopenharmony_ci
22147db96d56Sopenharmony_ci.. _upgrading-optparse-code:
22157db96d56Sopenharmony_ci
22167db96d56Sopenharmony_ciUpgrading optparse code
22177db96d56Sopenharmony_ci-----------------------
22187db96d56Sopenharmony_ci
22197db96d56Sopenharmony_ciOriginally, the :mod:`argparse` module had attempted to maintain compatibility
22207db96d56Sopenharmony_ciwith :mod:`optparse`.  However, :mod:`optparse` was difficult to extend
22217db96d56Sopenharmony_citransparently, particularly with the changes required to support the new
22227db96d56Sopenharmony_ci``nargs=`` specifiers and better usage messages.  When most everything in
22237db96d56Sopenharmony_ci:mod:`optparse` had either been copy-pasted over or monkey-patched, it no
22247db96d56Sopenharmony_cilonger seemed practical to try to maintain the backwards compatibility.
22257db96d56Sopenharmony_ci
22267db96d56Sopenharmony_ciThe :mod:`argparse` module improves on the standard library :mod:`optparse`
22277db96d56Sopenharmony_cimodule in a number of ways including:
22287db96d56Sopenharmony_ci
22297db96d56Sopenharmony_ci* Handling positional arguments.
22307db96d56Sopenharmony_ci* Supporting sub-commands.
22317db96d56Sopenharmony_ci* Allowing alternative option prefixes like ``+`` and ``/``.
22327db96d56Sopenharmony_ci* Handling zero-or-more and one-or-more style arguments.
22337db96d56Sopenharmony_ci* Producing more informative usage messages.
22347db96d56Sopenharmony_ci* Providing a much simpler interface for custom ``type`` and ``action``.
22357db96d56Sopenharmony_ci
22367db96d56Sopenharmony_ciA partial upgrade path from :mod:`optparse` to :mod:`argparse`:
22377db96d56Sopenharmony_ci
22387db96d56Sopenharmony_ci* Replace all :meth:`optparse.OptionParser.add_option` calls with
22397db96d56Sopenharmony_ci  :meth:`ArgumentParser.add_argument` calls.
22407db96d56Sopenharmony_ci
22417db96d56Sopenharmony_ci* Replace ``(options, args) = parser.parse_args()`` with ``args =
22427db96d56Sopenharmony_ci  parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
22437db96d56Sopenharmony_ci  calls for the positional arguments. Keep in mind that what was previously
22447db96d56Sopenharmony_ci  called ``options``, now in the :mod:`argparse` context is called ``args``.
22457db96d56Sopenharmony_ci
22467db96d56Sopenharmony_ci* Replace :meth:`optparse.OptionParser.disable_interspersed_args`
22477db96d56Sopenharmony_ci  by using :meth:`~ArgumentParser.parse_intermixed_args` instead of
22487db96d56Sopenharmony_ci  :meth:`~ArgumentParser.parse_args`.
22497db96d56Sopenharmony_ci
22507db96d56Sopenharmony_ci* Replace callback actions and the ``callback_*`` keyword arguments with
22517db96d56Sopenharmony_ci  ``type`` or ``action`` arguments.
22527db96d56Sopenharmony_ci
22537db96d56Sopenharmony_ci* Replace string names for ``type`` keyword arguments with the corresponding
22547db96d56Sopenharmony_ci  type objects (e.g. int, float, complex, etc).
22557db96d56Sopenharmony_ci
22567db96d56Sopenharmony_ci* Replace :class:`optparse.Values` with :class:`Namespace` and
22577db96d56Sopenharmony_ci  :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with
22587db96d56Sopenharmony_ci  :exc:`ArgumentError`.
22597db96d56Sopenharmony_ci
22607db96d56Sopenharmony_ci* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
22617db96d56Sopenharmony_ci  the standard Python syntax to use dictionaries to format strings, that is,
22627db96d56Sopenharmony_ci  ``%(default)s`` and ``%(prog)s``.
22637db96d56Sopenharmony_ci
22647db96d56Sopenharmony_ci* Replace the OptionParser constructor ``version`` argument with a call to
22657db96d56Sopenharmony_ci  ``parser.add_argument('--version', action='version', version='<the version>')``.
22667db96d56Sopenharmony_ci
22677db96d56Sopenharmony_ciExceptions
22687db96d56Sopenharmony_ci----------
22697db96d56Sopenharmony_ci
22707db96d56Sopenharmony_ci.. exception:: ArgumentError
22717db96d56Sopenharmony_ci
22727db96d56Sopenharmony_ci   An error from creating or using an argument (optional or positional).
22737db96d56Sopenharmony_ci
22747db96d56Sopenharmony_ci   The string value of this exception is the message, augmented with
22757db96d56Sopenharmony_ci   information about the argument that caused it.
22767db96d56Sopenharmony_ci
22777db96d56Sopenharmony_ci.. exception:: ArgumentTypeError
22787db96d56Sopenharmony_ci
22797db96d56Sopenharmony_ci   Raised when something goes wrong converting a command line string to a type.
2280