app: support flags/aliases given as (--long, -short) tuple #319

ankostis · 2016-09-21T21:10:00Z

Specify both short/long forms of flags & aliases at once.
Explain explicitely equivalence of flags/aliases.
Handle and log exceptions while printing flag/alias help-msgs - stacktrace was too convoluted otherwise.
FIX Enhance --help-all to print all relevant configurables, along with their relations #296: print all relevant (sub)classes in help-msg.

An example of the new flags/aliases help message:

-f, --force
    Force various sub-commands perform their duties without complaints.
    Equivalent to: [Spec.force=True]
-v, --verbose
    Make various sub-commands increase their verbosity (not to be confused with --debug):
    Equivalent to: [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]
--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]

+ Specify both short/long flags/aliases of a once. + Update print-flag logic to print both flags in one place. + Print flag-equivalence at the end, e.g.: "Equivalent to: [Spec.verbose=True, Foo.bar=2] + Use the same format for aliases (do not clutter 1st line). + Renamed build-in varname `help` --> `fhelp`. - Had to catch exceptions in print_XXX_help(), otherwise difficult to debug miss-configurations. + Added TCs for short/long flags & flag equivalance.

ankostis · 2016-09-21T22:45:22Z

Now it is ready to merge.
An example of the new flags/aliases help message:

-f, --force
    Force various sub-commands perform their duties without complaints.
    Equivalent to: [Spec.force=True]
-v, --verbose
    Make various sub-commands increase their verbosity (not to be confused with --debug):
    Equivalent to: [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]
--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]

ankostis · 2016-09-21T23:02:15Z

This PR tries to maintain compatibility with existing behavior, and adds single letter flags/alias prefixed both with single('-') and double('--') dashed.
The end result is that (-v, --verbose) gets added as (-v, --v, --verbose).

I would prefer a simplification using the standard convention where a single-letter flag/alias are added only once, with single-dash.
What do you think?

minrk

I would prefer a simplification using the standard convention where a single-letter flag/alias are added only once, with single-dash.
What do you think?

If I were starting from scratch, I would agree, but for backward-compatibility I think it's not worth breaking things for a minuscule aesthetic improvement.

minrk · 2016-09-22T11:15:18Z

traitlets/config/application.py

