Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r85617 | georg.brandl | 2010-10-17 12:09:06 +0200 (So, 17 Okt 2010) | 1 line
#5212: md5 weaknesses do not affect hmac, so remove the note about that.
........
r85618 | georg.brandl | 2010-10-17 12:14:38 +0200 (So, 17 Okt 2010) | 1 line
#9086: correct wrong terminology about linking with pythonXY.dll.
........
r85619 | georg.brandl | 2010-10-17 12:15:50 +0200 (So, 17 Okt 2010) | 1 line
Make file names consistent.
........
r85620 | georg.brandl | 2010-10-17 12:22:28 +0200 (So, 17 Okt 2010) | 1 line
Remove second parser module example; it referred to non-readily-available example files, and this kind of discovery is much better done with the AST nowadays anyway.
........
r85621 | georg.brandl | 2010-10-17 12:24:54 +0200 (So, 17 Okt 2010) | 1 line
#9105: move pickle warning to a bit more prominent location.
........
r85622 | georg.brandl | 2010-10-17 12:28:04 +0200 (So, 17 Okt 2010) | 1 line
#9112: document error() and exit() methods of ArgumentParser.
........
r85624 | georg.brandl | 2010-10-17 12:34:28 +0200 (So, 17 Okt 2010) | 1 line
Some markup and style fixes in argparse docs.
........
r85626 | georg.brandl | 2010-10-17 12:38:20 +0200 (So, 17 Okt 2010) | 1 line
#9117: fix syntax for class definition.
........
r85627 | georg.brandl | 2010-10-17 12:44:11 +0200 (So, 17 Okt 2010) | 1 line
#9138: reword introduction to classes in Python.
........
r85629 | georg.brandl | 2010-10-17 12:51:45 +0200 (So, 17 Okt 2010) | 1 line
#5962: clarify sys.exit() vs. threads.
........
r85631 | georg.brandl | 2010-10-17 12:53:54 +0200 (So, 17 Okt 2010) | 1 line
Fix capitalization.
........
r85635 | georg.brandl | 2010-10-17 13:03:22 +0200 (So, 17 Okt 2010) | 1 line
#5121: fix claims about default values leading to segfaults.
........
r85636 | georg.brandl | 2010-10-17 13:06:14 +0200 (So, 17 Okt 2010) | 1 line
#9237: document sys.call_tracing().
........
r85638 | georg.brandl | 2010-10-17 13:13:37 +0200 (So, 17 Okt 2010) | 1 line
Port changes to pickle docs apparently lost in py3k.
........
r85639 | georg.brandl | 2010-10-17 13:23:56 +0200 (So, 17 Okt 2010) | 1 line
Make twisted example a bit more logical.
........
r85641 | georg.brandl | 2010-10-17 13:29:07 +0200 (So, 17 Okt 2010) | 1 line
Fix documentation of dis.opmap direction.
........
r85642 | georg.brandl | 2010-10-17 13:36:28 +0200 (So, 17 Okt 2010) | 1 line
#9730: fix example.
........
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 6bd011b..0ea8195 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 @@
module also automatically generates help and usage messages and issues errors
when users give the program invalid arguments.
+
Example
-------
@@ -64,6 +65,7 @@
The following sections walk you through this example.
+
Creating a parser
^^^^^^^^^^^^^^^^^
@@ -97,6 +99,7 @@
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 @@
+h, ++help show this help message and exit
-
prefix_chars
^^^^^^^^^^^^
@@ -295,6 +297,7 @@
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 following sections describe how each of these are used.
+
name or flags
^^^^^^^^^^^^^
@@ -623,6 +627,7 @@
usage: PROG [-h] [-f FOO] bar
PROG: error: too few arguments
+
action
^^^^^^
@@ -767,8 +772,10 @@
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 @@
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 @@
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 @@
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 @@
: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 @@
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 @@
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 @@
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,37 +1645,36 @@
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`.
-
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
@@ -1690,12 +1697,12 @@
.. 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.
@@ -1709,6 +1716,20 @@
yield arg
+Exiting methods
+^^^^^^^^^^^^^^^
+
+.. method:: ArgumentParser.exit(status=0, message=None)
+
+ This method terminates the program, exiting with the specified *status*
+ and, if given, it prints a *message* before that.
+
+.. method:: ArgumentParser.error(message)
+
+ This method prints a usage message including the *message* to the
+ standard output and terminates the program with a status code of 2.
+
+
.. _argparse-from-optparse:
Upgrading optparse code