diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/argparse.rst | 104 |
1 files changed, 52 insertions, 52 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 08231411..d93c0d5 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -2,7 +2,7 @@ =============================================================================== .. module:: argparse - :synopsis: Command-line option and argument-parsing library. + :synopsis: Command-line option and argument parsing library. .. moduleauthor:: Steven Bethard <steven.bethard@gmail.com> .. versionadded:: 2.7 .. sectionauthor:: Steven Bethard <steven.bethard@gmail.com> @@ -103,9 +103,9 @@ or the :func:`max` function if it was not. Parsing arguments ^^^^^^^^^^^^^^^^^ -:class:`ArgumentParser` parses args through the +:class:`ArgumentParser` parses arguments through the :meth:`~ArgumentParser.parse_args` method. This will inspect the command line, -convert each arg to the appropriate type and then invoke the appropriate action. +convert each argument to the appropriate type and then invoke the appropriate action. In most cases, this means a simple :class:`Namespace` object will be built up from attributes parsed out of the command line:: @@ -114,7 +114,7 @@ attributes parsed out of the command line:: In a script, :meth:`~ArgumentParser.parse_args` will typically be called with no arguments, and the :class:`ArgumentParser` will automatically determine the -command-line args from :data:`sys.argv`. +command-line arguments from :data:`sys.argv`. ArgumentParser objects @@ -238,7 +238,7 @@ This can be achieved by passing ``False`` as the ``add_help=`` argument to --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 +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:: @@ -254,7 +254,7 @@ the help options:: prefix_chars ^^^^^^^^^^^^ -Most command-line options will use ``'-'`` as the prefix, e.g. ``-f/--foo``. +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 @@ -267,7 +267,7 @@ to the ArgumentParser constructor:: 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 +characters that does not include ``-`` will cause ``-f/--foo`` options to be disallowed. @@ -389,7 +389,7 @@ epilog_ texts in command-line help messages:: likewise for this epilog whose whitespace will be cleaned up and whose words will be wrapped across a couple lines -Passing :class:`~argparse.RawDescriptionHelpFormatter` as ``formatter_class=`` +Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=`` indicates that description_ and epilog_ are already correctly formatted and should not be line-wrapped:: @@ -415,7 +415,7 @@ should not be line-wrapped:: optional arguments: -h, --help show this help message and exit -:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text +:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text, including argument descriptions. The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`, @@ -642,11 +642,11 @@ be positional:: action ^^^^^^ -:class:`ArgumentParser` objects associate command-line args with actions. These -actions can do just about anything with the command-line args associated with +:class:`ArgumentParser` objects associate command-line arguments with actions. These +actions can do just about anything with the command-line arguments associated with them, though most actions simply add an attribute to the object returned by :meth:`~ArgumentParser.parse_args`. The ``action`` keyword argument specifies -how the command-line args should be handled. The supported actions are: +how the command-line arguments should be handled. The supported actions are: * ``'store'`` - This just stores the argument's value. This is the default action. For example:: @@ -718,8 +718,8 @@ the Action API. The easiest way to do this is to extend :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this object. -* ``values`` - The associated command-line args, with any type-conversions - applied. (Type-conversions are specified with the type_ keyword argument to +* ``values`` - The associated command-line arguments, with any type conversions + applied. (Type conversions are specified with the type_ keyword argument to :meth:`~ArgumentParser.add_argument`. * ``option_string`` - The option string that was used to invoke this action. @@ -751,7 +751,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`` arguments from the command line will be gathered together into a list. For example:: >>> parser = argparse.ArgumentParser() @@ -763,11 +763,11 @@ 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 - produced as a single item. If no command-line arg is present, the value from +* ``'?'``. One argument will be consumed from the command line if possible, and + produced as a single item. If no command-line argument 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 - command-line arg. In this case the value from const_ will be produced. Some + command-line argument. In this case the value from const_ will be produced. Some examples to illustrate this:: >>> parser = argparse.ArgumentParser() @@ -795,7 +795,7 @@ values are: Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>, outfile=<open file '<stdout>', mode 'w' at 0x...>) -* ``'*'``. All command-line args present are gathered into a list. Note that +* ``'*'``. All command-line arguments present are gathered into a list. Note that it generally doesn't make much sense to have more than one positional argument with ``nargs='*'``, but multiple optional arguments with ``nargs='*'`` is possible. For example:: @@ -809,7 +809,7 @@ values are: * ``'+'``. Just like ``'*'``, all command-line args present are gathered into a list. Additionally, an error message will be generated if there wasn't at - least one command-line arg present. For example:: + least one command-line argument present. For example:: >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('foo', nargs='+') @@ -819,8 +819,8 @@ values are: usage: PROG [-h] foo [foo ...] PROG: error: too few arguments -If the ``nargs`` keyword argument is not provided, the number of args consumed -is determined by the action_. Generally this means a single command-line arg +If the ``nargs`` keyword argument is not provided, the number of arguments consumed +is determined by the action_. Generally this means a single command-line argument will be consumed and a single item (not a list) will be produced. @@ -837,9 +837,9 @@ the various :class:`ArgumentParser` actions. The two most common uses of it are * When :meth:`~ArgumentParser.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. + argument that can be followed by zero or one command-line arguments. 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. + command-line argument following it, the value of ``const`` will be assumed instead. See the nargs_ description for examples. The ``const`` keyword argument defaults to ``None``. @@ -851,7 +851,7 @@ default All optional arguments and some positional arguments may be omitted at the command line. The ``default`` keyword argument of :meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``, -specifies what value should be used if the command-line arg is not present. +specifies what value should be used if the command-line argument is not present. For optional arguments, the ``default`` value is used when the option string was not present at the command line:: @@ -862,8 +862,8 @@ was not present at the command line:: >>> parser.parse_args(''.split()) Namespace(foo=42) -For positional arguments with nargs_ ``='?'`` or ``'*'``, the ``default`` value -is used when no command-line arg was present:: +For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value +is used when no command-line argument was present:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', nargs='?', default=42) @@ -887,12 +887,12 @@ command-line argument was not present.:: type ^^^^ -By default, ArgumentParser objects read command-line args in as simple strings. -However, quite often the command-line string should instead be interpreted as -another type, like a :class:`float`, :class:`int` or :class:`file`. The +By default, :class:`ArgumentParser` objects read command-line arguments in as simple +strings. However, quite often the command-line string should instead be +interpreted as another type, like a :class:`float` or :class:`int`. The ``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any -necessary type-checking and type-conversions to be performed. Many common -built-in types can be used directly as the value of the ``type`` argument:: +necessary type-checking and type conversions to be performed. Common built-in +types and functions can be used directly as the value of the ``type`` argument:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', type=int) @@ -911,7 +911,7 @@ writable file:: Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>) ``type=`` can take any callable that takes a single string argument and returns -the type-converted value:: +the converted value:: >>> def perfect_square(string): ... value = int(string) @@ -946,11 +946,11 @@ See the choices_ section for more details. choices ^^^^^^^ -Some command-line args should be selected from a restricted set of values. +Some command-line arguments 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:`~ArgumentParser.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:: +parsed, argument values will be checked, and an error message will be displayed if +the argument was not one of the acceptable values:: >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('foo', choices='abc') @@ -1053,7 +1053,7 @@ value as the "name" of each object. By default, for positional argument actions, the dest_ value is used directly, and for optional argument actions, the dest_ value is uppercased. So, a single positional argument with ``dest='bar'`` will that argument will be referred to as ``bar``. A single -optional argument ``--foo`` that should be followed by a single command-line arg +optional argument ``--foo`` that should be followed by a single command-line argument will be referred to as ``FOO``. An example:: >>> parser = argparse.ArgumentParser() @@ -1125,10 +1125,10 @@ attribute is determined by the ``dest`` keyword argument of For optional argument actions, the value of ``dest`` is normally inferred from the option strings. :class:`ArgumentParser` generates the value of ``dest`` by -taking the first long option string and stripping away the initial ``'--'`` +taking the first long option string and stripping away the initial ``--`` string. If no long option strings were supplied, ``dest`` will be derived from -the first short option string by stripping the initial ``'-'`` character. Any -internal ``'-'`` characters will be converted to ``'_'`` characters to make sure +the first short option string by stripping the initial ``-`` character. Any +internal ``-`` characters will be converted to ``_`` characters to make sure the string is a valid attribute name. The examples below illustrate this behavior:: @@ -1160,7 +1160,7 @@ The parse_args() method created and how they are assigned. See the documentation for :meth:`add_argument` for details. - By default, the arg strings are taken from :data:`sys.argv`, and a new empty + By default, the argument strings are taken from :data:`sys.argv`, and a new empty :class:`Namespace` object is created for the attributes. @@ -1231,15 +1231,15 @@ it exits and prints the error along with a usage message:: PROG: error: extra arguments found: badger -Arguments containing ``"-"`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Arguments containing ``-`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ The :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever the user has clearly made a mistake, but some situations are inherently -ambiguous. For example, the command-line arg ``'-1'`` could either be an +ambiguous. For example, the command-line argument ``-1`` could either be an attempt to specify an option or an attempt to provide a positional argument. The :meth:`~ArgumentParser.parse_args` method is cautious here: positional -arguments may only begin with ``'-'`` if they look like negative numbers and +arguments may only begin with ``-`` if they look like negative numbers and there are no options in the parser that look like negative numbers:: >>> parser = argparse.ArgumentParser(prog='PROG') @@ -1272,7 +1272,7 @@ there are no options in the parser that look like negative numbers:: usage: PROG [-h] [-1 ONE] [foo] PROG: error: argument -1: expected one argument -If you have positional arguments that must begin with ``'-'`` and don't look +If you have positional arguments that must begin with ``-`` and don't look like negative numbers, you can insert the pseudo-argument ``'--'`` which tells :meth:`~ArgumentParser.parse_args` that everything after that is a positional argument:: @@ -1304,7 +1304,7 @@ An error is produced for arguments that could produce more than one options. Beyond ``sys.argv`` ^^^^^^^^^^^^^^^^^^^ -Sometimes it may be useful to have an ArgumentParser parse args other than those +Sometimes it may be useful to have an ArgumentParser parse arguments other than those of :data:`sys.argv`. This can be accomplished by passing a list of strings to :meth:`~ArgumentParser.parse_args`. This is useful for testing at the interactive prompt:: @@ -1390,7 +1390,7 @@ Sub-commands >>> parser_b = subparsers.add_parser('b', help='b help') >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help') >>> - >>> # parse some arg lists + >>> # parse some argument lists >>> parser.parse_args(['a', '12']) Namespace(bar=12, foo=False) >>> parser.parse_args(['--foo', 'b', '--baz', 'Z']) @@ -1399,8 +1399,8 @@ Sub-commands Note that the object returned by :meth:`parse_args` will only contain attributes for the main parser and the subparser that was selected by the command line (and not any other subparsers). So in the example above, when - the ``"a"`` command is specified, only the ``foo`` and ``bar`` attributes are - present, and when the ``"b"`` command is specified, only the ``foo`` and + the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are + present, and when the ``b`` command is specified, only the ``foo`` and ``baz`` attributes are present. Similarly, when a help message is requested from a subparser, only the help @@ -1522,7 +1522,7 @@ FileType objects The :class:`FileType` factory creates objects that can be passed to the type argument of :meth:`ArgumentParser.add_argument`. Arguments that have - :class:`FileType` objects as their type will open command-line args as files + :class:`FileType` objects as their type will open command-line arguments as files with the requested modes and buffer sizes: >>> parser = argparse.ArgumentParser() @@ -1636,7 +1636,7 @@ Parser defaults .. method:: ArgumentParser.set_defaults(**kwargs) 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 + will be fully determined by inspecting the command-line arguments and the argument actions. :meth:`set_defaults` allows some additional attributes that are determined without any inspection of the command line to be added:: |