Properly set docstring so it contains help message

Author: kotfu

cmd2.py

@@ -258,8 +258,16 @@ def cmd_wrapper(instance, arg):
                     temp_arglist.append(strip_quotes(arg))
                 lexed_arglist = temp_arglist
             opts = argparser.parse_args(lexed_arglist)
-
             func(instance, arg, opts)
+
+        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())
         return cmd_wrapper
     return arg_decorator
 

examples/argparse_example.py

@@ -1,14 +1,15 @@
 #!/usr/bin/env python
 # coding=utf-8
-"""A sample application for cmd2 showing how to use Argparse to process command line arguments for your application.
-It parses command line arguments looking for known arguments, but then still passes any unknown arguments onto cmd2
-to treat them as arguments at invocation.
+"""A sample application for cmd2 showing how to use argparse to
+process command line arguments for your application.
 
-Thanks to cmd2's built-in transcript testing capability, it also serves as a test suite for argparse_example.py when
-used with the exampleSession.txt transcript.
+Thanks to cmd2's built-in transcript testing capability, it also
+serves as a test suite for argparse_example.py when used with the
+exampleSession.txt transcript.
 
-Running `python argparse_example.py -t exampleSession.txt` will run all the commands in the transcript against
-argparse_example.py, verifying that the output produced matches the transcript.
+Running `python argparse_example.py -t exampleSession.txt` will run
+all the commands in the transcript against argparse_example.py,
+verifying that the output produced matches the transcript.
 """
 import argparse
 import sys
@@ -39,40 +40,14 @@ def __init__(self, ip_addr=None, port=None, transcript_files=None):
         # Setting this true makes it run a shell command if a cmd2/cmd command doesn't exist
         # self.default_to_shell = True
 
-    @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
-              make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
-              make_option('-r', '--repeat', type="int", help="output [n] times")
-              ])
-    def do_speak(self, arg, opts=None):
-        """Repeats what you tell me to."""
-        words = []
-        for word in arg:
-            if opts.piglatin:
-                word = '%s%say' % (word[1:], word[0])
-            if opts.shout:
-                arg = arg.upper()
-            words.append(word)
-        repetitions = opts.repeat or 1
-        for i in range(min(repetitions, self.maxrepeats)):
-            self.stdout.write(' '.join(words))
-            self.stdout.write('\n')
-            # self.stdout.write is better than "print", because Cmd can be
-            # initialized with a non-standard output destination
 
-    do_say = do_speak  # now "say" is a synonym for "speak"
-    do_orate = do_speak  # another synonym, but this one takes multi-line input
-
-
-    argparser = argparse.ArgumentParser(
-      prog='sspeak',
-      description='Repeats what you tell me to'
-    )
+    argparser = argparse.ArgumentParser(prog='speak')
     argparser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     argparser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     argparser.add_argument('-r', '--repeat', type=int, help='output [n] times')
     argparser.add_argument('words', nargs='+', help='words to say')
     @with_argument_parser(argparser)
-    def do_sspeak(self, rawarg, args=None):
+    def do_speak(self, rawarg, args=None):
         """Repeats what you tell me to."""
         words = []
         for word in args.words:
@@ -88,10 +63,13 @@ def do_sspeak(self, rawarg, args=None):
             # self.stdout.write is better than "print", because Cmd can be
             # initialized with a non-standard output destination
 
+    do_say = do_speak  # now "say" is a synonym for "speak"
+    do_orate = do_speak  # another synonym, but this one takes multi-line input
+
 
     argparser = argparse.ArgumentParser(
       prog='tag',
-      description='create an html tag, the first argument is the tag, the rest is the contents'
+      description='create a html tag',
     )
     argparser.add_argument('tag', nargs=1, help='tag')
     argparser.add_argument('content', nargs='+', help='content to surround with tag')
@@ -102,6 +80,28 @@ def do_tag(self, cmdline, args=None):
         # self.stdout.write is better than "print", because Cmd can be
         # initialized with a non-standard output destination
 
+    # @options uses the python optparse module which has been deprecated
+    # since 2011. Use @with_argument_parser instead, which utilizes the
+    # python argparse module
+    @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
+              make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
+              make_option('-r', '--repeat', type="int", help="output [n] times")
+              ])
+    def do_deprecated_speak(self, arg, opts=None):
+        """Repeats what you tell me to."""
+        words = []
+        for word in arg:
+            if opts.piglatin:
+                word = '%s%say' % (word[1:], word[0])
+            if opts.shout:
+                arg = arg.upper()
+            words.append(word)
+        repetitions = opts.repeat or 1
+        for i in range(min(repetitions, self.maxrepeats)):
+            self.stdout.write(' '.join(words))
+            self.stdout.write('\n')
+            # self.stdout.write is better than "print", because Cmd can be
+            # initialized with a non-standard output destination
 
 if __name__ == '__main__':
     # You can do your custom Argparse parsing here to meet your application's needs

tests/test_argparse.py

@@ -15,14 +15,14 @@ def __init__(self):
 
     argparser = argparse.ArgumentParser(
       prog='say',
-      description='Repeats what you tell me to'
     )
     argparser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     argparser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     argparser.add_argument('-r', '--repeat', type=int, help='output [n] times')
     argparser.add_argument('words', nargs='+', help='words to say')
     @cmd2.with_argument_parser(argparser)
     def do_say(self, cmdline, args=None):
+        """Repeat what you tell me to."""
         words = []
         for word in args.words:
             if word is None:
@@ -39,7 +39,7 @@ def do_say(self, cmdline, args=None):
 
     argparser = argparse.ArgumentParser(
       prog='tag',
-      description='create an html tag, the first argument is the tag, the rest is the contents'
+      description='create a html tag'
     )
     argparser.add_argument('tag', nargs=1, help='tag')
     argparser.add_argument('content', nargs='+', help='content to surround with tag')
@@ -80,3 +80,11 @@ def test_argparse_quoted_arguments_posix_multiple(argparse_app):
     argparse_app.POSIX = True
     out = run_cmd(argparse_app, 'tag strong this "should  be" loud')
     assert out == ['<strong>this should  be loud</strong>']
+
+def test_argparse_help_docstring(argparse_app):
+    out = run_cmd(argparse_app, 'help say')
+    assert out[0] == 'Repeat what you tell me to.'
+
+def test_argparse_help_description(argparse_app):
+    out = run_cmd(argparse_app, 'help tag')
+    assert out[2] == 'create a html tag'