diff options
| -rw-r--r-- | Doc/library/argparse.rst | 50 |
1 files changed, 29 insertions, 21 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index c2d7e73..349df00 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -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. |