diff options
| -rw-r--r-- | cmd2/cmd2.py | 34 | ||||
| -rw-r--r-- | docs/argument_processing.rst | 17 |
2 files changed, 38 insertions, 13 deletions
diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index f8dd63d3..669c4a5a 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -173,11 +173,17 @@ def with_category(category: str) -> Callable: return cat_decorator -def with_argument_list(func: Callable, preserve_quotes: bool=False) -> Callable: - """A decorator to alter the arguments passed to a do_* cmd2 - 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 using shlex.split().""" +def with_argument_list(func: Callable[[Statement], Optional[bool]], + preserve_quotes: bool=False) -> Callable[[List], Optional[bool]]: + """A decorator to alter the arguments passed to a do_* cmd2 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 using + shlex.split(). + + :param func: do_* method this decorator is wrapping + :param preserve_quotes: if True, then arguments passed to arparse maintain their quotes + :return: function that gets passed a list of argument strings + """ + """""" import functools @functools.wraps(func) @@ -189,18 +195,19 @@ def with_argument_list(func: Callable, preserve_quotes: bool=False) -> Callable: return cmd_wrapper -def with_argparser_and_unknown_args(argparser: argparse.ArgumentParser, preserve_quotes: bool=False) -> Callable: +def with_argparser_and_unknown_args(argparser: argparse.ArgumentParser, preserve_quotes: bool=False) -> \ + Callable[[argparse.Namespace, List], 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. :param argparser: unique instance of ArgumentParser - :param preserve_quotes: if True, then the arguments passed to arparse be maintain their quotes - :return: function that gets passed parsed args and a list of unknown args + :param preserve_quotes: if True, then arguments passed to arparse maintain their quotes + :return: function that gets passed argparse-parsed args and a list of unknown argument strings """ import functools # noinspection PyProtectedMember - def arg_decorator(func: Callable): + def arg_decorator(func: Callable[[Statement], Optional[bool]]): @functools.wraps(func) def cmd_wrapper(instance, cmdline): lexed_arglist = parse_quoted_string(cmdline, preserve_quotes) @@ -230,18 +237,19 @@ def with_argparser_and_unknown_args(argparser: argparse.ArgumentParser, preserve return arg_decorator -def with_argparser(argparser: argparse.ArgumentParser, preserve_quotes: bool=False) -> Callable: +def with_argparser(argparser: argparse.ArgumentParser, + 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. :param argparser: unique instance of ArgumentParser - :param preserve_quotes: if True, then the arguments passed to arparse be maintain their quotes - :return: function that gets passed parsed args + :param preserve_quotes: if True, then arguments passed to arparse maintain their quotes + :return: function that gets passed the argparse-parsed args """ import functools # noinspection PyProtectedMember - def arg_decorator(func: Callable): + def arg_decorator(func: Callable[[Statement], Optional[bool]]): @functools.wraps(func) def cmd_wrapper(instance, cmdline): lexed_arglist = parse_quoted_string(cmdline, preserve_quotes) diff --git a/docs/argument_processing.rst b/docs/argument_processing.rst index 8931c60b..7e8d8f3e 100644 --- a/docs/argument_processing.rst +++ b/docs/argument_processing.rst @@ -21,6 +21,20 @@ processing decorators in your ``cmd2`` applications. .. _argprint: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py .. _decorator: https://github.com/python-cmd2/cmd2/blob/master/examples/decorator_example.py + +Decorators provided by cmd2 for argument processing +=================================================== +``cmd2`` provides the following decorators for assisting with parsing arguments passed to commands: + +.. automethod:: cmd2.cmd2.with_argument_list +.. automethod:: cmd2.cmd2.with_argparser +.. automethod:: cmd2.cmd2.with_argparser_and_unknown_args + +All of these decorators accept an optional **preserve_quotes** argument which defaults to ``False``. +Setting this argument to ``True`` is useful for cases where you are passing the arguments to another +command which might have its own argument parsing. + + Using the argument parser decorator =================================== @@ -402,3 +416,6 @@ See the subcommands_ and tab_autocompletion_ example to learn more about how to .. _subcommands: https://github.com/python-cmd2/cmd2/blob/master/examples/subcommands.py .. _tab_autocompletion: https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py + + + |