Add a missing check and associated unit test

Also:
- Reword a couple TypeError messages which read awkwardly

Author: tleonhardt

cmd2/annotated.py

@@ -2931,6 +2931,8 @@ def handler(*args: _CommandParams.args, **kwargs: _CommandParams.kwargs) -> bool
         """Unpack Namespace into typed kwargs for the subcommand handler."""
         if kwargs:
             raise TypeError("subcommand handlers do not accept keyword arguments")
+        if len(args) != 2:
+            raise TypeError(f"subcommand handlers require 2 positional arguments (self, namespace), got {len(args)}")
         self_arg, ns = args
         if not isinstance(ns, argparse.Namespace):
             raise TypeError("subcommand handlers require a parsed argparse.Namespace")

cmd2/cmd2.py

@@ -5959,7 +5959,7 @@ def _validate_postparsing_callable(cls, func: Callable[[plugin.PostparsingData],
         if par_ann != plugin.PostparsingData:
             raise TypeError(f"{func_name} must have one parameter declared with type 'cmd2.plugin.PostparsingData'")
         if ret_ann != plugin.PostparsingData:
-            raise TypeError(f"{func_name} must declare return a return type of 'cmd2.plugin.PostparsingData'")
+            raise TypeError(f"{func_name} must declare a return type of 'cmd2.plugin.PostparsingData'")
 
     def register_postparsing_hook(self, func: Callable[[plugin.PostparsingData], plugin.PostparsingData]) -> None:
         """Register a function to be called after parsing user input but before running the command."""
@@ -6016,7 +6016,7 @@ def _validate_cmdfinalization_callable(
                 f"{func_name} must have one parameter declared with type {plugin.CommandFinalizationData}, got: {par_ann}"
             )
         if ret_ann != plugin.CommandFinalizationData:
-            raise TypeError(f"{func_name} must declare return a return type of {plugin.CommandFinalizationData}")
+            raise TypeError(f"{func_name} must declare a return type of {plugin.CommandFinalizationData}")
 
     def register_cmdfinalization_hook(
         self, func: Callable[[plugin.CommandFinalizationData], plugin.CommandFinalizationData]

tests/test_annotated.py

@@ -2318,6 +2318,20 @@ def root_child(self) -> None:
         root_child(object(), argparse.Namespace(), unexpected=True)
 
 
+def test_subcommand_handler_rejects_wrong_positional_argument_count() -> None:
+    """The internal subcommand adapter requires exactly two positional arguments (self, namespace)."""
+
+    @with_annotated(subcommand_to="root")
+    def root_child(self) -> None:
+        pass
+
+    with pytest.raises(TypeError, match=r"require 2 positional arguments"):
+        root_child(object())
+
+    with pytest.raises(TypeError, match=r"require 2 positional arguments"):
+        root_child(object(), argparse.Namespace(), "extra")
+
+
 def test_subcommand_handler_requires_namespace() -> None:
     """The internal subcommand adapter rejects calls without a parsed namespace."""