cmd2.decorators

Decorators for cmd2 commands

cmd2.decorators.ArgListCommandFunc = typing.Union[typing.Callable[[ForwardRef('cmd2.Cmd'), typing.List[str]], typing.Union[bool, NoneType]], typing.Callable[[cmd2.command_definition.CommandSet, typing.List[str]], typing.Union[bool, NoneType]], typing.Callable[[ForwardRef('cmd2.Cmd'), typing.List[str]], bool], typing.Callable[[cmd2.command_definition.CommandSet, typing.List[str]], bool], typing.Callable[[ForwardRef('cmd2.Cmd'), typing.List[str]], NoneType], typing.Callable[[cmd2.command_definition.CommandSet, typing.List[str]], NoneType]]

Aggregate of all accepted function signatures for Command Functions that accept a pre-processed argument list

cmd2.decorators.ArgListCommandFuncBoolReturn = typing.Union[typing.Callable[[ForwardRef('cmd2.Cmd'), typing.List[str]], bool], typing.Callable[[cmd2.command_definition.CommandSet, typing.List[str]], bool]]

Function signature for an Command Function that accepts a pre-processed argument list from user input and returns a boolean

cmd2.decorators.ArgListCommandFuncNoneReturn = typing.Union[typing.Callable[[ForwardRef('cmd2.Cmd'), typing.List[str]], NoneType], typing.Callable[[cmd2.command_definition.CommandSet, typing.List[str]], NoneType]]

Function signature for an Command Function that accepts a pre-processed argument list from user input and returns Nothing

cmd2.decorators.ArgListCommandFuncOptionalBoolReturn = typing.Union[typing.Callable[[ForwardRef('cmd2.Cmd'), typing.List[str]], typing.Union[bool, NoneType]], typing.Callable[[cmd2.command_definition.CommandSet, typing.List[str]], typing.Union[bool, NoneType]]]

Function signature for an Command Function that accepts a pre-processed argument list from user input and optionally returns a boolean

cmd2.decorators.ArgparseCommandFunc = typing.Union[typing.Callable[[ForwardRef('cmd2.Cmd'), argparse.Namespace], typing.Union[bool, NoneType]], typing.Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], typing.Union[bool, NoneType]], typing.Callable[[ForwardRef('cmd2.Cmd'), argparse.Namespace], bool], typing.Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], bool], typing.Callable[[ForwardRef('cmd2.Cmd'), argparse.Namespace], NoneType], typing.Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], NoneType]]

Aggregate of all accepted function signatures for an argparse Command Function

cmd2.decorators.ArgparseCommandFuncBoolReturn = typing.Union[typing.Callable[[ForwardRef('cmd2.Cmd'), argparse.Namespace], bool], typing.Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], bool]]

Function signature for a Command Function that uses an argparse.ArgumentParser to process user input and returns a boolean

cmd2.decorators.ArgparseCommandFuncNoneReturn = typing.Union[typing.Callable[[ForwardRef('cmd2.Cmd'), argparse.Namespace], NoneType], typing.Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], NoneType]]

Function signature for an Command Function that uses an argparse.ArgumentParser to process user input and returns nothing

cmd2.decorators.ArgparseCommandFuncOptionalBoolReturn = typing.Union[typing.Callable[[ForwardRef('cmd2.Cmd'), argparse.Namespace], typing.Union[bool, NoneType]], typing.Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], typing.Union[bool, NoneType]]]

Function signature for a Command Function that uses an argparse.ArgumentParser to process user input and optionally returns a boolean

cmd2.decorators.as_subcommand_to(command: str, subcommand: str, parser: argparse.ArgumentParser, *, help: Optional[str] = None, aliases: Optional[List[str]] = None) → Callable[[Union[Callable[[cmd2.Cmd, argparse.Namespace], Optional[bool]], Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], Optional[bool]], Callable[[cmd2.Cmd, argparse.Namespace], bool], Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], bool], Callable[[cmd2.Cmd, argparse.Namespace], None], Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], None]]], Union[Callable[[cmd2.Cmd, argparse.Namespace], Optional[bool]], Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], Optional[bool]], Callable[[cmd2.Cmd, argparse.Namespace], bool], Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], bool], Callable[[cmd2.Cmd, argparse.Namespace], None], Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], None]]]

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 – Help message for this subcommand which displays in the list of subcommands of the command we are adding to. This is passed as the help argument to ArgumentParser.add_subparser().
  • aliases – Alternative names for this subcommand. This is passed as the alias argument to ArgumentParser.add_subparser().
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[[Union[Callable[[cmd2.Cmd, argparse.Namespace], Optional[bool]], Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], Optional[bool]], Callable[[cmd2.Cmd, argparse.Namespace], bool], Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], bool], Callable[[cmd2.Cmd, argparse.Namespace], None], Callable[[cmd2.command_definition.CommandSet, argparse.Namespace], None]]], Callable[[Union[cmd2.command_definition.CommandSet, cmd2.Cmd], Union[cmd2.parsing.Statement, str]], 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 or cmd2.CommandSet 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 argparse-parsed args in a Namespace A cmd2.argparse_custom.Cmd2AttributeWrapper called cmd2_statement is included in the Namespace to provide access to the cmd2.Statement object that was created when parsing the command line. This can be useful if the command function needs to know the command line.
Example: 
>>> 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')
>>> 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(f'args: {args!r}')
Example with unknown args:
  
>>> 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')
>>>
>>> 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(f'args: {args!r}')
>>>         self.poutput(f'unknowns: {unknown}')
cmd2.decorators.with_argument_list(func_arg: Union[Callable[[cmd2.Cmd, List[str]], Optional[bool]], Callable[[cmd2.command_definition.CommandSet, List[str]], Optional[bool]], Callable[[cmd2.Cmd, List[str]], bool], Callable[[cmd2.command_definition.CommandSet, List[str]], bool], Callable[[cmd2.Cmd, List[str]], None], Callable[[cmd2.command_definition.CommandSet, List[str]], None], None] = None, *, preserve_quotes: bool = False) → Union[Callable[[Union[cmd2.command_definition.CommandSet, cmd2.Cmd], Union[cmd2.parsing.Statement, str]], Optional[bool]], Callable[[Union[Callable[[cmd2.Cmd, List[str]], Optional[bool]], Callable[[cmd2.command_definition.CommandSet, List[str]], Optional[bool]], Callable[[cmd2.Cmd, List[str]], bool], Callable[[cmd2.command_definition.CommandSet, List[str]], bool], Callable[[cmd2.Cmd, List[str]], None], Callable[[cmd2.command_definition.CommandSet, List[str]], None]]], Callable[[Union[cmd2.command_definition.CommandSet, cmd2.Cmd], Union[cmd2.parsing.Statement, str]], 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:
  • func_arg – 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[[Callable[[...], Optional[bool]]], Callable[[...], Optional[bool]]]

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()