cmd2.annotated

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

    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/cross-config rules (e.g. a
    # variable-arity positional must be last; double-assignment and required-mutex-member) once the
    # whole list is built and the group memberships are linked.
    resolved = _resolve_parameters(
        func,
        skip_params=skip_params,
        groups=groups,
        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 (member references already validated by _resolve_parameters).
    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

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