Argparse: GNU style help message for arguments

Python Help
1

I am (happily!) using argparse to accept and parse arguments for my app, and would like the help message to show the options to the app in GNU style.

For example, for an option that takes an argument ARG identified by the short option -f and long option --file the help message relevant to the option should be formatted like this:

  -f, --file=ARG            Help text for option file

instead of how argparse formats it:

  -f ARG, --file ARG        Help text for option file

I tried to read the documentation for argparse and see if there was a way to do this, but neither of the help formatters seem to do it for me.

I ended up deriving my own help formatter class from argparse.HelpFormatter that modifies _format_action_invocation(), but I worry that is probably not the right thing to do (same file, Line 160).

If someone could let me know if there is an alternative, perhaps easier, way to do this, I would appreciate it very much.

Thanks in advance.

2

Is there a particular reason you need your application to follow GNU style (confirming to a particular coding UI standard, etc?).

FWIW, I find the GNU style slightly less clear as it is potentially ambiguous (unless one is both familiar with GNU style, and knows for certain that the a particular CLI program is using it), as it could be read to imply that only the long option form takes an argument while the short form assumes a default. Funny enough, just the other day I ran into a case where this ambiguity was significant (particularly so if ARG is optional).

Additionally, the second form makes it clearer how should pass an argument to -f. Particularly with the general trend with fewer users being experienced with CLIs and their conventions while having ever-larger and higher-resolution screens, the clarity, explicitness and un-ambiguity benefits of the argparse form seem to trump a few extra characters, IMO.

AFAIK, I’m not aware of a mechanism to change this in argparse other than monkeypatching as you’re doing now, but given the above I at least personally wouldn’t be in favor of adding one, at least for this reason.

1 Like
3

Thanks for your response.

I agree with you about the ambiguity of the first form in so far as the short forms of the options are concerned. Indeed, I initially wanted the format to be more of a hybrid between the two (the best of both worlds, in my opinion):

  -f ARG, --file=ARG                Help text for option file

Having then looked around for standards about help messages, I found nothing like what I had in mind but eventually came across the GNU standard I linked above and emulated that.

My main point is rather about the = sign following long form options that do take arguments. This helps to distinguish them from those that do not, for example, when the interactive shell aids command-line completion. For example, bash reads completions off the help message. So, when <TAB> completing long options in the GNU form or the form shown in this reply, bash will helpfully suggest (if completions are correctly set up):

cmd --f<TAB>
cmd --file=

That is, it will show a trailing = making it clear to the user that the option takes an argument, whereas in the Argparse format the suggested completion does not have the following = and does not apparently distinguish it from an option not taking an argument.

1 Like
4

Am I missing something? Isn’t this what you listed above as being done by argparse right now?

I looked through the docs there and could not find any specifies as to how help messages should, or even are, formatted for the case where a short name is an alias for a long one. Could you provide a more specific link, and preferably an example of a real tool help page that does this?

1 Like
5

I share @MegaIng 's confusion — perhaps you made a copy/paste mistake somewhere? Additionally, I’m equally confused by your second point:

Likewise, in the example you showed for argparse:

The = is present following the option name.

Did you perhaps mean, for argparse,

-f ARG, --file ARG        Help text for option file

This appears to be what I get in testing.

1 Like
6

-f ARG, --file=ARG Help text for option file

Am I missing something? Isn’t this what you listed above as being done by argparse right now?

So sorry for the confusion. Yes, I messed up my very first post (sigh!). That is not how Argparse formats it. Argparse does this:

  -f ARG, --file ARG                Help text for option file

That is, no equals = sign between long form option and its argument.

I shall go ahead and edit my first message.

7

Yes, I definitely meant that and made a copy paste error in my first post. Sorry about that and the confusion that ensued.

Except that I do not think there is a way to do that, so I will just leave it as it is and wallow in my embarrassment.

1 Like
8

On my Linux system on bash, the help messages of coreutils tools are formatted this way. For example,

ls --help
[snip]
  -w, --width=COLS           set output width to COLS.  0 means no limit
9

Okay, thanks for clarifying. In that case, I have no particular opinion myself on = vs for formatting, though I would be interested in hearing if any veteran core devs passing by might have some insight on why it was spelled the way it was.

No need to be embarrassed! :slight_smile: Copy/paste errors happen to the best of us, and certainly me too. New users of TL1 (Basic User) and below can only edit their posts for 24 hours after posting (which I wouldn’t be opposed to increasing), while users of TL2 (Member) and above can edit their posts for up to 30 days. Since your account was TL1 and your OP was just over this limit, you weren’t able to, but as a mod I edited it for you. FWIW, you can normally do so with the pencil icon below it:

image

1 Like
10

Many thanks for fixing the post for me and for the guidance.

1 Like