chore: update implementation

Author: tleonhardt

cmd2/annotated.py

@@ -743,12 +743,11 @@ def _get_raw_choices(self, arg_state: _ArgumentState) -> list[CompletionItem] |
 
                 return ChoicesCallable(is_completer=True, to_call=Cmd.path_complete)
 
-            if isinstance(action_type, type) and issubclass(action_type, enum.Enum):
-                return [CompletionItem(str(m.value), display_meta=m.name) for m in action_type]
-
-            enum_from_converter = getattr(action_type, '_cmd2_enum_class', None)
-            if isinstance(enum_from_converter, type) and issubclass(enum_from_converter, enum.Enum):
-                return [CompletionItem(str(m.value), display_meta=m.name) for m in enum_from_converter]
+            enum_class = action_type if isinstance(action_type, type) and issubclass(action_type, enum.Enum) else None
+            if enum_class is None:
+                enum_class = getattr(action_type, '_cmd2_enum_class', None)
+            if isinstance(enum_class, type) and issubclass(enum_class, enum.Enum):
+                return [CompletionItem(str(m.value), display_meta=m.name) for m in enum_class]
 
         return None
 

cmd2/argparse_completer.py

@@ -308,6 +308,14 @@ class AsyncAlert:
     timestamp: float = field(default_factory=time.monotonic, init=False)
 
 
+class _ConsoleCache(threading.local):
+    """Thread-local storage for cached Rich consoles used by core print methods."""
+
+    def __init__(self) -> None:
+        self.stdout: Cmd2BaseConsole | None = None
+        self.stderr: Cmd2BaseConsole | None = None
+
+
 class Cmd:
     """An easy but powerful framework for writing line-oriented command interpreters.
 
@@ -441,6 +449,9 @@ def __init__(
         self.scripts_add_to_history = True  # Scripts and pyscripts add commands to history
         self.timing = False  # Prints elapsed time for each command
 
+        # Cached Rich consoles used by core print methods.
+        self._console_cache = _ConsoleCache()
+
         # The maximum number of items to display in a completion table. If the number of completion
         # suggestions exceeds this number, then no table will appear.
         self.max_completion_table_items: int = 50
@@ -1324,28 +1335,57 @@ def visible_prompt(self) -> str:
         """
         return su.strip_style(self.prompt)
 
