feat(parser): bind parser to command instance and improve subparser handling

Author: Ovizro

src/ptcmd/command.py

@@ -6,7 +6,6 @@
 
 import sys
 from argparse import ArgumentParser, Namespace, _SubParsersAction
-from copy import copy
 from functools import partial, update_wrapper
 from types import MethodType
 from typing import (
@@ -30,7 +29,7 @@
 
 from .argument import build_parser, invoke_from_ns
 from .completer import ArgparseCompleter
-from .info import CommandInfo, CompleterGetterFunc
+from .info import CommandInfo, CompleterGetterFunc, bind_parser
 
 if TYPE_CHECKING:
     from .core import BaseCmd
@@ -262,7 +261,7 @@ def _ensure_subparsers(self) -> _SubParsersAction:
         for action in self.parser._actions:
             if isinstance(action, _SubParsersAction):
                 return action
-        return self.parser.add_subparsers(metavar='SUBCOMMAND')
+        return self.parser.add_subparsers(metavar='SUBCOMMAND', required=True)
 
     @overload
     def __get__(self, instance: None, owner: Optional[type]) -> Self: ...
@@ -305,10 +304,7 @@ def __cmd_info__(self, cmd: "BaseCmd") -> CommandInfo:
         else:
             assert self.__func__.__name__.startswith(cmd.COMMAND_FUNC_PREFIX), f"{self.__func__} is not a command function"
             cmd_name = self.__func__.__name__[len(cmd.COMMAND_FUNC_PREFIX) :]
-        parser = self.parser
-        if parser.prog != cmd_name:
-            parser = copy(parser)
-            parser.prog = cmd_name
+        parser = bind_parser(self.parser, cmd_name, cmd)
         if self._completer_getter is not None:
             completer = self._completer_getter(cmd)
         else:

src/ptcmd/core.py

@@ -2,7 +2,9 @@
 import pydoc
 import shlex
 import sys
-from argparse import Action, ArgumentParser
+import warnings
+from abc import ABCMeta
+from argparse import _StoreAction
 from asyncio import iscoroutine
 from collections import defaultdict
 from subprocess import run
@@ -13,7 +15,6 @@
     Coroutine,
     Dict,
     List,
-    Literal,
     Optional,
     Sequence,
     Set,
@@ -23,7 +24,6 @@
     Union,
     cast,
 )
-import warnings
 
 from prompt_toolkit.completion import Completer, NestedCompleter
 from prompt_toolkit.formatted_text import ANSI, is_formatted_text
@@ -42,8 +42,8 @@
 
 from .argument import Arg
 from .command import auto_argument
-from .completer import ArgparseCompleter, MultiPrefixCompleter
-from .info import CommandInfo, CommandLike, build_cmd_info, set_info
+from .completer import MultiPrefixCompleter
+from .info import CommandInfo, CommandLike, build_cmd_info, set_info, get_cmd_ins
 from .theme import DEFAULT as THEME
 
 
@@ -64,7 +64,7 @@ async def _ensure_coroutine(coro: Union[Coroutine[Any, Any, _T], _T]) -> _T:
         return coro
 
 
-class BaseCmd(object):
+class BaseCmd(object, metaclass=ABCMeta):
     """Base class for command line interfaces in ptcmd.
 
     This class provides the core functionality for building interactive command-line
@@ -492,36 +492,17 @@ def __init_subclass__(cls, **kwds: Any) -> None:
 
 
 
-class _TopicAction(Action):
-    def __init__(
-        self,
-        option_strings: Sequence[str],
-        dest: str,
-        nargs: Optional[Literal[1]] = None,
-        default: None = None,
-        type: None = None,
-        choices: None = None,
-        required: bool = False,
-        help: Optional[str] = None,
-        metavar: Union[str, Tuple[str], None] = None,
-        cmd: Optional["Cmd"] = None,
-    ) -> None:
-        self.option_strings = option_strings
-        self.dest = dest
-        self.nargs = nargs
-        self.const = None
-        self.default = default
-        self.type = type
-        self.required = required
-        self.help = help
-        self.metavar = metavar
-        self.cmd = cmd
-
+class _TopicAction(_StoreAction):
     @property
     def choices(self) -> Optional[Sequence[str]]:
-        if self.cmd is None:  # pragma: no cover
+        cmd = get_cmd_ins(self)
+        if cmd is None:  # pragma: no cover
             return
-        return self.cmd.get_visible_commands()
+        return cmd.get_visible_commands()
+
+    @choices.setter
+    def choices(self, _: Any) -> None:
+        pass
 
 
 class Cmd(BaseCmd):
@@ -604,7 +585,12 @@ def __init__(
         self.nohelp = nohelp
 
     @auto_argument
-    def do_help(self, topic: str = "", *, verbose: Arg[bool, "-v", "--verbose"] = False) -> None:  # noqa: F821,B002
+    def do_help(
+        self,
+        topic: Arg[Optional[str], {"action": _TopicAction, "help": "Command or topic for help"}] = None,  # noqa: F821,F722,B002
+        *,
+        verbose: Arg[bool, "-v", "--verbose", {"help": "Show more detailed help"}] = False  # noqa: F821,F722,B002
+    ) -> None:
         """List available commands or provide detailed help for a specific command.
 
         :param topic: Command or topic for which to get help, defaults to ""
