[docs] [issue13540] Document the Action API in argparse

[Jason R. Coombs]

Jason R. Coombs <jaraco at jaraco.com> added the comment:

You're right. The documentation isn't incorrect, if you're splitting hairs. But it's not super friendly either.

Questions that the documentation should answer:

1) Does the action always need to be a subclass of an Action, or is that recommended? If it's recommended, replace "easiest" with "recommended".
2) If it does not always need to be a subclass of Action, what is the interface expected of a class for a custom action?
3) If one does use a subclass of Action, are there any hooks that are called at any point? How does one customize an action other than to override __call__? What attributes are available on the object (the example shows .dest only)?
4) What is the action required to do in __call__, if anything? Is there any way to invoke the default behavior (if for example a special case wasn't detected)?

All of these questions can be answered by going to the source, but I've twice now gone to the documentation to reference how to provide a custom action and found the documentation insufficient.

Now that I review the source again, I think I know the answers to those questions.

1) It does not always need to be a subclass of Action, but it is recommended.
2) The action API expects a callable with the following signature: Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None) which when called returns another callable accepting the four parameters.
3) Argparse does nothing with the custom action except to call it first with the init parameters, then calls the result with four parameters. If subclassing Action, the default __init__ simply stores each of those parameters as attributes on the object. Most subclasses of Action will override the __init__ to validate the options and raise an exception (typically a ValueError) when the parameters aren't valid.
4) The action is not required to do anything. Most actions will perform some logic and then invoke setattr(namespace, self.dest, result) where result is the result of some logic.

I can see why no one wanted to write this documentation. It's difficult to describe simply.

Here's what I propose:

First, remove the phrase "Action API" which suggests that there's an API outside of subclassing the Action that's recommended.

Second, change "easiest" to "recommended" to using the class.

Third, explain what attributes are available on an object initialized from a subclass of Action. Provide a link to code or other section that describes advanced usage (overriding __init__).

Fourth, explain what is expected when calling an Action instance (i.e. setattr).

Fifth, consider extending the Action class so that __call__ calls an actual named method so that those writing custom actions aren't writing classes with only a __call__ method. Perhaps "invoke". I feel less strongly about this point, but it seems strange that the recommended usage is to write a class with only a __call__ method.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13540>
_______________________________________