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

yuehua_ziniao_webdriver/exceptions.py

@@ -0,0 +1,237 @@
+"""异常定义模块
+
+定义所有自定义异常类，提供清晰的错误层次结构。
+"""
+
+from typing import Optional, Any
+
+
+class ZiniaoError(Exception):
+    """紫鸟浏览器 SDK 基础异常类
+    
+    所有自定义异常的基类。
+    """
+    
+    def __init__(self, message: str, details: Optional[Any] = None) -> None:
+        """初始化异常
+        
+        Args:
+            message: 错误消息
+            details: 额外的错误详情（可选）
+        """
+        self.message = message
+        self.details = details
+        super().__init__(message)
+    
+    def __str__(self) -> str:
+        if self.details:
+            return f"{self.message} (详情: {self.details})"
+        return self.message
+
+
+class ConfigurationError(ZiniaoError):
+    """配置错误
+    
+    当配置参数无效或缺失时抛出。
+    """
+    pass
+
+
+class AuthenticationError(ZiniaoError):
+    """认证失败错误
+    
+    当登录紫鸟客户端失败时抛出。
+    """
+    pass
+
+
+class ClientNotStartedError(ZiniaoError):
+    """客户端未启动错误
+    
+    当尝试操作未启动的客户端时抛出。
+    """
+    
+    def __init__(self, message: str = "紫鸟客户端尚未启动，请先调用 start() 方法") -> None:
+        super().__init__(message)
+
+
+class BrowserStartError(ZiniaoError):
+    """浏览器启动失败错误
+    
+    当启动紫鸟客户端进程失败时抛出。
+    """
+    pass
+
+
+class ProcessError(ZiniaoError):
+    """进程操作错误
+    
+    当进程管理操作失败时抛出（如关闭进程失败）。
+    """
+    pass
+
+
+class CommunicationError(ZiniaoError):
+    """通信错误
+    
+    当与紫鸟客户端 HTTP 通信失败时抛出。
+    """
+    pass
+
+
+class TimeoutError(ZiniaoError):
+    """超时错误
+    
+    当操作超时时抛出。
+    """
+    pass
+
+
+class StoreError(ZiniaoError):
+    """店铺操作基础错误
+    
+    所有店铺相关错误的基类。
+    """
+    pass
+
+
+class StoreNotFoundError(StoreError):
+    """店铺未找到错误
+    
+    当按名称或 ID 查找店铺但未找到时抛出。
+    """
+    
+    def __init__(
+        self, 
+        store_identifier: str, 
+        search_type: str = "名称"
+    ) -> None:
+        """初始化错误
+        
+        Args:
+            store_identifier: 店铺标识（名称或 ID）
+            search_type: 搜索类型（"名称" 或 "ID"）
+        """
+        message = f"未找到匹配的店铺：{search_type}='{store_identifier}'"
+        super().__init__(message, {"identifier": store_identifier, "type": search_type})
+        self.store_identifier = store_identifier
+        self.search_type = search_type
+
+
+class MultipleStoresFoundError(StoreError):
+    """找到多个店铺错误
+    
+    当按名称搜索店铺但找到多个匹配结果时抛出。
+    """
+    
+    def __init__(
+        self, 
+        store_name: str, 
+        count: int,
+        store_names: Optional[list] = None
+    ) -> None:
+        """初始化错误
+        
+        Args:
+            store_name: 搜索的店铺名称
+            count: 找到的店铺数量
+            store_names: 找到的店铺名称列表（可选）
+        """
+        if store_names:
+            message = (
+                f"找到 {count} 个匹配的店铺：'{store_name}'。"
+                f"匹配的店铺：{', '.join(store_names)}"
+            )
+        else:
+            message = f"找到 {count} 个匹配的店铺：'{store_name}'"
+        
+        super().__init__(
+            message, 
+            {"search_name": store_name, "count": count, "stores": store_names}
+        )
+        self.store_name = store_name
+        self.count = count
+        self.store_names = store_names
+
+
+class StoreOperationError(StoreError):
+    """店铺操作失败错误
+    
+    当打开、关闭店铺等操作失败时抛出。
+    """
+    
+    def __init__(
+        self, 
+        operation: str, 
+        store_id: str, 
+        status_code: Optional[int] = None,
+        message: Optional[str] = None
+    ) -> None:
+        """初始化错误
+        
+        Args:
+            operation: 操作类型（如 "打开"、"关闭"）
+            store_id: 店铺 ID
+            status_code: 状态码（可选）
+            message: 错误消息（可选）
+        """
+        error_msg = f"{operation}店铺失败：{store_id}"
+        if status_code is not None:
+            error_msg += f"，状态码：{status_code}"
+        if message:
+            error_msg += f"，消息：{message}"
+        
+        super().__init__(
+            error_msg,
+            {
+                "operation": operation,
+                "store_id": store_id,
+                "status_code": status_code,
+                "message": message
+            }
+        )
+        self.operation = operation
+        self.store_id = store_id
+        self.status_code = status_code
+
+
+class IPCheckError(ZiniaoError):
+    """IP 检测错误
+    
+    当 IP 检测失败或超时时抛出。
+    """
+    pass
+
+
+class CoreUpdateError(ZiniaoError):
+    """内核更新错误
+    
+    当更新浏览器内核失败时抛出。
+    """
+    pass
+
+
+class UnsupportedVersionError(ZiniaoError):
+    """不支持的版本错误
+    
+    当客户端版本不支持某个功能时抛出。
+    """
+    
+    def __init__(
+        self, 
+        feature: str, 
+        required_version: Optional[str] = None
+    ) -> None:
+        """初始化错误
+        
+        Args:
+            feature: 不支持的功能名称
+            required_version: 需要的版本（可选）
+        """
+        message = f"当前客户端版本不支持功能：{feature}"
+        if required_version:
+            message += f"，请升级到 {required_version} 或更高版本"
+        
+        super().__init__(message, {"feature": feature, "required_version": required_version})
+        self.feature = feature
+        self.required_version = required_version

