cmd2.annotated

Build argparse parsers from type-annotated function signatures.

The with_annotated decorator inspects a command function's type hints and default values to build a Cmd2ArgumentParser. Argument and Option metadata classes give finer per-parameter control via typing.Annotated.

Parameters without defaults become positional arguments; parameters with defaults become --option flags; keyword-only parameters (after *) are always options. A bool option is a flag, not a value: when absent it means False (or None for bool | None), so it defaults to that and is never required. A *args parameter becomes a variadic positional accepting zero or more values (nargs='*'), collected into a tuple. Underscores in a parameter name become dashes in the generated 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_subcommand_func receives the subcommand handler:

class MyApp(cmd2.Cmd):
    @cmd2.with_annotated
    def do_greet(self, name: str, count: int = 1, loud: bool = False):
        for _ in range(count):
            msg = f"Hello {name}"
            self.poutput(msg.upper() if loud else msg)

Use Annotated with Argument or Option for finer control over individual parameters:

from typing import Annotated


class MyApp(cmd2.Cmd):
    def color_choices(self) -> cmd2.Choices:
        return cmd2.Choices.from_values(["red", "green", "blue"])

    @cmd2.with_annotated
    def do_paint(
        self,
        item: str,
        color: Annotated[str, Option("--color", "-c", choices_provider=color_choices, help_text="Color to use")] = "blue",
    ):
        self.poutput(f"Painting {item} {color}")

How annotations map to argparse settings:

• str -- default string argument
• int, float -- sets type=
• bool option -- --flag / --no-flag via BooleanOptionalAction; defaults to False (or None for bool | None) when omitted, so it is never required
• positional bool -- parsed from true/false, yes/no, on/off, 1/0
• pathlib.Path -- sets type=Path
• enum.Enum subclass -- type=converter, choices from member values
• a union of Enums (e.g. EnumA | EnumB) -- each member keeps its own converter; a token resolves to the first member that accepts it, and the merged choices are the concatenation of each member's choices
• decimal.Decimal -- sets type=Decimal
• Literal[...] -- type=converter and choices from the literal values
• list[T] / set[T] / frozenset[T] / tuple[T, ...] -- nargs='+' (or '*' with a default or | None)
• tuple[T, T] (fixed arity, same type) -- nargs=N with type=T
• *args: T -- variadic positional (nargs='*'); T is each value's type, not the collected tuple. Annotated[T, Argument(...)] metadata is honored
• T | None (no default) -- positional with nargs='?' (0-or-1 tokens)
• T | None = None -- --flag option with default=None

A value option with no default is made required (omitting it would pass None, violating a non-Optional hint); annotate it T | None or give it a default to make it omittable.

Explicit Option(action=...) is type-checked so the parsed result matches the declared type:

• store_true / store_false -- require a bool parameter (type= is dropped; argparse supplies the False/True default)
• count -- requires an int parameter; defaults to 0 (None for int | None)
• append / extend -- require a list[T] parameter and default to [] (append takes one value per flag; extend takes nargs values per flag)
• store_const / append_const -- store the Option(const=...) value (type= is dropped). The action is inferred from the type when action= is omitted: a scalar Option(const=X) becomes store_const (present -> const, absent -> the default, which must exist or be T | None); a list[T] Option(const=X) becomes append_const (each flag appends const; defaults to []). A scalar Option(const=X) given an explicit nargs (e.g. nargs='?') instead keeps the store action for argparse's optional-value idiom (absent -> default, bare flag -> const, flag VALUE -> converted VALUE); the const is stored verbatim and must match the declared type. const is validated against the declared type and is rejected on a positional Argument (argparse ignores it there)
• a custom argparse.Action subclass -- passed straight through to add_argument. The user's class owns storage, so the collection-casting wrapper is dropped and the action-specific type/const/collection-shape constraints are skipped. The type-inferred converter, default, and required are still applied; the action receives them like any hand-built add_argument call. action='help' and action='version' are not supported.

