Help categories #348

anselor · 2018-04-10T19:08:05Z

Adds ability to optionally group commands into categories:

As well as a way to see more verbose help output:
help -v / help --verbose

This addresses #278

Added example of multiple commands grouped by categories

Reads the __doc__ for a command function and provides the first block of text for each command. Updated help_categories.py to demonstrate a multi-line comment block for a command.

tleonhardt · 2018-04-10T20:13:31Z

cmd2.py

+                widest = 0
+                # measure the commands
+                for command in cmds:
+                    width = wcswidth(command)


You need to put this in a conditional check since wcswidth() is not available on Windows. You would so something like the following:

if 'gnureadline' in sys.modules or 'readline' in sys.modules: width = wcswidth(command) else: width = len(command)

It turns out we don't allow arbitrary unicode characters in the command names so I can actually just remove this.

That is an even better solution.

tleonhardt

Need to fix the issue where wcswidth isn't available on Windows.

tleonhardt · 2018-04-10T20:16:08Z

examples/help_categories.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python


The example is nice and helps explain to end users how to use it.

A couple unit tests covering the new features added would be extremely beneficial from a maintenance perspective.

tleonhardt · 2018-04-10T20:17:07Z

Thanks for the PR @anselor!

Please fix the dependency issue on Windows.

A few unit tests covering the new features would be greatly appreciated if you don't mind taking the time to add them.

tleonhardt · 2018-04-10T20:19:00Z

If you update the Sphinx docs a little to mention the new features, you get bonus points ;-)

kmvanbrunt · 2018-04-10T22:56:36Z

I will need to tweak complete_help() since it isn't expecting a flag.

kmvanbrunt · 2018-04-11T04:34:52Z

@anselor @tleonhardt
Nevermind, the complete_help() function is fine with this change.

I do think we need to change what displays in verbose for some commands.
For instance, help says "usage: history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]"
I would assume it would say, "View, run, edit, and save previously entered commands" from the docstring.

codecov · 2018-04-11T05:10:17Z

Codecov Report

Merging #348 into master will increase coverage by 0.4%.
The diff coverage is 100%.

@@            Coverage Diff            @@
##           master     #348     +/-   ##
=========================================
+ Coverage   89.23%   89.64%   +0.4%     
=========================================
  Files           1        1             
  Lines        1932     2008     +76     
=========================================
+ Hits         1724     1800     +76     
  Misses        208      208

