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 theNamespace
to provide command functions access to thecmd2.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)
- args – Single-element positional argument list containing
-
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()