summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJason R. Coombs <jaraco@jaraco.com>2011-12-14 04:36:45 (GMT)
committerJason R. Coombs <jaraco@jaraco.com>2011-12-14 04:36:45 (GMT)
commitf28cf7abcfcdc33e1f47a439b8ceed8a13bc3f69 (patch)
tree6efe13d0e953ad2a1bd80395390f46d987f84e85
parent915a30fb0db8d4fc09cdf2f91db103edb5ad2cef (diff)
downloadcpython-f28cf7abcfcdc33e1f47a439b8ceed8a13bc3f69.zip
cpython-f28cf7abcfcdc33e1f47a439b8ceed8a13bc3f69.tar.gz
cpython-f28cf7abcfcdc33e1f47a439b8ceed8a13bc3f69.tar.bz2
Issue #13540: Expanded argparse documents to clarify the action API
-rw-r--r--Doc/library/argparse.rst95
1 files changed, 76 insertions, 19 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 1b80d2a..b692115 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -663,7 +663,7 @@ action
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 arguments should be handled. The supported actions are:
+how the command-line arguments should be handled. The supplied actions are:
* ``'store'`` - This just stores the argument's value. This is the default
action. For example::
@@ -737,24 +737,9 @@ how the command-line arguments should be handled. The supported actions are:
>>> parser.parse_args(['--version'])
PROG 2.0
-You can also specify an arbitrary action by passing an object that implements
-the Action API. The easiest way to do this is to extend
-:class:`argparse.Action`, supplying an appropriate ``__call__`` method. The
-``__call__`` method should accept four parameters:
-
-* ``parser`` - The ArgumentParser object which contains this action.
-
-* ``namespace`` - The :class:`Namespace` object that will be returned by
- :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this
- object.
-
-* ``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.
- The ``option_string`` argument is optional, and will be absent if the action
- is associated with a positional argument.
+You may also specify an arbitrary action by passing an Action class or other
+class that implements the same interface. The recommended way to do this is
+to extend :class:`argparse.Action`, overriding the ``__call__`` method.
An example of a custom action::
@@ -772,6 +757,9 @@ An example of a custom action::
>>> args
Namespace(bar='1', foo='2')
+Many actions also override the ``__init__`` method, validating the parameters
+to the argument definition and raising a ValueError or other Exception on
+failure.
nargs
^^^^^
@@ -1218,6 +1206,75 @@ behavior::
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')
+Action classes
+^^^^^^^^^^^^^^
+
+.. class:: Action(option_strings, dest, nargs=None, const=None, default=None,
+ type=None, choices=None, required=False, help=None,
+ metavar=None)
+
+Action objects are used by an ArgumentParser to represent the information
+needed to parse a single argument from one or more strings from the
+command line. The keyword arguments to the Action constructor are made
+available as attributes of Action instances.
+
+* ``option_strings`` - A list of command-line option strings which
+ should be associated with this action.
+
+* ``dest`` - The name of the attribute to hold the created object(s)
+
+* ``nargs`` - The number of command-line arguments that should be
+ consumed. By default, one argument will be consumed and a single
+ value will be produced. Other values include:
+ - N (an integer) consumes N arguments (and produces a list)
+ - '?' consumes zero or one arguments
+ - '*' consumes zero or more arguments (and produces a list)
+ - '+' consumes one or more arguments (and produces a list)
+ Note that the difference between the default and nargs=1 is that
+ with the default, a single value will be produced, while with
+ nargs=1, a list containing a single value will be produced.
+
+* ``const`` - The value to be produced if the option is specified and the
+ option uses an action that takes no values.
+
+* ``default`` - The value to be produced if the option is not specified.
+
+* ``type`` - The type which the command-line arguments should be converted
+ to, should be one of 'string', 'int', 'float', 'complex' or a
+ callable object that accepts a single string argument. If None,
+ 'string' is assumed.
+
+* ``choices`` - A container of values that should be allowed. If not None,
+ after a command-line argument has been converted to the appropriate
+ type, an exception will be raised if it is not a member of this
+ collection.
+
+* ``required`` - True if the action must always be specified at the
+ command line. This is only meaningful for optional command-line
+ arguments.
+
+* ``help`` - The help string describing the argument.
+
+* ``metavar`` - The name to be used for the option's argument with the
+ help string. If None, the 'dest' value will be used as the name.
+
+Action classes must also override the ``__call__`` method, which should accept
+four parameters:
+
+* ``parser`` - The ArgumentParser object which contains this action.
+
+* ``namespace`` - The :class:`Namespace` object that will be returned by
+ :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this
+ object using :func:`setattr`.
+
+* ``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.
+ The ``option_string`` argument is optional, and will be absent if the action
+ is associated with a positional argument.
+
The parse_args() method
-----------------------