Feature or enhancement

Proposal:

The way argparse's auto-generated script help messages display arguments and options is as follows:

• The help text is formatted into two columns, the first displaying the option names and metavariables, and the second the help text for each option
• Each of these two columns is left-aligned, and the alignment of the second column is set such that it starts 2 characters later than the longest row in the first column
• However, the amount of space the first column can be assigned is capped at a certain amount, 24 characters by default. If any of the option names in the left column are long enough that they would require a larger column width than this, that option's name is allowed to overflow into the space normally reserved for the second column, and the start of the option's help text is moved to the next line down to maintain alignment with the other help messages.

The problem with this is that the length of these overlong options is still considered when determining the common alignment, even though that option's help text will be on a seperate line anyway and thus can be aligned anywhere without conflict. So a single long option will cause the column indent to be set to the cap, even if none of the other options comes anywhere near requiring that much space.

Instead, when determining the size to make the first column, any option with a name larger than the column's maximum width should be discounted entirely, and the column width set to be 2 characters more than the longestother option name. (And if all the options are over the limit, default to a column width of 4 chars.)

E.g.:

importargparseas_argparseparser:_argparse.ArgumentParser=_argparse.ArgumentParser()parser.add_argument("--foo",action="store_true",help="foo foo foo")parser.add_argument("--bar",action="store_true",help="bar bar bar")parser.add_argument("--baz",action="store_true",help="baz baz baz")parser.add_argument("--really-long-option-name-with-many-chars",action="store_true",help="zip zap")args:_argparse.Namespace=parser.parse_args()

Produces this help text:

usage: test.py [-h] [--foo] [--bar] [--baz] [--really-long-option-name-with-many-chars]options:  -h, --help            show this help message and exit  --foo                 foo foo foo  --bar                 bar bar bar  --baz                 baz baz baz  --really-long-option-name-with-many-chars                        zip zap

When it really ought to produce something more like this:

usage: test.py [-h] [--foo] [--bar] [--baz] [--really-long-option-name-with-many-chars]options:  -h, --help  show this help message and exit  --foo       foo foo foo  --bar       bar bar bar  --baz       baz baz baz  --really-long-option-name-with-many-chars              zip zap

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-134200: Add adaptive global alignment for help text #134308