From f28cf7abcfcdc33e1f47a439b8ceed8a13bc3f69 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Tue, 13 Dec 2011 23:36:45 -0500 Subject: Issue #13540: Expanded argparse documents to clarify the action API --- Doc/library/argparse.rst | 95 ++++++++++++++++++++++++++++++++++++++---------- 1 file 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 ----------------------- -- cgit v0.12 From eb0ef415d597dfbe98ef46d063872facd55e7aff Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 20 Jul 2014 10:52:46 -0400 Subject: Issue #13540: Removed redundant documentation about Action instance attributes. Updated example and documentation per recommendations by Steven Bethard in msg149524. --- Doc/library/argparse.rst | 75 +++++++++++++++++------------------------------- 1 file changed, 26 insertions(+), 49 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index b692115..547ad14 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -737,13 +737,18 @@ how the command-line arguments should be handled. The supplied actions are: >>> parser.parse_args(['--version']) PROG 2.0 -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. +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:`argparse.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) @@ -757,9 +762,7 @@ 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. +For more details, see :class:`argparse.Action`. nargs ^^^^^ @@ -1209,57 +1212,28 @@ behavior:: 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 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. +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. -* ``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. +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__``. -* ``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: +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. @@ -1275,6 +1249,9 @@ four parameters: 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 ----------------------- -- cgit v0.12 From 79690ac1d0b25c048768e9d3870b475e235f9e7a Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 3 Aug 2014 14:54:11 -0400 Subject: Issue #13540: Update references to Action class to match syntax used for other classes in this file. --- Doc/library/argparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 547ad14..0b403b7 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -739,7 +739,7 @@ how the command-line arguments should be handled. The supplied actions are: 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:`argparse.Action`, overriding the ``__call__`` method +this is to extend :class:`Action`, overriding the ``__call__`` method and optionally the ``__init__`` method. An example of a custom action:: @@ -762,7 +762,7 @@ An example of a custom action:: >>> args Namespace(bar='1', foo='2') -For more details, see :class:`argparse.Action`. +For more details, see :class:`Action`. nargs ^^^^^ -- cgit v0.12