8000 Issue #13540: Removed redundant documentation about Action instance a… · python/cpython@eb0ef41 · GitHub
[go: up one dir, main page]

Skip to content

Commit eb0ef41

Browse files
committed
Issue #13540: Removed redundant documentation about Action instance attributes. Updated example and documentation per recommendations by Steven Bethard in msg149524.
1 parent f28cf7a commit eb0ef41

File tree

1 file changed

+26
-49
lines changed

1 file changed

+26
-49
lines changed

Doc/library/argparse.rst

Lines changed: 26 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -737,13 +737,18 @@ how the command-line arguments should be handled. The supplied actions are:
737737
>>> parser.parse_args(['--version'])
738738
PROG 2.0
739739

740-
You may also specify an arbitrary action by passing an Action class or other
741-
class that implements the same interface. The recommended way to do this is
742-
to extend :class:`argparse.Action`, overriding the ``__call__`` method.
740+
You may also specify an arbitrary action by passing an Action subclass or
741+
other object that implements the same interface. The recommended way to do
742+
this is to extend :class:`argparse.Action`, overriding the ``__call__`` method
743+
and optionally the ``__init__`` method.
743744

744745
An example of a custom action::
745746

746747
>>> class FooAction(argparse.Action):
748+
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
749+
... if nargs is not None:
750+
... raise ValueError("nargs not allowed")
751+
... super(FooAction, self).__init__(option_strings, dest, **kwargs)
747752
... def __call__(self, parser, namespace, values, option_string=None):
748753
... print('%r %r %r' % (namespace, values, option_string))
749754
... setattr(namespace, self.dest, values)
@@ -757,9 +762,7 @@ An example of a custom action::
757762
>>> args
758763
Namespace(bar='1', foo='2')
759764

760-
Many actions also override the ``__init__`` method, validating the parameters
761-
to the argument definition and raising a ValueError or other Exception on
762-
failure.
765+
For more details, see :class:`argparse.Action`.
763766

764767
nargs
765768
^^^^^
@@ -1209,57 +1212,28 @@ behavior::
12091212
Action classes
12101213
^^^^^^^^^^^^^^
12111214

1215+
Action classes implement the Action API, a callable which returns a callable
1216+
which processes arguments from the command-line. Any object which follows
1217+
this API may be passed as the ``action`` parameter to
1218+
:method:`add_argument`.
1219+
12121220
.. class:: Action(option_strings, dest, nargs=None, const=None, default=None,
12131221
type=None, choices=None, required=False, help=None,
12141222
metavar=None)
12151223

12161224
Action objects are used by an ArgumentParser to represent the information
12171225
needed to parse a single argument from one or more strings from the
1218-
command line. The keyword arguments to the Action constructor are made
1219-
available as attributes of Action instances.
1220-
1221-
* ``option_strings`` - A list of command-line option strings which
1222-
should be associated with this action.
1223-
1224-
* ``dest`` - The name of the attribute to hold the created object(s)
1225-
1226-
* ``nargs`` - The number of command-line arguments that should be
1227-
consumed. By default, one argument will be consumed and a single
1228-
value will be produced. Other values include:
1229-
- N (an integer) consumes N arguments (and produces a list)
1230-
- '?' consumes zero or one arguments
1231-
- '*' consumes zero or more arguments (and produces a list)
1232-
- '+' consumes one or more arguments (and produces a list)
1233-
Note that the difference between the default and nargs=1 is that
1234-
with the default, a single value will be produced, while with
1235-
nargs=1, a list containing a single value will be produced.
1236-
1237-
* ``const`` - The value to be produced if the option is specified and the
1238-
option uses an action that takes no values.
1239-
1240-
* ``default`` - The value to be produced if the option is not specified.
1226+
command line. The Action class must accept the two positional arguments
1227+
plus any keyword arguments passed to :method:`ArgumentParser.add_argument`
1228+
except for the ``action`` itself.
12411229

1242-
* ``type`` - The type which the command-line arguments should be converted
1243-
to, should be one of 'string', 'int', 'float', 'complex' or a
1244-
callable object that accepts a single string argument. If None,
1245-
'string' is assumed.
1230+
Instances of Action (or return value of any callable to the ``action``
1231+
parameter) should have attributes "dest", "option_strings", "default", "type",
1232+
"required", "help", etc. defined. The easiest way to ensure these attributes
1233+
are defined is to call ``Action.__init__``.
12461234

1247-
* ``choices`` - A container of values that should be allowed. If not None,
1248-
after a command-line argument has been converted to the appropriate
1249-
type, an exception will be raised if it is not a member of this
1250-
collection.
1251-
1252-
* ``required`` - True if the action must always be specified at the
1253-
command line. This is only meaningful for optional command-line
1254-
arguments.
1255-
1256-
* ``help`` - The help string describing the argument.
1257-
1258-
* ``metavar`` - The name to be used for the option's argument with the
1259-
help string. If None, the 'dest' value will be used as the name.
1260-
1261-
Action classes must also override the ``__call__`` method, which should accept
1262-
four parameters:
1235+
Action instances should be callable, so subclasses must override the
1236+
``__call__`` method, which should accept four parameters:
12631237

12641238
* ``parser`` - The ArgumentParser object which contains this action.
12651239

@@ -1275,6 +1249,9 @@ four parameters:
12751249
The ``option_string`` argument is optional, and will be absent if the action
12761250
is associated with a positional argument.
12771251

1252+
The ``__call__`` method may perform arbitrary actions, but will typically set
1253+
attributes on the ``namespace`` based on ``dest`` and ``values``.
1254+
12781255

12791256
The parse_args() method
12801257
-----------------------

0 commit comments

Comments
 (0)
0