diff options
Diffstat (limited to 'Doc/library/argparse.rst')
| -rw-r--r-- | Doc/library/argparse.rst | 36 |
1 files changed, 18 insertions, 18 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index ebc1360..bdd9464 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1,4 +1,4 @@ -:mod:`argparse` --- Parser for command line options, arguments and sub-commands +:mod:`argparse` --- Parser for command-line options, arguments and sub-commands =============================================================================== .. module:: argparse @@ -108,10 +108,10 @@ Parsing arguments ^^^^^^^^^^^^^^^^^ :class:`ArgumentParser` parses args through the -:meth:`~ArgumentParser.parse_args` method. This will inspect the command-line, +:meth:`~ArgumentParser.parse_args` method. This will inspect the command line, convert each arg to the appropriate type and then invoke the appropriate action. In most cases, this means a simple namespace object will be built up from -attributes parsed out of the command-line:: +attributes parsed out of the command line:: >>> parser.parse_args(['--sum', '7', '-1', '42']) Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42]) @@ -221,7 +221,7 @@ the parser's help message. For example, consider a file named parser.add_argument('--foo', help='foo help') args = parser.parse_args() -If ``-h`` or ``--help`` is supplied is at the command-line, the ArgumentParser +If ``-h`` or ``--help`` is supplied is at the command line, the ArgumentParser help will be printed:: $ python myprogram.py --help @@ -594,21 +594,21 @@ The add_argument() method [const], [default], [type], [choices], [required], \ [help], [metavar], [dest]) - Define how a single command line argument should be parsed. Each parameter + Define how a single command-line argument should be parsed. Each parameter has its own more detailed description below, but in short they are: * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo`` or ``-f, --foo`` * action_ - The basic type of action to be taken when this argument is - encountered at the command-line. + encountered at the command line. * nargs_ - The number of command-line arguments that should be consumed. * const_ - A constant value required by some action_ and nargs_ selections. * default_ - The value produced if the argument is absent from the - command-line. + command line. * type_ - The type to which the command-line arg should be converted. @@ -768,7 +768,7 @@ single action to be taken. The ``nargs`` keyword argument associates a different number of command-line arguments with a single action.. The supported values are: -* N (an integer). N args from the command-line will be gathered together into a +* N (an integer). N args from the command line will be gathered together into a list. For example:: >>> parser = argparse.ArgumentParser() @@ -780,7 +780,7 @@ values are: Note that ``nargs=1`` produces a list of one item. This is different from the default, in which the item is produced by itself. -* ``'?'``. One arg will be consumed from the command-line if possible, and +* ``'?'``. One arg will be consumed from the command line if possible, and produced as a single item. If no command-line arg is present, the value from default_ will be produced. Note that for optional arguments, there is an additional case - the option string is present but not followed by a @@ -855,7 +855,7 @@ ArgumentParser actions. The two most common uses of it are: * When :meth:`add_argument` is called with option strings (like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional argument that can be - followed by zero or one command-line args. When parsing the command-line, if + followed by zero or one command-line args. When parsing the command line, if the option string is encountered with no command-line arg following it, the value of ``const`` will be assumed instead. See the nargs_ description for examples. @@ -867,7 +867,7 @@ default ^^^^^^^ All optional arguments and some positional arguments may be omitted at the -command-line. The ``default`` keyword argument of :meth:`add_argument`, whose +command line. The ``default`` keyword argument of :meth:`add_argument`, whose value defaults to ``None``, specifies what value should be used if the command-line arg is not present. For optional arguments, the ``default`` value is used when the option string was not present at the command line:: @@ -965,7 +965,7 @@ choices Some command-line args should be selected from a restricted set of values. These can be handled by passing a container object as the ``choices`` keyword -argument to :meth:`add_argument`. When the command-line is parsed, arg values +argument to :meth:`add_argument`. When the command line is parsed, arg values will be checked, and an error message will be displayed if the arg was not one of the acceptable values:: @@ -998,7 +998,7 @@ required ^^^^^^^^ In general, the argparse module assumes that flags like ``-f`` and ``--bar`` -indicate *optional* arguments, which can always be omitted at the command-line. +indicate *optional* arguments, which can always be omitted at the command line. To make an option *required*, ``True`` can be specified for the ``required=`` keyword argument to :meth:`add_argument`:: @@ -1024,7 +1024,7 @@ help The ``help`` value is a string containing a brief description of the argument. When a user requests help (usually by using ``-h`` or ``--help`` at the -command-line), these ``help`` descriptions will be displayed with each +command line), these ``help`` descriptions will be displayed with each argument:: >>> parser = argparse.ArgumentParser(prog='frobble') @@ -1195,7 +1195,7 @@ passed as two separate arguments:: Namespace(foo='FOO', x=None) For long options (options with names longer than a single character), the option -and value can also be passed as a single command line argument, using ``=`` to +and value can also be passed as a single command-line argument, using ``=`` to separate them:: >>> parser.parse_args('--foo=FOO'.split()) @@ -1221,7 +1221,7 @@ as long as only the last option (or none of them) requires a value:: Invalid arguments ^^^^^^^^^^^^^^^^^ -While parsing the command-line, ``parse_args`` checks for a variety of errors, +While parsing the command line, ``parse_args`` checks for a variety of errors, including ambiguous options, invalid types, invalid options, wrong number of positional arguments, etc. When it encounters such an error, it exits and prints the error along with a usage message:: @@ -1657,7 +1657,7 @@ Parser defaults Most of the time, the attributes of the object returned by :meth:`parse_args` will be fully determined by inspecting the command-line args and the argument actions. :meth:`ArgumentParser.set_defaults` allows some additional - attributes that are determined without any inspection of the command-line to + attributes that are determined without any inspection of the command line to be added:: >>> parser = argparse.ArgumentParser() @@ -1728,7 +1728,7 @@ Partial parsing .. method:: ArgumentParser.parse_known_args(args=None, namespace=None) -Sometimes a script may only parse a few of the command line arguments, passing +Sometimes a script may only parse a few of the command-line arguments, passing the remaining arguments on to another script or program. In these cases, the :meth:`parse_known_args` method can be useful. It works much like :meth:`~ArgumentParser.parse_args` except that it does not produce an error when |