bitool 0.1.2__py3-none-any.whl

bitool/utils/cli_parser.py

@@ -0,0 +1,412 @@
+"""CLI 命令组解析器模块.
+
+本模块提供通用的 CLI 命令组解析器,允许通过简单的配置
+来定义复杂的命令行工具.
+
+核心功能
+--------
+- 声明式 CLI 命令组定义
+- 自动参数解析和验证
+- 支持子命令和参数配置
+- 与 TaskGroup 无缝集成
+- 统一的错误处理和日志记录
+
+快速开始
+--------
+>>> from pytola_core.command.cli_parser import CliParser
+>>> from pytola_core.command.task_group import TaskGroup, Task
+>>>
+>>> # 定义任务组工厂函数
+>>> def create_hello_group() -> TaskGroup:
+...     return TaskGroup(
+...         name="hello",
+...         commands=[
+...             Task(cmd=["echo", "Hello, World!"]),
+...         ],
+...     )
+>>>
+>>> # 创建解析器
+>>> parser = CliParser(
+...     name="mytool",
+...     description="我的命令行工具",
+...     command_factories={
+...         "hello": create_hello_group,
+...     }
+... )
+>>>
+>>> # 运行 CLI (模拟)
+>>> # parser.run()  # 实际使用时调用
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from ..core.logger import logger
+from .executor import RunResult
+from .task import Task
+from .task_group import TaskGroup
+
+
+@dataclass
+class ArgumentConfig:
+    """命令行参数配置."""
+
+    args: list[str] = field(default_factory=list)
+    help: str = ""
+    action: str = "store"
+    dest: str | None = None
+    default: Any = None
+    type: Any = None
+    choices: list[Any] | None = None
+    required: bool = False
+    nargs: str | int | None = None
+    metavar: str | None = None
+
+
+@dataclass
+class CliCommandConfig:
+    """CLI 命令配置."""
+
+    help: str = ""
+    arguments: list[ArgumentConfig] = field(default_factory=list)
+
+
+@dataclass
+class CliParser:
+    """CLI 命令组解析器.
+
+    用于将 TaskGroup 工厂函数映射到 CLI 子命令,
+    提供统一的参数解析、验证和执行逻辑.
+
+    Attributes
+    ----------
+    name : str
+        工具名称
+    description : str
+        工具描述信息
+    command_factories : dict[str, Callable[[], TaskGroup]]
+        命令名到 TaskGroup 工厂函数的映射
+    command_configs : dict[str, CliCommandConfig]
+        命令配置,用于定义子命令的参数
+    """
+
+    name: str
+    description: str = ""
+    command_factories: dict[str, Callable[[], TaskGroup]] = field(default_factory=dict)
+    command_configs: dict[str, CliCommandConfig] = field(default_factory=dict)
+
+    def add_command(
+        self,
+        name: str,
+        factory: Callable[[], TaskGroup] | TaskGroup,
+        config: CliCommandConfig | None = None,
+    ) -> CliParser:
+        """添加命令到解析器.
+
+        Parameters
+        ----------
+        name : str
+            命令名称
+        factory : Callable[[], TaskGroup] | TaskGroup
+            TaskGroup 工厂函数或 TaskGroup 实例
+        config : CliCommandConfig, optional
+            命令配置,用于定义子命令的参数
+
+        Returns
+        -------
+        CliParser
+            返回自身以支持链式调用
+        """
+        # 支持直接传入 TaskGroup 实例
+        if isinstance(factory, TaskGroup):
+            command_group = factory
+            self.command_factories[name] = lambda: command_group
+        else:
+            self.command_factories[name] = factory
+
+        if config is not None:
+            self.command_configs[name] = config
+        return self
+
+    def build_parser(self) -> argparse.ArgumentParser:
+        """构建 argparse 解析器.
+
+        Returns
+        -------
+        argparse.ArgumentParser
+            配置好的参数解析器
+        """
+        parser = argparse.ArgumentParser(
+            prog=self.name,
+            description=self.description,
+        )
+        subparsers = parser.add_subparsers(
+            dest="command",
+            help="可用命令",
+            required=True,
+        )
+
+        # 为每个命令创建子解析器
+        for cmd_name in self.command_factories:
+            cmd_config = self.command_configs.get(cmd_name, CliCommandConfig())
+            cmd_help = cmd_config.help or f"执行 {cmd_name} 命令"
+
+            sub_parser = subparsers.add_parser(cmd_name, help=cmd_help)
+
+            # 添加命令特定的参数
+            for arg_config in cmd_config.arguments:
+                kwargs = arg_config.__dict__.copy()
+                args = kwargs.pop("args", [])
+                # 移除内部字段,不传递给 argparse
+                kwargs.pop("condition_value", None)
+                kwargs.pop("alternative_commands", None)
+                kwargs = {k: v for k, v in kwargs.items() if v is not None and k != "help"}
+
+                # 位置参数（不以 - 或 -- 开头）不支持 required 属性
+                if args and not args[0].startswith("-"):
+                    kwargs.pop("required", None)
+
+                if arg_config.help:
+                    kwargs["help"] = arg_config.help
+                sub_parser.add_argument(*args, **kwargs)
+
+        return parser
+
+    def parse_args(self, args: list[str] | None = None) -> argparse.Namespace:
+        """解析命令行参数.
+
+        Parameters
+        ----------
+        args : list[str], optional
+            要解析的参数列表,默认使用 sys.argv[1:]
+
+        Returns
+        -------
+        argparse.Namespace
+            解析后的参数
+        """
+        parser = self.build_parser()
+        return parser.parse_args(args)
+
+    def add_cmd(
+        self,
+        name: str,
+        cmd: list[str] | Callable[[], RunResult],
+        description: str = "",
+        config: CliCommandConfig | None = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> CliParser:
+        """快捷添加单命令任务.
+
+        适用于只有一条命令的场景,免去嵌套 commands 列表.
+
+        Parameters
+        ----------
+        name : str
+            命令名称
+        cmd : list[str] | Callable[[], RunResult]
+            命令及其参数列表,或返回RunResult的可调用对象
+        description : str
+            命令描述
+        config : CliCommandConfig, optional
+            命令参数配置
+        **kwargs : Any
+            传递给 TaskGroup 的其他参数 (如 enabled, stop_on_failure)
+
+        Returns
+        -------
+        CliParser
+            返回自身以支持链式调用
+
+        Examples
+        --------
+        >>> # 使用命令列表
+        >>> parser.add_cmd("p", ["git", "push", "--all"], description="推送所有分支")
+        >>>
+        >>> # 使用可调用对象
+        >>> def my_task() -> RunResult:
+        ...     return RunResult(returncode=0, stdout="Done", stderr="", execution_time=0.0)
+        >>> parser.add_cmd("t", my_task, description="执行自定义任务")
+        """
+        if callable(cmd):
+            # 可调用对象,直接传递给 add_multi_commands
+            return self.add_multi_commands(
+                name,
+                commands=[cmd],
+                description=description,
+                config=config,
+                **kwargs,
+            )
+        else:
+            # 命令列表,使用原有的字典方式
+            return self.add_multi_commands(
+                name,
+                commands=[{"cmd": cmd}],
+                description=description,
+                config=config,
+                **kwargs,
+            )
+
+    def add_multi_commands(
+        self,
+        name: str,
+        commands: list[dict | Task | Callable[[], RunResult] | list[str]] | None = None,
+        description: str = "",
+        config: CliCommandConfig | None = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> CliParser:
+        """添加简单命令(便捷方法).
+
+        快速创建包含 Task 列表的任务组,适用于不需要动态生成的简单场景.
+
+        Parameters
+        ----------
+        name : str
+            命令名称
+        description : str
+            命令描述
+        commands : list, optional
+            Task 列表或可转换为 Task 的配置
+        config : CliCommandConfig, optional
+            命令参数配置
+        **kwargs : Any
+            传递给 TaskGroup 的其他参数
+
+        Returns
+        -------
+        CliParser
+            返回自身以支持链式调用
+
+        Examples
+        --------
+        >>> parser.add_multi_commands(
+        ...     "init",
+        ...     description="初始化仓库",
+        ...     commands=[
+        ...         {"cmd": ["git", "init"], "description": "初始化"},
+        ...         {"cmd": ["git", "add", "."], "description": "添加文件"},
+        ...     ],
+        ... )
+
+        >>> # 使用工厂函数实现条件命令
+        >>> def create_init_group(args: argparse.Namespace) -> TaskGroup:
+        ...     if getattr(args, "sub", False):
+        ...         commands = [{"func": init_repo_with_sub, "description": "初始化仓库及子文件夹"}]
+        ...     else:
+        ...         commands = [{"func": init_repo, "description": "初始化仓库"}]
+        ...     return TaskGroup(name="init", commands=[Task.from_dict(c) for c in commands])
+        >>>
+        >>> parser.add_command("i", create_init_group)
+        """
+        from .task_group import Task
+
+        # 创建工厂函数
+        def create_command_group(parsed_args: argparse.Namespace | None = None) -> TaskGroup:
+            """根据参数创建任务组."""
+            # 将字典或列表转换为 Task
+            items = []
+            if commands:
+                is_single = len(commands) == 1
+                for cmd in commands:
+                    if isinstance(cmd, dict):
+                        items.append(Task.from_dict(cmd))  # type: ignore[arg-type]
+                    elif isinstance(cmd, Task):
+                        items.append(cmd)
+                    elif callable(cmd):
+                        items.append(
+                            Task.from_callable(cmd, description=description if is_single else ""),  # type: ignore[arg-type]
+                        )
+                    elif isinstance(cmd, list):
+                        items.append(Task.from_list(cmd, description=description if is_single else ""))
+
+            return TaskGroup(
+                name=f"{self.name}-{name}",
+                description=description,
+                commands=items,
+                **kwargs,
+            )
+
+        return self.add_command(name, create_command_group, config or CliCommandConfig(help=description))
+
+    def run(self, args: list[str] | None = None) -> None:
+        """运行 CLI 工具.
+
+        Parameters
+        ----------
+        args : list[str], optional
+            要解析的参数列表,默认使用 sys.argv[1:]
+
+        Raises
+        ------
+        SystemExit
+            如果指定了无效命令或执行失败
+        """
+        parsed_args = self.parse_args(args)
+        command_name = parsed_args.command
+        factory = self.command_factories.get(command_name)
+
+        if not factory:
+            logger.error("无效命令: %s", command_name)
+            sys.exit(1)
+
+        try:
+            # 创建并执行任务组
+            # 尝试检查工厂函数是否接受参数
+            import inspect
+
+            sig = inspect.signature(factory)
+            params = list(sig.parameters.values())
+
+            # 如果函数接受参数（除了 self），则传递 parsed_args
+            command_group = factory(parsed_args) if len(params) > 0 else factory()  # type: ignore[call-arg]
+            results = command_group.execute()
+
+            # 检查执行结果
+            if results:
+                failed_count = sum(1 for r in results if not r.success)
+                if failed_count > 0:
+                    logger.warning(f"命令执行完成,但有 {failed_count} 个命令失败")
+                    sys.exit(1)
+
+        except (RuntimeError, ValueError, TypeError, OSError) as e:
+            logger.error(f"执行命令 '{command_name}' 时发生错误: {e}")
+            sys.exit(1)
+
+    @classmethod
+    def from_dict(cls, config: dict[str, Any]) -> CliParser:
+        """从字典配置创建解析器.
+
+        Parameters
+        ----------
+        config : dict[str, Any]
+            解析器配置字典
+
+        Returns
+        -------
+        CliParser
+            CLI 解析器实例
+        """
+        # 转换 command_configs 为 CliCommandConfig 对象
+        command_configs = {}
+        raw_configs = config.get("command_configs", {})
+        for cmd_name, cmd_config in raw_configs.items():
+            if isinstance(cmd_config, CliCommandConfig):
+                command_configs[cmd_name] = cmd_config
+            else:
+                # 从字典创建 CliCommandConfig
+                arguments = [ArgumentConfig(**arg_dict) for arg_dict in cmd_config.get("arguments", [])]
+                command_configs[cmd_name] = CliCommandConfig(
+                    help=cmd_config.get("help", ""),
+                    arguments=arguments,
+                )
+
+        return cls(
+            name=config.get("name", "cli-tool"),
+            description=config.get("description", ""),
+            command_factories=config.get("command_factories", {}),
+            command_configs=command_configs,
+        )