Impacted Files	Coverage Δ
cmd2.py	`89.64% <100%> (+0.4%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 322a7c2...e4ca6c8. Read the comment docs.

anselor · 2018-04-11T15:40:13Z

@tleonhardt I don't see anything in the current Sphinx docs covering how to document your commands.

…and> function provided. In verbose help, added check for argparse usage block (starting with 'usage: '), to skip that block and move to the next comment block Added unit tests for new categorization code Updated example to demonstrate skipping of argparse usage statement

tleonhardt · 2018-04-11T15:46:46Z

Wow, we really don't. The closest we have is this paragraph in the Argument Processing section.

Feel free to add something earlier ;-)

I think the initial thought was we didn't want to duplicate documentation for features which were implemented and documented within cmd. But now our support for help has grown beyond the base cmd capabilities.

tleonhardt · 2018-04-11T16:25:39Z

tests/conftest.py

 edit   history  py    quit      shell  unalias
 """

+BASE_HELP_VERBOSE = """


Thanks for adding the unit tests. They should really help with maintainability.

tleonhardt

This is looking pretty good. Thanks for the fixes and updates.

tleonhardt

The test_base_argparse_help unit test is now failing on Python 2.7.

Fix that and then this PR should hopefully be good to go minus potential documentation updates.

…egory. Changed the detection of with_argparse decorated commands to be less hacky/brittle. Now it tags the function with help_summary. Fixed issue with handling commands that provide a custom help_ function. We can now redirect the output to a string to be formatted with the other commands. Added some documentation explaining the new help categories. Updated unit tests.

anselor · 2018-04-11T19:19:16Z

@tleonhardt I'm looking forward to retiring Python 2 support. The gymnastics to keep it working are annoying.

tleonhardt · 2018-04-11T19:32:07Z

@anselor Yeah, I now wish that @kotfu and I had agreed on an earlier date for ending Python 2 support than August 31, 2018. The burden of supporting Python 2.7 is getting worse by the month.

Tell you what, if you can convince @kotfu that moving the date earlier (perhaps May 31, 2018 or even April 30, 2018) is desirable then I am happy to buy-in to that decision. I know moving it earlier would make @kmvanbrunt very happy.

tleonhardt · 2018-04-11T19:45:06Z

cmd2.py

 else:
    from contextlib import redirect_stdout, redirect_stderr

+if sys.version_info > (3, 0):


FYI, using the six module can help avoid Python 2 vs 3 compatibility gymnastics such as this.

six is a Python 2 vs 3 compatibility module (6 == 2 * 3 == 3 * 2).

tleonhardt · 2018-04-11T19:49:23Z

cmd2.py

    return lexed_arglist


+def with_category(category):


I like that you added a decorator, that should make the code clean and easy to read.

I strongly encourage you to make one simple change to your decorator to help avoid order-of-operations dependencies when multiple decorators are involved.

You should apply the "@functools.wraps(func)" decorator to your internal cat_decorator function - see how we do it in other decorators below such as with_argument_list:

def with_category(category): """A decorator to apply a category to a command function""" @functools.wraps(func) def cat_decorator(func): categorize(func, category) return func return cat_decorator

I don't think that's necessary in this situation because this decorator function is truly a decorator function rather than a wrapping function. This adds an attribute the the passed-in function and returns it.

You make a good point, your decorator is mutating and returning the original function. I think you are fine as-is.

tleonhardt

Use functools.wraps in your new decorator to avoid decorator order of application mattering when multiple deorators are used on a function.

tleonhardt

I think this is good to go.

Every now and then the AppVeyor Windows CI tool just gets stuck for no good reason. Can you please push some trivial change to force it to run? Maybe updated the CHANGELOG or something?

anselor and others added 7 commits April 9, 2018 17:47

Added ability to group commands by category when printing the help menu.

5d1e981

Added example of multiple commands grouped by categories

Added a convenience function for tagging command categories.

ef23633

Merge branch 'master' into help_categories

62d8c23

Remove usage of optional type hinting which is not allowed in Python 2.7

5e349dc

Fixed imports since new categorization feature requires Iterable

4f68eb2

Merge remote-tracking branch 'origin/master' into help_categories

da28564

Added verbose help output with help -v or help --verbose

f4f2b9e

Reads the __doc__ for a command function and provides the first block of text for each command. Updated help_categories.py to demonstrate a multi-line comment block for a command.

anselor requested a review from tleonhardt as a code owner April 10, 2018 19:08

tleonhardt reviewed Apr 10, 2018

View reviewed changes

tleonhardt requested changes Apr 10, 2018

View reviewed changes

tleonhardt reviewed Apr 10, 2018

View reviewed changes

tleonhardt added the enhancement label Apr 10, 2018

tleonhardt added this to the 0.8.5 milestone Apr 10, 2018

Removed extra new line

2ffd342

tleonhardt reviewed Apr 11, 2018

View reviewed changes

tleonhardt approved these changes Apr 11, 2018

View reviewed changes

tleonhardt requested changes Apr 11, 2018

View reviewed changes

tleonhardt reviewed Apr 11, 2018

View reviewed changes

tleonhardt requested changes Apr 11, 2018

View reviewed changes

tleonhardt previously approved these changes Apr 11, 2018

View reviewed changes

Removed an emty line.

e4ca6c8

anselor dismissed tleonhardt’s stale review via e4ca6c8 April 11, 2018 22:40

tleonhardt merged commit 2026747 into master Apr 11, 2018

tleonhardt deleted the help_categories branch April 11, 2018 23:01

tleonhardt mentioned this pull request Apr 11, 2018

Consider categorizing output of 'help' command #278

Closed

Help categories #348

Help categories #348

Uh oh!

Conversation

anselor commented Apr 10, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tleonhardt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tleonhardt commented Apr 10, 2018

Uh oh!

tleonhardt commented Apr 10, 2018

Uh oh!

kmvanbrunt commented Apr 10, 2018

Uh oh!

kmvanbrunt commented Apr 11, 2018

Uh oh!

codecov bot commented Apr 11, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

anselor commented Apr 11, 2018

Uh oh!

tleonhardt commented Apr 11, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tleonhardt left a comment

Choose a reason for hiding this comment

Uh oh!

tleonhardt left a comment

Choose a reason for hiding this comment

Uh oh!

anselor commented Apr 11, 2018

Uh oh!

tleonhardt commented Apr 11, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tleonhardt left a comment

Choose a reason for hiding this comment

Uh oh!

tleonhardt left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Apr 11, 2018 •

edited

Loading

tleonhardt commented Apr 11, 2018 •

edited

Loading

tleonhardt left a comment •

edited

Loading