Improved how new argparse-based decorators provide help

Now "help command_name" and "command_name -h" provide exactly the same text.

The function docstring for the "do_*" command sets and overrides the ArgumentParser "description" if the docstring is not empty.

Author: tleonhardt

cmd2.py

@@ -288,13 +288,10 @@ def cmd_wrapper(instance, cmdline):
         argparser.prog = func.__name__[3:]
 
         # put the help message in the method docstring
-        funcdoc = func.__doc__
-        if funcdoc:
-            funcdoc += '\n'
-        else:
-            # if it's None, make it an empty string
-            funcdoc = ''
-        cmd_wrapper.__doc__ = '{}{}'.format(funcdoc, argparser.format_help())
+        if func.__doc__:
+            argparser.description = func.__doc__
+
+        cmd_wrapper.__doc__ = argparser.format_help()
         return cmd_wrapper
     return arg_decorator
 
@@ -315,13 +312,10 @@ def cmd_wrapper(instance, cmdline):
         argparser.prog = func.__name__[3:]
 
         # put the help message in the method docstring
-        funcdoc = func.__doc__
-        if funcdoc:
-            funcdoc += '\n'
-        else:
-            # if it's None, make it an empty string
-            funcdoc = ''
-        cmd_wrapper.__doc__ = '{}{}'.format(funcdoc, argparser.format_help())
+        if func.__doc__:
+            argparser.description = func.__doc__
+
+        cmd_wrapper.__doc__ = argparser.format_help()
         return cmd_wrapper
     return arg_decorator
 
@@ -1341,7 +1335,7 @@ def show(self, args, parameter):
         else:
             raise LookupError("Parameter '%s' not supported (type 'show' for list of parameters)." % param)
 
-    set_parser = argparse.ArgumentParser(description='show or set value of a parameter')
+    set_parser = argparse.ArgumentParser()
     set_parser.add_argument('-a', '--all', action='store_true', help='display read-only settings as well')
     set_parser.add_argument('-l', '--long', action='store_true', help='describe function of parameter')
     set_parser.add_argument('settable', nargs='*', help='[param_name] [value]')
@@ -1693,13 +1687,11 @@ def do_ipy(self, arg):
             exit_msg = 'Leaving IPython, back to {}'.format(sys.argv[0])
             embed(banner1=banner, exit_msg=exit_msg)
 
-    history_parser = argparse.ArgumentParser(
-                    description='run, edit, and save previously entered commands',
-                    formatter_class=argparse.RawTextHelpFormatter,
-                )
+    history_parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter)
     history_parser_group = history_parser.add_mutually_exclusive_group()
     history_parser_group.add_argument('-r', '--run', action='store_true', help='run selected history items')
-    history_parser_group.add_argument('-e', '--edit', action='store_true', help='edit and then run selected history items')
+    history_parser_group.add_argument('-e', '--edit', action='store_true',
+                                      help='edit and then run selected history items')
     history_parser_group.add_argument('-o', '--output-file', metavar='FILE', help='output to file')
     history_parser.add_argument('-s', '--script', action='store_true', help='script format; no separation lines')
     _history_arg_help = """empty               all history items
@@ -1711,8 +1703,8 @@ def do_ipy(self, arg):
 
     @with_argument_parser(history_parser)
     def do_history(self, args):
-        # If an argument was supplied, then retrieve partial contents of the
-        # history
+        """View, run, edit, and save previously entered commands."""
+        # If an argument was supplied, then retrieve partial contents of the history
         cowardly_refuse_to_run = False
         if args.arg:
             # If a character indicating a slice is present, retrieve
@@ -1735,7 +1727,8 @@ def do_history(self, args):
         if args.run:
             if cowardly_refuse_to_run:
                 self.perror("Cowardly refusing to run all previously entered commands.", traceback_war=False)
-                self.perror("If this is what you want to do, specify '1:' as the range of history.", traceback_war=False)
+                self.perror("If this is what you want to do, specify '1:' as the range of history.",
+                            traceback_war=False)
             else:
                 for runme in history:
                     self.pfeedback(runme)
@@ -1744,20 +1737,20 @@ def do_history(self, args):
         elif args.edit:
             fd, fname = tempfile.mkstemp(suffix='.txt', text=True)
             with os.fdopen(fd, 'w') as fobj:
-                for cmd in history:
-                    fobj.write('{}\n'.format(cmd))
+                for command in history:
+                    fobj.write('{}\n'.format(command))
             try:
                 os.system('"{}" "{}"'.format(self.editor, fname))
                 self.do_load(fname)
-            except:
+            except Exception:
                 raise
             finally:
                 os.remove(fname)
         elif args.output_file:
             try:
                 with open(os.path.expanduser(args.output_file), 'w') as fobj:
-                    for cmd in history:
-                        fobj.write('{}\n'.format(cmd))
+                    for command in history:
+                        fobj.write('{}\n'.format(command))
                 plural = 's' if len(history) > 1 else ''
                 self.pfeedback('{} command{} saved to {}'.format(len(history), plural, args.output_file))
             except Exception as e:
@@ -1770,7 +1763,6 @@ def do_history(self, args):
                 else:
                     self.poutput(hi.pr())
 
-
     @with_argument_list
     def do_edit(self, arglist):
         """Edit a file or command in a text editor.
@@ -1876,7 +1868,6 @@ def do_load(self, arglist):
 
         self._script_dir.append(os.path.dirname(expanded_path))
 
-
     @staticmethod
     def is_text_file(file_path):
         """

examples/argparse_example.py

@@ -64,7 +64,7 @@ def do_speak(self, args):
     do_say = do_speak  # now "say" is a synonym for "speak"
     do_orate = do_speak  # another synonym, but this one takes multi-line input
 
-    tag_parser = argparse.ArgumentParser(description='create a html tag')
+    tag_parser = argparse.ArgumentParser()
     tag_parser.add_argument('tag', nargs=1, help='tag')
     tag_parser.add_argument('content', nargs='+', help='content to surround with tag')
 

tests/conftest.py

@@ -21,7 +21,7 @@
 # Help text for the history command
 HELP_HISTORY = """usage: history [-h] [-r | -e | -o FILE] [-s] [arg]
 
-run, edit, and save previously entered commands
+View, run, edit, and save previously entered commands.
 
 positional arguments:
   arg                   empty               all history items

tests/test_argparse.py

@@ -140,10 +140,14 @@ def test_argparse_quoted_arguments_posix_multiple(argparse_app):
 
 def test_argparse_help_docstring(argparse_app):
     out = run_cmd(argparse_app, 'help say')
-    assert out[0] == 'Repeat what you tell me to.'
+    assert out[0].startswith('usage: say')
+    assert out[1] == ''
+    assert out[2] == 'Repeat what you tell me to.'
 
 def test_argparse_help_description(argparse_app):
     out = run_cmd(argparse_app, 'help tag')
+    assert out[0].startswith('usage: tag')
+    assert out[1] == ''
     assert out[2] == 'create a html tag'
 
 def test_argparse_prog(argparse_app):