cmd2.decorators

Decorators for cmd2 commands

cmd2.decorators.with_category(category: str) → Callable[[Callable[[...], bool | None]], Callable[[...], bool | None]]

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

cmd2.decorators.ArgListCommandFuncOptionalBoolReturn

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

alias of Callable[[CommandParent, List[str]], bool | None]

cmd2.decorators.ArgListCommandFuncBoolReturn

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

alias of Callable[[CommandParent, List[str]], bool]

cmd2.decorators.ArgListCommandFuncNoneReturn

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

alias of Callable[[CommandParent, List[str]], None]

cmd2.decorators.ArgListCommandFunc

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

alias of Callable[[CommandParent, List[str]], bool | None] | Callable[[CommandParent, List[str]], bool] | Callable[[CommandParent, List[str]], None]

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 doi_* 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.ArgparseCommandFuncOptionalBoolReturn

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

alias of Callable[[CommandParent, Namespace], bool | None]

cmd2.decorators.ArgparseCommandFuncBoolReturn

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

alias of Callable[[CommandParent, Namespace], bool]

cmd2.decorators.ArgparseCommandFuncNoneReturn

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

alias of Callable[[CommandParent, Namespace], None]

cmd2.decorators.ArgparseCommandFunc

Aggregate of all accepted function signatures for an argparse Command Function

alias of Callable[[CommandParent, Namespace], bool | None] | Callable[[CommandParent, Namespace], bool] | Callable[[CommandParent, Namespace], None]

cmd2.decorators.with_argparser(parser: ArgumentParser | Callable[[], ArgumentParser] | Callable[[CommandParentType], ArgumentParser], *, ns_provider: Callable[[...], Namespace] | None = None, preserve_quotes: bool = False, with_unknown_args: bool = False) → Callable[[Callable[[CommandParent, Namespace], bool | None] | Callable[[CommandParent, Namespace], bool] | Callable[[CommandParent, Namespace], None]], Callable[[CommandParent, Statement | str], bool | None]]

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 or a callable that returns an 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.as_subcommand_to(command: str, subcommand: str, parser: ArgumentParser | Callable[[], ArgumentParser] | Callable[[CommandParentType], ArgumentParser], *, help: str | None = None, aliases: List[str] | None = None) → Callable[[Callable[[CommandParent, Namespace], bool | None] | Callable[[CommandParent, Namespace], bool] | Callable[[CommandParent, Namespace], None]], Callable[[CommandParent, Namespace], bool | None] | Callable[[CommandParent, Namespace], bool] | Callable[[CommandParent, 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 subparsers.add_parser().
aliases – Alternative names for this subcommand. This is passed as the alias argument to subparsers.add_parser().

Returns:

Wrapper function that can receive an argparse.Namespace