@@ -622,13 +608,6 @@ def do_help(self, topic: str = "", *, verbose: Arg[bool, "-v", "--verbose"] = Fa
             return self.perror(f"Unknown command: {topic}")
         return self.poutput(self._format_help_text(self.command_info[topic], verbose))
 
-    @do_help.completer_getter
-    def _help_completer(self) -> Completer:
-        parser = ArgumentParser("help", description=self.do_help.__doc__)
-        parser.add_argument("topic", nargs="?", help="Command or topic for help", action=_TopicAction, cmd=self)
-        parser.add_argument("-v", "--verbose", action="store_true", help="Show more detailed help")
-        return ArgparseCompleter(parser)
-
     def _help_menu(self, verbose: bool = False) -> None:
         """Display the help menu showing available commands and help topics.
 

src/ptcmd/info.py

@@ -4,7 +4,8 @@
 and retrieving command metadata.
 """
 
-from argparse import ArgumentParser
+import copy
+from argparse import Action, ArgumentParser, _SubParsersAction
 from types import MethodType
 from typing import TYPE_CHECKING, Any, Callable, List, NamedTuple, Optional, Protocol, Union
 
@@ -29,6 +30,10 @@
 CMD_ATTR_DISABLED = "disabled"
 CMD_ATTR_HELP_CATEGORY = "help_category"
 CMD_ATTR_SHUTCUT = "shortcut"
+PARSER_ATTR_CMD = "cmd_ins"
+PARSER_ATTR_NAME = "cmd_name"
+ACTION_ATTR_CMD = "cmd_ins"
+ACTION_ATTR_NAME = "cmd_name"
 
 
 class CommandInfo(NamedTuple):
@@ -111,3 +116,83 @@ def inner(func: CommandFunc) -> CommandFunc:
         return func
 
     return inner
+
+
+def bind_parser(parser: ArgumentParser, cmd_name: str, cmd_ins: "BaseCmd") -> ArgumentParser:
+    """
+    Binds an ArgumentParser to a command function.
+
+    Creates a copy of the parser, sets its prog to the full command path,
+    and binds the command name and command instance to the parser and all
+    its actions. Handles subparsers recursively. Raises ValueError if
+    the parser is already bound.
+
+    :param parser: The ArgumentParser to bind
+    :type parser: ArgumentParser
+    :param cmd_name: The name of the command
+    :type cmd_name: str
+    :param cmd_ins: The instance of the command
+    :type cmd_ins: BaseCmd
+    :return: The bound ArgumentParser
+    :rtype: ArgumentParser
+    :raises ValueError: If parser is already bound
+    """
+    # Check if parser is already bound
+    if hasattr(parser, PARSER_ATTR_CMD):
+        raise ValueError("Parser is already bound to a command")
+
+    # Create a shallow copy of the parser
+    new_parser = copy.copy(parser)
+
+    # Build full command path for this parser
+    if ' ' in new_parser.prog:
+        cmds = new_parser.prog.split(' ')
+        cmds[0] = cmd_name
+        new_parser.prog = ' '.join(cmds)
+    else:
+        new_parser.prog = cmd_name
+
+    # Bind command metadata to parser
+    try:
+        setattr(new_parser, PARSER_ATTR_CMD, cmd_ins)
+        setattr(new_parser, PARSER_ATTR_NAME, cmd_name)
+    except AttributeError:
+        pass
+
+    # Process all actions in the parser
+    new_actions = []
+    for action in new_parser._actions:
+        action = copy.copy(action)
+        # Bind command metadata to action
+        try:
+            setattr(action, ACTION_ATTR_CMD, cmd_ins)
+            setattr(action, ACTION_ATTR_NAME, cmd_name)
+        except AttributeError:
+            pass
+
+        # Handle subparsers recursively
+        if isinstance(action, _SubParsersAction):
+            for n, subparser in action.choices.items():
+                # Recursively bind subparsers
+                action.choices[n] = bind_parser(subparser, cmd_name, cmd_ins)
+        new_actions.append(action)
+
+    new_parser._actions = new_actions
+    return new_parser
+
+
+def get_cmd_ins(obj: Union["BaseCmd", ArgumentParser, Action]) -> Optional["BaseCmd"]:
+    """Get the BaseCmd instance from an object.
+
+    :param obj: The object to get the BaseCmd instance from
+    :type obj: Union[BaseCmd, ArgumentParser, Action]
+    :return: The BaseCmd instance
+    :rtype: Optional[BaseCmd]
+    """
+    from .core import BaseCmd
+    if isinstance(obj, BaseCmd):
+        return obj
+    elif isinstance(obj, ArgumentParser):
+        return getattr(obj, PARSER_ATTR_CMD, None)
+    elif isinstance(obj, Action):
+        return getattr(obj, ACTION_ATTR_CMD, None)

tests/test_command.py

@@ -264,10 +264,6 @@ def do_main_sub(self, arg: Optional[str] = None) -> None:
 
     cmd = TestCmd()
 
-    # Test main command
-    await cmd.onecmd("main --arg test")
-    assert cmd.output == "Main command: test"
-
     # Test subcommand
     await cmd.onecmd("main sub subarg")
     assert cmd.output == "Subcommand: subarg"