summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJason R. Coombs <jaraco@jaraco.com>2014-08-03 19:26:32 (GMT)
committerJason R. Coombs <jaraco@jaraco.com>2014-08-03 19:26:32 (GMT)
commit89e186f24ea6c10c39e90eb153bf714934be4e62 (patch)
tree2c48eeaf7e269dd7779eadd32f74b5ac965adfbf
parent217f4cd7ee587310587f70c28cd3b25c722275ba (diff)
parent79690ac1d0b25c048768e9d3870b475e235f9e7a (diff)
downloadcpython-89e186f24ea6c10c39e90eb153bf714934be4e62.zip
cpython-89e186f24ea6c10c39e90eb153bf714934be4e62.tar.gz
cpython-89e186f24ea6c10c39e90eb153bf714934be4e62.tar.bz2
Issue #13540: Merge changes from 3.2
-rw-r--r--Doc/library/argparse.rst72
1 files changed, 53 insertions, 19 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index b686c44..dc9c27f 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -683,7 +683,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::
@@ -757,28 +757,18 @@ 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 subclass or
+other object that implements the same interface. The recommended way to do
+this is to extend :class:`Action`, overriding the ``__call__`` method
+and optionally the ``__init__`` method.
An example of a custom action::
>>> class FooAction(argparse.Action):
+ ... def __init__(self, option_strings, dest, nargs=None, **kwargs):
+ ... if nargs is not None:
+ ... raise ValueError("nargs not allowed")
+ ... super(FooAction, self).__init__(option_strings, dest, **kwargs)
... def __call__(self, parser, namespace, values, option_string=None):
... print('%r %r %r' % (namespace, values, option_string))
... setattr(namespace, self.dest, values)
@@ -792,6 +782,7 @@ An example of a custom action::
>>> args
Namespace(bar='1', foo='2')
+For more details, see :class:`Action`.
nargs
^^^^^
@@ -1238,6 +1229,49 @@ behavior::
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')
+Action classes
+^^^^^^^^^^^^^^
+
+Action classes implement the Action API, a callable which returns a callable
+which processes arguments from the command-line. Any object which follows
+this API may be passed as the ``action`` parameter to
+:method:`add_argument`.
+
+.. 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 Action class must accept the two positional arguments
+plus any keyword arguments passed to :method:`ArgumentParser.add_argument`
+except for the ``action`` itself.
+
+Instances of Action (or return value of any callable to the ``action``
+parameter) should have attributes "dest", "option_strings", "default", "type",
+"required", "help", etc. defined. The easiest way to ensure these attributes
+are defined is to call ``Action.__init__``.
+
+Action instances should be callable, so subclasses must 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 ``__call__`` method may perform arbitrary actions, but will typically set
+attributes on the ``namespace`` based on ``dest`` and ``values``.
+
The parse_args() method
-----------------------