yuehua-ziniao-webdriver 0.1.0__py3-none-any.whl

yuehua_ziniao_webdriver/client.py

@@ -0,0 +1,435 @@
+"""主客户端模块
+
+提供 ZiniaoClient 主类，是 SDK 的核心接口。
+"""
+
+import json
+import logging
+import time
+import uuid
+from typing import List, Dict, Optional, Union
+
+from .config import ZiniaoConfig
+from .types import Store, ConfigSource
+from .http_client import HttpClient
+from .process import ProcessManager
+from .store import StoreManager
+from .browser import BrowserSession
+from .exceptions import (
+    ClientNotStartedError,
+    UnsupportedVersionError,
+    CoreUpdateError,
+    ConfigurationError
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ZiniaoClient:
+    """紫鸟浏览器客户端
+    
+    这是 SDK 的主要入口类，提供所有核心功能。
+    
+    使用示例:
+        ```python
+        from yuehua_ziniao_webdriver import ZiniaoClient, ZiniaoConfig
+        
+        config = ZiniaoConfig(
+            client_path=r"D:\ziniao\ziniao.exe",
+            company="企业名",
+            username="用户名",
+            password="密码"
+        )
+        
+        client = ZiniaoClient(config)
+        client.start()
+        
+        # 通过名称打开店铺
+        session = client.open_store_by_name("我的店铺")
+        
+        client.stop()
+        ```
+    """
+    
+    def __init__(self, config: ConfigSource) -> None:
+        """初始化紫鸟客户端
+        
+        Args:
+            config: 配置对象、配置字典或配置文件路径
+            
+        Raises:
+            ConfigurationError: 配置无效
+        """
+        # 解析配置
+        self.config = self._parse_config(config)
+        
+        # 初始化组件
+        self.http_client = HttpClient(
+            port=self.config.socket_port,
+            timeout=self.config.request_timeout,
+            max_retries=self.config.max_retries,
+            retry_delay=self.config.retry_delay
+        )
+        
+        self.process_manager = ProcessManager(
+            client_path=self.config.client_path,
+            socket_port=self.config.socket_port,
+            version=self.config.version
+        )
+        
+        self.store_manager = StoreManager(
+            http_client=self.http_client,
+            user_info=self.config.get_user_info()
+        )
+        
+        self._started = False
+        
+        logger.info(f"紫鸟客户端已初始化：{self.config}")
+    
+    def _parse_config(self, config: ConfigSource) -> ZiniaoConfig:
+        """解析配置
+        
+        Args:
+            config: 配置源
+            
+        Returns:
+            ZiniaoConfig: 解析后的配置对象
+            
+        Raises:
+            ConfigurationError: 配置解析失败
+        """
+        if isinstance(config, ZiniaoConfig):
+            return config
+        
+        elif isinstance(config, dict):
+            return ZiniaoConfig.from_dict(config)  # type: ignore
+        
+        elif isinstance(config, str):
+            # 假设是文件路径
+            return ZiniaoConfig.from_json_file(config)
+        
+        else:
+            raise ConfigurationError(
+                f"不支持的配置类型：{type(config)}",
+                {"type": str(type(config))}
+            )
+    
+    def start(
+        self,
+        kill_existing: bool = False,
+        update_core: bool = False,
+        wait_time: int = 5
+    ) -> None:
+        """启动紫鸟客户端
+        
+        Args:
+            kill_existing: 是否自动关闭已存在的进程，默认 False（会询问用户）
+            update_core: 是否在启动后更新内核，默认 False
+            wait_time: 启动后等待时间（秒），默认 5
+            
+        Raises:
+            BrowserStartError: 启动失败
+        """
+        if self._started:
+            logger.warning("客户端已启动，跳过重复启动")
+            return
+        
+        logger.info("=== 启动紫鸟客户端 ===")
+        
+        # 关闭已存在的进程
+        if not self.process_manager.kill_existing_process(force=kill_existing):
+            logger.info("用户取消启动")
+            return
+        
+        # 启动客户端
+        self.process_manager.start_browser(wait_time=wait_time)
+        
+        self._started = True
+        
+        # 更新内核（如果需要）
+        if update_core:
+            logger.info("=== 更新浏览器内核 ===")
+            self.update_core()
+    
+    def stop(self) -> None:
+        """关闭紫鸟客户端
+        
+        会先关闭客户端进程，然后发送退出命令。
+        """
+        if not self._started:
+            logger.warning("客户端未启动，无需关闭")
+            return
+        
+        logger.info("=== 关闭紫鸟客户端 ===")
+        
+        try:
+            # 发送退出命令
+            self._send_exit()
+            
+            # 等待一下让客户端处理
+            time.sleep(2)
+            
+            # 终止进程（如果还在运行）
+            self.process_manager.terminate()
+            
+        except Exception as e:
+            logger.error(f"关闭客户端时出错：{e}")
+        
+        finally:
+            self._started = False
+            logger.info("客户端已关闭")
+    
+    def update_core(self, max_wait_time: int = 300) -> None:
+        """更新浏览器内核
+        
+        需要客户端版本 5.285.7 以上。
+        会循环调用直到更新完成或超时。
+        
+        Args:
+            max_wait_time: 最大等待时间（秒），默认 300（5分钟）
+            
+        Raises:
+            ClientNotStartedError: 客户端未启动
+            UnsupportedVersionError: 版本不支持
+            CoreUpdateError: 更新失败
+        """
+        if not self._started:
+            raise ClientNotStartedError()
+        
+        logger.info("开始更新内核...")
+        
+        start_time = time.time()
+        
+        while True:
+            # 检查超时
+            if time.time() - start_time > max_wait_time:
+                raise CoreUpdateError(
+                    f"更新内核超时（{max_wait_time} 秒）",
+                    {"max_wait_time": max_wait_time}
+                )
+            
+            # 发送更新请求
+            data = {
+                "action": "updateCore",
+                "requestId": str(uuid.uuid4()),
+            }
+            data.update(self.config.get_user_info())
+            
+            result = self.http_client.send_request(data, retry_on_none=True)
+            
+            if result is None:
+                logger.info("等待客户端启动...")
+                time.sleep(2)
+                continue
+            
+            status_code = result.get("statusCode")
+            
+            if status_code is None or status_code == -10003:
+                raise UnsupportedVersionError(
+                    "updateCore",
+                    required_version="5.285.7"
+                )
+            
+            elif status_code == 0:
+                logger.info("内核更新完成")
+                return
+            
+            else:
+                logger.info(
+                    f"等待更新内核：{json.dumps(result, ensure_ascii=False)}"
+                )
+                time.sleep(2)
+    
+    def get_store_list(self, use_cache: bool = False) -> List[Store]:
+        """获取店铺列表
+        
+        Args:
+            use_cache: 是否使用缓存，默认 False
+            
+        Returns:
+            List[Store]: 店铺列表
+            
+        Raises:
+            ClientNotStartedError: 客户端未启动
+            StoreOperationError: 获取失败
+        """
+        if not self._started:
+            raise ClientNotStartedError()
+        
+        return self.store_manager.get_store_list(use_cache=use_cache)
+    
+    def find_stores_by_name(
+        self,
+        name: str,
+        exact_match: bool = False
+    ) -> List[Store]:
+        """通过名称搜索店铺
+        
+        Args:
+            name: 店铺名称
+            exact_match: 是否精确匹配，False 则模糊匹配
+            
+        Returns:
+            List[Store]: 匹配的店铺列表
+            
+        Raises:
+            ClientNotStartedError: 客户端未启动
+        """
+        if not self._started:
+            raise ClientNotStartedError()
+        
+        return self.store_manager.find_stores_by_name(
+            name,
+            exact_match_mode=exact_match
+        )
+    
+    def open_store(
+        self,
+        store_id: str,
+        **options
+    ) -> BrowserSession:
+        """通过店铺 ID 打开店铺
+        
+        Args:
+            store_id: 店铺 ID 或 OAuth 标识
+            **options: 打开店铺的选项
+            
+        Returns:
+            BrowserSession: 浏览器会话对象
+            
+        Raises:
+            ClientNotStartedError: 客户端未启动
+            StoreOperationError: 打开失败
+        """
+        if not self._started:
+            raise ClientNotStartedError()
+        
+        return self.store_manager.open_store(store_id, **options)
+    
+    def open_store_by_name(
+        self,
+        store_name: str,
+        exact_match: bool = False,
+        **options
+    ) -> BrowserSession:
+        """通过店铺名称打开店铺
+        
+        Args:
+            store_name: 店铺名称（支持模糊匹配）
+            exact_match: 是否精确匹配，默认 False（模糊匹配）
+            **options: 打开店铺的选项
+            
+        Returns:
+            BrowserSession: 浏览器会话对象
+            
+        Raises:
+            ClientNotStartedError: 客户端未启动
+            StoreNotFoundError: 未找到匹配的店铺
+            MultipleStoresFoundError: 找到多个匹配的店铺
+            StoreOperationError: 打开失败
+        """
+        if not self._started:
+            raise ClientNotStartedError()
+        
+        return self.store_manager.open_store_by_name(
+            store_name,
+            exact_match_mode=exact_match,
+            **options
+        )
+    
+    def open_stores_by_names(
+        self,
+        store_names: List[str],
+        max_workers: int = 3,
+        exact_match: bool = False,
+        **options
+    ) -> Dict[str, BrowserSession]:
+        """并发打开多个店铺（通过店铺名称）
+        
+        Args:
+            store_names: 店铺名称列表
+            max_workers: 最大并发数，默认 3
+            exact_match: 是否精确匹配，默认 False
+            **options: 打开店铺的选项
+            
+        Returns:
+            Dict[str, BrowserSession]: 店铺名称到浏览器会话的映射
+            
+        Note:
+            如果某个店铺打开失败，会记录错误但不会中断其他店铺的打开。
+            返回的字典中只包含成功打开的店铺。
+            
+        Raises:
+            ClientNotStartedError: 客户端未启动
+        """
+        if not self._started:
+            raise ClientNotStartedError()
+        
+        return self.store_manager.open_stores_by_names(
+            store_names,
+            max_workers=max_workers,
+            exact_match_mode=exact_match,
+            **options
+        )
+    
+    def close_store(self, store_id: str) -> None:
+        """关闭店铺
+        
+        Args:
+            store_id: 店铺 ID/OAuth
+            
+        Raises:
+            ClientNotStartedError: 客户端未启动
+            StoreOperationError: 关闭失败
+        """
+        if not self._started:
+            raise ClientNotStartedError()
+        
+        self.store_manager.close_store(store_id)
+    
+    def _send_exit(self) -> None:
+        """发送退出命令到客户端"""
+        data = {
+            "action": "exit",
+            "requestId": str(uuid.uuid4())
+        }
+        data.update(self.config.get_user_info())
+        
+        logger.debug("发送退出命令...")
+        
+        try:
+            self.http_client.send_request(data)
+        except Exception as e:
+            logger.warning(f"发送退出命令失败：{e}")
+    
+    def is_started(self) -> bool:
+        """检查客户端是否已启动
+        
+        Returns:
+            bool: 已启动返回 True
+        """
+        return self._started
+    
+    def is_process_running(self) -> bool:
+        """检查客户端进程是否正在运行
+        
+        Returns:
+            bool: 运行中返回 True
+        """
+        return self.process_manager.is_running()
+    
+    def __enter__(self) -> "ZiniaoClient":
+        """上下文管理器入口，自动启动客户端"""
+        if not self._started:
+            self.start()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """上下文管理器退出，自动关闭客户端"""
+        self.stop()
+    
+    def __repr__(self) -> str:
+        return (
+            f"ZiniaoClient(version='{self.config.version}', "
+            f"port={self.config.socket_port}, started={self._started})"
+        )

yuehua_ziniao_webdriver/config.py

@@ -0,0 +1,265 @@
+"""配置管理模块
+
+提供配置类和配置加载功能。
+"""
+
+import json
+import os
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+from .types import VersionType, ConfigDict
+from .exceptions import ConfigurationError
+
+
+@dataclass
+class ZiniaoConfig:
+    """紫鸟浏览器客户端配置类
+    
+    使用 dataclass 提供类型提示和默认值。
+    
+    Attributes:
+        client_path: 紫鸟客户端可执行文件路径（必需）
+        socket_port: 客户端通信端口，默认 16851
+        company: 企业名称（用于登录）
+        username: 用户名（用于登录）
+        password: 密码（用于登录）
+        version: 客户端版本，"v5" 或 "v6"，默认 "v6"
+        request_timeout: HTTP 请求超时时间（秒），默认 120
+        max_retries: 失败重试次数，默认 3
+        retry_delay: 重试延迟时间（秒），默认 2.0
+    """
+    
+    client_path: str
+    socket_port: int = 16851
+    company: str = ""
+    username: str = ""
+    password: str = ""
+    version: VersionType = "v6"
+    request_timeout: int = 120
+    max_retries: int = 3
+    retry_delay: float = 2.0
+    
+    def __post_init__(self) -> None:
+        """初始化后的验证"""
+        self.validate()
+    
+    def validate(self) -> None:
+        """验证配置有效性
+        
+        Raises:
+            ConfigurationError: 当配置无效时
+        """
+        # 验证必需字段
+        if not self.client_path:
+            raise ConfigurationError("client_path 不能为空")
+        
+        # 验证客户端路径是否存在
+        if not os.path.exists(self.client_path):
+            raise ConfigurationError(
+                f"客户端路径不存在：{self.client_path}",
+                {"path": self.client_path}
+            )
+        
+        # 验证端口范围
+        if not (1024 <= self.socket_port <= 65535):
+            raise ConfigurationError(
+                f"端口号必须在 1024-65535 之间，当前值：{self.socket_port}",
+                {"port": self.socket_port}
+            )
+        
+        # 验证版本
+        if self.version not in ("v5", "v6"):
+            raise ConfigurationError(
+                f"version 必须是 'v5' 或 'v6'，当前值：{self.version}",
+                {"version": self.version}
+            )
+        
+        # 验证超时时间
+        if self.request_timeout <= 0:
+            raise ConfigurationError(
+                f"request_timeout 必须大于 0，当前值：{self.request_timeout}",
+                {"timeout": self.request_timeout}
+            )
+        
+        # 验证重试次数
+        if self.max_retries < 0:
+            raise ConfigurationError(
+                f"max_retries 不能为负数，当前值：{self.max_retries}",
+                {"retries": self.max_retries}
+            )
+        
+        # 验证重试延迟
+        if self.retry_delay < 0:
+            raise ConfigurationError(
+                f"retry_delay 不能为负数，当前值：{self.retry_delay}",
+                {"delay": self.retry_delay}
+            )
+    
+    @classmethod
+    def from_dict(cls, config_dict: ConfigDict) -> "ZiniaoConfig":
+        """从字典创建配置对象
+        
+        Args:
+            config_dict: 配置字典
+            
+        Returns:
+            ZiniaoConfig: 配置对象
+            
+        Raises:
+            ConfigurationError: 当配置无效时
+        """
+        try:
+            return cls(**config_dict)  # type: ignore
+        except TypeError as e:
+            raise ConfigurationError(f"配置字典格式错误：{e}", {"dict": config_dict})
+    
+    @classmethod
+    def from_json_file(cls, file_path: str) -> "ZiniaoConfig":
+        """从 JSON 文件加载配置
+        
+        Args:
+            file_path: JSON 配置文件路径
+            
+        Returns:
+            ZiniaoConfig: 配置对象
+            
+        Raises:
+            ConfigurationError: 当文件不存在或格式错误时
+        """
+        path = Path(file_path)
+        
+        if not path.exists():
+            raise ConfigurationError(
+                f"配置文件不存在：{file_path}",
+                {"path": file_path}
+            )
+        
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                config_dict = json.load(f)
+            return cls.from_dict(config_dict)
+        except json.JSONDecodeError as e:
+            raise ConfigurationError(
+                f"JSON 文件格式错误：{e}",
+                {"path": file_path, "error": str(e)}
+            )
+        except Exception as e:
+            raise ConfigurationError(
+                f"加载配置文件失败：{e}",
+                {"path": file_path, "error": str(e)}
+            )
+    
+    @classmethod
+    def from_env(cls, prefix: str = "ZINIAO_") -> "ZiniaoConfig":
+        """从环境变量加载配置
+        
+        环境变量命名规则：前缀 + 大写字段名
+        例如：ZINIAO_CLIENT_PATH, ZINIAO_SOCKET_PORT
+        
+        Args:
+            prefix: 环境变量前缀，默认 "ZINIAO_"
+            
+        Returns:
+            ZiniaoConfig: 配置对象
+            
+        Raises:
+            ConfigurationError: 当必需的环境变量不存在时
+        """
+        config_dict: Dict[str, Any] = {}
+        
+        # 字段映射：Python 字段名 -> 环境变量名
+        field_mapping = {
+            "client_path": f"{prefix}CLIENT_PATH",
+            "socket_port": f"{prefix}SOCKET_PORT",
+            "company": f"{prefix}COMPANY",
+            "username": f"{prefix}USERNAME",
+            "password": f"{prefix}PASSWORD",
+            "version": f"{prefix}VERSION",
+            "request_timeout": f"{prefix}REQUEST_TIMEOUT",
+            "max_retries": f"{prefix}MAX_RETRIES",
+            "retry_delay": f"{prefix}RETRY_DELAY",
+        }
+        
+        # 从环境变量读取
+        for field_name, env_name in field_mapping.items():
+            env_value = os.getenv(env_name)
+            if env_value is not None:
+                # 类型转换
+                if field_name == "socket_port":
+                    config_dict[field_name] = int(env_value)
+                elif field_name == "request_timeout":
+                    config_dict[field_name] = int(env_value)
+                elif field_name == "max_retries":
+                    config_dict[field_name] = int(env_value)
+                elif field_name == "retry_delay":
+                    config_dict[field_name] = float(env_value)
+                else:
+                    config_dict[field_name] = env_value
+        
+        # 检查必需字段
+        if "client_path" not in config_dict:
+            raise ConfigurationError(
+                f"环境变量 {prefix}CLIENT_PATH 未设置",
+                {"required_env": f"{prefix}CLIENT_PATH"}
+            )
+        
+        return cls.from_dict(config_dict)  # type: ignore
+    
+    def to_dict(self) -> ConfigDict:
+        """将配置转换为字典
+        
+        Returns:
+            ConfigDict: 配置字典
+        """
+        return asdict(self)  # type: ignore
+    
+    def to_json_file(self, file_path: str, indent: int = 2) -> None:
+        """将配置保存到 JSON 文件
+        
+        Args:
+            file_path: 目标文件路径
+            indent: JSON 缩进空格数，默认 2
+            
+        Raises:
+            ConfigurationError: 当保存失败时
+        """
+        try:
+            path = Path(file_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            
+            with open(path, "w", encoding="utf-8") as f:
+                json.dump(self.to_dict(), f, ensure_ascii=False, indent=indent)
+        except Exception as e:
+            raise ConfigurationError(
+                f"保存配置文件失败：{e}",
+                {"path": file_path, "error": str(e)}
+            )
+    
+    def get_user_info(self) -> Dict[str, str]:
+        """获取用户登录信息字典
+        
+        用于 HTTP 请求。
+        
+        Returns:
+            Dict[str, str]: 包含 company, username, password 的字典
+        """
+        return {
+            "company": self.company,
+            "username": self.username,
+            "password": self.password
+        }
+    
+    def __repr__(self) -> str:
+        """安全的字符串表示（隐藏密码）"""
+        return (
+            f"ZiniaoConfig("
+            f"client_path='{self.client_path}', "
+            f"socket_port={self.socket_port}, "
+            f"company='{self.company}', "
+            f"username='{self.username}', "
+            f"password='***', "
+            f"version='{self.version}'"
+            f")"
+        )