Update argparse docs to follow order of ArgumentParser() arguments.
This commit is contained in:
Andrew Svetlov
parent
e16f4dc80a
commit
5b6e1cad37
|
|
@ -137,40 +137,136 @@ ArgumentParser objects
|
|||
argument_default=None, conflict_handler='error', \
|
||||
add_help=True)
|
||||
|
||||
Create a new :class:`ArgumentParser` object. Each parameter has its own more
|
||||
detailed description below, but in short they are:
|
||||
Create a new :class:`ArgumentParser` object. All parameters should be passed
|
||||
as keyword arguments. Each parameter has its own more detailed description
|
||||
below, but in short they are:
|
||||
|
||||
* description_ - Text to display before the argument help.
|
||||
* prog_ - The name of the program (default: ``sys.argv[0]``)
|
||||
|
||||
* epilog_ - Text to display after the argument help.
|
||||
* usage_ - The string describing the program usage (default: generated from
|
||||
arguments added to parser)
|
||||
|
||||
* add_help_ - Add a -h/--help option to the parser. (default: ``True``)
|
||||
* description_ - Text to display before the argument help (default: none)
|
||||
|
||||
* argument_default_ - Set the global default value for arguments.
|
||||
(default: ``None``)
|
||||
* epilog_ - Text to display after the argument help (default: none)
|
||||
|
||||
* parents_ - A list of :class:`ArgumentParser` objects whose arguments should
|
||||
also be included.
|
||||
also be included
|
||||
|
||||
* prefix_chars_ - The set of characters that prefix optional arguments.
|
||||
* formatter_class_ - A class for customizing the help output
|
||||
|
||||
* prefix_chars_ - The set of characters that prefix optional arguments
|
||||
(default: '-')
|
||||
|
||||
* fromfile_prefix_chars_ - The set of characters that prefix files from
|
||||
which additional arguments should be read. (default: ``None``)
|
||||
which additional arguments should be read (default: ``None``)
|
||||
|
||||
* formatter_class_ - A class for customizing the help output.
|
||||
* argument_default_ - The global default value for arguments
|
||||
(default: ``None``)
|
||||
|
||||
* conflict_handler_ - Usually unnecessary, defines strategy for resolving
|
||||
conflicting optionals.
|
||||
* conflict_handler_ - The strategy for resolving conflicting optionals
|
||||
(usually unnecessary)
|
||||
|
||||
* prog_ - The name of the program (default:
|
||||
``sys.argv[0]``)
|
||||
|
||||
* usage_ - The string describing the program usage (default: generated)
|
||||
* add_help_ - Add a -h/--help option to the parser (default: ``True``)
|
||||
|
||||
The following sections describe how each of these are used.
|
||||
|
||||
|
||||
prog
|
||||
^^^^
|
||||
|
||||
By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determine
|
||||
how to display the name of the program in help messages. This default is almost
|
||||
always desirable because it will make the help messages match how the program was
|
||||
invoked on the command line. For example, consider a file named
|
||||
``myprogram.py`` with the following code::
|
||||
|
||||
import argparse
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument('--foo', help='foo help')
|
||||
args = parser.parse_args()
|
||||
|
||||
The help for this program will display ``myprogram.py`` as the program name
|
||||
(regardless of where the program was invoked from)::
|
||||
|
||||
$ python myprogram.py --help
|
||||
usage: myprogram.py [-h] [--foo FOO]
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo FOO foo help
|
||||
$ cd ..
|
||||
$ python subdir\myprogram.py --help
|
||||
usage: myprogram.py [-h] [--foo FOO]
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo FOO foo help
|
||||
|
||||
To change this default behavior, another value can be supplied using the
|
||||
``prog=`` argument to :class:`ArgumentParser`::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='myprogram')
|
||||
>>> parser.print_help()
|
||||
usage: myprogram [-h]
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
|
||||
Note that the program name, whether determined from ``sys.argv[0]`` or from the
|
||||
``prog=`` argument, is available to help messages using the ``%(prog)s`` format
|
||||
specifier.
|
||||
|
||||
::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='myprogram')
|
||||
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
|
||||
>>> parser.print_help()
|
||||
usage: myprogram [-h] [--foo FOO]
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo FOO foo of the myprogram program
|
||||
|
||||
|
||||
usage
|
||||
^^^^^
|
||||
|
||||
By default, :class:`ArgumentParser` calculates the usage message from the
|
||||
arguments it contains::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG')
|
||||
>>> parser.add_argument('--foo', nargs='?', help='foo help')
|
||||
>>> parser.add_argument('bar', nargs='+', help='bar help')
|
||||
>>> parser.print_help()
|
||||
usage: PROG [-h] [--foo [FOO]] bar [bar ...]
|
||||
|
||||
positional arguments:
|
||||
bar bar help
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo [FOO] foo help
|
||||
|
||||
The default message can be overridden with the ``usage=`` keyword argument::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
|
||||
>>> parser.add_argument('--foo', nargs='?', help='foo help')
|
||||
>>> parser.add_argument('bar', nargs='+', help='bar help')
|
||||
>>> parser.print_help()
|
||||
usage: PROG [options]
|
||||
|
||||
positional arguments:
|
||||
bar bar help
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo [FOO] foo help
|
||||
|
||||
The ``%(prog)s`` format specifier is available to fill in the program name in
|
||||
your usage messages.
|
||||
|
||||
|
||||
description
|
||||
^^^^^^^^^^^
|
||||
|
||||
|
|
@ -218,122 +314,6 @@ line-wrapped, but this behavior can be adjusted with the formatter_class_
|
|||
argument to :class:`ArgumentParser`.
|
||||
|
||||
|
||||
add_help
|
||||
^^^^^^^^
|
||||
|
||||
By default, ArgumentParser objects add an option which simply displays
|
||||
the parser's help message. For example, consider a file named
|
||||
``myprogram.py`` containing the following code::
|
||||
|
||||
import argparse
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument('--foo', help='foo help')
|
||||
args = parser.parse_args()
|
||||
|
||||
If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
|
||||
help will be printed::
|
||||
|
||||
$ python myprogram.py --help
|
||||
usage: myprogram.py [-h] [--foo FOO]
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo FOO foo help
|
||||
|
||||
Occasionally, it may be useful to disable the addition of this help option.
|
||||
This can be achieved by passing ``False`` as the ``add_help=`` argument to
|
||||
:class:`ArgumentParser`::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
|
||||
>>> parser.add_argument('--foo', help='foo help')
|
||||
>>> parser.print_help()
|
||||
usage: PROG [--foo FOO]
|
||||
|
||||
optional arguments:
|
||||
--foo FOO foo help
|
||||
|
||||
The help option is typically ``-h/--help``. The exception to this is
|
||||
if the ``prefix_chars=`` is specified and does not include ``-``, in
|
||||
which case ``-h`` and ``--help`` are not valid options. In
|
||||
this case, the first character in ``prefix_chars`` is used to prefix
|
||||
the help options::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
|
||||
>>> parser.print_help()
|
||||
usage: PROG [+h]
|
||||
|
||||
optional arguments:
|
||||
+h, ++help show this help message and exit
|
||||
|
||||
|
||||
prefix_chars
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
|
||||
Parsers that need to support different or additional prefix
|
||||
characters, e.g. for options
|
||||
like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
|
||||
to the ArgumentParser constructor::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
|
||||
>>> parser.add_argument('+f')
|
||||
>>> parser.add_argument('++bar')
|
||||
>>> parser.parse_args('+f X ++bar Y'.split())
|
||||
Namespace(bar='Y', f='X')
|
||||
|
||||
The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of
|
||||
characters that does not include ``-`` will cause ``-f/--foo`` options to be
|
||||
disallowed.
|
||||
|
||||
|
||||
fromfile_prefix_chars
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes, for example when dealing with a particularly long argument lists, it
|
||||
may make sense to keep the list of arguments in a file rather than typing it out
|
||||
at the command line. If the ``fromfile_prefix_chars=`` argument is given to the
|
||||
:class:`ArgumentParser` constructor, then arguments that start with any of the
|
||||
specified characters will be treated as files, and will be replaced by the
|
||||
arguments they contain. For example::
|
||||
|
||||
>>> with open('args.txt', 'w') as fp:
|
||||
... fp.write('-f\nbar')
|
||||
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
|
||||
>>> parser.add_argument('-f')
|
||||
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
|
||||
Namespace(f='bar')
|
||||
|
||||
Arguments read from a file must by default be one per line (but see also
|
||||
:meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they
|
||||
were in the same place as the original file referencing argument on the command
|
||||
line. So in the example above, the expression ``['-f', 'foo', '@args.txt']``
|
||||
is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
|
||||
|
||||
The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
|
||||
arguments will never be treated as file references.
|
||||
|
||||
|
||||
argument_default
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Generally, argument defaults are specified either by passing a default to
|
||||
:meth:`~ArgumentParser.add_argument` or by calling the
|
||||
:meth:`~ArgumentParser.set_defaults` methods with a specific set of name-value
|
||||
pairs. Sometimes however, it may be useful to specify a single parser-wide
|
||||
default for arguments. This can be accomplished by passing the
|
||||
``argument_default=`` keyword argument to :class:`ArgumentParser`. For example,
|
||||
to globally suppress attribute creation on :meth:`~ArgumentParser.parse_args`
|
||||
calls, we supply ``argument_default=SUPPRESS``::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
|
||||
>>> parser.add_argument('--foo')
|
||||
>>> parser.add_argument('bar', nargs='?')
|
||||
>>> parser.parse_args(['--foo', '1', 'BAR'])
|
||||
Namespace(bar='BAR', foo='1')
|
||||
>>> parser.parse_args([])
|
||||
Namespace()
|
||||
|
||||
|
||||
parents
|
||||
^^^^^^^
|
||||
|
||||
|
|
@ -471,6 +451,74 @@ as the regular formatter does)::
|
|||
--foo int
|
||||
|
||||
|
||||
prefix_chars
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
|
||||
Parsers that need to support different or additional prefix
|
||||
characters, e.g. for options
|
||||
like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
|
||||
to the ArgumentParser constructor::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
|
||||
>>> parser.add_argument('+f')
|
||||
>>> parser.add_argument('++bar')
|
||||
>>> parser.parse_args('+f X ++bar Y'.split())
|
||||
Namespace(bar='Y', f='X')
|
||||
|
||||
The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of
|
||||
characters that does not include ``-`` will cause ``-f/--foo`` options to be
|
||||
disallowed.
|
||||
|
||||
|
||||
fromfile_prefix_chars
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes, for example when dealing with a particularly long argument lists, it
|
||||
may make sense to keep the list of arguments in a file rather than typing it out
|
||||
at the command line. If the ``fromfile_prefix_chars=`` argument is given to the
|
||||
:class:`ArgumentParser` constructor, then arguments that start with any of the
|
||||
specified characters will be treated as files, and will be replaced by the
|
||||
arguments they contain. For example::
|
||||
|
||||
>>> with open('args.txt', 'w') as fp:
|
||||
... fp.write('-f\nbar')
|
||||
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
|
||||
>>> parser.add_argument('-f')
|
||||
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
|
||||
Namespace(f='bar')
|
||||
|
||||
Arguments read from a file must by default be one per line (but see also
|
||||
:meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they
|
||||
were in the same place as the original file referencing argument on the command
|
||||
line. So in the example above, the expression ``['-f', 'foo', '@args.txt']``
|
||||
is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
|
||||
|
||||
The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
|
||||
arguments will never be treated as file references.
|
||||
|
||||
|
||||
argument_default
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Generally, argument defaults are specified either by passing a default to
|
||||
:meth:`~ArgumentParser.add_argument` or by calling the
|
||||
:meth:`~ArgumentParser.set_defaults` methods with a specific set of name-value
|
||||
pairs. Sometimes however, it may be useful to specify a single parser-wide
|
||||
default for arguments. This can be accomplished by passing the
|
||||
``argument_default=`` keyword argument to :class:`ArgumentParser`. For example,
|
||||
to globally suppress attribute creation on :meth:`~ArgumentParser.parse_args`
|
||||
calls, we supply ``argument_default=SUPPRESS``::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
|
||||
>>> parser.add_argument('--foo')
|
||||
>>> parser.add_argument('bar', nargs='?')
|
||||
>>> parser.parse_args(['--foo', '1', 'BAR'])
|
||||
Namespace(bar='BAR', foo='1')
|
||||
>>> parser.parse_args([])
|
||||
Namespace()
|
||||
|
||||
|
||||
conflict_handler
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -508,22 +556,20 @@ action is retained as the ``-f`` action, because only the ``--foo`` option
|
|||
string was overridden.
|
||||
|
||||
|
||||
prog
|
||||
^^^^
|
||||
add_help
|
||||
^^^^^^^^
|
||||
|
||||
By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determine
|
||||
how to display the name of the program in help messages. This default is almost
|
||||
always desirable because it will make the help messages match how the program was
|
||||
invoked on the command line. For example, consider a file named
|
||||
``myprogram.py`` with the following code::
|
||||
By default, ArgumentParser objects add an option which simply displays
|
||||
the parser's help message. For example, consider a file named
|
||||
``myprogram.py`` containing the following code::
|
||||
|
||||
import argparse
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument('--foo', help='foo help')
|
||||
args = parser.parse_args()
|
||||
|
||||
The help for this program will display ``myprogram.py`` as the program name
|
||||
(regardless of where the program was invoked from)::
|
||||
If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
|
||||
help will be printed::
|
||||
|
||||
$ python myprogram.py --help
|
||||
usage: myprogram.py [-h] [--foo FOO]
|
||||
|
|
@ -531,76 +577,31 @@ The help for this program will display ``myprogram.py`` as the program name
|
|||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo FOO foo help
|
||||
$ cd ..
|
||||
$ python subdir\myprogram.py --help
|
||||
usage: myprogram.py [-h] [--foo FOO]
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo FOO foo help
|
||||
Occasionally, it may be useful to disable the addition of this help option.
|
||||
This can be achieved by passing ``False`` as the ``add_help=`` argument to
|
||||
:class:`ArgumentParser`::
|
||||
|
||||
To change this default behavior, another value can be supplied using the
|
||||
``prog=`` argument to :class:`ArgumentParser`::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='myprogram')
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
|
||||
>>> parser.add_argument('--foo', help='foo help')
|
||||
>>> parser.print_help()
|
||||
usage: myprogram [-h]
|
||||
usage: PROG [--foo FOO]
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo FOO foo help
|
||||
|
||||
Note that the program name, whether determined from ``sys.argv[0]`` or from the
|
||||
``prog=`` argument, is available to help messages using the ``%(prog)s`` format
|
||||
specifier.
|
||||
The help option is typically ``-h/--help``. The exception to this is
|
||||
if the ``prefix_chars=`` is specified and does not include ``-``, in
|
||||
which case ``-h`` and ``--help`` are not valid options. In
|
||||
this case, the first character in ``prefix_chars`` is used to prefix
|
||||
the help options::
|
||||
|
||||
::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='myprogram')
|
||||
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
|
||||
>>> parser.print_help()
|
||||
usage: myprogram [-h] [--foo FOO]
|
||||
usage: PROG [-h]
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo FOO foo of the myprogram program
|
||||
|
||||
|
||||
usage
|
||||
^^^^^
|
||||
|
||||
By default, :class:`ArgumentParser` calculates the usage message from the
|
||||
arguments it contains::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG')
|
||||
>>> parser.add_argument('--foo', nargs='?', help='foo help')
|
||||
>>> parser.add_argument('bar', nargs='+', help='bar help')
|
||||
>>> parser.print_help()
|
||||
usage: PROG [-h] [--foo [FOO]] bar [bar ...]
|
||||
|
||||
positional arguments:
|
||||
bar bar help
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo [FOO] foo help
|
||||
|
||||
The default message can be overridden with the ``usage=`` keyword argument::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
|
||||
>>> parser.add_argument('--foo', nargs='?', help='foo help')
|
||||
>>> parser.add_argument('bar', nargs='+', help='bar help')
|
||||
>>> parser.print_help()
|
||||
usage: PROG [options]
|
||||
|
||||
positional arguments:
|
||||
bar bar help
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--foo [FOO] foo help
|
||||
|
||||
The ``%(prog)s`` format specifier is available to fill in the program name in
|
||||
your usage messages.
|
||||
-h, --help show this help message and exit
|
||||
|
||||
|
||||
The add_argument() method
|
||||
|
|
|
|||
Loading…
Reference in New Issue