On Mon, 06 Sep 2021 03:11:16 +0000, Raymond Hettinger wrote:

>The repetition helps improve understanding because not everyone would assume
>that a METAVAR shown once would automatically also apply to its long form.

I'm struggling to think of a real-world example that would lead someone to
think otherwise.  Is there a program with a short & long form option where
only one of those accepts an argument?

If such a thing does exist somewhere, the current behavior seems even worse
in that case: it shows the METAVAR alongside both forms, despite only one
form accepting an argument.

>Also, showing the METAVAR more than one is a norm.  For example, see this
>excerpt from "man grep":

I disagree about that being a norm. Counterexamples include:

cp -t, --target-directory=DIRECTORY
mv -S, --suffix=SUFFIX
ls -T, --tabsize=COLS
man -L, --locale=LOCALE

And, as Jeremy pointed out, we are not discussing man pages here, but
command line help text.  Even grep does it the way I suggest:

grep -e, --regexp=PATTERNS
grep -f, --file=FILE
grep -m, --max-count=NUM
(etc.)

More importantly, even if we do accept the current behavior as potentially
useful, do we really want Python's standard library to prescribe it?  Should
the application developer not be given an easy way for her program to
display cleaner, simpler, more space-efficient help text?