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.

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

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,
)

339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403

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()

405
406
407
408
409
410
411

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)

425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442

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()

444
445
446
447
448
449
450
451

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

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

457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477

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,
)

2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306

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 = _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))

    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,
)

2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657

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:])
        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)

            func_kwargs = _filtered_namespace_kwargs(ns, accepted=accepted, exclude_subcommand=base_command)

            if with_unknown_args:
                func_kwargs["_unknown"] = unknown

            func_kwargs.update(kwargs)
            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