The zero-argument actions above (store_true / store_false / count / store_const / append_const) take no value from the command line, so the value-oriented metadata inferred from the type is dropped before add_argument is called: the type= converter, the static choices, and any inferred tab-completer (e.g. the path completer for Path). There is nothing to complete or convert on a value-less action. A completer that was only inferred from the type is dropped silently, but a completer / choices_provider you supply explicitly on such an action is a contradiction and raises TypeError (matching argparse, which rejects it outright). Actions that do consume values (append / extend on a list[T], or a plain value option) keep the inferred converter and completer unchanged.

The metadata classes refuse a handful of add_argument kwargs that the decorator derives from the signature itself, so passing them through Argument(...) / Option(...) raises TypeError: type (from the annotation), dest (from the parameter name), help (use the help_text parameter, which maps to it -- a raw help would silently shadow it), and -- on Argument only -- action / required (which have no meaning on a positional). Every other add_argument parameter, including those registered via register_argparse_argument_parameter, passes through unchanged.

A default may be supplied either as the function-signature default (param: T = v) or as Argument(default=v) / Option(default=v) -- the two forms are equivalent. Specifying both at once raises TypeError (the value would have two sources of truth), and argparse.SUPPRESS is rejected as a default from either source because it would remove the keyword argument the function expects.

Parser-level customization is forwarded to Cmd2ArgumentParser's constructor via PEP 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, completer_class, and on Python >= 3.14 suggest_on_error / color -- flows straight through; the 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 behaviors layer on top of the raw passthrough: if description is omitted, the first paragraph of func.__doc__ (up to the first blank line) is used so docstrings double as help text without leaking :param: directives; and prog is rejected with subcommand_to because cmd2 rewrites it from the parent command's hierarchy. Mutually exclusive groups accept Group(required=True) to require exactly one member; the same flag on a plain groups= entry raises ValueError (argparse's add_argument_group has no required). Give a mutually_exclusive_groups entry a title/description to render it as a titled help section (argparse's one supported nesting -- a mutex inside an argument group), and use Option(action='store_true') for any bool member so the mutex reads as [--foo | --bar] instead of expanding to --no-* variants. To put non-mutex parameters in the same section, list its members in a groups= entry instead and leave the title off the mutex; declaring the section in both places, a mutex that sits only partly in a groups= entry, or one that spans two of them all raise ValueError. The other three nesting directions (an argument group in an argument group or in a mutex, and a mutex in a mutex) are removed in argparse on Python 3.14 and cannot be expressed here. These group-spec rules (and member references, double-assignment, and the required=True rejection) are checked at decoration time from parameter names alone -- type hints are not resolved, so forward-referenced annotations still decorate -- meaning a misconfigured group raises when the class is defined rather than on first command use. The one group rule that needs the annotations (a required member in a mutually exclusive group) fires when the parser is built.

A parameter annotated with a @dataclass that subclasses ArgumentBlock is a reusable argument block: each of the dataclass's init fields is expanded into a flat command-line argument (field name == argument name) at the parameter's position, and the parsed values are reconstructed into a dataclass instance passed to the command. This lets several commands share one block without duplicating parameters, and a base block shared by inheritance is the reuse mechanism (a subclass of a block is itself a block):

@dataclass
class CommonArgs(cmd2.ArgumentBlock):
    verbose: Annotated[bool, Option("-v", "--verbose")] = False
    output: Annotated[Path | None, Option("--output")] = None


class MyApp(cmd2.Cmd):
    @cmd2.with_annotated
    def do_build(self, target: str, common: CommonArgs):
        if common.verbose:
            self.poutput(common.output)

