help: Alias overriding help-text (like flags), options list human-help before automated infos #361

ankostis · 2017-01-13T17:40:15Z

To keep the API symmetric to flags, add the capability to aliases to override the printed help-msg.

With this PR, the Application.aliases dict may contain two-tuples as values like this (alias: (longname, help-text)}:

    aliases = Dict({
                    ('fooi', 'i') : 'Foo.i',                          # simple longname
                    ('j', 'fooj') : ('Foo.j', "`j` terse help msg"),  # longname, help-text
    )

Renamed the use of builtin help in one occasion;
changed 2 TCs to test with two-tuples;
improved slightly the documentation.

Rational:

Currently code that prints the help-text for the aliases fetches the help-text from the aliased trait, and that is possible since there is a 1-1 correspondence (in contrast to flags where it is 1-n, and thus had to introduce the two-tuple with help-text).
But since this might be long, the end result will be a long help message, scrolling past the end of the screen.
For flags, it is possible (actually forced) to provide shorter versions of the help-messages, and use --help-all to read all content, but this flexibility is impossible for aliases.

To facilitate comparison, the before and after help messages are provided for the --config-paths alias:

"Before" Help Messages:

$ co2dice --help
prepare/sign/send/receive/validate & archive Type Approval sampling

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

-d, --debug
    Log more logging, fail on configuration errors, and print configuration on each cmd startup.
    Equivalent to: [--Application.log_level=0 --Spec.log_level=0 --Cmd.raise_config_file_errors=True]
--config-paths=<list-item-1>...
    Default: []
    Absolute/relative path(s) to read "static" configurable parameters from.
    If false, and no `CO2DICE_CONFIG_PATH` envvar is defined, defaults to:
        ['D:\\Apps\\cygwin64\\home\\anastkn\\.co2dice\\co2dice_config', 'd:\\work\\compas.vinz\\co2mpas\\sampling\\co2dice_config']
    Multiple values may be given, and each value may be a single or multiple paths
    separated by ';'.  All paths collected are considered in descending order
    (1st one overrides the rest).
    For paths resolving to folders, the filename `co2dice_config.[json | py]` is appended;
    otherwise, any file-extensions are ignored, and '.py' and/or '.json' are loaded (in this order).
    Tip:
        Use `config init` sub-command to produce a skeleton of the config-file.

To see all available configurables, use `--help-all`

"After" Help Message:

$ co2dice --help
prepare/sign/send/receive/validate & archive Type Approval sampling

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

-d, --debug
    Log more logging, fail on configuration errors, and print configuration on each cmd startup.
    Equivalent to: [--Application.log_level=0 --Spec.log_level=0 Cmd.raise_config_file_errors=True]
--config-paths=<list-item-1>...
    Default: []
    Absolute/relative path(s) to read "static" configurable parameters from.

To see all available configurables, use `--help-all`

- Renamed the use of builtin `help` in one occasion; - changed 2 TCs to test with 2-tuples; - improved slightly the documentation. See ipython#361 for rational.

+ Mimic behavior of similar libraries (docopt, click) and tools. Part of ipython#361.

ankostis · 2017-01-13T18:27:42Z

Pushed a stylistic help-message modification: put human explanation for opts above automated infos

"Before" Help Message:

-d, --debug
    Log more logging, fail on configuration errors, and print configuration on each cmd startup.
    Equivalent to: [--Spec.log_level=0 --Cmd.print_config=True --Cmd.raise_config_file_errors=True --Application.log_level=0]
-v, --verbose
    Make various sub-commands increase their verbosity (not to be confused with --debug):
    Equivalent to: [--Cmd.verbose=True --Spec.verbose=True]
-f, --force
    Force various sub-commands to perform their duties without complaints.
    Equivalent to: [--Cmd.force=True --Spec.force=True]
--config-paths=<list-item-1>...
    Default: []
    Absolute/relative path(s) to read "static" configurable parameters from.
    Equivalent to: [--Cmd.config_paths]
--log-level=<Enum>
    Default: 30
    Choices: (0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL')
    Set the log level by value or name.
    Equivalent to: [--Application.log_level]
--persist-path=<Unicode>
    Default: None
    Absolute/relative path to read/write persistent parameters on runtime, if
    `CO2DICE_PERSIST_PATH` envvar is not defined.
    Equivalent to: [--Cmd.persist_path]

"After" Help Message:

-v, --verbose
    Make various sub-commands increase their verbosity (not to be confused with --debug):
    Equivalent to: [--Cmd.verbose=True --Spec.verbose=True]
-d, --debug
    Log more logging, fail on configuration errors, and print configuration on each cmd startup.
    Equivalent to: [--Cmd.raise_config_file_errors=True --Cmd.print_config=True --Spec.log_level=0 --Application.log_level=0]
-f, --force
    Force various sub-commands to perform their duties without complaints.
    Equivalent to: [--Cmd.force=True --Spec.force=True]
--persist-path=<Unicode>
    Absolute/relative path to read/write persistent parameters on runtime, if
    `CO2DICE_PERSIST_PATH` envvar is not defined.
    Default: None
    Equivalent to: [--Cmd.persist_path]
--log-level=<Enum>
    Set the log level by value or name.
    Default: 30
    Choices: (0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL')
    Equivalent to: [--Application.log_level]
--config-paths=<list-item-1>...
    Absolute/relative path(s) to read "static" configurable parameters from.
    Default: []
    Equivalent to: [--Cmd.config_paths]

ankostis · 2017-01-13T18:39:59Z

Regarding my last 6a93d8c for putting human option-infos on top:
till now, the human explanation was "sanditched" between the Default and the Equivalent to lines, and I had introduced that with #319, because it was the easiest thing to do.

I'm now thinking that it may be appropriate to keep the Equivalent to line to the top (or immediately below the human-text) because it is part of the explanation, and to have the Default and the other auto-infos at the end, which is customary for cmd-line tools.

(regardless, this last commit still has to apply)

Part of ipython#361 PR.

ankostis · 2017-01-13T19:04:00Z

Pushed fix commit 4148033:
since #289 has ensured that all parent hierarchy gets to be printed,
we may avoid clutter on --help-all by not reprinting all traits on child classes.

ankostis · 2017-01-23T00:14:22Z

Is there any problem with this PR?

minrk

Sorry, I've been very busy, and haven't had time to review these PRs. I made a few comments inline.

minrk · 2017-01-24T15:25:09Z

traitlets/config/configurable.py

@@ -221,17 +221,20 @@ class defaults.
        base_classes = ','.join(p.__name__ for p in cls.__bases__)
        final_help.append(u'%s(%s) options' % (cls.__name__, base_classes))
        final_help.append(len(final_help[0])*u'-')
-        for k, v in sorted(cls.class_traits(config=True).items()):
+        for k, v in sorted(cls.class_own_traits(config=True).items()):


It seems like this should still be .class_traits, since it should include all configurables on the class, not just those it didn't inherit.

No strong opinion on that.
As reasoned in this comment, this was also to avoid clutter on --help-all: since #289 class-parents are printed, so the user may connect the dots and deduce which traits belong to subclasses.

But I will retract it, to keep the --help-all extra helpfull.

minrk · 2017-01-24T15:26:19Z

traitlets/config/tests/test_application.py

@@ -66,7 +66,7 @@ class MyApp(Application):

    aliases = Dict({
                    ('fooi', 'i') : 'Foo.i',
-                    ('j', 'fooj') : 'Foo.j',
+                    ('j', 'fooj') : ('Foo.j', "`j` terse help msg"),


The point of the help string on traitlets is to specify this help string. Under what circumstances would one set a help string that one didn't want to use?

The point is foo --help and foo --help-all to print gradually more text for options.

Optimally, with --help, each option "should" occupy a single line, as most unix-utils do, to waste as little screen estate as possible (ok, we're cannot achieve 1-line bc there are default values, equivalent flags, etc). That is important for apps with a lot of aliases.

The --help-all is like printing the full man-page.

Of course it is still possible to use the original help-string.
Personally I use a little function that puts in the tuple the 1st line from the full help-msg.

More detailed reasoning on the PR OP.

I have difficulty with that, since I can't think of any cases where I would want the two messages differ. I see the rationale in the OP, but it's not accurate, for instance:

For flags, it is possible (actually forced) to provide shorter versions

There's a field for a help string only because it's not retrievable from the traits. There is no restriction on its length.

The only difference between --help output and --help-all output should be whether the entirety of classes are walked, vs only those items with aliases and flags. The .help key exists solely for the purpose of populating this output, so I don't understand why it wouldn't be used.

The same reasoning you explained could have been applied also in the flags, like that:
Since .help keys exist for all options a flag masp to, then just concatenate all of them in one big help-message, and use this for the flag - no need to have a shorter version in a 2-tuple.
But hopefully the case is not like that.

[edit: more accurate numbers concerning my app]
I have a need for this because my app has ~~15 subcommands~~ 31 configurables and 40 config-params, with 3 levels of nesting. And since i did a trick to merge aliases and flags from parent cmds, at times the output of root foo bar --help is simply overwhelming, with tens of of aliases & flags.
So I'm striving to use shorter versions to conserve screen estate and help the users see what's important.

I repeat this PR provides an optional functionality, so by default the longer-help message is used.

By the way, the number of config-params above is an order of magnitude bigger if you include has_traits() instead of has_own_traits(). That is why my retracted 4148033 was trying to save space also for --help-all case.

For the future reader: describing here cases where it is totally necessary to override the help-msg on the alias: the trait is defined in some base-class, and each alias wants to explain its exact usage.

ankostis · 2017-01-25T17:44:31Z

@minrk I retracted the 4148033 commit which had the conversation about listing "own only" traits in help msg or not, so you cannot see it anymore.

Part of ipython#361 PR.

feat(alias): support 2-tuple also for aliases, for terser help-msgs

b9c6d01

- Renamed the use of builtin `help` in one occasion; - changed 2 TCs to test with 2-tuples; - improved slightly the documentation. See ipython#361 for rational.

ankostis force-pushed the aliashelp branch from 836c1fe to b9c6d01 Compare January 13, 2017 17:40

style(help): put human explanation for opts above automated infos

6a93d8c

+ Mimic behavior of similar libraries (docopt, click) and tools. Part of ipython#361.

ankostis changed the title ~~Make alias support extra help-msg, like flags do~~ help: Alias overriding help-text (like flags), options list human-help before automated infos Jan 13, 2017

ankostis force-pushed the aliashelp branch from d4d340e to 6a93d8c Compare January 13, 2017 18:40

ankostis added a commit to ankostis/traitlets that referenced this pull request Jan 13, 2017

fix(help): since ipython#289, --help-all may print own-traits only

4148033

Part of ipython#361 PR.

minrk reviewed Jan 24, 2017

View reviewed changes

ankostis force-pushed the aliashelp branch from 4148033 to 6a93d8c Compare January 25, 2017 17:39

ankostis added a commit to ankostis/traitlets that referenced this pull request Jan 25, 2017

fix(help): since ipython#289, --help-all may print own-traits only

a5decb9

Part of ipython#361 PR.

minrk added this to the 5.0 milestone Jan 25, 2017

minrk merged commit 25b16ca into ipython:master Jan 25, 2017

ankostis added a commit to ankostis/traitlets that referenced this pull request Jan 30, 2017

fix(help): since ipython#289, --help-all may print own-traits only

ae6a15b

Part of ipython#361 PR.

Carreau added 5.0-re-review Need to re-review for potential API impact changes. 5.0-major Major change in 5.0 need proper documentation and removed 5.0-re-review Need to re-review for potential API impact changes. labels Jun 4, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

help: Alias overriding help-text (like flags), options list human-help before automated infos #361

help: Alias overriding help-text (like flags), options list human-help before automated infos #361

ankostis commented Jan 13, 2017 •

edited

Loading

ankostis commented Jan 13, 2017 •

edited

Loading

ankostis commented Jan 13, 2017 •

edited

Loading

ankostis commented Jan 13, 2017 •

edited

Loading

ankostis commented Jan 23, 2017

minrk left a comment

minrk Jan 24, 2017

ankostis Jan 24, 2017 •

edited

Loading

minrk Jan 24, 2017

ankostis Jan 24, 2017

minrk Jan 25, 2017

ankostis Jan 25, 2017 •

edited

Loading

ankostis Jan 25, 2017

ankostis Feb 5, 2017

ankostis commented Jan 25, 2017

help: Alias overriding help-text (like flags), options list human-help before automated infos #361

help: Alias overriding help-text (like flags), options list human-help before automated infos #361

Conversation

ankostis commented Jan 13, 2017 • edited Loading

Rational:

"Before" Help Messages:

"After" Help Message:

ankostis commented Jan 13, 2017 • edited Loading

"Before" Help Message:

"After" Help Message:

ankostis commented Jan 13, 2017 • edited Loading

ankostis commented Jan 13, 2017 • edited Loading

ankostis commented Jan 23, 2017

minrk left a comment

Choose a reason for hiding this comment

minrk Jan 24, 2017

Choose a reason for hiding this comment

ankostis Jan 24, 2017 • edited Loading

Choose a reason for hiding this comment

minrk Jan 24, 2017

Choose a reason for hiding this comment

ankostis Jan 24, 2017

Choose a reason for hiding this comment

minrk Jan 25, 2017

Choose a reason for hiding this comment

ankostis Jan 25, 2017 • edited Loading

Choose a reason for hiding this comment

ankostis Jan 25, 2017

Choose a reason for hiding this comment

ankostis Feb 5, 2017

Choose a reason for hiding this comment

ankostis commented Jan 25, 2017

ankostis commented Jan 13, 2017 •

edited

Loading

ankostis commented Jan 13, 2017 •

edited

Loading

ankostis commented Jan 13, 2017 •

edited

Loading

ankostis commented Jan 13, 2017 •

edited

Loading

ankostis Jan 24, 2017 •

edited

Loading

ankostis Jan 25, 2017 •

edited

Loading