--- c:/users/botjan~1/appdata/local/temp/thg.6fhctg/Documentation.1.69393/Doc/library/argparse.rst sob apr 16 16:50:04 2011 +++ C:/Users/Boštjan/Desktop/Documentation/Doc/library/argparse.rst sob apr 16 16:47:34 2011 @@ -1,8 +1,8 @@ -: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. + :synopsis: Command-line option and argument-parsing library. .. moduleauthor:: Steven Bethard .. sectionauthor:: Steven Bethard @@ -12,7 +12,7 @@ -------------- -The :mod:`argparse` module makes it easy to write user friendly command line +The :mod:`argparse` module makes it easy to write user-friendly command-line interfaces. The program defines what arguments it requires, and :mod:`argparse` 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 @@ -38,7 +38,7 @@ print(args.accumulate(args.integers)) Assuming the Python code above is saved into a file called ``prog.py``, it can -be run at the command line and provides useful help messages:: +be run at the command-line and provides useful help messages:: $ prog.py -h usage: prog.py [-h] [--sum] N [N ...] @@ -79,7 +79,7 @@ >>> parser = argparse.ArgumentParser(description='Process some integers.') The :class:`ArgumentParser` object will hold all the information necessary to -parse the command line into python data types. +parse the command-line into python data types. Adding arguments @@ -88,7 +88,7 @@ Filling an :class:`ArgumentParser` with information about program arguments is done by making calls to the :meth:`~ArgumentParser.add_argument` method. Generally, these calls tell the :class:`ArgumentParser` how to take the strings -on the command line and turn them into objects. This information is stored and +on the command-line and turn them into objects. This information is stored and used when :meth:`~ArgumentParser.parse_args` is called. For example:: >>> parser.add_argument('integers', metavar='N', type=int, nargs='+', @@ -100,7 +100,7 @@ Later, calling :meth:`parse_args` will return an object with two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute 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, +either the :func:`sum` function, if ``--sum`` was specified at the command-line, or the :func:`max` function if it was not. @@ -282,7 +282,7 @@ 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 +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:: @@ -296,7 +296,7 @@ Arguments read from a file must by default be one per line (but see also :meth:`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 +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']``. @@ -498,7 +498,7 @@ 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 +invoked on the command-line. For example, consider a file named ``myprogram.py`` with the following code:: import argparse @@ -594,7 +594,7 @@ [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`` @@ -845,7 +845,7 @@ ^^^^^ The ``const`` argument of :meth:`add_argument` is used to hold constant values -that are not read from the command line but are required for the various +that are not read from the command-line but are required for the various ArgumentParser actions. The two most common uses of it are: * When :meth:`add_argument` is called with ``action='store_const'`` or @@ -870,7 +870,7 @@ 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:: +is used when the option string was not present at the command-line:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default=42) @@ -1011,7 +1011,7 @@ argparse.py: error: option --foo is required As the example shows, if an option is marked as ``required``, :meth:`parse_args` -will report an error if that option is not present at the command line. +will report an error if that option is not present at the command-line. .. note:: @@ -1195,7 +1195,7 @@ 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()) @@ -1408,7 +1408,7 @@ 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 + 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 ``baz`` attributes are present. @@ -1700,7 +1700,7 @@ .. 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 ``None``, :data:`sys.stdout` is + invoked on the command-line. If *file* is ``None``, :data:`sys.stdout` is assumed. .. method:: ArgumentParser.print_help(file=None) @@ -1715,7 +1715,7 @@ .. method:: ArgumentParser.format_usage() Return a string containing a brief description of how the - :class:`ArgumentParser` should be invoked on the command line. + :class:`ArgumentParser` should be invoked on the command-line. .. method:: ArgumentParser.format_help() @@ -1728,7 +1728,7 @@ .. 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