|
| 1 | +# coding=utf-8 |
| 2 | +"""Decorators for cmd2 commands""" |
| 3 | +import argparse |
| 4 | +from typing import Callable, Iterable, List, Optional, Union |
| 5 | + |
| 6 | +from . import constants |
| 7 | +from .parsing import Statement |
| 8 | + |
| 9 | + |
| 10 | +def categorize(func: Union[Callable, Iterable[Callable]], category: str) -> None: |
| 11 | + """Categorize a function. |
| 12 | +
|
| 13 | + The help command output will group this function under the specified category heading |
| 14 | +
|
| 15 | + :param func: function or list of functions to categorize |
| 16 | + :param category: category to put it in |
| 17 | + """ |
| 18 | + if isinstance(func, Iterable): |
| 19 | + for item in func: |
| 20 | + setattr(item, constants.CMD_ATTR_HELP_CATEGORY, category) |
| 21 | + else: |
| 22 | + setattr(func, constants.CMD_ATTR_HELP_CATEGORY, category) |
| 23 | + |
| 24 | + |
| 25 | +def with_category(category: str) -> Callable: |
| 26 | + """A decorator to apply a category to a command function.""" |
| 27 | + def cat_decorator(func): |
| 28 | + categorize(func, category) |
| 29 | + return func |
| 30 | + return cat_decorator |
| 31 | + |
| 32 | + |
| 33 | +def with_argument_list(*args: List[Callable], preserve_quotes: bool = False) -> Callable[[List], Optional[bool]]: |
| 34 | + """A decorator to alter the arguments passed to a do_* cmd2 method. Default passes a string of whatever the user |
| 35 | + typed. With this decorator, the decorated method will receive a list of arguments parsed from user input. |
| 36 | +
|
| 37 | + :param args: Single-element positional argument list containing do_* method this decorator is wrapping |
| 38 | + :param preserve_quotes: if True, then argument quotes will not be stripped |
| 39 | + :return: function that gets passed a list of argument strings |
| 40 | + """ |
| 41 | + import functools |
| 42 | + |
| 43 | + def arg_decorator(func: Callable): |
| 44 | + @functools.wraps(func) |
| 45 | + def cmd_wrapper(cmd2_app, statement: Union[Statement, str]): |
| 46 | + _, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(command_name, |
| 47 | + statement, |
| 48 | + preserve_quotes) |
| 49 | + |
| 50 | + return func(cmd2_app, parsed_arglist) |
| 51 | + |
| 52 | + command_name = func.__name__[len(constants.COMMAND_FUNC_PREFIX):] |
| 53 | + cmd_wrapper.__doc__ = func.__doc__ |
| 54 | + return cmd_wrapper |
| 55 | + |
| 56 | + if len(args) == 1 and callable(args[0]): |
| 57 | + # noinspection PyTypeChecker |
| 58 | + return arg_decorator(args[0]) |
| 59 | + else: |
| 60 | + # noinspection PyTypeChecker |
| 61 | + return arg_decorator |
| 62 | + |
| 63 | + |
| 64 | +# noinspection PyProtectedMember |
| 65 | +def set_parser_prog(parser: argparse.ArgumentParser, prog: str): |
| 66 | + """ |
| 67 | + Recursively set prog attribute of a parser and all of its subparsers so that the root command |
| 68 | + is a command name and not sys.argv[0]. |
| 69 | + :param parser: the parser being edited |
| 70 | + :param prog: value for the current parsers prog attribute |
| 71 | + """ |
| 72 | + # Set the prog value for this parser |
| 73 | + parser.prog = prog |
| 74 | + |
| 75 | + # Set the prog value for the parser's subcommands |
| 76 | + for action in parser._actions: |
| 77 | + if isinstance(action, argparse._SubParsersAction): |
| 78 | + |
| 79 | + # Set the prog value for each subcommand |
| 80 | + for sub_cmd, sub_cmd_parser in action.choices.items(): |
| 81 | + sub_cmd_prog = parser.prog + ' ' + sub_cmd |
| 82 | + set_parser_prog(sub_cmd_parser, sub_cmd_prog) |
| 83 | + |
| 84 | + # We can break since argparse only allows 1 group of subcommands per level |
| 85 | + break |
| 86 | + |
| 87 | + |
| 88 | +def with_argparser_and_unknown_args(parser: argparse.ArgumentParser, *, |
| 89 | + ns_provider: Optional[Callable[..., argparse.Namespace]] = None, |
| 90 | + preserve_quotes: bool = False) -> \ |
| 91 | + Callable[[argparse.Namespace, List], Optional[bool]]: |
| 92 | + """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing arguments with the given |
| 93 | + instance of argparse.ArgumentParser, but also returning unknown args as a list. |
| 94 | +
|
| 95 | + :param parser: unique instance of ArgumentParser |
| 96 | + :param ns_provider: An optional function that accepts a cmd2.Cmd object as an argument and returns an |
| 97 | + argparse.Namespace. This is useful if the Namespace needs to be prepopulated with |
| 98 | + state data that affects parsing. |
| 99 | + :param preserve_quotes: if True, then arguments passed to argparse maintain their quotes |
| 100 | + :return: function that gets passed argparse-parsed args in a Namespace and a list of unknown argument strings |
| 101 | + A member called __statement__ is added to the Namespace to provide command functions access to the |
| 102 | + Statement object. This can be useful if the command function needs to know the command line. |
| 103 | +
|
| 104 | + """ |
| 105 | + import functools |
| 106 | + |
| 107 | + def arg_decorator(func: Callable): |
| 108 | + @functools.wraps(func) |
| 109 | + def cmd_wrapper(cmd2_app, statement: Union[Statement, str]): |
| 110 | + statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(command_name, |
| 111 | + statement, |
| 112 | + preserve_quotes) |
| 113 | + |
| 114 | + if ns_provider is None: |
| 115 | + namespace = None |
| 116 | + else: |
| 117 | + namespace = ns_provider(cmd2_app) |
| 118 | + |
| 119 | + try: |
| 120 | + args, unknown = parser.parse_known_args(parsed_arglist, namespace) |
| 121 | + except SystemExit: |
| 122 | + return |
| 123 | + else: |
| 124 | + setattr(args, '__statement__', statement) |
| 125 | + return func(cmd2_app, args, unknown) |
| 126 | + |
| 127 | + # argparser defaults the program name to sys.argv[0], but we want it to be the name of our command |
| 128 | + command_name = func.__name__[len(constants.COMMAND_FUNC_PREFIX):] |
| 129 | + set_parser_prog(parser, command_name) |
| 130 | + |
| 131 | + # If the description has not been set, then use the method docstring if one exists |
| 132 | + if parser.description is None and func.__doc__: |
| 133 | + parser.description = func.__doc__ |
| 134 | + |
| 135 | + # Set the command's help text as argparser.description (which can be None) |
| 136 | + cmd_wrapper.__doc__ = parser.description |
| 137 | + |
| 138 | + # Set some custom attributes for this command |
| 139 | + setattr(cmd_wrapper, constants.CMD_ATTR_ARGPARSER, parser) |
| 140 | + setattr(cmd_wrapper, constants.CMD_ATTR_PRESERVE_QUOTES, preserve_quotes) |
| 141 | + |
| 142 | + return cmd_wrapper |
| 143 | + |
| 144 | + # noinspection PyTypeChecker |
| 145 | + return arg_decorator |
| 146 | + |
| 147 | + |
| 148 | +def with_argparser(parser: argparse.ArgumentParser, *, |
| 149 | + ns_provider: Optional[Callable[..., argparse.Namespace]] = None, |
| 150 | + preserve_quotes: bool = False) -> Callable[[argparse.Namespace], Optional[bool]]: |
| 151 | + """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing arguments |
| 152 | + with the given instance of argparse.ArgumentParser. |
| 153 | +
|
| 154 | + :param parser: unique instance of ArgumentParser |
| 155 | + :param ns_provider: An optional function that accepts a cmd2.Cmd object as an argument and returns an |
| 156 | + argparse.Namespace. This is useful if the Namespace needs to be prepopulated with |
| 157 | + state data that affects parsing. |
| 158 | + :param preserve_quotes: if True, then arguments passed to argparse maintain their quotes |
| 159 | + :return: function that gets passed the argparse-parsed args in a Namespace |
| 160 | + A member called __statement__ is added to the Namespace to provide command functions access to the |
| 161 | + Statement object. This can be useful if the command function needs to know the command line. |
| 162 | + """ |
| 163 | + import functools |
| 164 | + |
| 165 | + def arg_decorator(func: Callable): |
| 166 | + @functools.wraps(func) |
| 167 | + def cmd_wrapper(cmd2_app, statement: Union[Statement, str]): |
| 168 | + statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(command_name, |
| 169 | + statement, |
| 170 | + preserve_quotes) |
| 171 | + |
| 172 | + if ns_provider is None: |
| 173 | + namespace = None |
| 174 | + else: |
| 175 | + namespace = ns_provider(cmd2_app) |
| 176 | + |
| 177 | + try: |
| 178 | + args = parser.parse_args(parsed_arglist, namespace) |
| 179 | + except SystemExit: |
| 180 | + return |
| 181 | + else: |
| 182 | + setattr(args, '__statement__', statement) |
| 183 | + return func(cmd2_app, args) |
| 184 | + |
| 185 | + # argparser defaults the program name to sys.argv[0], but we want it to be the name of our command |
| 186 | + command_name = func.__name__[len(constants.COMMAND_FUNC_PREFIX):] |
| 187 | + set_parser_prog(parser, command_name) |
| 188 | + |
| 189 | + # If the description has not been set, then use the method docstring if one exists |
| 190 | + if parser.description is None and func.__doc__: |
| 191 | + parser.description = func.__doc__ |
| 192 | + |
| 193 | + # Set the command's help text as argparser.description (which can be None) |
| 194 | + cmd_wrapper.__doc__ = parser.description |
| 195 | + |
| 196 | + # Set some custom attributes for this command |
| 197 | + setattr(cmd_wrapper, constants.CMD_ATTR_ARGPARSER, parser) |
| 198 | + setattr(cmd_wrapper, constants.CMD_ATTR_PRESERVE_QUOTES, preserve_quotes) |
| 199 | + |
| 200 | + return cmd_wrapper |
| 201 | + |
| 202 | + # noinspection PyTypeChecker |
| 203 | + return arg_decorator |
0 commit comments