> Try `nargs='?'` or try providing a `default` along with the '*'.

Why would I do that? I want 0 or more arguments, and there's no default value.

> Including your ARGUMENT action in the error message is intentional.

It will likely confuse the user. The syntax message says that it's optional, the error suggests (wrongly) that it is required.

Patching the Python documentation will not help in this case, because the user of my program will not be reading the Python documentation to understand how it works, only the program's own documentation.

Note that I did not suggest that the behavior be changed, only the message that is output.

The analysis of why the message is output is useful, but it does not demonstrate that the error message is correct; the error message, as I've already demonstrated, is undeniably wrong. In no sense is "ARGUMENT" missing, because 0 occurrences are entirely legal. Therefore although in terms of the API the argument is "required", it makes no sense to tell the user this (the user will assume that "required" has its colloquial sense, not a technical sense).

I entirely sympathise with the argument that the behavior of argparse should not change; I see nothing wrong with the behavior, in any case.

The problems are purely cosmetic:

1. The syntax message says, redundantly and confusingly, "[ARGUMENT [ARGUMENT ...]]" where it should say just  "[ARGUMENT ...]".

2. The error message says that ARGUMENT is "required", whereas, from the user's point of view, it clearly is not.

These are serious annoyances from the developer's point of view (in this case, from my point of view), because they mean that in order to release a production-quality tool, I have to hack around argparse's shortcomings.

So in fact, you're quite right that the documentation should be fixed; only in this case it is the documentation generated by argparse, not the documentation of argparse (which, again, is fine as far as I can see).