chore: more clean up

Author: KelvinChung2000

cmd2/argparse_completer.py

@@ -750,7 +750,7 @@ def _get_raw_choices(self, arg_state: _ArgumentState) -> list[CompletionItem] |
             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]
 
-            if action_type.__name__ == '_parse_bool':
+            if getattr(action_type, '__name__', None) == '_parse_bool':
                 return [CompletionItem(v) for v in ['true', 'false', 'yes', 'no', 'on', 'off', '1', '0']]
 
         return None

docs/features/argument_processing.md

@@ -64,7 +64,9 @@ required.
 ### Basic usage
 
 Parameters without defaults become positional arguments. Parameters with defaults become `--option`
-flags. The function receives typed keyword arguments directly instead of an `argparse.Namespace`.
+flags. Keyword-only parameters (after `*`) always become options, and without a default they become
+required options. The function receives typed keyword arguments directly instead of an
+`argparse.Namespace`.
 
 ```py
 from cmd2 import with_annotated
@@ -89,14 +91,14 @@ The decorator converts Python type annotations into `add_argument()` calls:
 | -------------------------------------------------------- | --------------------------------------------------- |
 | `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'`             |
+| `bool` with a default                                    | boolean optional flag via `BooleanOptionalAction`   |
 | 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)          |
+| `tuple[T, T]`                                            | fixed `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
@@ -106,6 +108,15 @@ function as:
 - `set[T]` as `set`
 - `tuple[T, ...]` as `tuple`
 
+Unsupported patterns raise `TypeError`, including:
+
+- unions with multiple non-`None` members such as `str | int`
+- mixed-type tuples such as `tuple[int, str]`
+- `Annotated[T, meta] | None`; write `Annotated[T | None, meta]` instead
+
+The parameter names `dest` and `subcommand` are reserved and may not be used as annotated parameter
+names.
+
 ### Annotated metadata
 
 For finer control, use `typing.Annotated` with [Argument][cmd2.annotated.Argument] or
@@ -171,15 +182,69 @@ def do_greet(self, name: str, count: int = 1, loud: bool = False):
         self.poutput(msg.upper() if loud else msg)
 ```
 
-The annotated version is more concise and gives you typed parameters. The argparse version gives you
-more control (e.g. `ns_provider`, subcommand handlers via `cmd2_handler`).
+The annotated version is more concise and gives you typed parameters. It also supports several
+advanced cmd2 features directly, including `ns_provider`, `with_unknown_args`, and typed
+subcommands.
 
 ### Decorator options
 
-`@with_annotated` accepts the same keyword arguments as `@with_argparser`:
+`@with_annotated` currently supports:
 
+- `ns_provider` -- prepopulate the namespace before parsing, mirroring `@with_argparser`
 - `preserve_quotes` -- if `True`, quotes in arguments are preserved
 - `with_unknown_args` -- if `True`, unrecognised arguments are passed as `_unknown`
