Add with_annotated to top-level cmd2 namespace

Also:
- Fix minor edge case silent failure bug
- Add description of this new feature to CHANGELOG under an "Experimental Features" section for the 4.0.0 release

Author: tleonhardt

CHANGELOG.md

@@ -171,6 +171,12 @@ prompt is displayed.
       is enabled.
     - `alias` and `macro` subcommands for `create` and `delete` now output their non-essential
       success case output using `pfeedback`
+- Experimental features
+    - New `@with_annotated` decorator, a type-hint-driven alternative to `@with_argparse` that
+      builds the parser automatically from a command's signature (positional/option inference,
+      enum/literal/path/collection handling, subcommands, groups, mutex). See the
+      [annotated_example.py](https://github.com/python-cmd2/cmd2/blob/main/examples/annotated_example.py)
+      example for demonstration of usage.
 
 ## 3.5.1 (April 24, 2026)
 

cmd2/__init__.py

@@ -11,6 +11,7 @@
     rich_utils,
     string_utils,
 )
+from .annotated import with_annotated
 from .argparse_completer import set_default_ap_completer_type
 from .argparse_utils import (
     Cmd2ArgumentParser,
@@ -88,6 +89,7 @@
     "CompletionItem",
     "Completions",
     # Decorators
+    "with_annotated",
     "with_argument_list",
     "with_argparser",
     "with_category",

cmd2/annotated.py

@@ -1925,7 +1925,7 @@ def _invoke_command_func(
     """Call *func* from parsed kwargs, unpacking ``*args`` positionally when present."""
     if var_positional_name is None:
         return func(self_arg, **func_kwargs)
-    positional = [func_kwargs.pop(name) for name in leading_names if name in func_kwargs]
+    positional = [func_kwargs.pop(name) for name in leading_names]
     var_values = func_kwargs.pop(var_positional_name, None) or ()
     return func(self_arg, *positional, *var_values, **func_kwargs)
 

docs/features/annotated.md

@@ -11,10 +11,9 @@
     For production code that needs stable behavior, use
     [@with_argparser](argument_processing.md#with_argparser-decorator) instead.
 
-The [@with_annotated][cmd2.annotated.with_annotated] decorator builds an argparse parser
-automatically from the decorated function's type annotations. No manual `add_argument()` calls are
-required, and the command body receives typed keyword arguments directly instead of an
-`argparse.Namespace`.
+The [@with_annotated][cmd2.with_annotated] decorator builds an argparse parser automatically from
+the decorated function's type annotations. No manual `add_argument()` calls are required, and the
+command body receives typed keyword arguments directly instead of an `argparse.Namespace`.
 
 The two decorators are interchangeable -- here is the same command written both ways:
 

docs/features/argument_processing.md

@@ -19,7 +19,7 @@ following for you:
 These features are provided by two decorators:
 
 - [@with_argparser][cmd2.with_argparser] -- build parsers manually with `add_argument()` calls
-- [@with_annotated][cmd2.annotated.with_annotated] -- build parsers automatically from type hints
+- [@with_annotated][cmd2.with_annotated] -- build parsers automatically from type hints
 
 See the
 [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py)
@@ -61,10 +61,10 @@ stores internally. A consequence is that parsers don't need to be unique across
 
     The `@with_annotated` decorator is **experimental** and its API may change in future releases.
 
-The [@with_annotated][cmd2.annotated.with_annotated] decorator builds an argparse parser
-automatically from the decorated function's type annotations -- no manual `add_argument()` calls
-required. See [Annotated Argument Processing](annotated.md) for the full reference, including type
-mapping, metadata classes, subcommands, and stability caveats.
+The [@with_annotated][cmd2.with_annotated] decorator builds an argparse parser automatically from
+the decorated function's type annotations -- no manual `add_argument()` calls required. See
+[Annotated Argument Processing](annotated.md) for the full reference, including type mapping,
+metadata classes, subcommands, and stability caveats.
 
 ## Argument Parsing