Adding long form of help arguments to the help output

Review Request #1732 — Created Feb. 7, 2015 and submitted

zundel
pants
zundel/help-long-format
1055
f3b1967...
pants-reviews
benjyw, jsirois, lahosken
Adding long form of help arguments to the help output

As discussed at the Pants summit, this change modifies the existing help output to print the long form of the option.

Previously, the help output printed only the short form (scoped) flags:

run.jvm
  -h, --help              show this help message and exit
  --jvm-options <option>...
                          Run the jvm with these extra jvm options. (default:
                          ['-Xmx1g', '-XX:MaxPermSize=256m'])
  --args <arg>...         Run the jvm with these extra program args. (default:
                          [])
  --[no-]debug            Run the jvm under a debugger. (default: None)
  ...

The updated output is as follows:

run.jvm
  --run-jvm-help
  -h, --help              show this help message and exit
  --run-jvm-jvm-options
  --jvm-options <option>...
                          Run the jvm with these extra jvm options. (default:
                          ['-Xmx1g', '-XX:MaxPermSize=256m'])
  --run-jvm-args
  --args <arg>...         Run the jvm with these extra program args. (default:
                          [])
  --[no-]run-jvm-debug
  --[no-]debug            Run the jvm under a debugger. (default: None)
  ...
LA
  1. Why do folks want this change? In the docs, we have a lot of --options and I'm wondering if they should look like --goal-task-options instead.

    1. These options are often easier to specify. The short options are, well, shorter, but you have to match them up to the task on the commandline, and that can be a challenge when the task is being run implicitly.

      for example

      ./pants compile foo --report

      does nothing

      ./pants compile resolve.ivy --report foo

      is probably what you wanted. Another way to do the same thing is

      ./pants compile foo --resolve-ivy-report

  2. 
      
BE
  1. Looks good, and that's a nifty way to implement it! Thanks for fixing this. It's on my TODO list from the summit, but I've had very little time to devote to coding on Pants since then, unfortunately.

  2. Maybe rename to _pants_arg_long_format_helper?

  3. Maybe rename to _pants_arg_long_format_helper?

  4. Maybe a comment above this line saying something like "Add the fully-qualified flag to the help output." ? Just to clarify to the casual reader that you get both forms.

    1. +1 - this accesses a baseclass private function so it deserves comment.  This path scares me a bit since the argparse docs are pretty explicit about these types being opaque - and presumably subject to change - but it works for now!
    2. Added an explicit comment about this.

      When I read that I took it to mean they just didn't want to be held responsible for maintaining a backwards compatible API. They don't say which methods are interfaces in the formatter, yet clearly, some of them are private and some not. Also, they allow you to pass it as an input parameter to the parser and passing a formatter is the only way to extend it. If they really didn't want people to modify it, they'd have an API where pass in an string or an opaque symbol to specify the type of help formatter.

      I agree using a private method is a bit more risky than what we've already done. But I feel that the overall risk isn't that high. I don't think it would be too hard for us to just roll our own help formatting completely if we had to if all this broke, this is just a convenience.

  5. 
      
ZU
ZU
Review request changed

Status: Closed (submitted)

Change Summary:

thanks for the reviews submitted at 31629b1

Loading...