The ArgumentBlock trait -- not "is a dataclass" -- is the trigger, so a plain @dataclass is never expanded and can still be used as an ordinary single argument value (e.g. with an Argument(converter=...)). Each field carries the usual Annotated[T, Option(...)] / Annotated[T, Argument(...)] metadata and behaves exactly as a top-level parameter of the same shape (type inference, completion, choices). The dataclass is the single source of truth for defaults: a field with a default (default or default_factory) is emitted with argparse.SUPPRESS and filled by the dataclass constructor at reconstruction time, so a default_factory yields a fresh value per invocation (no shared-mutable default) and __post_init__ runs. A field with no default becomes a required argument. A field whose type is itself a block is not expanded (no recursion) and raises the unsupported-type error. Because fields expand flat, every field name must be unique across the command's own parameters and every other block's fields -- a collision (which would put two argparse actions on one namespace dest) raises TypeError when the parser is built. Block fields cannot participate in groups= / mutually_exclusive_groups= (those reference the function's own parameter names, which are validated without resolving type hints). A block must be the bare annotation of a regular parameter: wrapping it in Annotated/Optional/a union, or using it as *args / **kwargs, raises TypeError (to use a dataclass as a single value instead, make it a plain @dataclass with an Argument(converter=...)). An ArgumentBlock subclass that is not a @dataclass has no fields and also raises TypeError.

Unsupported patterns (raise TypeError):

• a non-Optional type with a None default (e.g. name: str = None); annotate it T | None or use a non-None default. Any/object/unannotated are exempt
• a scalar type with no converter (e.g. datetime.datetime, uuid.UUID, bytes, or any custom class), which would silently arrive as a plain string. Supported scalars are str, int, float, bool, decimal.Decimal, pathlib.Path, enum.Enum subclasses, and Literal[...] (str/Any/object pass through raw)
• str | int -- a union of multiple non-None types is ambiguous (unless every member is an enum.Enum subclass, which resolves by trying each member's converter in turn)
• tuple[int, str, float] -- mixed element types (argparse applies one type= per argument)
• *args: tuple[T, ...] (or any collection element) -- the annotation is each value's type, so a collection element means a tuple-of-collections; annotate the element, e.g. *args: str
• *args: Annotated[T, Option(...)] -- *args is always positional; use Argument()
• *args: Annotated[T, Argument(nargs=N)] -- *args arity is fixed to nargs='*'
• a keyword-only parameter annotated with Argument() -- it marks a positional; use Option()
• a required option (no default, not T | None) in a mutually_exclusive_groups group -- only one member is supplied, so the others arrive as None; give it a default or T | None
• Annotated[T, Argument(nargs=N)] producing a list ('*', '+', integer >= 1) on a non-collection T; use list[T] or tuple[T, ...] to match the runtime shape
• Annotated[tuple[T, T], Argument(nargs=N)] where N differs from the tuple's arity
• Option(action=...) whose result type mismatches the declared type, an unsupported action, or a non-list action on a collection (use append/extend/append_const with list[T])
• a variable-arity positional (T | None, list[T], tuple[T, ...]) followed by another positional -- it must come last (def f(self, a: str, *rest: str) is fine)

When combining Annotated with Optional, the union should go inside: Annotated[T | None, meta]. Annotated[T, meta] | None is ambiguous and raises -- unless the inner type already carries the None (Annotated[T | None, meta] | None), in which case the redundant outer | None is accepted as equivalent to Annotated[T | None, meta].

Path and Enum annotations also get automatic tab completion. A user-supplied choices_provider or completer drives completion in place of the inferred static choices, while the inferred type converter is kept so values still coerce to the declared type (an Enum to its member, Literal[1, 2] to int) and out-of-type values are rejected at parse time. An Enum accepts both member values and member names on the command line (completion and --help show the values).

An explicit choices= is reconciled with the inferred type rather than fighting it: its values are run through the inferred type converter so they match argparse's post-conversion comparison (Annotated[int, Option('--n', choices=['1', '2'])] becomes choices=[1, 2], so --n 1 matches; a value the converter rejects is a build-time TypeError), and an explicit choices= takes precedence over a type-inferred completer (the Path completer is dropped so the choices drive both validation and completion). A choices_provider / completer you supply yourself still wins over choices=.

Two hooks customize the string -> value conversion, parity with a hand-built add_argument(type=...) (a raw type= in the metadata is rejected; use these instead):

• converter -- a Callable[[str], Any] that replaces the inferred type= converter. Because the converter owns the conversion, the annotation is no longer required to be a supported scalar -- any type is legal (Annotated[datetime, Argument(converter=parse_iso)]), and the "unsupported type" error is suppressed. The inferred choices and completer (which described the inferred value-space) are dropped; supply choices= / completer / choices_provider to re-add them (an explicit choices= is still run through your converter). argparse applies it per token, so on a list[T] it converts each value; a non-collection annotation such as Any keeps a single token, so the converter may itself return a collection (Annotated[Any, Option('--idx', converter=parse_intset)]).
• preprocess -- a Callable[[str], str] that runs before the inferred converter, transforming the raw token while keeping the inferred type=, choices, completer, and coercion. Use it to normalize input for a type that already has rich inference, e.g. Annotated[Color, Argument(preprocess= str.lower)] accepts RED while still showing the Color choices, or Annotated[Path, Argument(preprocess=os.path.expanduser)] keeps the path completer. With a plain str (no inferred converter) it becomes the type= directly.

converter and preprocess are mutually exclusive on one parameter (fold the preprocessing into the converter, which already receives the raw token), and neither may be combined with a value-less action (store_true / store_false / count / store_const / append_const), which consumes no token to convert.

ArgMetadata = Argument | Option | None

NS_ATTR_BASE_ARGS = constants.cmd2_public_attr_name(
    "base_args"
)

NS_ATTR_PARENT_ARGS = constants.cmd2_public_attr_name(
    "parent_args"
)

prog

usage

description

epilog

parents

formatter_class

prefix_chars

fromfile_prefix_chars

argument_default

conflict_handler

add_help

allow_abbrev

exit_on_error

suggest_on_error

color

completer_class

Argument(
    *,
    help_text=None,
    metavar=None,
    nargs=None,
    choices=None,
    choices_provider=None,
    completer=None,
    table_columns=None,
    suppress_tab_hint=None,
    const=_UNSET,
    default=_UNSET,
    allow_unknown_entry=False,
    converter=None,
    preprocess=None,
    **extra_kwargs,
)

382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446

def __init__(
    self,
    *,
    help_text: str | None = None,
    metavar: str | tuple[str, ...] | None = None,
    nargs: _NargsValue | None = None,
    choices: Iterable[Any] | None = None,
    choices_provider: UnboundChoicesProvider[CmdOrSetT] | None = None,
    completer: UnboundCompleter[CmdOrSetT] | None = None,
    table_columns: Sequence[str | Column] | None = None,
    suppress_tab_hint: bool | None = None,
    const: Any = _UNSET,
    default: Any = _UNSET,
    allow_unknown_entry: bool = False,
    converter: Callable[[str], Any] | None = None,
    preprocess: Callable[[str], str] | None = None,
    **extra_kwargs: Any,
) -> None:
    """Initialise shared metadata fields.

    ``const`` is the value stored on a present flag with no argument (``Option`` only:
    ``store_const``/``append_const``); ``_UNSET`` distinguishes "no const" from ``const=None``.
    ``default`` mirrors the signature default (``Option(default=v)`` == ``... = v``); supplying
    both, or ``argparse.SUPPRESS``, is rejected.  ``allow_unknown_entry`` only affects ``Enum``
    annotations: when set, a token matched by neither a member value nor name is routed through
    the enum's ``_missing_`` hook (for aliases / special keywords) instead of being rejected
    outright.  ``converter`` replaces the inferred ``type=`` converter (and makes any annotation
    type legal); ``preprocess`` runs before the inferred converter to transform the raw token while
    keeping the inferred choices/completer.  The two are mutually exclusive and neither combines with
    a value-less action (see the module docstring).  ``extra_kwargs`` forwards any other
    ``add_argument`` parameter (incl. those from
    [`register_argparse_argument_parameter`][cmd2.argparse_utils.register_argparse_argument_parameter]) straight through.
    """
    reserved = self._RESERVED_EXTRA_KWARGS & extra_kwargs.keys()
    if reserved:
        name = sorted(reserved)[0]
        # Per-key remediation hint for the reserved kwarg.
        hint = {
            "type": (
                "The converter is derived from the parameter annotation; change the annotation, or pass "
                "converter= for a custom string -> value callable (preprocess= to transform the token first)."
            ),
            "dest": "The dest is the parameter name; rename the parameter instead.",
            "action": "Use Option(action=...) (only Option supports an action; Argument is always positional).",
            "required": (
                "Use Option(required=True); a positional Argument is always required unless it has "
                "a default or is annotated as `T | None`."
            ),
            "help": "Use the help_text= parameter instead; it maps to argparse's help= and would otherwise be shadowed.",
        }[name]
        raise TypeError(f"{type(self).__name__}({name}=...) is not accepted by @with_annotated. {hint}")
    self.help_text = help_text
    self.metavar = metavar
    self.nargs = nargs
    self.choices = choices
    self.choices_provider = choices_provider
    self.completer = completer
    self.table_columns = table_columns
    self.suppress_tab_hint = suppress_tab_hint
    self.const = const
    self.default = default
    self.allow_unknown_entry = allow_unknown_entry
    self.converter = converter
    self.preprocess = preprocess
    self.extra_kwargs = extra_kwargs

help_text = help_text

metavar = metavar

nargs = nargs

choices = choices

choices_provider = choices_provider

completer = completer

table_columns = table_columns

suppress_tab_hint = suppress_tab_hint

const = const

default = default

allow_unknown_entry = allow_unknown_entry

converter = converter

preprocess = preprocess

extra_kwargs = extra_kwargs

to_kwargs()

448
449
450
451
452
453
454

def to_kwargs(self) -> dict[str, Any]:
    """Return non-None mapped fields, an explicit ``const``, and any passthrough ``extra_kwargs``."""
    kwargs = {kwarg: val for attr, kwarg in self._KWARGS_MAP.items() if (val := getattr(self, attr)) is not None}
    if self.const is not _UNSET:
        kwargs["const"] = self.const
    kwargs.update(self.extra_kwargs)
    return kwargs

Option(*names, action=None, required=False, **kwargs)

468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485

def __init__(
    self,
    *names: str,
    action: str | type[argparse.Action] | None = None,
    required: bool = False,
    **kwargs: Any,
) -> None:
    """Initialise Option metadata.

    ``action`` is a supported string action (``store_true``/``store_false``/``count``/
    ``append``/``extend``/``store_const``/``append_const``) or a custom
    `argparse.Action` subclass (passed through; it owns storage, so the inferred
    action and the action-specific constraints are skipped).
    """
    super().__init__(**kwargs)
    self.names = names
    self.action = action
    self.required = required

names = names

action = action

required = required

help_text = help_text

metavar = metavar

nargs = nargs

choices = choices

choices_provider = choices_provider

completer = completer

table_columns = table_columns

suppress_tab_hint = suppress_tab_hint

const = const

default = default

allow_unknown_entry = allow_unknown_entry

converter = converter

preprocess = preprocess

extra_kwargs = extra_kwargs

to_kwargs()

487
488
489
490
491
492
493
494

def to_kwargs(self) -> dict[str, Any]:
    """Return non-None fields as an argparse kwargs dict."""
    kwargs = super().to_kwargs()
    if self.action is not None:
        kwargs["action"] = self.action
    if self.required:
        kwargs["required"] = True
    return kwargs

@dataclass
class CommonArgs(ArgumentBlock):
    verbose: Annotated[bool, Option("-v", "--verbose")] = False


class MyApp(cmd2.Cmd):
    @cmd2.with_annotated
    def do_build(self, target: str, common: CommonArgs): ...

@dataclass
class SharedOpts(ArgumentBlock):
    verbose: Annotated[bool, Option("-v", "--verbose")] = False


class MyApp(cmd2.Cmd):
    @cmd2.with_annotated(base_command=True)
    def do_root(self, cmd2_subcommand_func, cmd2_base_args: SharedOpts): ...

    @cmd2.with_annotated(subcommand_to="root")
    def root_show(self, cmd2_parent_args: SharedOpts):
        self.poutput(cmd2_parent_args.verbose)  # parsed on `root`, read here

Group(
    *members, title=None, description=None, required=False
)

546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566

def __init__(
    self,
    *members: str,
    title: str | None = None,
    description: str | None = None,
    required: bool = False,
) -> None:
    """Initialise an argument group definition.

    :param members: parameter names to place in the group (at least one)
    :param title: group title shown as a help section header
    :param description: group description shown under the title
    :param required: ``mutually_exclusive_groups`` only -- require exactly one member.
                     On a ``groups=`` entry it raises ``ValueError``.
    """
    if not members:
        raise ValueError("Group requires at least one member parameter name")
    self.members = members
    self.title = title
    self.description = description
    self.required = required

members = members

title = title

description = description

required = required

build_parser_from_function(
    func,
    *,
    skip_params=_SKIP_PARAMS,
    groups=None,
    mutually_exclusive_groups=None,
    parser_class=None,
    **parser_kwargs,
)

2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770

def build_parser_from_function(
    func: Callable[..., Any],
    *,
    skip_params: frozenset[str] = _SKIP_PARAMS,
    groups: tuple[Group, ...] | None = None,
    mutually_exclusive_groups: tuple[Group, ...] | None = None,
    parser_class: type[Cmd2ArgumentParser] | None = None,
    **parser_kwargs: Unpack[Cmd2ParserKwargs],
) -> Cmd2ArgumentParser:
    """Inspect a function's signature and build a ``Cmd2ArgumentParser``.

    The lower-level entry point behind [`with_annotated`][cmd2.annotated.with_annotated].  ``parser_kwargs`` is forwarded to
    the parser ctor (see [`Cmd2ParserKwargs`][cmd2.annotated.Cmd2ParserKwargs]); when ``description`` is omitted, the first
    paragraph of ``func.__doc__`` is used.

    :param func: the command function to inspect
    :param skip_params: parameter names to exclude from the parser
    :param groups: [`Group`][cmd2.annotated.Group] instances assigning parameters to argument groups
    :param mutually_exclusive_groups: [`Group`][cmd2.annotated.Group] instances of mutually exclusive parameters
    :param parser_class: custom parser class (defaults to the configured default)
    :param parser_kwargs: forwarded [`Cmd2ParserKwargs`][cmd2.annotated.Cmd2ParserKwargs]
    :return: a fully configured ``Cmd2ArgumentParser``
    """
    from . import argparse_utils

    # The decorator already ran this at decoration time; direct callers get the same checks here.
    _validate_group_specs(func, skip_params=skip_params, groups=groups, mutually_exclusive_groups=mutually_exclusive_groups)

    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:
            parser_kwargs["description"] = auto_description
    parser = parser_cls(**parser_kwargs)

    # _resolve_parameters validates each argument and the cross-argument rules (e.g. a variable-arity
    # positional must be last; a required member in a mutex group) once the whole list is built.
    resolved, base_args_types = _resolve_parameters(
        func,
        skip_params=skip_params,
        mutually_exclusive_groups=mutually_exclusive_groups,
    )

    # ``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:
        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 (specs already validated by _validate_group_specs above).
    target_for, argument_group_for = _build_argument_group_targets(parser, groups=groups)
    _apply_mutex_group_targets(
        parser,
        target_for=target_for,
        argument_group_for=argument_group_for,
        mutually_exclusive_groups=mutually_exclusive_groups,
    )

    # Add each argument to its target (its group/mutex group if assigned, else the parser).
    for arg in resolved:
        arg.add_to(target_for.get(arg.name, parser))

    # A cmd2_base_args block is inheritable: stamp a parse-time presence marker so a descendant's
    # cmd2_parent_args can confirm an ancestor actually declared the block.
    for base_args_type in base_args_types:
        parser.set_defaults(**{_base_args_marker_dest(base_args_type): True})

    return parser

with_annotated(
    func: Callable[_CommandParams, _CommandReturn],
) -> Callable[_CommandParams, _CommandReturn]

with_annotated(
    func: None = ...,
    *,
    ns_provider: Callable[..., Namespace] | None = ...,
    preserve_quotes: bool = ...,
    with_unknown_args: bool = ...,
    base_command: bool = ...,
    subcommand_to: str | None = ...,
    help: str | None = ...,
    aliases: Sequence[str] = ...,
    deprecated: bool = ...,
    groups: tuple[Group, ...] | None = ...,
    mutually_exclusive_groups: tuple[Group, ...]
    | None = ...,
    parser_class: type[Cmd2ArgumentParser] | None = ...,
    subcommand_required: bool = ...,
    subcommand_metavar: str = ...,
    subcommand_title: str | None = ...,
    subcommand_description: str | None = ...,
    **parser_kwargs: Unpack[Cmd2ParserKwargs],
) -> _WithAnnotatedDecorator

with_annotated(
    func=None,
    *,
    ns_provider=None,
    preserve_quotes=False,
    with_unknown_args=False,
    base_command=False,
    subcommand_to=None,
    help=None,
    aliases=(),
    deprecated=False,
    groups=None,
    mutually_exclusive_groups=None,
    parser_class=None,
    subcommand_required=True,
    subcommand_metavar="SUBCOMMAND",
    subcommand_title=None,
    subcommand_description=None,
    **parser_kwargs,
)

2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128

def with_annotated(
    func: Callable[..., Any] | None = None,
    *,
    ns_provider: Callable[..., argparse.Namespace] | None = None,
    preserve_quotes: bool = False,
    with_unknown_args: bool = False,
    base_command: bool = False,
    subcommand_to: str | None = None,
    help: str | None = None,  # noqa: A002
    aliases: Sequence[str] = (),
    deprecated: bool = False,
    groups: tuple[Group, ...] | None = None,
    mutually_exclusive_groups: tuple[Group, ...] | None = None,
    parser_class: type[Cmd2ArgumentParser] | None = None,
    subcommand_required: bool = True,
    subcommand_metavar: str = "SUBCOMMAND",
    subcommand_title: str | None = None,
    subcommand_description: str | None = None,
    **parser_kwargs: Unpack[Cmd2ParserKwargs],
) -> Callable[..., Any] | Callable[[Callable[..., Any]], Callable[..., Any]]:
    """Decorate a ``do_*`` method to build its argparse parser from type annotations.

    :param func: the command function (when used without parentheses)
    :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_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``)
    :param deprecated: mark the subcommand deprecated in ``--help`` (only with ``subcommand_to``)
    :param groups: [`Group`][cmd2.annotated.Group] instances assigning parameters to titled argument groups
    :param mutually_exclusive_groups: [`Group`][cmd2.annotated.Group] instances of mutually exclusive parameters
    :param parser_class: custom parser class (defaults to the configured default)
    :param subcommand_required: whether a subcommand must be supplied (``base_command`` only)
    :param subcommand_metavar: metavar for the subcommands group (``base_command`` only)
    :param subcommand_title: title for the subcommands ``--help`` section (``base_command`` only)
    :param subcommand_description: description for that section (``base_command`` only)
    :param parser_kwargs: any [`Cmd2ArgumentParser`][cmd2.argparse_utils.Cmd2ArgumentParser] ctor kwarg
                          (see [`Cmd2ParserKwargs`][cmd2.annotated.Cmd2ParserKwargs]).
                          ``description`` defaults to the docstring's first paragraph when omitted;
                          ``prog`` is rejected with ``subcommand_to`` (cmd2 rewrites it from the parent).
    """
    if aliases is None:
        raise TypeError(
            "aliases must be a sequence of subcommand-name strings (e.g. ('co', 'ci')), not None; "
            "omit it or pass an empty tuple for no aliases."
        )
    if (help is not None or aliases or deprecated) and subcommand_to is None:
        raise TypeError("'help', 'aliases', and 'deprecated' are only valid with subcommand_to")
    if subcommand_to is not None:
        unsupported: list[str] = []
        if ns_provider is not None:
            unsupported.append("ns_provider")
        if preserve_quotes:
            unsupported.append("preserve_quotes")
        if with_unknown_args:
            unsupported.append("with_unknown_args")
        if "prog" in parser_kwargs:
            # cmd2's subcommand machinery (``update_prog``) rewrites prog from the parent
            # command hierarchy, so any value supplied here would be silently overwritten.
            unsupported.append("prog")
        if unsupported:
            names = ", ".join(unsupported)
            raise TypeError(
                f"{names} {'is' if len(unsupported) == 1 else 'are'} not supported with subcommand_to. "
                "Configure these behaviors on the base command instead."
            )

    options = _ParserBuildOptions(
        groups=groups,
        mutually_exclusive_groups=mutually_exclusive_groups,
        parser_class=parser_class,
        parser_kwargs=dict(parser_kwargs),
        subcommand_required=subcommand_required,
        subcommand_metavar=subcommand_metavar,
        subcommand_title=subcommand_title,
        subcommand_description=subcommand_description,
    )

    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
        if with_unknown_args:
            unknown_param = inspect.signature(fn).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")

        if not base_command and constants.NS_ATTR_SUBCOMMAND_FUNC in inspect.signature(fn).parameters:
            raise TypeError(
                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:
            handler, subcmd_name, subcmd_parser_builder = _build_subcommand_handler(
                fn,
                subcommand_to,
                base_command=base_command,
                options=options,
            )
            subcommand_spec = SubcommandSpec(
                name=subcmd_name,
                command=subcommand_to,
                help=help,
                aliases=tuple(aliases),
                deprecated=deprecated,
                parser_source=subcmd_parser_builder,
            )
            setattr(handler, constants.SUBCOMMAND_ATTR_SPEC, subcommand_spec)
            return handler

        command_name = fn.__name__[len(constants.COMMAND_FUNC_PREFIX) :]

        skip_params = _SKIP_PARAMS | ({"_unknown"} if with_unknown_args else frozenset())
        # Validate the group specs eagerly (decoration time) so a misconfigured group hard-fails when
        # the class is defined; the name-only checks never resolve type hints, so forward-referenced
        # annotations still decorate and the parser build stays deferred.
        _validate_group_specs(
            fn,
            skip_params=skip_params,
            groups=options.groups,
            mutually_exclusive_groups=options.mutually_exclusive_groups,
        )
        if base_command:
            # Validate eagerly (decoration time); the base-command rows in _CONSTRAINTS fire here.
            _resolve_parameters(fn, skip_params=skip_params, base_command=True)

        # Cache signature introspection at decoration time, not per-invocation
        accepted = set(list(inspect.signature(fn).parameters.keys())[1:])
        resolve_blocks = _lazy_block_resolver(fn, base_accepted=accepted, skip_params=skip_params)
        leading_names, var_positional_name = _var_positional_call_plan(fn)

        parser_builder = _make_parser_builder(fn, skip_params=skip_params, base_command=base_command, options=options)

        @functools.wraps(fn)
        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(
                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}")

            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, namespace)
                else:
                    ns = arg_parser.parse_args(parsed_arglist, namespace)
                    unknown = None
            except SystemExit as exc:
                raise Cmd2ArgparseError from exc

            setattr(ns, constants.NS_ATTR_STATEMENT, statement)
            handler = getattr(ns, constants.NS_ATTR_SUBCOMMAND_FUNC, None)
            if base_command and handler is not None:
                handler = functools.partial(handler, ns)
            setattr(ns, constants.NS_ATTR_SUBCOMMAND_FUNC, handler)

            blocks, eff_accepted = resolve_blocks()
            func_kwargs = _filtered_namespace_kwargs(ns, accepted=eff_accepted, exclude_subcommand=base_command)

            if with_unknown_args:
                func_kwargs["_unknown"] = unknown

            func_kwargs.update(kwargs)
            _reconstruct_dataclass_blocks(func_kwargs, blocks, ns)
            result: bool | None = _invoke_command_func(
                fn, owner, func_kwargs, leading_names=leading_names, var_positional_name=var_positional_name
            )
            return result

        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

    # Support both @with_annotated and @with_annotated(...)
    if func is not None:
        return decorator(func)
    return decorator