New %(flag)s format specifier for argparse.add_argument help string

[whalebot-helmsman]

BPO	34744
Nosy	@whalebot-helmsman
PRs	bpo-34744 Lib/argparse.py %(flag)s format specifier for argparse.add_argument help string #9427
Files	example.py

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2018-09-23.01:23:23.426>
created_at = <Date 2018-09-19.19:44:40.033>
labels = ['type-feature', 'library']
title = 'New %(flag)s format specifier for argparse.add_argument help string'
updated_at = <Date 2018-09-30.06:45:52.580>
user = 'https://github.com/whalebot-helmsman'

bugs.python.org fields:

activity = <Date 2018-09-30.06:45:52.580>
actor = 'paul.j3'
assignee = 'none'
closed = True
closed_date = <Date 2018-09-23.01:23:23.426>
closer = 'paul.j3'
components = ['Library (Lib)']
creation = <Date 2018-09-19.19:44:40.033>
creator = 'helmsman helmsman'
dependencies = []
files = ['47815']
hgrepos = []
issue_num = 34744
keywords = ['patch']
message_count = 6.0
messages = ['325788', '325812', '326046', '326208', '326519', '326707']
nosy_count = 2.0
nosy_names = ['paul.j3', 'helmsman helmsman']
pr_nums = ['9427']
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue34744'
versions = []

[whalebot-helmsman]

Sometimes you want to provide format description in help message for argparse.add_argument, e.g. for comma-separated key/value set "--flag key1=value1,key2=value2". At this moment there is no format specifier for flag or name of arguments.
I propose add new %(flag)s specifier for help strings, see example.py

[paulj3]

In your example, what is 'flag'? There's no Action attribute of that name. There is a 'dest' and a 'option_strings' list.

All the 'help' '%(...)s' does is display one of the Action object attributes, the most common one is 'default'.

Try this:

    a = parser.add_argument(...)
    print(vars(a))

to see all the attributes of such an object.

[paulj3]

In your proposed change:

        params = dict(vars(action), prog=self._prog)
      +  if action.option_strings:
      +      params['flag'] = action.option_strings[0]

'params', as I noted earlier already includes the 'dest' and 'option_strings' list.

'option_strings' is already being used in '_format_action_invocation()'. So I don't see why this flag needs to appear again in the help line. Though the user can certainly hard code it into the line when defining the 'add_argument'

e.g.

    cmdline.add_argument('--complex-argument', help='format --complex-argument key1=value1,key2=value2')

What's special about the comma-separated key/value input?

A patch/pull-request needs needs documentation, and unittest. It appears to be innocuous from a testing stand point, but good documentation could be problem - it could easily end up being confusing without adding much value.

I propose closing this because I don't think it is needed.

[whalebot-helmsman]

'option_strings' is already being used in '_format_action_invocation()'. So I don't see why this flag needs to appear again in the help line.

'option_strings' is available as a whole list, you can not use just first element of it

Though the user can certainly hard code it into the line when defining the 'add_argument'

Same logic can be applied to other members of this dictionary, but it's purpose

The help strings can include various format specifiers to avoid repetition of things like the program name or the argument default.

[paulj3]

The preferred way of adding new features to the Formatter is to subclass it, and modify one or more methods. That's what the existing alternative formatters do.

A user can easily create such a subclass, and use it with their own parser, without having to modify the stock argparse.py file.

Given that flexibility, adding new features (as opposed to bug fixes) to the help formatter should have a low priority.

[paulj3]

https://bugs.python.org/issue13280, argparse should use the new Formatter class

Raymond Hettinger argued against making such a switch.

However there may be some value in allowing its use in parallel with the '%' style of formatting. That is, if the 'help' string has '%(...)' use the '%' formatting, if it has '{}' compatible formats use the '.format' expression. I think that can be done transparently; but I haven't tested it.

The reason I bring it up here, is that I think `.format' can provide the functionality this issue is asking for.

If I define an Action like:

    a1 = parser.add_argument('--foo', '-f', default='foobar'.
       help='help for {dest} or {option_strings[0]}, default is {default}'  

Then:

    a1.help.format(**vars(a1))                                                                                    

produces:

'help for foo or --foo, default is foobar'

So if there is another reason to add new style formatting to help lines, it's worth keeping this issue in mind.