+                lines.extend(fhelp)
+                lines.append(indent("Equivalent to: [%s]" % longname))
+            except Exception as ex:
+                self.log.error('Failed collecting help-message for aias %r, due to: %s',


Why catch/log these errors. Shouldn't they be bugs that raise?

While developing it, the stack-traces for such errors happened very early in the boot-strap process and it was extremely confusing for me to debug such issues (practically speaking); eventually I had to manually wrap the offending code in a try-catch every time to locate the problem; eventually, I left it there for others, as explained in the commit message.

You can try it yourself if you have some class without description trait, or badly formed flag.
Maybe we can retrofit the error behavior to help developers.

Raising a clearer error sounds great. But I still think it should be an error, not a message that allows the application to continue. If you add raise below here, it should be fine.

Then I will remove the exception-wrapper completely; the point was to be able to read the help-message and discover what config-property were missing - the log-error actually does not help either; practically it just tells you that something went wrong.

Sorry, I will leave it because by catching exceptions, the log-message knows which property failed and it DOES help; it will just raise as you said.

Now that I think of it, (-n, --n, --name) is the same as (-n, --name), because argparse already accepts --n if you specify -n.

Nope...it doesn't work! All TCs with --i fail.

minrk

Now that I think of it, (-n, --n, --name) is the same as (-n, --name), because argparse already accepts --n if you specify -n.

minrk · 2016-09-22T13:33:43Z

traitlets/config/application.py

@@ -381,7 +404,7 @@ def print_help(self, classes=False):
        self.print_options()

        if classes:
-            help_classes = self.classes
+            help_classes = self._classes_in_config_sample()


Why is this not self.classes?

See #289 discussion, and my example just entered in #180, specifically the comment in classes trait.
[edit] And read the docstring description of Application._classes_in_config_sample():

Yields only classes with own traits, and their subclasses. Thus, produced sample config-file will contain all classes on which a trait-value may be overridden: - either on the class owning the trait, - or on its subclasses, even if those subclasses do not define any traits themselves.

The same should apply for cmd-line options.

Makes sense, thanks.

@minrk

+ After @minrk codereview: ipython#319 (review) + minor: Remove unused builtin varname `help`.

@minrk

+ After @minrk codereview: ipython#319 (comment)

@minrk

+ After @minrk codereview: ipython#319 (comment)

@minrk

+ After @minrk codereview: ipython#319 (comment)

minrk · 2016-09-25T15:26:29Z

This is adding four -- to aliases, so the output looks like:

----alias=<Unicode>

+ Enhance checking TCs.

ankostis · 2016-09-25T17:36:06Z

This is adding four -- to aliases, so the output looks like: ----alias=<Unicode>

Thanks, the TC were not that accurate; fixed both.

ankostis · 2016-10-05T13:47:20Z

Note, this has been merged (probably on 4.3.1) bust is not mentioned in the Changelog.

minrk · 2016-10-05T18:52:41Z

This is not in 4.3.1, only unreleased master (will be 5.0).

ankostis force-pushed the short_long_flags branch 2 times, most recently from ca39361 to b58e007 Compare September 21, 2016 22:18

ankostis added a commit to ankostis/traitlets that referenced this pull request Sep 21, 2016

app, ipython#319: TCs for short/long flags & flag equivalance

b58e007

ankostis force-pushed the short_long_flags branch from b58e007 to 0448f35 Compare September 21, 2016 22:21

ankostis added a commit to ankostis/traitlets that referenced this pull request Sep 21, 2016

app, ipython#319: Skip TCs with redirect_stdout in py<3.4

11f0049

app, ipython#319: Skip TCs with redirect_stdout in py<3.4

8a90693

ankostis force-pushed the short_long_flags branch from 11f0049 to 8a90693 Compare September 21, 2016 22:40

app, FIX ipython#296: print all relevant (sub)classes in help-msg

eefb9bb

ankostis force-pushed the short_long_flags branch 2 times, most recently from 9be8541 to 73e1250 Compare September 21, 2016 23:11

conf, ipython#296: Also print the subclasses of each configurable.

ea395a3

ankostis force-pushed the short_long_flags branch from 73e1250 to ea395a3 Compare September 21, 2016 23:30

ankostis changed the title ~~flags: support flags given as (--long, -short) tuple~~ app: support flags/aliaes given as (--long, -short) tuple Sep 21, 2016

ankostis changed the title ~~app: support flags/aliaes given as (--long, -short) tuple~~ app: support flags/aliases given as (--long, -short) tuple Sep 21, 2016

minrk reviewed Sep 22, 2016

View reviewed changes

ankostis added a commit to ankostis/traitlets that referenced this pull request Sep 22, 2016

app, ipython#319: do not add both -f & --f argparse options.

df74127

+ After @minrk codereview: ipython#319 (review) + minor: Remove unused builtin varname `help`.

ankostis added a commit to ankostis/traitlets that referenced this pull request Sep 22, 2016

app, ipython#319: re-raise alias/flag help-msg errors

4a5bc60

+ After @minrk codereview: ipython#319 (comment)

ankostis force-pushed the short_long_flags branch from 4a5bc60 to 0a13126 Compare September 22, 2016 15:24

ankostis added a commit to ankostis/traitlets that referenced this pull request Sep 22, 2016

app, ipython#319: re-raise alias/flag help-msg errors

0a13126

+ After @minrk codereview: ipython#319 (comment)

app, ipython#319: re-raise alias/flag help-msg errors

d327731

+ After @minrk codereview: ipython#319 (comment)

ankostis force-pushed the short_long_flags branch from 0a13126 to d327731 Compare September 22, 2016 15:43

app, ipython#319: fix triple-dash in alias help-msg

6b7031d

+ Enhance checking TCs.

minrk added this to the 5.0 milestone Sep 26, 2016

minrk merged commit 1d8bb23 into ipython:master Sep 26, 2016

ankostis mentioned this pull request Jan 13, 2017

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

Merged

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

app: support flags/aliases given as (--long, -short) tuple #319

app: support flags/aliases given as (--long, -short) tuple #319

ankostis commented Sep 21, 2016 •

edited

Loading

ankostis commented Sep 21, 2016

ankostis commented Sep 21, 2016

minrk left a comment

minrk Sep 22, 2016

ankostis Sep 22, 2016 •

edited

Loading

minrk Sep 22, 2016

ankostis Sep 22, 2016

ankostis Sep 22, 2016

ankostis Sep 22, 2016

minrk left a comment

minrk Sep 22, 2016

ankostis Sep 22, 2016 •

edited

Loading

minrk Sep 22, 2016

minrk commented Sep 25, 2016

ankostis commented Sep 25, 2016

ankostis commented Oct 5, 2016

minrk commented Oct 5, 2016

app: support flags/aliases given as (--long, -short) tuple #319

app: support flags/aliases given as (--long, -short) tuple #319

Conversation

ankostis commented Sep 21, 2016 • edited Loading

ankostis commented Sep 21, 2016

ankostis commented Sep 21, 2016

minrk left a comment

Choose a reason for hiding this comment

minrk Sep 22, 2016

Choose a reason for hiding this comment

ankostis Sep 22, 2016 • edited Loading

Choose a reason for hiding this comment

minrk Sep 22, 2016

Choose a reason for hiding this comment

ankostis Sep 22, 2016

Choose a reason for hiding this comment

ankostis Sep 22, 2016

Choose a reason for hiding this comment

ankostis Sep 22, 2016

Choose a reason for hiding this comment

minrk left a comment

Choose a reason for hiding this comment

minrk Sep 22, 2016

Choose a reason for hiding this comment

ankostis Sep 22, 2016 • edited Loading

Choose a reason for hiding this comment

minrk Sep 22, 2016

Choose a reason for hiding this comment

minrk commented Sep 25, 2016

ankostis commented Sep 25, 2016

ankostis commented Oct 5, 2016

minrk commented Oct 5, 2016

ankostis commented Sep 21, 2016 •

edited

Loading

ankostis Sep 22, 2016 •

edited

Loading

ankostis Sep 22, 2016 •

edited

Loading