Updated all examples to use Cmd2ArgumentParser instead of argparse.ArgumentParser.

This is best practice for consistency of appearance between built-in and custom commands.

Author: kmvanbrunt

README.md

@@ -130,10 +130,9 @@ Instructions for implementing each feature follow.
       - Optionally, `cmd2.with_argparser(.., with_unknown_args=True)` can be used to pass all unknown arguments as a list
 
     ```Python
-    import argparse
-    from cmd2 import with_argparser
+    from cmd2 import Cmd2ArgumentParser, with_argparser
 
-    argparser = argparse.ArgumentParser()
+    argparser = Cmd2ArgumentParser()
     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('words', nargs='+', help='words to say')
@@ -232,7 +231,6 @@ Example cmd2 application (**examples/example.py**):
 """
 A sample application for cmd2.
 """
-import argparse
 import random
 import sys
 import cmd2
@@ -256,7 +254,7 @@ class CmdLineApp(cmd2.Cmd):
         # Make maxrepeats settable at runtime
         self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
-    speak_parser = argparse.ArgumentParser()
+    speak_parser = cmd2.Cmd2ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
@@ -280,7 +278,7 @@ class CmdLineApp(cmd2.Cmd):
     do_say = do_speak  # now "say" is a synonym for "speak"
     do_orate = do_speak  # another synonym, but this one takes multi-line input
 
-    mumble_parser = argparse.ArgumentParser()
+    mumble_parser = cmd2.Cmd2ArgumentParser()
     mumble_parser.add_argument('-r', '--repeat', type=int, help='how many times to repeat')
     mumble_parser.add_argument('words', nargs='+', help='words to say')
 

cmd2/decorators.py

@@ -288,7 +288,7 @@ def with_argparser(
 
     :Example:
 
-    >>> parser = argparse.ArgumentParser()
+    >>> parser = cmd2.Cmd2ArgumentParser()
     >>> parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     >>> parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     >>> parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
@@ -302,7 +302,7 @@ def with_argparser(
 
     :Example with unknown args:
 
-    >>> parser = argparse.ArgumentParser()
+    >>> parser = cmd2.Cmd2ArgumentParser()
     >>> parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     >>> parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     >>> parser.add_argument('-r', '--repeat', type=int, help='output [n] times')

docs/examples/first_app.rst

@@ -96,7 +96,7 @@ can shout and talk piglatin. We will also use some built in methods for
 this code to ``first_app.py``, so that the ``speak_parser`` attribute and the
 ``do_speak()`` method are part of the ``CmdLineApp()`` class::
 
-    speak_parser = argparse.ArgumentParser()
+    speak_parser = cmd2.Cmd2ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')

docs/features/argument_processing.rst

@@ -55,10 +55,9 @@ method, which will contain the results of ``ArgumentParser.parse_args()``.
 
 Here's what it looks like::
 
-      import argparse
-      from cmd2 import with_argparser
+      from cmd2 import Cmd2ArgumentParser, with_argparser
 
-      argparser = argparse.ArgumentParser()
+      argparser = Cmd2ArgumentParser()
       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')
@@ -106,10 +105,9 @@ docstring for the ``do_*`` method is used to set the description for the
 
 With this code::
 
-   import argparse
-   from cmd2 import with_argparser
+   from cmd2 import Cmd2ArgumentParser, with_argparser
 
-   argparser = argparse.ArgumentParser()
+   argparser = Cmd2ArgumentParser()
    argparser.add_argument('tag', help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argparser(argparser)
@@ -137,10 +135,9 @@ the ``help tag`` command displays:
 If you would prefer you can set the ``description`` while instantiating the
 ``argparse.ArgumentParser`` and leave the docstring on your method empty::
 
-   import argparse
-   from cmd2 import with_argparser
+   from cmd2 import Cmd2ArgumentParser, with_argparser
 
-   argparser = argparse.ArgumentParser(description='create an html tag')
+   argparser = Cmd2ArgumentParser(description='create an html tag')
    argparser.add_argument('tag', help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argparser(argparser)
@@ -166,11 +163,10 @@ Now when the user enters ``help tag`` they see:
 
 To add additional text to the end of the generated help message, use the ``epilog`` variable::
 
-   import argparse
-   from cmd2 import with_argparser
+   from cmd2 import Cmd2ArgumentParser, with_argparser
 
-   argparser = argparse.ArgumentParser(description='create an html tag',
-                                       epilog='This command cannot generate tags with no content, like <br/>.')
+   argparser = Cmd2ArgumentParser(description='create an html tag',
+                                  epilog='This command cannot generate tags with no content, like <br/>.')
    argparser.add_argument('tag', help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argparser(argparser)
@@ -265,10 +261,9 @@ strings, then decorate the command method with the
 
 Here's what it looks like::
 
-    import argparse
-    from cmd2 import with_argparser
+    from cmd2 import Cmd2ArgumentParser, with_argparser
 
-    dir_parser = argparse.ArgumentParser()
+    dir_parser = Cmd2ArgumentParser()
     dir_parser.add_argument('-l', '--long', action='store_true', help="display in long format with one item per line")
 
     @with_argparser(dir_parser, with_unknown_args=True)

examples/arg_decorators.py

@@ -42,7 +42,7 @@ def do_fsize(self, args: argparse.Namespace) -> None:
         self.poutput('{} {}'.format(size, args.unit))
 
     # do_pow parser
-    pow_parser = argparse.ArgumentParser()
+    pow_parser = cmd2.Cmd2ArgumentParser()
     pow_parser.add_argument('base', type=int)
     pow_parser.add_argument('exponent', type=int, choices=range(-5, 6))
 

examples/arg_print.py

@@ -9,7 +9,6 @@
 
 It also serves as an example of how to create shortcuts.
 """
-import argparse
 
 import cmd2
 
@@ -40,7 +39,7 @@ def do_rprint(self, arglist):
         """Print the argument list this basic command is called with (with quotes preserved)."""
         self.poutput('rprint was called with the following list of arguments: {!r}'.format(arglist))
 
-    oprint_parser = argparse.ArgumentParser()
+    oprint_parser = cmd2.Cmd2ArgumentParser()
     oprint_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     oprint_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     oprint_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
@@ -51,7 +50,7 @@ def do_oprint(self, args):
         """Print the options and argument list this options command was called with."""
         self.poutput('oprint was called with the following\n\toptions: {!r}'.format(args))
 
-    pprint_parser = argparse.ArgumentParser()
+    pprint_parser = cmd2.Cmd2ArgumentParser()
     pprint_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     pprint_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     pprint_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')

examples/cmd_as_argument.py

@@ -38,7 +38,7 @@ def __init__(self):
         # Make maxrepeats settable at runtime
         self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command', self))
 
-    speak_parser = argparse.ArgumentParser()
+    speak_parser = cmd2.Cmd2ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
@@ -62,7 +62,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
 
-    mumble_parser = argparse.ArgumentParser()
+    mumble_parser = cmd2.Cmd2ArgumentParser()
     mumble_parser.add_argument('-r', '--repeat', type=int, help='how many times to repeat')
     mumble_parser.add_argument('words', nargs='+', help='words to say')
 
@@ -86,7 +86,7 @@ def do_mumble(self, args):
 def main(argv=None):
     """Run when invoked from the operating system shell"""
 
-    parser = argparse.ArgumentParser(description='Commands as arguments')
+    parser = cmd2.Cmd2ArgumentParser(description='Commands as arguments')
     command_help = 'optional command to run, if no command given, enter an interactive shell'
     parser.add_argument('command', nargs='?', help=command_help)
     arg_help = 'optional arguments for command'

examples/colors.py

@@ -23,7 +23,6 @@
     poutput(), pfeedback(), and ppaged() never strip ANSI style sequences,
     regardless of the output destination
 """
-import argparse
 from typing import (
     Any,
 )
@@ -54,7 +53,7 @@ def __init__(self):
         # Should ANSI color output be allowed
         self.allow_style = ansi.STYLE_TERMINAL
 
-    speak_parser = argparse.ArgumentParser()
+    speak_parser = cmd2.Cmd2ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')

examples/decorator_example.py

@@ -37,7 +37,7 @@ 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
 
-    speak_parser = argparse.ArgumentParser()
+    speak_parser = cmd2.Cmd2ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
@@ -60,7 +60,7 @@ def do_speak(self, args: argparse.Namespace):
     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()
+    tag_parser = cmd2.Cmd2ArgumentParser()
     tag_parser.add_argument('tag', help='tag')
     tag_parser.add_argument('content', nargs='+', help='content to surround with tag')
 
@@ -89,7 +89,7 @@ def do_tagg(self, arglist: List[str]):
     import sys
 
     # You can do your custom Argparse parsing here to meet your application's needs
-    parser = argparse.ArgumentParser(description='Process the arguments however you like.')
+    parser = cmd2.Cmd2ArgumentParser(description='Process the arguments however you like.')
 
     # Add a few arguments which aren't really used, but just to get the gist
     parser.add_argument('-p', '--port', type=int, help='TCP port')

examples/example.py

@@ -10,7 +10,6 @@
 the transcript against example.py, verifying that the output produced matches
 the transcript.
 """
-import argparse
 import random
 
 import cmd2
@@ -34,7 +33,7 @@ def __init__(self):
         self.maxrepeats = 3
         self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command', self))
 
-    speak_parser = argparse.ArgumentParser()
+    speak_parser = cmd2.Cmd2ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
@@ -58,7 +57,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
 
-    mumble_parser = argparse.ArgumentParser()
+    mumble_parser = cmd2.Cmd2ArgumentParser()
     mumble_parser.add_argument('-r', '--repeat', type=int, help='how many times to repeat')
     mumble_parser.add_argument('words', nargs='+', help='words to say')
 

examples/first_app.py

@@ -12,7 +12,6 @@
     * Multiline Commands
     * History
 """
-import argparse
 
 import cmd2
 
@@ -29,7 +28,7 @@ def __init__(self):
         self.maxrepeats = 3
         self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command', self))
 
-    speak_parser = argparse.ArgumentParser()
+    speak_parser = cmd2.Cmd2ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')

examples/pirate.py

@@ -6,7 +6,6 @@
 
 It demonstrates many features of cmd2.
 """
-import argparse
 
 import cmd2
 import cmd2.ansi
@@ -75,7 +74,7 @@ def do_sing(self, arg):
         """Sing a colorful song."""
         self.poutput(cmd2.ansi.style(arg, fg=self.songcolor))
 
-    yo_parser = argparse.ArgumentParser()
+    yo_parser = cmd2.Cmd2ArgumentParser()
     yo_parser.add_argument('--ho', type=int, default=2, help="How often to chant 'ho'")
     yo_parser.add_argument('-c', '--commas', action='store_true', help='Intersperse commas')
     yo_parser.add_argument('beverage', help='beverage to drink with the chant')

examples/plumbum_colors.py

@@ -25,7 +25,6 @@
 
 WARNING: This example requires the plumbum package, which isn't normally required by cmd2.
 """
-import argparse
 
 from plumbum.colors import (
     bg,
@@ -88,7 +87,7 @@ def __init__(self):
         # Should ANSI color output be allowed
         self.allow_style = ansi.STYLE_TERMINAL
 
-    speak_parser = argparse.ArgumentParser()
+    speak_parser = cmd2.Cmd2ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')

examples/python_scripting.py

@@ -20,7 +20,6 @@
 This application and the "examples/scripts/conditional.py" script serve as an
 example for one way in which this can be done.
 """
-import argparse
 import os
 
 import cmd2
@@ -95,7 +94,7 @@ def complete_cd(self, text, line, begidx, endidx):
         # Tab complete only directories
         return self.path_complete(text, line, begidx, endidx, path_filter=os.path.isdir)
 
-    dir_parser = argparse.ArgumentParser()
+    dir_parser = cmd2.Cmd2ArgumentParser()
     dir_parser.add_argument('-l', '--long', action='store_true', help="display in long format with one item per line")
 
     @cmd2.with_argparser(dir_parser, with_unknown_args=True)

examples/subcommands.py

@@ -6,14 +6,13 @@
 This example shows an easy way for a single command to have many subcommands, each of which takes different arguments
 and provides separate contextual help.
 """
-import argparse
 
 import cmd2
 
 sport_item_strs = ['Bat', 'Basket', 'Basketball', 'Football', 'Space Ball']
 
 # create the top-level parser for the base command
-base_parser = argparse.ArgumentParser()
+base_parser = cmd2.Cmd2ArgumentParser()
 base_subparsers = base_parser.add_subparsers(title='subcommands', help='subcommand help')
 
 # create the parser for the "foo" subcommand
@@ -39,7 +38,7 @@
 
 # create the top-level parser for the alternate command
 # The alternate command doesn't provide its own help flag
-base2_parser = argparse.ArgumentParser(add_help=False)
+base2_parser = cmd2.Cmd2ArgumentParser(add_help=False)
 base2_subparsers = base2_parser.add_subparsers(title='subcommands', help='subcommand help')
 
 # create the parser for the "foo" subcommand