@@ -737,13 +737,18 @@ how the command-line arguments should be handled. The supplied actions are:
737
737
>>> parser.parse_args(['--version'])
738
738
PROG 2.0
739
739
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.
743
744
744
745
An example of a custom action::
745
746
746
747
>>> 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)
747
752
... def __call__(self, parser, namespace, values, option_string=None):
748
753
... print('%r %r %r' % (namespace, values, option_string))
749
754
... setattr(namespace, self.dest, values)
@@ -757,9 +762,7 @@ An example of a custom action::
757
762
>>> args
758
763
Namespace(bar='1', foo='2')
759
764
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 `.
763
766
764
767
nargs
765
768
^^^^^
@@ -1209,57 +1212,28 @@ behavior::
1209
1212
Action classes
1210
1213
^^^^^^^^^^^^^^
1211
1214
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
+
1212
1220
.. class :: Action(option_strings, dest, nargs=None, const=None, default=None,
1213
1221
type=None, choices=None, required=False, help=None,
1214
1222
metavar=None)
1215
1223
1216
1224
Action objects are used by an ArgumentParser to represent the information
1217
1225
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.
1241
1229
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__ `` .
1246
1234
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:
1263
1237
1264
1238
* ``parser `` - The ArgumentParser object which contains this action.
1265
1239
@@ -1275,6 +1249,9 @@ four parameters:
1275
1249
The ``option_string `` argument is optional, and will be absent if the action
1276
1250
is associated with a positional argument.
1277
1251
1252
+ The ``__call__ `` method may perform arbitrary actions, but will typically set
1253
+ attributes on the ``namespace `` based on ``dest `` and ``values ``.
1254
+
1278
1255
1279
1256
The parse_args() method
1280
1257
-----------------------
0 commit comments