[docs] [issue20039] Missing documentation for argparse.ArgumentTypeError
paul j3
report at bugs.python.org
Sat Dec 21 19:37:45 CET 2013
paul j3 added the comment:
In argparse.py the status of ArgumentTypeError is ambiguous.
ArgumentError is listed as a public class, ArgumentTypeError is not. It also says 'All other classes in this module are considered implementation details.'
ArgumentTypeError is a subclass of Exception (with no added functionality).
ArgumentTypeError is raised only once, in the FileType class (which is both a scripting convenience and example of a custom type). As you note it is also used in the documentation example. There is also one such example in test_argparse.py.
It is caught once, where it is converted into an ArgumentError. It is handled much like a ValueError or TypeError - except that its message is passed through unchanged.
In http://bugs.python.org/issue13824 I use it several times in the FileContext class for just this reason.
In fact ArgumentTypeError could be documented as a footnote to the `type` block, saying to the effect: 'An ArgumentTypeError may be raised (instead of a ValueError or TypeError) to produce a custom error message.'
Normally an ArgumentTypeError is not passed back to the user code, consistent with the claim that it is not public.
--------------
Along the same line, should ArgumentError be documented better? Currently it is just mentioned at the end, as a replacement for an optparse error class.
As best I can tell, the user code will only see an ArgumentError if the ArgumentParser.error method is customized. Otherwise that error is caught and converted into a system exit. Maybe the `error` paragraph in the documentation should get a sentence about ArgumentError.
In test_argparse.py, ArgumentError is used extensively (with a custom error method).
----------
nosy: +paul.j3
_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue20039>
_______________________________________
More information about the docs
mailing list