From 5d1e981ee18136d41574c20e10a77f1b0e8b30a1 Mon Sep 17 00:00:00 2001 From: Eric Lin Date: Mon, 9 Apr 2018 17:47:16 -0400 Subject: Added ability to group commands by category when printing the help menu. Added example of multiple commands grouped by categories --- examples/help_categories.py | 131 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100755 examples/help_categories.py (limited to 'examples') diff --git a/examples/help_categories.py b/examples/help_categories.py new file mode 100755 index 00000000..272344f7 --- /dev/null +++ b/examples/help_categories.py @@ -0,0 +1,131 @@ +#!/usr/bin/env python +# coding=utf-8 +""" +A sample application for tagging categories on commands. +""" + +from cmd2 import Cmd, HELP_CATEGORY, __version__ + + +class HelpCategories(Cmd): + """ Example cmd2 application. """ + + # Command categories + CMD_CAT_CONNECTING = 'Connecting' + CMD_CAT_APP_MGMT = 'Application Management' + CMD_CAT_SERVER_INFO = 'Server Information' + + def __init__(self): + # Set use_ipython to True to enable the "ipy" command which embeds and interactive IPython shell + Cmd.__init__(self, use_ipython=False) + + def do_connect(self, _): + """Connect command""" + self.poutput('Connect') + + def do_which(self, _): + """Which command""" + self.poutput('Which') + + # Tag the above command functions under the category Connecting + setattr(do_connect, HELP_CATEGORY, CMD_CAT_CONNECTING) + setattr(do_which, HELP_CATEGORY, CMD_CAT_CONNECTING) + + def do_list(self, _): + """List command""" + self.poutput('List') + + def do_deploy(self, _): + """Deploy command""" + self.poutput('Which') + + def do_start(self, _): + """Start command""" + self.poutput('Start') + + def do_sessions(self, _): + """Sessions command""" + self.poutput('Sessions') + + def do_redeploy(self, _): + """Redeploy command""" + self.poutput('Redeploy') + + def do_restart(self, _): + """Restart command""" + self.poutput('Restart') + + def do_expire(self, _): + """Expire command""" + self.poutput('Expire') + + def do_undeploy(self, _): + """Undeploy command""" + self.poutput('Undeploy') + + def do_stop(self, _): + """Stop command""" + self.poutput('Stop') + + def do_findleakers(self, _): + """Find Leakers command""" + self.poutput('Find Leakers') + + # Tag the above command functions under the category Application Management + setattr(do_list, HELP_CATEGORY, CMD_CAT_APP_MGMT) + setattr(do_deploy, HELP_CATEGORY, CMD_CAT_APP_MGMT) + setattr(do_start, HELP_CATEGORY, CMD_CAT_APP_MGMT) + setattr(do_sessions, HELP_CATEGORY, CMD_CAT_APP_MGMT) + setattr(do_redeploy, HELP_CATEGORY, CMD_CAT_APP_MGMT) + setattr(do_restart, HELP_CATEGORY, CMD_CAT_APP_MGMT) + setattr(do_expire, HELP_CATEGORY, CMD_CAT_APP_MGMT) + setattr(do_undeploy, HELP_CATEGORY, CMD_CAT_APP_MGMT) + setattr(do_stop, HELP_CATEGORY, CMD_CAT_APP_MGMT) + setattr(do_findleakers, HELP_CATEGORY, CMD_CAT_APP_MGMT) + + def do_resources(self, _): + """Resources command""" + self.poutput('Resources') + + def do_status(self, _): + """Status command""" + self.poutput('Status') + + def do_serverinfo(self, _): + """Server Info command""" + self.poutput('Server Info') + + def do_thread_dump(self, _): + """Thread Dump command""" + self.poutput('Thread Dump') + + def do_sslconnectorciphers(self, _): + """SSL Connector Ciphers command""" + self.poutput('SSL Connector Ciphers') + + def do_vminfo(self, _): + """VM Info command""" + self.poutput('VM Info') + + # Tag the above command functions under the category Server Information + setattr(do_resources, HELP_CATEGORY, CMD_CAT_SERVER_INFO) + setattr(do_status, HELP_CATEGORY, CMD_CAT_SERVER_INFO) + setattr(do_serverinfo, HELP_CATEGORY, CMD_CAT_SERVER_INFO) + setattr(do_thread_dump, HELP_CATEGORY, CMD_CAT_SERVER_INFO) + setattr(do_sslconnectorciphers, HELP_CATEGORY, CMD_CAT_SERVER_INFO) + setattr(do_vminfo, HELP_CATEGORY, CMD_CAT_SERVER_INFO) + + # The following command functions don't have the HELP_CATEGORY attribute set + # and show up in the 'Other' group + def do_config(self, _): + """Config command""" + self.poutput('Config') + + def do_version(self, _): + """Version command""" + self.poutput(__version__) + + +if __name__ == '__main__': + c = HelpCategories() + c.cmdloop() -- cgit v1.2.1 From ef23633daba9538360af61d7547e8d0d0f6c1139 Mon Sep 17 00:00:00 2001 From: Eric Lin Date: Mon, 9 Apr 2018 18:14:31 -0400 Subject: Added a convenience function for tagging command categories. --- examples/help_categories.py | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'examples') diff --git a/examples/help_categories.py b/examples/help_categories.py index 272344f7..6583d795 100755 --- a/examples/help_categories.py +++ b/examples/help_categories.py @@ -4,7 +4,7 @@ A sample application for tagging categories on commands. """ -from cmd2 import Cmd, HELP_CATEGORY, __version__ +from cmd2 import Cmd, categorize, __version__ class HelpCategories(Cmd): @@ -28,8 +28,8 @@ class HelpCategories(Cmd): self.poutput('Which') # Tag the above command functions under the category Connecting - setattr(do_connect, HELP_CATEGORY, CMD_CAT_CONNECTING) - setattr(do_which, HELP_CATEGORY, CMD_CAT_CONNECTING) + categorize(do_connect, CMD_CAT_CONNECTING) + categorize(do_which, CMD_CAT_CONNECTING) def do_list(self, _): """List command""" @@ -72,16 +72,16 @@ class HelpCategories(Cmd): self.poutput('Find Leakers') # Tag the above command functions under the category Application Management - setattr(do_list, HELP_CATEGORY, CMD_CAT_APP_MGMT) - setattr(do_deploy, HELP_CATEGORY, CMD_CAT_APP_MGMT) - setattr(do_start, HELP_CATEGORY, CMD_CAT_APP_MGMT) - setattr(do_sessions, HELP_CATEGORY, CMD_CAT_APP_MGMT) - setattr(do_redeploy, HELP_CATEGORY, CMD_CAT_APP_MGMT) - setattr(do_restart, HELP_CATEGORY, CMD_CAT_APP_MGMT) - setattr(do_expire, HELP_CATEGORY, CMD_CAT_APP_MGMT) - setattr(do_undeploy, HELP_CATEGORY, CMD_CAT_APP_MGMT) - setattr(do_stop, HELP_CATEGORY, CMD_CAT_APP_MGMT) - setattr(do_findleakers, HELP_CATEGORY, CMD_CAT_APP_MGMT) + categorize((do_list, + do_deploy, + do_start, + do_sessions, + do_redeploy, + do_restart, + do_expire, + do_undeploy, + do_stop, + do_findleakers), CMD_CAT_APP_MGMT) def do_resources(self, _): """Resources command""" @@ -108,12 +108,12 @@ class HelpCategories(Cmd): self.poutput('VM Info') # Tag the above command functions under the category Server Information - setattr(do_resources, HELP_CATEGORY, CMD_CAT_SERVER_INFO) - setattr(do_status, HELP_CATEGORY, CMD_CAT_SERVER_INFO) - setattr(do_serverinfo, HELP_CATEGORY, CMD_CAT_SERVER_INFO) - setattr(do_thread_dump, HELP_CATEGORY, CMD_CAT_SERVER_INFO) - setattr(do_sslconnectorciphers, HELP_CATEGORY, CMD_CAT_SERVER_INFO) - setattr(do_vminfo, HELP_CATEGORY, CMD_CAT_SERVER_INFO) + categorize(do_resources, CMD_CAT_SERVER_INFO) + categorize(do_status, CMD_CAT_SERVER_INFO) + categorize(do_serverinfo, CMD_CAT_SERVER_INFO) + categorize(do_thread_dump, CMD_CAT_SERVER_INFO) + categorize(do_sslconnectorciphers, CMD_CAT_SERVER_INFO) + categorize(do_vminfo, CMD_CAT_SERVER_INFO) # The following command functions don't have the HELP_CATEGORY attribute set # and show up in the 'Other' group -- cgit v1.2.1 From f4f2b9ede5f34459d84dee21400cc23bc6008776 Mon Sep 17 00:00:00 2001 From: Eric Lin Date: Tue, 10 Apr 2018 14:53:53 -0400 Subject: Added verbose help output with help -v or help --verbose 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. --- examples/help_categories.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'examples') diff --git a/examples/help_categories.py b/examples/help_categories.py index 6583d795..2a88edba 100755 --- a/examples/help_categories.py +++ b/examples/help_categories.py @@ -100,7 +100,14 @@ class HelpCategories(Cmd): self.poutput('Thread Dump') def do_sslconnectorciphers(self, _): - """SSL Connector Ciphers command""" + """ + SSL Connector Ciphers command is an example of a command that contains + multiple lines of help information for the user. Each line of help in a + contiguous set of lines will be printed and aligned in the verbose output + provided with 'help --verbose' + + This is after a blank line and won't de displayed in the verbose help + """ self.poutput('SSL Connector Ciphers') def do_vminfo(self, _): -- cgit v1.2.1 From 52bf16c412eb7933eac159ed0fc6363ccc37a82c Mon Sep 17 00:00:00 2001 From: Eric Lin Date: Wed, 11 Apr 2018 11:44:18 -0400 Subject: Fixed issue where categorization is skipped when there's a help_ 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 --- examples/help_categories.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'examples') diff --git a/examples/help_categories.py b/examples/help_categories.py index 2a88edba..8a33e62c 100755 --- a/examples/help_categories.py +++ b/examples/help_categories.py @@ -4,7 +4,8 @@ A sample application for tagging categories on commands. """ -from cmd2 import Cmd, categorize, __version__ +from cmd2 import Cmd, categorize, __version__, with_argparser +import argparse class HelpCategories(Cmd): @@ -51,6 +52,12 @@ class HelpCategories(Cmd): """Redeploy command""" self.poutput('Redeploy') + restart_parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter) + restart_parser.add_argument('when', default='now', + choices=['now', 'later', 'sometime', 'whenever'], + help='Specify when to restart') + + @with_argparser(restart_parser) def do_restart(self, _): """Restart command""" self.poutput('Restart') -- cgit v1.2.1 From 33decb449c61e2a78877563309929c4686ea081e Mon Sep 17 00:00:00 2001 From: Eric Lin Date: Wed, 11 Apr 2018 15:11:52 -0400 Subject: Added a with_category decorator that can be used to tag a command category. 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. --- examples/help_categories.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'examples') diff --git a/examples/help_categories.py b/examples/help_categories.py index 8a33e62c..e7e3373d 100755 --- a/examples/help_categories.py +++ b/examples/help_categories.py @@ -4,7 +4,7 @@ A sample application for tagging categories on commands. """ -from cmd2 import Cmd, categorize, __version__, with_argparser +from cmd2 import Cmd, categorize, __version__, with_argparser, with_category import argparse @@ -24,14 +24,14 @@ class HelpCategories(Cmd): """Connect command""" self.poutput('Connect') + # Tag the above command functions under the category Connecting + categorize(do_connect, CMD_CAT_CONNECTING) + + @with_category(CMD_CAT_CONNECTING) def do_which(self, _): """Which command""" self.poutput('Which') - # Tag the above command functions under the category Connecting - categorize(do_connect, CMD_CAT_CONNECTING) - categorize(do_which, CMD_CAT_CONNECTING) - def do_list(self, _): """List command""" self.poutput('List') @@ -58,6 +58,7 @@ class HelpCategories(Cmd): help='Specify when to restart') @with_argparser(restart_parser) + @with_category(CMD_CAT_APP_MGMT) def do_restart(self, _): """Restart command""" self.poutput('Restart') @@ -84,7 +85,6 @@ class HelpCategories(Cmd): do_start, do_sessions, do_redeploy, - do_restart, do_expire, do_undeploy, do_stop, -- cgit v1.2.1