The argparse documentation and tutorial as well as its default option groups speak of "positional arguments" and "optional arguments". These are not used correctly, though.

Elements of the argument vector (past item #0) are distinguished as options and (positional) arguments.

Options are either flags (ls "-l", cmd "/c") or GNU long options ("--help"). They are usually optional ("[-h]") but may be mandatory (such as -o/-i/-p for cpio(1)). They may have option arguments (cpio(1) "-H format").

Arguments (also called positional arguments) may be mandatory ("file") or optional ("[file]"). They are also called operands (mostly in POSIX, not very common).

The argparse documentation confused the hell out of me at first because I only saw argument documentation and could not find option documentation…

I’m afraid this is a basic decision of argparse, and one of its reasons for existing as an rework of optparse.

Éric is correct.  There is not much that can be done about this.  The nomenclature is deeply baked into the code and the docs.

We did change the help output to list "options" rather than "optional arguments".  That helps the end users so that "optional" doesn't imply the opposite of "required".

Hm, the change helps indeed. I did this in my code:

    p = argparse.ArgumentParser(description='…', add_help=False)
    g = p.add_argument_group('Options')
    g.add_argument('-h', action='help', help='show this help message and exit')
    g.add_argument(………
    g = p.add_argument_group('Arguments')
    g.add_argument('file', ………
    args = p.parse_args()

Maybe adjust the documentation to match? As it stands, https://docs.python.org/3/library/argparse.html is somewhat helpful, but https://docs.python.org/3/howto/argparse.html is totally confusing.