yuehua_ziniao_webdriver/http_client.py

@@ -0,0 +1,214 @@
+"""HTTP 通信客户端模块
+
+封装与紫鸟客户端的 HTTP 通信，提供重试机制和错误处理。
+"""
+
+import json
+import logging
+import time
+from typing import Dict, Any, Optional
+
+import requests
+
+from .types import HttpRequestData, HttpResponse
+from .exceptions import (
+    CommunicationError,
+    TimeoutError as ZiniaoTimeoutError,
+    AuthenticationError
+)
+
+logger = logging.getLogger(__name__)
+
+
+class HttpClient:
+    """HTTP 通信客户端
+    
+    负责与紫鸟客户端进行 HTTP 通信。
+    """
+    
+    def __init__(
+        self,
+        port: int,
+        timeout: int = 120,
+        max_retries: int = 3,
+        retry_delay: float = 2.0
+    ) -> None:
+        """初始化 HTTP 客户端
+        
+        Args:
+            port: 通信端口
+            timeout: 请求超时时间（秒）
+            max_retries: 最大重试次数
+            retry_delay: 重试延迟时间（秒）
+        """
+        self.port = port
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.base_url = f"http://127.0.0.1:{port}"
+        
+        logger.debug(
+            f"初始化 HTTP 客户端：port={port}, timeout={timeout}, "
+            f"max_retries={max_retries}, retry_delay={retry_delay}"
+        )
+    
+    def send_request(
+        self,
+        data: Dict[str, Any],
+        retry_on_none: bool = False
+    ) -> Optional[HttpResponse]:
+        """发送 HTTP 请求
+        
+        Args:
+            data: 请求数据字典
+            retry_on_none: 当返回 None 时是否重试，默认 False
+            
+        Returns:
+            Optional[HttpResponse]: 响应数据，失败返回 None
+            
+        Raises:
+            CommunicationError: 通信失败
+            ZiniaoTimeoutError: 请求超时
+            AuthenticationError: 认证失败
+        """
+        action = data.get("action", "unknown")
+        request_id = data.get("requestId", "unknown")
+        
+        logger.debug(f"发送请求：action={action}, requestId={request_id}")
+        
+        # 重试逻辑
+        last_exception: Optional[Exception] = None
+        
+        for attempt in range(self.max_retries + 1):
+            try:
+                # 发送 POST 请求
+                response = requests.post(
+                    self.base_url,
+                    data=json.dumps(data).encode('utf-8'),
+                    timeout=self.timeout
+                )
+                
+                # 解析响应
+                result = json.loads(response.text)
+                
+                # 检查是否需要重试（返回 None）
+                if result is None and retry_on_none and attempt < self.max_retries:
+                    logger.warning(
+                        f"请求返回 None，{self.retry_delay} 秒后重试 "
+                        f"(尝试 {attempt + 1}/{self.max_retries})"
+                    )
+                    time.sleep(self.retry_delay)
+                    continue
+                
+                # 检查状态码
+                status_code = result.get("statusCode") if result else None
+                
+                # 认证失败
+                if status_code == -10003:
+                    error_msg = f"认证失败：{json.dumps(result, ensure_ascii=False)}"
+                    logger.error(error_msg)
+                    raise AuthenticationError(error_msg, result)
+                
+                logger.debug(
+                    f"请求成功：action={action}, statusCode={status_code}"
+                )
+                
+                return result
+                
+            except requests.Timeout as e:
+                last_exception = e
+                logger.warning(
+                    f"请求超时：action={action}, attempt={attempt + 1}/{self.max_retries + 1}"
+                )
+                
+                if attempt < self.max_retries:
+                    logger.info(f"等待 {self.retry_delay} 秒后重试...")
+                    time.sleep(self.retry_delay)
+                    continue
+                
+                # 最后一次尝试失败
+                error_msg = f"请求超时（已重试 {self.max_retries} 次）：{e}"
+                logger.error(error_msg)
+                raise ZiniaoTimeoutError(error_msg, {"action": action, "error": str(e)})
+            
+            except requests.ConnectionError as e:
+                last_exception = e
+                logger.warning(
+                    f"连接失败：action={action}, attempt={attempt + 1}/{self.max_retries + 1}, "
+                    f"error={e}"
+                )
+                
+                if attempt < self.max_retries:
+                    logger.info(f"等待 {self.retry_delay} 秒后重试...")
+                    time.sleep(self.retry_delay)
+                    continue
+                
+                # 最后一次尝试失败
+                error_msg = (
+                    f"无法连接到紫鸟客户端（已重试 {self.max_retries} 次），"
+                    f"请确认客户端已启动且端口 {self.port} 可访问"
+                )
+                logger.error(error_msg)
+                raise CommunicationError(error_msg, {"port": self.port, "error": str(e)})
+            
+            except json.JSONDecodeError as e:
+                last_exception = e
+                error_msg = f"响应 JSON 解析失败：{e}"
+                logger.error(error_msg)
+                raise CommunicationError(error_msg, {"error": str(e)})
+            
+            except Exception as e:
+                last_exception = e
+                logger.error(f"未知错误：action={action}, error={e}")
+                
+                if attempt < self.max_retries:
+                    logger.info(f"等待 {self.retry_delay} 秒后重试...")
+                    time.sleep(self.retry_delay)
+                    continue
+                
+                # 最后一次尝试失败
+                error_msg = f"通信失败（已重试 {self.max_retries} 次）：{e}"
+                logger.error(error_msg)
+                raise CommunicationError(error_msg, {"action": action, "error": str(e)})
+        
+        # 不应该到达这里，但为了类型检查
+        if last_exception:
+            raise CommunicationError(
+                f"请求失败：{last_exception}",
+                {"error": str(last_exception)}
+            )
+        
+        return None
+    
+    def update_port(self, new_port: int) -> None:
+        """更新通信端口
+        
+        Args:
+            new_port: 新的端口号
+        """
+        self.port = new_port
+        self.base_url = f"http://127.0.0.1:{new_port}"
+        logger.info(f"更新通信端口：{new_port}")
+    
+    def test_connection(self) -> bool:
+        """测试连接是否可用
+        
+        Returns:
+            bool: 连接正常返回 True，否则返回 False
+        """
+        try:
+            response = requests.get(
+                self.base_url,
+                timeout=5
+            )
+            logger.debug(f"连接测试成功：port={self.port}")
+            return True
+        except Exception as e:
+            logger.debug(f"连接测试失败：port={self.port}, error={e}")
+            return False
+    
+    def __repr__(self) -> str:
+        return (
+            f"HttpClient(port={self.port}, timeout={self.timeout}, "
+            f"max_retries={self.max_retries})"
+        )