A new “required arguments” section seems too arbitrary to me. It would clash with the “positional arguments” heading, since those are also required by default.

I would go with the heading “options”, as a noun. That term seems to be well used, at least on Linux and Wikipedia (see https://en.wikipedia.org/wiki/Command-line_option). Other terms are “flag” and “switch”. In this thread I see two arguments against this:

1. Eric Smith prefers to retain the noun “arguments”. How about something like “non-positional arguments” then?

2. Steven Bethard is worried about backwards compatibility. I thought the Python people were happy to make these sort of changes each minor release (e.g. 3.4 to 3.5).

The module’s source code uses the term “optionals” a lot more than this one heading. It would be clearer if this term were dropped, or only used for things that are truly optional. So even if you can’t fix the help output until Python 4, please fix the documentation and the rest of the source code :)