The description from -r and -s are displayed in a weird way that made me think at first that they were the same thing. This happened when I was reading the help from black.
You can subclass argparse.ArgumentParser to increase the maximum number of columns used to display flags (aka the starting column of the argument help), an attribute of the argparse.HelpFormatter instance
While you’re at it, you may want to use shutil to set the formatted help width to the terminal width
I’d agree it’s a little funky in Black: looks like they’ve chosen if an option’s description wraps to more than one line, add a blank line; if it fits on one line, don’t - and then in the case of a long option field, it drops to the next line for the description, but doesn’t add a blank line, ie. that one doesn’t count as multi-line. But afaik that’s a project choice, you might grumble to them? The default doesn’t do the blank-line-adding, and at least is more consistent. Your example is unlucky in two ways - very-long-option is just over the limit, which is the worst of both worlds - the line break looks bad there, but is okay if the option part goes on doesn’t end right at the gutter; meanwhile your option text is just about a full line and that give you no visual indication all those blocks don’t flow together ( if I try your example on what must be just a bit narrower terminal, the “elit” wraps to the next line and it makes more sense again). You’d have to do a pretty sophisticated formatter to “do better”, but of course it can be done.