classification
Title: New %(flag)s format specifier for argparse.add_argument help string
Type: enhancement Stage: resolved
Components: Library (Lib) Versions:
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: Nosy List: helmsman helmsman, paul.j3
Priority: normal Keywords: patch

Created on 2018-09-19 19:44 by helmsman helmsman, last changed 2018-09-30 06:45 by paul.j3. This issue is now closed.

Files
File name Uploaded Description Edit
example.py helmsman helmsman, 2018-09-19 19:44
Pull Requests
URL Status Linked Edit
PR 9427 open python-dev, 2018-09-19 19:57
Messages (6)
msg325788 - (view) Author: Vostretsov Nikita (helmsman helmsman) * Date: 2018-09-19 19:44
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
msg325812 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2018-09-19 22:42
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.
msg326046 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2018-09-21 21:41
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.
msg326208 - (view) Author: Vostretsov Nikita (helmsman helmsman) * Date: 2018-09-24 08:00
>'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.
msg326519 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2018-09-27 03:26
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.
msg326707 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2018-09-30 06:45
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.
History
Date User Action Args
2018-09-30 06:45:52paul.j3setmessages: + msg326707
2018-09-27 03:26:29paul.j3setmessages: + msg326519
2018-09-24 08:00:58helmsman helmsmansetmessages: + msg326208
2018-09-23 01:23:23paul.j3setstatus: open -> closed
resolution: rejected
stage: patch review -> resolved
2018-09-21 21:41:29paul.j3setmessages: + msg326046
2018-09-19 22:42:44paul.j3setnosy: + paul.j3
messages: + msg325812
2018-09-19 19:57:48python-devsetkeywords: + patch
stage: patch review
pull_requests: + pull_request8845
2018-09-19 19:44:40helmsman helmsmancreate