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).