I agree with Bigbird and paul.j3.

> But I think this is a real bug in argparse, not a documentation problem.

> Off hand I can't think of clean way of refining the description without getting overly technical about the error handling.

It seems like a reasonable conclusion to make that, "If the user would like to catch errors manually, the feature can be enabled by setting exit_on_error to False" indicates that wrapping any call to parser.parse_args() or parser.parse_known_args() will catch any known error that may raised. So outside of adding the workaround of subclassing ArgumentParser to the documentation, this probably needs a patch to the code.

Any solution will probably also need to implement a new error type to be able to handle these cases since they can be caused by multiple arguments being included / excluded, which is not something that ArgumentError can adequately describe by referencing only a single argument. Something like:

class MultipleArgumentError(ArgumentError):

    def __init__(self, arguments, message):
        self.argument_names = filter([_get_action_name(arg) for arg in arguments], lambda name: name)
        self.message = message

    def __str__(self):
        if self.argument_names is None:
            format = '%(message)s'
        else:
            format = 'argument %(argument_names): %(message)s'
        return format % dict(message=self.message,
                             argument_names=', '.join(self.argument_name))

I'm not sure I like the idea of changing the exit or error methods since they have a a clear purpose and don't need to be repurposed to also include error handling. It seems to me that adding checks to self.exit_on_error in _parse_known_args to handle the missing required arguments and in parse_args to handle unknown arguments is probably a quick and clean solution.