Merge pull request #247 from python-cmd2/argparse

Argparse support

Author: tleonhardt

CHANGELOG.md

@@ -1,6 +1,12 @@
 ## 0.8.0 (TBD, 2018)
 * Bug Fixes
     * Fixed unit tests on Python 3.7 due to changes in how re.escape() behaves in Python 3.7
+* Enhancements
+    * Added new **with_argument_parser** decorator for argparse-based argument parsing of command arguments
+        * This replaces the old **options** decorator for optparse-based argument parsing
+            * The old decorator is still present for now, but should be considered *deprecated* and will eventually be removed
+        * See the **Argument Processing** section of the documentation for more information
+            * Alternatively, see the **argparse_example.py** example
 
 ## 0.7.9 (January 4, 2018)
 

cmd2.py

@@ -31,6 +31,7 @@
 import glob
 import io
 import optparse
+import argparse
 import os
 import platform
 import re
@@ -241,6 +242,40 @@ def strip_quotes(arg):
     return arg
 
 
+def with_argument_parser(argparser):
+    """A decorator to alter a cmd2 method to populate its ``opts``
+    argument by parsing arguments with the given instance of
+    argparse.ArgumentParser.
+    """
+    def arg_decorator(func):
+        def cmd_wrapper(instance, arg):
+            # Use shlex to split the command line into a list of arguments based on shell rules
+            lexed_arglist = shlex.split(arg, posix=POSIX_SHLEX)
+            # If not using POSIX shlex, make sure to strip off outer quotes for convenience
+            if not POSIX_SHLEX and STRIP_QUOTES_FOR_NON_POSIX:
+                temp_arglist = []
+                for arg in lexed_arglist:
+                    temp_arglist.append(strip_quotes(arg))
+                lexed_arglist = temp_arglist
+            opts = argparser.parse_args(lexed_arglist)
+            func(instance, arg, opts)
+
+        # argparser defaults the program name to sys.argv[0]
+        # we want it to be the name of our command
+        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())
+        return cmd_wrapper
+    return arg_decorator
+
+
 def options(option_list, arg_desc="arg"):
     """Used as a decorator and passed a list of optparse-style options,
        alters a cmd2 method to populate its ``opts`` argument from its

docs/argument_processing.rst

@@ -0,0 +1,175 @@
+===================
+Argument Processing
+===================
+
+``cmd2`` makes it easy to add sophisticated argument processing to your commands using the ``argparse`` python module. ``cmd2`` handles the following for you:
+
+1. Parsing input and quoted strings like the Unix shell
+2. Parse the resulting argument list using an instance of ``argparse.ArgumentParser`` that you provide
+3. Passes the resulting ``argparse.Namespace`` object to your command function
+4. Adds the usage message from the argument parser to your command.
+5. Checks if the ``-h/--help`` option is present, and if so, display the help message for the command
+
+These features are all provided by the ``@with_argument_parser`` decorator.
+
+Using the decorator
+===================
+
+For each command in the ``cmd2`` subclass which requires argument parsing,
+create an instance of ``argparse.ArgumentParser()`` which can parse the
+input appropriately for the command. Then decorate the command method with
+the ``@with_argument_parser`` decorator, passing the argument parser as the
+first parameter to the decorator. Add a third variable to the command method, which will contain the results of ``ArgumentParser.parse_args()``.
+
+Here's what it looks like::
+
+      argparser = argparse.ArgumentParser()
+      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('word', nargs='?', help='word to say')
+
+      @with_argument_parser(argparser)
+      def do_speak(self, argv, opts)
+         """Repeats what you tell me to."""
+         arg = opts.word
+         if opts.piglatin:
+            arg = '%s%say' % (arg[1:], arg[0])
+         if opts.shout:
+            arg = arg.upper()
+         repetitions = opts.repeat or 1
+         for i in range(min(repetitions, self.maxrepeats)):
+            self.poutput(arg)
+
+.. note::
+
+   The ``@with_argument_parser`` decorator sets the ``prog`` variable in
+   the argument parser based on the name of the method it is decorating.
+   This will override anything you specify in ``prog`` variable when
+   creating the argument parser.
+
+
+Help Messages
+=============
+
+By default, cmd2 uses the docstring of the command method when a user asks
+for help on the command. When you use the ``@with_argument_parser``
+decorator, the formatted help from the ``argparse.ArgumentParser`` is
+appended to the docstring for the method of that command. With this code::
+
+   argparser = argparse.ArgumentParser()
+   argparser.add_argument('tag', nargs=1, help='tag')
+   argparser.add_argument('content', nargs='+', help='content to surround with tag')
+   @with_argument_parser(argparser)
+   def do_tag(self, cmdline, args=None):
+      """create a html tag"""
+      self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
+      self.stdout.write('\n')
+
+The ``help tag`` command displays:
+
+.. code-block:: none
+
+   create a html tag
+   usage: tag [-h] tag content [content ...]
+
+   positional arguments:
+     tag         tag
+     content     content to surround with tag
+
+   optional arguments:
+     -h, --help  show this help message and exit
+
+   
+If you would prefer the short description of your command to come after the usage message, leave the docstring on your method empty, but supply a ``description`` variable to the argument parser::
+
+   argparser = argparse.ArgumentParser(description='create an html tag')
+   argparser.add_argument('tag', nargs=1, help='tag')
+   argparser.add_argument('content', nargs='+', help='content to surround with tag')
+   @with_argument_parser(argparser)
+   def do_tag(self, cmdline, args=None):
+      self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
+      self.stdout.write('\n')
+
+Now when the user enters ``help tag`` they see:
+
+.. code-block:: none
+
+   usage: tag [-h] tag content [content ...]
+
+   create an html tag
+
+   positional arguments:
+     tag         tag
+     content     content to surround with tag
+
+   optional arguments:
+     -h, --help  show this help message and exit
+
+
+To add additional text to the end of the generated help message, use the ``epilog`` variable::
+
+   argparser = argparse.ArgumentParser(
+      description='create an html tag',
+      epilog='This command can not generate tags with no content, like <br/>.'
+   )
+   argparser.add_argument('tag', nargs=1, help='tag')
+   argparser.add_argument('content', nargs='+', help='content to surround with tag')
+   @with_argument_parser(argparser)
+   def do_tag(self, cmdline, args=None):
+      self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
+      self.stdout.write('\n')
+
+Which yields:
+
+.. code-block:: none
+
+   usage: tag [-h] tag content [content ...]
+
+   create an html tag
+
+   positional arguments:
+     tag         tag
+     content     content to surround with tag
+
+   optional arguments:
+     -h, --help  show this help message and exit
+
+   This command can not generate tags with no content, like <br/>
+
+
+Deprecated optparse support
+===========================
+
+The ``optparse`` library has been deprecated since Python 2.7 (released on July
+3rd 2010) and Python 3.2 (released on February 20th, 2011). ``optparse`` is
+still included in the python standard library, but the documentation
+recommends using ``argparse`` instead.
+
+``cmd2`` includes a decorator which can parse arguments using ``optparse``. This decorator is deprecated just like the ``optparse`` library.
+
+Here's an example::
+
+   opts = [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")]
+
+   @options(opts, arg_desc='(text to say)')
+   def do_speak(self, arg, opts=None):
+     """Repeats what you tell me to."""
+     arg = ''.join(arg)
+     if opts.piglatin:
+         arg = '%s%say' % (arg[1:], arg[0])
+     if opts.shout:
+         arg = arg.upper()
+     repetitions = opts.repeat or 1
+     for i in range(min(repetitions, self.maxrepeats)):
+         self.poutput(arg)
+
+
+The optparse decorator performs the following key functions for you:
+
+1. Use `shlex` to split the arguments entered by the user.
+2. Parse the arguments using the given optparse options.
+3. Replace the `__doc__` string of the decorated function (i.e. do_speak) with the help string generated by optparse.
+4. Call the decorated function (i.e. do_speak) passing an additional parameter which contains the parsed options.

docs/index.rst

@@ -65,6 +65,7 @@ Contents:
    settingchanges
    unfreefeatures
    transcript
+   argument_processing
    integrating
    hooks
    alternatives

examples/argparse_example.py

@@ -1,19 +1,20 @@
 #!/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
 
-from cmd2 import Cmd, make_option, options
+from cmd2 import Cmd, make_option, options, with_argument_parser
 
 
 class CmdLineApp(Cmd):
@@ -39,28 +40,66 @@ 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
 
+
+    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_speak(self, argv, args=None):
+        """Repeats what you tell me to."""
+        words = []
+        for word in args.words:
+            if args.piglatin:
+                word = '%s%say' % (word[1:], word[0])
+            if args.shout:
+                word = word.upper()
+            words.append(word)
+        repetitions = args.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(description='create a html tag')
+    argparser.add_argument('tag', nargs=1, help='tag')
+    argparser.add_argument('content', nargs='+', help='content to surround with tag')
+    @with_argument_parser(argparser)
+    def do_tag(self, argv, args=None):
+        self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
+        self.stdout.write('\n')
+        # 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_speak(self, arg, opts=None):
+    def do_deprecated_speak(self, arg, opts=None):
         """Repeats what you tell me to."""
-        arg = ''.join(arg)
-        if opts.piglatin:
-            arg = '%s%say' % (arg[1:], arg[0])
-        if opts.shout:
-            arg = arg.upper()
+        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(arg)
+            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
-
-
 if __name__ == '__main__':
     # You can do your custom Argparse parsing here to meet your application's needs
     parser = argparse.ArgumentParser(description='Process the arguments however you like.')