cmd2.decorators

Decorators for cmd2 commands

cmd2.decorators.as_subcommand_to(command: str, subcommand: str, parser: argparse.ArgumentParser, *, help_text: Optional[str] = None, aliases: Iterable[str] = None) → Callable[[argparse.Namespace], Optional[bool]]

Tag this method as a subcommand to an existing argparse decorated command.

Parameters:
  • command – Command Name. Space-delimited subcommands may optionally be specified
  • subcommand – Subcommand name
  • parser – argparse Parser for this subcommand
  • help_text – Help message for this subcommand
  • aliases – Alternative names for this subcommand
Returns:

Wrapper function that can receive an argparse.Namespace
cmd2.decorators.with_argparser(parser: argparse.ArgumentParser, *, ns_provider: Optional[Callable[[...], argparse.Namespace]] = None, preserve_quotes: bool = False, with_unknown_args: 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
  • with_unknown_args – if true, then capture unknown args
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))
Example with unknown args:
  
>>> 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(parser, with_unknown_args=True)
>>>     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_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]]

Deprecated decorator. Use with_argparser(parser, with_unknown_args=True) instead.

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(parser, with_unknown_args=True)
>>>     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()