Some markup and style fixes in argparse docs.
This commit is contained in:
Georg Brandl
parent
9375492be3
commit
e0bf91d597
|
|
@ -1,5 +1,5 @@
|
|||
:mod:`argparse` -- Parser for command line options, arguments and sub-commands
|
||||
==============================================================================
|
||||
:mod:`argparse` --- Parser for command line options, arguments and sub-commands
|
||||
===============================================================================
|
||||
|
||||
.. module:: argparse
|
||||
:synopsis: Command-line option and argument parsing library.
|
||||
|
|
@ -14,6 +14,7 @@ will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse`
|
|||
module also automatically generates help and usage messages and issues errors
|
||||
when users give the program invalid arguments.
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
|
|
@ -64,6 +65,7 @@ If invalid arguments are passed in, it will issue an error::
|
|||
|
||||
The following sections walk you through this example.
|
||||
|
||||
|
||||
Creating a parser
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -97,6 +99,7 @@ will be a list of one or more ints, and the ``accumulate`` attribute will be
|
|||
either the :func:`sum` function, if ``--sum`` was specified at the command line,
|
||||
or the :func:`max` function if it was not.
|
||||
|
||||
|
||||
Parsing arguments
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -248,7 +251,6 @@ the help options::
|
|||
+h, ++help show this help message and exit
|
||||
|
||||
|
||||
|
||||
prefix_chars
|
||||
^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -295,6 +297,7 @@ 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
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -594,6 +597,7 @@ The add_argument() method
|
|||
|
||||
The following sections describe how each of these are used.
|
||||
|
||||
|
||||
name or flags
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -623,6 +627,7 @@ When :meth:`parse_args` is called, optional arguments will be identified by the
|
|||
usage: PROG [-h] [-f FOO] bar
|
||||
PROG: error: too few arguments
|
||||
|
||||
|
||||
action
|
||||
^^^^^^
|
||||
|
||||
|
|
@ -767,8 +772,10 @@ values are:
|
|||
output files::
|
||||
|
||||
>>> parser = argparse.ArgumentParser()
|
||||
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'), default=sys.stdin)
|
||||
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'), default=sys.stdout)
|
||||
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
|
||||
... default=sys.stdin)
|
||||
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
|
||||
... default=sys.stdout)
|
||||
>>> parser.parse_args(['input.txt', 'output.txt'])
|
||||
Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>, outfile=<open file 'output.txt', mode 'w' at 0x...>)
|
||||
>>> parser.parse_args([])
|
||||
|
|
@ -1128,7 +1135,7 @@ behavior::
|
|||
The parse_args() method
|
||||
-----------------------
|
||||
|
||||
.. method:: ArgumentParser.parse_args([args], [namespace])
|
||||
.. method:: ArgumentParser.parse_args(args=None, namespace=None)
|
||||
|
||||
Convert argument strings to objects and assign them as attributes of the
|
||||
namespace. Return the populated namespace.
|
||||
|
|
@ -1140,6 +1147,7 @@ The parse_args() method
|
|||
By default, the arg strings are taken from :data:`sys.argv`, and a new empty
|
||||
:class:`Namespace` object is created for the attributes.
|
||||
|
||||
|
||||
Option value syntax
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -1503,7 +1511,7 @@ FileType objects
|
|||
Argument groups
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. method:: ArgumentParser.add_argument_group([title], [description])
|
||||
.. method:: ArgumentParser.add_argument_group(title=None, description=None)
|
||||
|
||||
By default, :class:`ArgumentParser` groups command-line arguments into
|
||||
"positional arguments" and "optional arguments" when displaying help
|
||||
|
|
@ -1527,7 +1535,7 @@ Argument groups
|
|||
:class:`ArgumentParser`. When an argument is added to the group, the parser
|
||||
treats it just like a normal argument, but displays the argument in a
|
||||
separate group for help messages. The :meth:`add_argument_group` method
|
||||
accepts ``title`` and ``description`` arguments which can be used to
|
||||
accepts *title* and *description* arguments which can be used to
|
||||
customize this display::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
|
||||
|
|
@ -1555,7 +1563,7 @@ Argument groups
|
|||
Mutual exclusion
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. method:: add_mutually_exclusive_group([required=False])
|
||||
.. method:: add_mutually_exclusive_group(required=False)
|
||||
|
||||
Create a mutually exclusive group. argparse will make sure that only one of
|
||||
the arguments in the mutually exclusive group was present on the command
|
||||
|
|
@ -1573,7 +1581,7 @@ Mutual exclusion
|
|||
usage: PROG [-h] [--foo | --bar]
|
||||
PROG: error: argument --bar: not allowed with argument --foo
|
||||
|
||||
The :meth:`add_mutually_exclusive_group` method also accepts a ``required``
|
||||
The :meth:`add_mutually_exclusive_group` method also accepts a *required*
|
||||
argument, to indicate that at least one of the mutually exclusive arguments
|
||||
is required::
|
||||
|
||||
|
|
@ -1586,7 +1594,7 @@ Mutual exclusion
|
|||
PROG: error: one of the arguments --foo --bar is required
|
||||
|
||||
Note that currently mutually exclusive argument groups do not support the
|
||||
``title`` and ``description`` arguments of :meth:`add_argument_group`.
|
||||
*title* and *description* arguments of :meth:`add_argument_group`.
|
||||
|
||||
|
||||
Parser defaults
|
||||
|
|
@ -1637,27 +1645,27 @@ In most typical applications, :meth:`parse_args` will take care of formatting
|
|||
and printing any usage or error messages. However, several formatting methods
|
||||
are available:
|
||||
|
||||
.. method:: ArgumentParser.print_usage([file]):
|
||||
.. method:: ArgumentParser.print_usage(file=None)
|
||||
|
||||
Print a brief description of how the :class:`ArgumentParser` should be
|
||||
invoked on the command line. If ``file`` is not present, ``sys.stderr`` is
|
||||
invoked on the command line. If *file* is ``None``, :data:`sys.stderr` is
|
||||
assumed.
|
||||
|
||||
.. method:: ArgumentParser.print_help([file]):
|
||||
.. method:: ArgumentParser.print_help(file=None)
|
||||
|
||||
Print a help message, including the program usage and information about the
|
||||
arguments registered with the :class:`ArgumentParser`. If ``file`` is not
|
||||
present, ``sys.stderr`` is assumed.
|
||||
arguments registered with the :class:`ArgumentParser`. If *file* is
|
||||
``None``, :data:`sys.stderr` is assumed.
|
||||
|
||||
There are also variants of these methods that simply return a string instead of
|
||||
printing it:
|
||||
|
||||
.. method:: ArgumentParser.format_usage():
|
||||
.. method:: ArgumentParser.format_usage()
|
||||
|
||||
Return a string containing a brief description of how the
|
||||
:class:`ArgumentParser` should be invoked on the command line.
|
||||
|
||||
.. method:: ArgumentParser.format_help():
|
||||
.. method:: ArgumentParser.format_help()
|
||||
|
||||
Return a string containing a help message, including the program usage and
|
||||
information about the arguments registered with the :class:`ArgumentParser`.
|
||||
|
|
@ -1666,7 +1674,7 @@ printing it:
|
|||
Partial parsing
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. method:: ArgumentParser.parse_known_args([args], [namespace])
|
||||
.. method:: ArgumentParser.parse_known_args(args=None, namespace=None)
|
||||
|
||||
Sometimes a script may only parse a few of the command line arguments, passing
|
||||
the remaining arguments on to another script or program. In these cases, the
|
||||
|
|
@ -1689,12 +1697,12 @@ Customizing file parsing
|
|||
|
||||
.. method:: ArgumentParser.convert_arg_line_to_args(arg_line)
|
||||
|
||||
Arguments that are read from a file (see the ``fromfile_prefix_chars``
|
||||
Arguments that are read from a file (see the *fromfile_prefix_chars*
|
||||
keyword argument to the :class:`ArgumentParser` constructor) are read one
|
||||
argument per line. :meth:`convert_arg_line_to_args` can be overriden for
|
||||
fancier reading.
|
||||
|
||||
This method takes a single argument ``arg_line`` which is a string read from
|
||||
This method takes a single argument *arg_line* which is a string read from
|
||||
the argument file. It returns a list of arguments parsed from this string.
|
||||
The method is called once per line read from the argument file, in order.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue