Merge branch 'main' into feat/annotated-paramspec-typing

Author: tleonhardt

.github/workflows/tests.yml

@@ -40,14 +40,14 @@ jobs:
 
       - name: Upload test results to Codecov
         if: ${{ !cancelled() }}
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@v7
         with:
           flags: python${{ matrix.python-version }}
           name: codecov-umbrella-test-results
           report_type: test_results
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@v7
         with:
           env_vars: OS,PYTHON
           fail_ci_if_error: true

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.15"
+    rev: "v0.15.16"
     hooks:
       - id: ruff-format
         args: [--config=ruff.toml]
@@ -30,7 +30,7 @@ repos:
           - prettier-plugin-toml@2.0.6
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.47.0
+    rev: v1.47.2
     hooks:
       - id: typos
         exclude: |

CHANGELOG.md

@@ -1,4 +1,12 @@
-## 4.0.0 (June TBD, 2026)
+## 4.1.0 (TBD)
+
+- Enhancements
+    - New `cmd2.Cmd` parameters
+        - **complete_in_thread**: (boolean) if `True`, then completion will run in a separate
+          thread. If `False` then completion runs in the main thread and causes it to block if slow.
+          Defaults to `True`.
+
+## 4.0.0 (June 5, 2026)
 
 ### Summary
 
@@ -67,12 +75,14 @@ prompt is displayed.
     - Removed `Cmd.ruler` since `cmd2` no longer uses it.
     - All parsers used with `cmd2` commands must be an instance of `Cmd2ArgumentParser` or a child
       class of it.
-    - Removed `set_ap_completer_type()` and `get_ap_completer_type()` since `ap_completer_type` is
-      now a public member of `Cmd2ArgumentParser`.
+    - Renamed `set_default_argument_parser_type()` to `set_default_argument_parser()`.
+    - Renamed `set_default_ap_completer_type()` to `set_default_argparse_completer()`.
+    - Removed `set_ap_completer_type()` and `get_ap_completer_type()` since `completer_class` is now
+      a public member of `Cmd2ArgumentParser`.
     - Moved `set_parser_prog()` to `Cmd2ArgumentParser.update_prog()`.
-    - Renamed `cmd2_handler` to `cmd2_subcmd_handler` in the `argparse.Namespace` for clarity.
+    - Renamed `cmd2_handler` to `cmd2_subcommand_func` in the `argparse.Namespace` for clarity.
     - Removed `Cmd2AttributeWrapper` class. `argparse.Namespace` objects passed to command functions
-      now contain direct attributes for `cmd2_statement` and `cmd2_subcmd_handler`.
+      now contain direct attributes for `cmd2_statement` and `cmd2_subcommand_func`.
     - Renamed `cmd2/command_definition.py` to `cmd2/command_set.py`.
     - Removed `Cmd.doc_header` and the `with_default_category` decorator. Help categorization is now
       driven by the `DEFAULT_CATEGORY` class variable (see **Simplified command categorization** in

README.md

@@ -26,7 +26,7 @@ of cmd to make your life easier and eliminates much of the boilerplate code whic
 when using cmd.
 
 > :warning: **If you are upgrading from an older version of `cmd2`, both `3.x` and `4.x` have some
-> significant backwards incompatibilities from version `2.x`. Please see the
+> significant backwards incompatibilities from previous versions. Please see the
 > [CHANGELOG](./CHANGELOG.md) for info on what has changed and the
 > [Migration Guide](https://cmd2.readthedocs.io/en/latest/upgrades/) for tips on upgrading from an
 > older version of `cmd2` to `4.x`**

cmd2/__init__.py

@@ -12,12 +12,12 @@
     string_utils,
 )
 from .annotated import with_annotated
-from .argparse_completer import set_default_ap_completer_type
+from .argparse_completer import set_default_argparse_completer
 from .argparse_utils import (
     Cmd2ArgumentParser,
     SubcommandRecord,
     register_argparse_argument_parameter,
-    set_default_argument_parser_type,
+    set_default_argument_parser,
 )
 from .cmd2 import Cmd
 from .colors import Color
@@ -75,8 +75,8 @@
     "Cmd2ArgumentParser",
     "SubcommandRecord",
     "register_argparse_argument_parameter",
-    "set_default_ap_completer_type",
-    "set_default_argument_parser_type",
+    "set_default_argparse_completer",
+    "set_default_argument_parser",
     # Cmd2
     "Cmd",
     "CommandResult",

cmd2/annotated.py

@@ -18,7 +18,7 @@
 flag (``dry_run`` -> ``--dry-run``); pass an explicit ``Option("--my_flag")`` to opt out.
 Positional-only parameters (before ``/``) and ``**kwargs`` raise ``TypeError``.  The parameter
 names ``dest`` and ``subcommand`` are reserved; ``cmd2_statement`` receives the parsed
-``Statement`` and (with ``base_command=True``) ``cmd2_handler`` receives the subcommand handler:
+``Statement`` and (with ``base_command=True``) ``cmd2_subcommand_func`` receives the subcommand handler:
 
     class MyApp(cmd2.Cmd):
         @cmd2.with_annotated
@@ -118,7 +118,7 @@ def do_paint(
 692 ``**parser_kwargs: Unpack[Cmd2ParserKwargs]``.  Anything the parser ctor accepts -- ``description``,
 ``epilog``, ``prog``, ``usage``, ``parents``, ``argument_default``, ``prefix_chars``,
 ``fromfile_prefix_chars``, ``conflict_handler``, ``add_help``, ``allow_abbrev``, ``exit_on_error``,
-``formatter_class``, ``ap_completer_type``, and on Python >= 3.14 ``suggest_on_error`` / ``color`` --
+``formatter_class``, ``completer_class``, and on Python >= 3.14 ``suggest_on_error`` / ``color`` --
 flows straight through; the [`Cmd2ParserKwargs`][cmd2.annotated.Cmd2ParserKwargs] ``TypedDict`` is the single source of truth
 and gives type-checkers/IDEs autocomplete on the decorator's call site.  ``parser_class`` stays as
 its own explicit kwarg because it selects the class itself, not a value passed to it.  Two
@@ -181,8 +181,16 @@ def do_paint(
 import functools
 import inspect
 import types
-from collections.abc import Callable, Container, Iterable, Sequence
-from dataclasses import dataclass, field
+from collections.abc import (
+    Callable,
+    Container,
+    Iterable,
+    Sequence,
+)
+from dataclasses import (
+    dataclass,
+    field,
+)
 from pathlib import Path
 from typing import (
     TYPE_CHECKING,
@@ -205,14 +213,22 @@ def do_paint(
 from rich.table import Column
 
 from . import constants
-from .argparse_utils import DEFAULT_ARGUMENT_PARSER, Cmd2ArgumentParser, SubcommandSpec
+from .argparse_utils import (
+    ArgparseCommandSpec,
+    Cmd2ArgumentParser,
+    SubcommandSpec,
+)
 from .completion import CompletionItem
 from .decorators import _parse_positionals
 from .exceptions import Cmd2ArgparseError
 from .rich_utils import Cmd2HelpFormatter, HelpContent
-from .types import CmdOrSetT, UnboundChoicesProvider, UnboundCompleter
+from .types import (
+    CmdOrSetT,
+    UnboundChoicesProvider,
+    UnboundCompleter,
+)
 
-if TYPE_CHECKING:
+if TYPE_CHECKING:  # pragma: no cover
     from .argparse_completer import ArgparseCompleter
 
 #: ``nargs`` values accepted by cmd2's patched ``add_argument`` (incl. ranged tuples).
@@ -242,7 +258,7 @@ class Cmd2ParserKwargs(TypedDict, total=False):
     exit_on_error: bool
     suggest_on_error: bool
     color: bool
-    ap_completer_type: "type[ArgparseCompleter] | None"
+    completer_class: "type[ArgparseCompleter] | None"
 
 
 # ---------------------------------------------------------------------------
@@ -1689,7 +1705,7 @@ def _const_mismatches_type(a: _ArgparseArgument) -> bool:
 
 # Parameters handled specially by the decorator and not added to the parser.  The first positional
 # parameter (self/cls) is always skipped by position; these cover additional decorator-managed names.
-_SKIP_PARAMS = frozenset({"cmd2_handler", "cmd2_statement"})
+_SKIP_PARAMS = frozenset({constants.NS_ATTR_SUBCOMMAND_FUNC, constants.NS_ATTR_STATEMENT})
 
 
 def _link_group_membership(
@@ -1720,16 +1736,30 @@ def _resolve_parameters(
     """Resolve a function signature into a list of argparse-argument builders.
 
     ``base_command`` marks each argument's context for the base-command :data:`_CONSTRAINTS` rows and
-    drives the function-level ``cmd2_handler`` check below.  ``groups``/``mutually_exclusive_groups``
+    drives the function-level ``cmd2_subcommand_func`` check below.  ``groups``/``mutually_exclusive_groups``
     are linked onto each argument as membership facts for the cross-config constraint rows.
     """
     sig = inspect.signature(func)
     # Function-level check (not a per-argument _CONSTRAINTS row): a base command dispatches through
-    # cmd2_handler, so it must exist.  Here so it also fires when the function has zero parameters.
-    if base_command and "cmd2_handler" not in sig.parameters:
-        raise TypeError(f"with_annotated(base_command=True) requires a 'cmd2_handler' parameter in {func.__qualname__}")
+    # cmd2_subcommand_func, so it must exist.  Here so it also fires when the function has zero parameters.
+    if base_command and constants.NS_ATTR_SUBCOMMAND_FUNC not in sig.parameters:
+        raise TypeError(
+            f"with_annotated(base_command=True) requires a '{constants.NS_ATTR_SUBCOMMAND_FUNC}' "
+            f"parameter in {func.__qualname__}"
+        )
+    # Resolve hints only for the parameters that become arguments: the bound first parameter
+    # (self/cls), the injected skip_params, and the "return" annotation never become arguments
+    ignored = {next(iter(sig.parameters), None), "return", *skip_params}
+    ignored.discard(None)
+    relevant_annotations = {name: ann for name, ann in getattr(func, "__annotations__", {}).items() if name not in ignored}
+    # Forward references resolve against the *original* function's module during functools.wraps wrapper.
+    unwrapped = inspect.unwrap(func)
     try:
-        hints = get_type_hints(func, include_extras=True)
+        hints = get_type_hints(
+            types.SimpleNamespace(__annotations__=relevant_annotations),
+            globalns=getattr(unwrapped, "__globals__", {}),
+            include_extras=True,
+        )
     except (NameError, AttributeError, TypeError) as exc:
         raise TypeError(
             f"Failed to resolve type hints for {func.__qualname__}. Ensure all annotations use valid, importable types."
@@ -1830,14 +1860,10 @@ def _filtered_namespace_kwargs(
     exclude_subcommand: bool = False,
 ) -> dict[str, Any]:
     """Filter a parsed Namespace down to user-visible kwargs."""
-    from .constants import NS_ATTR_SUBCMD_HANDLER
-
     filtered: dict[str, Any] = {}
     for key, value in vars(ns).items():
         if accepted is not None and key not in accepted:
             continue
-        if key == NS_ATTR_SUBCMD_HANDLER:
-            continue
         if exclude_subcommand and key == "subcommand":
             continue
         filtered[key] = value
@@ -1954,7 +1980,9 @@ def build_parser_from_function(
     :param parser_kwargs: forwarded [`Cmd2ParserKwargs`][cmd2.annotated.Cmd2ParserKwargs]
     :return: a fully configured ``Cmd2ArgumentParser``
     """
-    parser_cls = parser_class or DEFAULT_ARGUMENT_PARSER
+    from . import argparse_utils
+
+    parser_cls = parser_class or argparse_utils.DEFAULT_ARGUMENT_PARSER
     if "description" not in parser_kwargs:
         auto_description = _docstring_first_paragraph(func.__doc__)
         if auto_description is not None:
@@ -1971,25 +1999,16 @@ def build_parser_from_function(
         mutually_exclusive_groups=mutually_exclusive_groups,
     )
 
-    # ``argument_default=argparse.SUPPRESS`` removes an absent argument from the parsed namespace.
-    # That is safe only for arguments that are always supplied (required) or carry their own default;
-    # an *omittable* argument with no default (e.g. a ``T | None`` positional -> nargs='?') would be
-    # dropped when absent, leaving the function without a keyword argument it expects.  ``*args`` is
-    # exempt: the invocation path substitutes an empty tuple for it.  Reject the combination here,
-    # mirroring the per-argument ``default=argparse.SUPPRESS`` rejection.
+    # ``argument_default=argparse.SUPPRESS`` drops an absent argument from the parsed namespace.
+    # @with_annotated builds the call from the function signature, so every declared parameter is
+    # expected at invocation -- an argument vanishing from the namespace can never be valid here.
+    # Reject it outright, mirroring the per-argument ``default=argparse.SUPPRESS`` rejection.
     if parser_kwargs.get("argument_default") is argparse.SUPPRESS:
-        dropped = [
-            arg.name
-            for arg in resolved
-            if arg.default is _UNSET and arg.omittable and not arg.required and not arg.is_variadic
-        ]
-        if dropped:
-            raise TypeError(
-                f"argument_default=argparse.SUPPRESS is not supported by @with_annotated for {func.__qualname__}: "
-                f"it would drop {dropped!r} from the parsed namespace when absent, but the function expects "
-                f"{'them' if len(dropped) > 1 else 'it'} as a keyword argument. Give each an explicit default or "
-                f"make it required, or drop argument_default=argparse.SUPPRESS."
-            )
+        raise TypeError(
+            f"argument_default=argparse.SUPPRESS is not supported by @with_annotated for {func.__qualname__}: "
+            f"it drops absent arguments from the parsed namespace, but every parameter built from the "
+            f"signature is expected at invocation. Drop argument_default=argparse.SUPPRESS."
+        )
 
     # Build the group lookup (member references already validated by _resolve_parameters).
     target_for, argument_group_for = _build_argument_group_targets(parser, groups=groups)
@@ -2107,10 +2126,10 @@ def _build_subcommand_handler(
     def handler(self_arg: Any, ns: Any) -> Any:
         """Unpack Namespace into typed kwargs for the subcommand handler."""
         filtered = _filtered_namespace_kwargs(ns, accepted=_accepted)
-        if "cmd2_handler" in filtered:
-            cmd2_h = filtered["cmd2_handler"]
-            if isinstance(cmd2_h, functools.partial) and cmd2_h.func is handler:
-                filtered["cmd2_handler"] = None
+        if constants.NS_ATTR_SUBCOMMAND_FUNC in filtered:
+            cmd2_h = filtered[constants.NS_ATTR_SUBCOMMAND_FUNC]
+            if isinstance(cmd2_h, functools.partial) and getattr(cmd2_h.func, "__func__", cmd2_h.func) is handler:
+                filtered[constants.NS_ATTR_SUBCOMMAND_FUNC] = None
         return _invoke_command_func(
             func, self_arg, filtered, leading_names=_leading_names, var_positional_name=_var_positional_name
         )
@@ -2182,7 +2201,7 @@ def with_annotated(
     :param ns_provider: callable returning a prepopulated Namespace (not with ``subcommand_to``)
     :param preserve_quotes: preserve quotes in arguments (not with ``subcommand_to``)
     :param with_unknown_args: capture unknown args as the ``_unknown`` kwarg (not with ``subcommand_to``)
-    :param base_command: add ``add_subparsers()``; requires a ``cmd2_handler`` param and no positionals
+    :param base_command: add ``add_subparsers()``; requires a ``cmd2_subcommand_func`` param and no positionals
     :param subcommand_to: parent command name; function must be named ``{parent_underscored}_{subcommand}``
     :param help: subcommand help text (only with ``subcommand_to``)
     :param aliases: alternative subcommand names (only with ``subcommand_to``)
@@ -2244,9 +2263,10 @@ def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
             if unknown_param.kind is inspect.Parameter.POSITIONAL_ONLY:
                 raise TypeError("Parameter _unknown must be keyword-compatible when with_unknown_args=True")
 
-        if not base_command and "cmd2_handler" in inspect.signature(fn).parameters:
+        if not base_command and constants.NS_ATTR_SUBCOMMAND_FUNC in inspect.signature(fn).parameters:
             raise TypeError(
-                f"Parameter 'cmd2_handler' in {fn.__qualname__} is only valid when with_annotated(base_command=True) is used."
+                f"Parameter '{constants.NS_ATTR_SUBCOMMAND_FUNC}' in {fn.__qualname__} "
+                "is only valid when with_annotated(base_command=True) is used."
             )
 
         if subcommand_to is not None:
@@ -2256,15 +2276,15 @@ def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
                 base_command=base_command,
                 options=options,
             )
-            spec = SubcommandSpec(
+            subcommand_spec = SubcommandSpec(
                 name=subcmd_name,
                 command=subcommand_to,
                 help=help,
                 aliases=tuple(aliases),
                 deprecated=deprecated,
                 parser_source=subcmd_parser_builder,
             )
-            setattr(handler, constants.SUBCMD_ATTR_SPEC, spec)
+            setattr(handler, constants.SUBCOMMAND_ATTR_SPEC, subcommand_spec)
             return handler
 
         command_name = fn.__name__[len(constants.COMMAND_FUNC_PREFIX) :]
@@ -2308,10 +2328,10 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
                 raise Cmd2ArgparseError from exc
 
             setattr(ns, constants.NS_ATTR_STATEMENT, statement)
-            handler = getattr(ns, constants.NS_ATTR_SUBCMD_HANDLER, None)
+            handler = getattr(ns, constants.NS_ATTR_SUBCOMMAND_FUNC, None)
             if base_command and handler is not None:
                 handler = functools.partial(handler, ns)
-            ns.cmd2_handler = handler
+            setattr(ns, constants.NS_ATTR_SUBCOMMAND_FUNC, handler)
 
             func_kwargs = _filtered_namespace_kwargs(ns, accepted=accepted, exclude_subcommand=base_command)
 
@@ -2324,8 +2344,11 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
             )
             return result
 
-        setattr(cmd_wrapper, constants.CMD_ATTR_PARSER_SOURCE, parser_builder)
-        setattr(cmd_wrapper, constants.CMD_ATTR_PRESERVE_QUOTES, preserve_quotes)
+        argparse_command_spec = ArgparseCommandSpec(
+            parser_source=parser_builder,
+            preserve_quotes=preserve_quotes,
+        )
+        setattr(cmd_wrapper, constants.ARGPARSE_COMMAND_ATTR_SPEC, argparse_command_spec)
 
         return cmd_wrapper