+- `subcommand_to` -- register the function as an annotated subcommand under a parent command
+- `base_command` -- create a base command whose parser also adds subparsers and exposes
+  `cmd2_handler`
+- `help` -- help text for an annotated subcommand
+- `aliases` -- aliases for an annotated subcommand
+
+```py
+@with_annotated(with_unknown_args=True)
+def do_rawish(self, name: str, _unknown: list[str] | None = None):
+    self.poutput((name, _unknown))
+```
+
+### Annotated subcommands
+
+`@with_annotated` can also build typed subcommand trees without manually constructing subparsers.
+
+```py
+@with_annotated(base_command=True)
+def do_manage(self, *, cmd2_handler):
+    handler = cmd2_handler.get()
+    if handler:
+        handler()
+
+@with_annotated(subcommand_to="manage", help="list projects")
+def manage_list(self):
+    self.poutput("listing")
+```
+
+For nested subcommands, `subcommand_to` can be space-delimited, for example
+`subcommand_to="manage project"`. The intermediate level must also be declared as a subcommand that
+creates its own subparsers:
+
+```py
+@with_annotated(subcommand_to="manage", base_command=True, help="manage projects")
+def manage_project(self, *, cmd2_handler):
+    handler = cmd2_handler.get()
+    if handler:
+        handler()
+
+@with_annotated(subcommand_to="manage project", help="add a project")
+def manage_project_add(self, name: str):
+    self.poutput(f"added {name}")
+```
+
+### Lower-level parser building
+
+If you need parser grouping or mutually-exclusive groups while still using annotation-driven parser
+generation, [cmd2.annotated.build_parser_from_function][cmd2.annotated.build_parser_from_function]
+also supports:
+
+- `groups=((...), (...))`
+- `mutually_exclusive_groups=((...), (...))`
 
 ```py
 @with_annotated(preserve_quotes=True)
@@ -211,7 +276,7 @@ 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.
+the equivalent parser configuration automatically.
 
 ## Argument Parsing
 

examples/annotated_example.py

@@ -17,9 +17,14 @@
 """
 
 import sys
+from argparse import Namespace
+from decimal import Decimal
 from enum import Enum
 from pathlib import Path
-from typing import Annotated
+from typing import (
+    Annotated,
+    Literal,
+)
 
 import cmd2
 from cmd2 import (
@@ -54,6 +59,7 @@ class AnnotatedExample(Cmd):
     def __init__(self) -> None:
         super().__init__(include_ipy=True)
         self._sports = ['Basketball', 'Football', 'Tennis', 'Hockey']
+        self._default_region = "staging"
 
     # -- Type inference: int, float, bool ------------------------------------
     # With @with_argparser you'd manually set type=int and action='store_true'.
@@ -109,10 +115,8 @@ def do_copy(self, src: Path, dst: Path) -> None:
         self.poutput(f"Copying {src} -> {dst}")
 
     # -- Bool flags ----------------------------------------------------------
-    # With @with_argparser you'd set action='store_true' or 'store_false'.
-    # Here bool defaults drive the flag style automatically.
-    #   False default -> --flag (store_true)
-    #   True default  -> --no-flag (store_false)
+    # With @with_argparser you'd spell out the action.
+    # Here bool defaults drive the generated boolean option.
 
     @cmd2.with_annotated
     @cmd2.with_category(ANNOTATED_CATEGORY)
@@ -124,8 +128,8 @@ def do_build(
     ) -> None:
         """Build a target. Bool flags are inferred from defaults.
 
-        ``verbose: bool = False`` becomes ``--verbose`` (store_true).
-        ``color: bool = True`` becomes ``--no-color`` (store_false).
+        ``verbose: bool = False`` becomes a boolean optional flag.
+        ``color: bool = True`` becomes a ``--color`` / ``--no-color`` style option.
 
         Try:
             build app --verbose --no-color
@@ -151,6 +155,25 @@ def do_sum(self, numbers: list[float]) -> None:
         """
         self.poutput(f"{' + '.join(str(n) for n in numbers)} = {sum(numbers)}")
 
+    # -- Literal + Decimal ---------------------------------------------------
+    # Literal values become validated choices. Decimal values preserve precision.
+
+    @cmd2.with_annotated
+    @cmd2.with_category(ANNOTATED_CATEGORY)
+    def do_deploy(
+        self,
+        service: str,
+        mode: Literal["safe", "fast"] = "safe",
+        budget: Decimal = Decimal("1.50"),
+    ) -> None:
+        """Deploy using Literal choices and Decimal parsing.
+
+        Try:
+            deploy api --mode <TAB>
+            deploy api --mode fast --budget 2.75
+        """
+        self.poutput(f"Deploying {service} in {mode} mode with budget {budget}")
+
     # -- Typed kwargs --------------------------------------------------------
     # With @with_argparser you'd access args.name, args.count on a Namespace.
     # Here each parameter is a typed local variable.
@@ -212,6 +235,69 @@ def do_score(
         """
         self.poutput(f"{sport}: {play} for {points} point(s)")
 
+    # -- Namespace provider --------------------------------------------------
+    # This mirrors one of @with_argparser's advanced features.
+
+    def default_namespace(self) -> Namespace:
+        return Namespace(region=self._default_region)
+
+    @cmd2.with_annotated(ns_provider=default_namespace)
+    @cmd2.with_category(ANNOTATED_CATEGORY)
+    def do_ship(self, package: str, region: str = "local") -> None:
+        """Use ns_provider to prepopulate parser defaults at runtime.
+
+        Try:
+            ship parcel
+            ship parcel --region remote
+        """
+        self.poutput(f"Shipping {package} to {region}")
+
+    # -- Unknown args --------------------------------------------------------
+
+    @cmd2.with_annotated(with_unknown_args=True)
+    @cmd2.with_category(ANNOTATED_CATEGORY)
+    def do_flex(self, name: str, _unknown: list[str] | None = None) -> None:
+        """Capture unknown arguments instead of failing parse.
+
+        Try:
+            flex alice --future-flag value
+        """
+        self.poutput(f"name={name}")
+        if _unknown:
+            self.poutput(f"unknown={_unknown}")
+
+    # -- Subcommands ---------------------------------------------------------
+    # @with_annotated also supports typed subcommand trees.
+
+    @cmd2.with_annotated(base_command=True)
+    @cmd2.with_category(ANNOTATED_CATEGORY)
+    def do_manage(self, verbose: bool = False, *, cmd2_handler) -> None:
+        """Base command for annotated subcommands.
+
+        Try:
+            help manage
+            manage project add demo
+        """
+        if verbose:
+            self.poutput("verbose mode")
+        handler = cmd2_handler.get()
+        if handler:
+            handler()
+
+    @cmd2.with_annotated(subcommand_to="manage", base_command=True, help="manage projects")
+    def manage_project(self, *, cmd2_handler) -> None:
+        handler = cmd2_handler.get()
+        if handler:
+            handler()
+
+    @cmd2.with_annotated(subcommand_to="manage project", help="add a project")
+    def manage_project_add(self, name: str) -> None:
+        self.poutput(f"project added: {name}")
+
+    @cmd2.with_annotated(subcommand_to="manage project", help="list projects")
+    def manage_project_list(self) -> None:
+        self.poutput("project list: demo")
+
     # -- Preserve quotes -----------------------------------------------------
 
     @cmd2.with_annotated(preserve_quotes=True)