-    def _create_base_printing_console(
+    def _get_core_print_console(
         self,
         *,
         file: IO[str],
         emoji: bool,
         markup: bool,
         highlight: bool,
     ) -> Cmd2BaseConsole:
-        """Create a Cmd2BaseConsole with formatting overrides.
+        """Get a console configured for the specified stream and formatting settings.
+
+        This method is intended for internal use by cmd2's core print methods.
+        To avoid the overhead of repeated initialization, it manages a thread-local
+        cache for consoles targeting ``self.stdout`` or ``sys.stderr``. It returns a cached
+        instance if its configuration matches the request. For all other streams, or if
+        the configuration has changed, a new console is created.
+
+        Note: This implementation works around a bug in Rich where passing formatting settings
+        (emoji, markup, and highlight) directly to console.print() or console.log() does not
+        always work when printing certain Renderables. Passing them to the constructor instead
+        ensures they are correctly propagated. Once this bug is fixed, these parameters can
+        be removed from this method. For more details, see:
+        https://github.com/Textualize/rich/issues/4028
+        """
+        # Dictionary of settings to check against cached consoles
+        kwargs = {
+            "emoji": emoji,
+            "markup": markup,
+            "highlight": highlight,
+        }
 
-        This works around a bug in Rich where passing these formatting settings directly to
-        console.print() or console.log() does not always work when printing certain Renderables.
-        Passing them to the constructor instead ensures they are correctly propagated.
+        # Check if we should use or update a cached console
+        if file is self.stdout:
+            cached = self._console_cache.stdout
+            if cached is not None and cached.matches_config(file=file, **kwargs):
+                return cached
 
-        See: https://github.com/Textualize/rich/issues/4028
-        """
-        return Cmd2BaseConsole(
-            file=file,
-            emoji=emoji,
-            markup=markup,
-            highlight=highlight,
-        )
+            # Create new console and update cache
+            self._console_cache.stdout = Cmd2BaseConsole(file=file, **kwargs)
+            return self._console_cache.stdout
+
+        if file is sys.stderr:
+            cached = self._console_cache.stderr
+            if cached is not None and cached.matches_config(file=file, **kwargs):
+                return cached
+
+            # Create new console and update cache
+            self._console_cache.stderr = Cmd2BaseConsole(file=file, **kwargs)
+            return self._console_cache.stderr
+
+        # For any other file, just create a new console
+        return Cmd2BaseConsole(file=file, **kwargs)
 
     def print_to(
         self,
@@ -1398,7 +1438,7 @@ def print_to(
         See the Rich documentation for more details on emoji codes, markup tags, and highlighting.
         """
         try:
-            self._create_base_printing_console(
+            self._get_core_print_console(
                 file=file,
                 emoji=emoji,
                 markup=markup,
@@ -1714,7 +1754,7 @@ def ppaged(
                 soft_wrap = True
 
             # Generate the bytes to send to the pager
-            console = self._create_base_printing_console(
+            console = self._get_core_print_console(
                 file=self.stdout,
                 emoji=emoji,
                 markup=markup,

cmd2/cmd2.py

@@ -280,7 +280,7 @@ def arg_decorator(func: ArgparseCommandFunc[CmdOrSet]) -> RawCommandFuncOptional
         """
 
         @functools.wraps(func)
-        def cmd_wrapper(*args: Any, **kwargs: dict[str, Any]) -> bool | None:
+        def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
             """Command function wrapper which translates command line into argparse Namespace and call actual command function.
 
             :param args: All positional arguments to this function.  We're expecting there to be:
@@ -349,72 +349,101 @@ def cmd_wrapper(*args: Any, **kwargs: dict[str, Any]) -> bool | None:
 def with_annotated(
     func: Callable[..., Any] | None = None,
     *,
+    ns_provider: Callable[..., argparse.Namespace] | None = None,
     preserve_quotes: bool = False,
     with_unknown_args: bool = False,
 ) -> Any:
     """Decorate a ``do_*`` method to build its argparse parser from type annotations.
 
-    Can be used bare or with keyword arguments::
+    :param func: the command function (when used without parentheses)
+    :param ns_provider: optional callable returning a prepopulated argparse.Namespace
+    :param preserve_quotes: if True, preserve quotes in arguments
+    :param with_unknown_args: if True, capture unknown args (passed as extra kwarg ``_unknown``)
+
 
+    Example:
+    ```py
+    class MyApp(cmd2.Cmd):
         @with_annotated
         def do_greet(self, name: str, count: int = 1): ...
 
         @with_annotated(preserve_quotes=True)
         def do_raw(self, text: str): ...
 
-    :param func: the command function (when used without parentheses)
-    :param preserve_quotes: if True, preserve quotes in arguments
-    :param with_unknown_args: if True, capture unknown args (passed as extra kwarg ``_unknown``)
     """
     from .annotated import build_parser_from_function
 
-    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
         if with_unknown_args:
-            unknown_param = inspect.signature(fn).parameters.get('_unknown')
+            unknown_param = inspect.signature(func).parameters.get('_unknown')
             if unknown_param is None:
                 raise TypeError('with_annotated(with_unknown_args=True) requires a parameter named _unknown')
             if unknown_param.kind is inspect.Parameter.POSITIONAL_ONLY:
                 raise TypeError('Parameter _unknown must be keyword-compatible when with_unknown_args=True')
 
-        command_name = fn.__name__[len(constants.COMMAND_FUNC_PREFIX) :]
+        command_name = func.__name__[len(constants.COMMAND_FUNC_PREFIX) :]
 
-        @functools.wraps(fn)
-        def cmd_wrapper(*args: Any, **_kwargs: Any) -> bool | None:
+        @functools.wraps(func)
+        def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
             cmd2_app, statement_arg = _parse_positionals(args)
             owner = args[0]  # Cmd or CommandSet instance
-            _statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(
+            statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(
                 command_name, statement_arg, preserve_quotes
             )
 
             arg_parser = cmd2_app._command_parsers.get(cmd_wrapper)
             if arg_parser is None:
                 raise ValueError(f'No argument parser found for {command_name}')
 
+            # Resolve namespace provider (same logic as with_argparser)
+            if ns_provider is None:
+                namespace = None
+            else:
+                provider_self = cmd2_app._resolve_func_self(ns_provider, args[0])
+                namespace = ns_provider(provider_self if provider_self is not None else cmd2_app)
+
             try:
                 if with_unknown_args:
-                    ns, unknown = arg_parser.parse_known_args(parsed_arglist)
+                    ns, unknown = arg_parser.parse_known_args(parsed_arglist, namespace)
                 else:
-                    ns = arg_parser.parse_args(parsed_arglist)
+                    ns = arg_parser.parse_args(parsed_arglist, namespace)
                     unknown = None
             except SystemExit as exc:
                 raise Cmd2ArgparseError from exc
 
-            # Unpack Namespace into function kwargs
+            # Unpack Namespace into function kwargs, filtering cmd2 internals
             func_kwargs: dict[str, Any] = {}
             for key, value in vars(ns).items():
                 if key.startswith('cmd2_') or key == constants.NS_ATTR_SUBCMD_HANDLER:
                     continue
                 func_kwargs[key] = value
 
+            # Attach statement for commands that need it (access via cmd2_statement kwarg)
+            func_kwargs['cmd2_statement'] = Cmd2AttributeWrapper(statement)
+
+            # Attach subcmd handler wrapper
+            handler = getattr(ns, constants.NS_ATTR_SUBCMD_HANDLER, None)
+            func_kwargs['cmd2_handler'] = Cmd2AttributeWrapper(handler)
+
             if with_unknown_args:
                 func_kwargs['_unknown'] = unknown
 
-            result: bool | None = fn(owner, **func_kwargs)
+            # Only pass kwargs the function actually accepts
+            sig = inspect.signature(func)
+            accepted = set(sig.parameters.keys()) - {'self'}
+            filtered_kwargs = {k: v for k, v in func_kwargs.items() if k in accepted}
+
+            # Explicit kwargs provided by direct wrapper invocation should override
+            # parser-derived values.
+            for key in kwargs:
+                filtered_kwargs.pop(key, None)
+
+            result: bool | None = func(owner, **filtered_kwargs, **kwargs)
             return result
 
         # Store a parser-builder callable — _CommandParsers._build_parser()
         # already handles callables by calling them with no arguments.
-        setattr(cmd_wrapper, constants.CMD_ATTR_ARGPARSER, lambda: build_parser_from_function(fn))
+        setattr(cmd_wrapper, constants.CMD_ATTR_ARGPARSER, lambda: build_parser_from_function(func))
         setattr(cmd_wrapper, constants.CMD_ATTR_PRESERVE_QUOTES, preserve_quotes)
 
         return cmd_wrapper

cmd2/decorators.py

@@ -160,6 +160,9 @@ def __init__(
                 "Passing 'theme' is not allowed. Its behavior is controlled by the global APP_THEME and set_theme()."
             )
 
+        # Store the configuration used to create this console for caching purposes.
+        self._config_key = self._generate_config_key(file=file, **kwargs)
+
         force_terminal: bool | None = None
         force_interactive: bool | None = None
 
@@ -180,6 +183,41 @@ def __init__(
             **kwargs,
         )
 
+    @staticmethod
+    def _generate_config_key(
+        *,
+        file: IO[str] | None,
+        **kwargs: Any,
+    ) -> tuple[Any, ...]:
+        """Generate a key representing the settings used to initialize a console.
+
+        This key includes the file identity, global settings (ALLOW_STYLE, APP_THEME),
+        and any other settings passed in via kwargs.
+
+        :param file: file stream being checked
+        :param kwargs: other console settings
+        """
+        return (
+            id(file),
+            ALLOW_STYLE,
+            id(APP_THEME),
+            tuple(sorted(kwargs.items())),
+        )
+
+    def matches_config(
+        self,
+        *,
+        file: IO[str] | None,
+        **kwargs: Any,
+    ) -> bool:
+        """Check if this console instance was initialized with the specified settings.
+
+        :param file: file stream being checked
+        :param kwargs: other console settings being checked
+        :return: True if the settings match this console's configuration
+        """
+        return self._config_key == self._generate_config_key(file=file, **kwargs)
+
     def on_broken_pipe(self) -> None:
         """Override which raises BrokenPipeError instead of SystemExit."""
         self.quiet = True

cmd2/rich_utils.py

@@ -85,27 +85,39 @@ them as keyword arguments.
 
 The decorator converts Python type annotations into `add_argument()` calls:
 
-| Type annotation                                          | Generated argparse setting                          |
-| -------------------------------------------------------- | --------------------------------------------------- |
-| `str`                                                    | default (no `type=` needed)                         |
-| `int`, `float`                                           | `type=int` or `type=float`                          |
-| `bool` (default `False`)                                 | `--flag` with `action='store_true'`                 |
-| `bool` (default `True`)                                  | `--no-flag` with `action='store_false'`             |
-| positional `bool`                                        | parsed from `true/false`, `yes/no`, `on/off`, `1/0` |
-| `Path`                                                   | `type=Path`                                         |
-| `Enum` subclass                                          | `type=converter`, `choices` from member values      |
-| `decimal.Decimal`                                        | `type=decimal.Decimal`                              |
-| `Literal[...]`                                           | `type=literal-converter`, `choices` from values     |
-| `Collection[T]` / `list[T]` / `set[T]` / `tuple[T, ...]` | `nargs='+'` (or `'*'` if it has a default)          |
-| `T \| None`                                              | unwrapped to `T`, treated as optional               |
+| Type annotation                        | Generated argparse setting                          |
+| -------------------------------------- | --------------------------------------------------- |
+| `str`                                  | default (no `type=` needed)                         |
+| `int`, `float`                         | `type=int` or `type=float`                          |
+| `bool` (default `False`)               | `--flag` with `action='store_true'`                 |
+| `bool` (default `True`)                | `--no-flag` with `action='store_false'`             |
+| positional `bool`                      | parsed from `true/false`, `yes/no`, `on/off`, `1/0` |
+| `Path`                                 | `type=Path`                                         |
+| `Enum` subclass                        | `type=converter`, `choices` from member values      |
+| `decimal.Decimal`                      | `type=decimal.Decimal`                              |
+| `Literal[...]`                         | `type=literal-converter`, `choices` from values     |
+| `list[T]` / `set[T]` / `tuple[T, ...]` | `nargs='+'` (or `'*'` if it has a default)          |
+| `tuple[T, T]` (fixed arity, same type) | `nargs=N` with `type=T`                             |
+| `T \| None`                            | unwrapped to `T`, treated as optional               |
 
 When collection types are used with `@with_annotated`, parsed values are passed to the command
 function as:
 
-- `list[T]` and `Collection[T]` as `list`
+- `list[T]` as `list`
 - `set[T]` as `set`
 - `tuple[T, ...]` as `tuple`
 
+### Unsupported type patterns
+
+The following type patterns raise `TypeError` at decoration time:
+
+- **Union types** like `str | int` -- ambiguous for argparse auto-resolution. Use
+  `Annotated[..., Argument()]` or `Annotated[..., Option()]` with an explicit type instead.
+  `T | None` is still supported (treated as optional `T`).
+- **Mixed-type tuples** like `tuple[int, str, float]` -- not currently supported because argparse
+  can only apply a single `type=` converter per argument. Use `tuple[T, T]` (same type for all
+  elements) or `tuple[T, ...]` instead.
+
 ### Annotated metadata
 
 For finer control, use `typing.Annotated` with [Argument][cmd2.annotated.Argument] or
@@ -213,6 +225,29 @@ def do_load(self, args):
 With `@with_annotated`, the same inference happens because `Path` and `Enum` annotations generate
 `type=Path` and `type=converter` in the underlying parser.
 
+### User completers override type inference
+
+If you set an explicit `choices_provider` or `completer` on an argument, it always takes priority
+over the type-inferred completion. This applies to both decorator styles:
+
+```py
+# @with_argparser: user completer overrides Path auto-completion
+parser.add_argument('file', type=Path, completer=my_custom_completer)
+
+# @with_annotated: user choices_provider overrides Enum auto-completion
+@with_annotated
+def do_pick(
+    self,
+    color: Annotated[MyEnum, Argument(choices_provider=my_provider)],
+): ...
+```
+
+The priority order is:
+
+1. Explicit `choices` on the action (highest)
+2. User-supplied `choices_provider` or `completer`
+3. Type inference from `Path` or `Enum` (lowest)
+
 ## Argument Parsing
 
 For each command in the `cmd2.Cmd` subclass which requires argument parsing, create an instance of