cmd2.decorators

Decorators for cmd2 commands

cmd2.decorators.with_argparser(parser: argparse.ArgumentParser, *, ns_provider: Optional[Callable[[...], argparse.Namespace]] = None, preserve_quotes: bool = False) → Callable[[argparse.Namespace], Optional[bool]]

A decorator to alter a cmd2 method to populate its args argument by parsing arguments with the given instance of argparse.ArgumentParser.

Parameters:
  • parser – unique instance of ArgumentParser
  • ns_provider – An optional function that accepts a cmd2.Cmd object as an argument and returns an argparse.Namespace. This is useful if the Namespace needs to be prepopulated with state data that affects parsing.
  • preserve_quotes – if True, then arguments passed to argparse maintain their quotes
Returns:

function that gets passed the argparse-parsed args in a Namespace A member called __statement__ is added to the Namespace to provide command functions access to the Statement object. This can be useful if the command function needs to know the command line.
Example: 
>>> parser = argparse.ArgumentParser()
>>> 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')
>>> parser.add_argument('words', nargs='+', help='words to print')
>>>
>>> class MyApp(cmd2.Cmd):
>>>     @cmd2.with_argparser(parser, preserve_quotes=True)
>>>     def do_argprint(self, args):
>>>         "Print the options and argument list this options command was called with."
>>>         self.poutput('args: {!r}'.format(args))
cmd2.decorators.with_argparser_and_unknown_args(parser: argparse.ArgumentParser, *, ns_provider: Optional[Callable[[...], argparse.Namespace]] = None, preserve_quotes: bool = False) → Callable[[argparse.Namespace, List[T]], Optional[bool]]

A decorator to alter a cmd2 method to populate its args argument by parsing arguments with the given instance of argparse.ArgumentParser, but also returning unknown args as a list.

Parameters:
  • parser – unique instance of ArgumentParser
  • ns_provider – An optional function that accepts a cmd2.Cmd object as an argument and returns an argparse.Namespace. This is useful if the Namespace needs to be prepopulated with state data that affects parsing.
  • preserve_quotes – if True, then arguments passed to argparse maintain their quotes
Returns:

function that gets passed argparse-parsed args in a Namespace and a list of unknown argument strings. A member called __statement__ is added to the Namespace to provide command functions access to the cmd2.Statement object. This can be useful if the command function needs to know the command line.
Example: 
>>> parser = argparse.ArgumentParser()
>>> 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')
>>>
>>> class MyApp(cmd2.Cmd):
>>>     @cmd2.with_argparser_and_unknown_args(parser)
>>>     def do_argprint(self, args, unknown):
>>>         "Print the options and argument list this options command was called with."
>>>         self.poutput('args: {!r}'.format(args))
>>>         self.poutput('unknowns: {}'.format(unknown))
cmd2.decorators.with_argument_list(*args, preserve_quotes: bool = False) → Callable[[List[T]], Optional[bool]]

A decorator to alter the arguments passed to a do_* method. Default passes a string of whatever the user typed. With this decorator, the decorated method will receive a list of arguments parsed from user input.

Parameters:
  • args – Single-element positional argument list containing do_* method this decorator is wrapping
  • preserve_quotes – if True, then argument quotes will not be stripped
Returns:

function that gets passed a list of argument strings
Example: 
>>> class MyApp(cmd2.Cmd):
>>>     @cmd2.with_argument_list
>>>     def do_echo(self, arglist):
>>>         self.poutput(' '.join(arglist)
cmd2.decorators.with_category(category: str) → Callable

A decorator to apply a category to a do_* command method.

Parameters:category – the name of the category in which this command should be grouped when displaying the list of commands.
Example: 
>>> class MyApp(cmd2.Cmd):
>>>   @cmd2.with_category('Text Functions')
>>>   def do_echo(self, args)
>>>     self.poutput(args)

For an alternative approach to categorizing commands using a function, see categorize()