Inconsistent error messages between parse_args and documentation #155352

Documentation

While working on #155339, I found out an inconsistency between what is actually being output and the documentation.

The actual output (current main):

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: unrecognized arguments: -2

While in the documentation:

# negative number options present, so -2 is an option
parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

So it should be 'unrecognized arguments' instead of 'no such option'.

Searching for 'no such option' in the docs and it reveals two more similar inconsistence instances, in the 'Invalid arguments' section just above:

# invalid option
parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar     # should be PROG: error: unrecognized arguments: --bar

# wrong number of arguments
parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger   # should be PROG: error: unrecognized arguments: badger

A little bit of digging shows that these inconsistencies have been here for ~15-16 years, and this change in the original argparse did not include the relevant changes in the documentation, and it looks like this has been carried over.

To be honestly I quite like the original error messages as it is clearer, but given it has been here for ~15-16 years, I think the sensible way is to just change the documentation for consistency, as a lot of downstream application/CI may catch the error/match the error messages.

Linked PRs

• gh-155352: Fix inconsistent error messages between parse_args and documentation #155353
• [3.15] gh-155352: Fix inconsistent error messages between parse_args and documentation (GH-155353) #155355
• [3.14] gh-155352: Fix inconsistent error messages between parse_args and documentation (GH-155353) #155356
• [3.13] gh-155352: Fix inconsistent error messages between parse_args and documentation (GH-155353) #155357