xparse-client 0.2.20__py3-none-any.whl → 0.3.0b1__py3-none-any.whl

xparse_client/_base.py

@@ -0,0 +1,179 @@
+"""API 模块基类
+
+提供所有 API 模块的基类，封装通用的 HTTP 请求和响应处理逻辑。
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import httpx
+
+if TYPE_CHECKING:
+    from ._config import SDKConfiguration
+    from ._http import HTTPClient
+
+T = TypeVar("T")
+
+
+class BaseAPI(ABC):  # noqa: B024
+    """API 模块基类
+
+    所有 API 模块的基类，提供统一的 HTTP 请求封装。
+
+    Attributes:
+        _base_path: API 路径前缀
+        _config: SDK 配置
+        _http: 同步 HTTP 客户端
+    """
+
+    _base_path: str = "/api/xparse"
+
+    def __init__(
+        self,
+        config: SDKConfiguration,
+        http_client: HTTPClient,
+    ) -> None:
+        """初始化 API 模块
+
+        Args:
+            config: SDK 配置
+            http_client: 同步 HTTP 客户端
+        """
+        self._config = config
+        self._http = http_client
+
+    # ========== 同步请求方法 ==========
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        """发送同步 HTTP 请求
+
+        Args:
+            method: HTTP 方法
+            path: 相对于 _base_path 的路径
+            json: JSON 请求体
+            data: 表单数据
+            files: 文件数据
+            params: 查询参数
+            headers: 额外请求头
+            timeout: 请求超时
+
+        Returns:
+            httpx.Response
+        """
+        full_path = f"{self._base_path}{path}"
+        return self._http.request(
+            method,
+            full_path,
+            json=json,
+            data=data,
+            files=files,
+            params=params,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    def _get(self, path: str, **kwargs) -> httpx.Response:
+        """发送 GET 请求"""
+        return self._request("GET", path, **kwargs)
+
+    def _post(self, path: str, **kwargs) -> httpx.Response:
+        """发送 POST 请求"""
+        return self._request("POST", path, **kwargs)
+
+    def _put(self, path: str, **kwargs) -> httpx.Response:
+        """发送 PUT 请求"""
+        return self._request("PUT", path, **kwargs)
+
+    def _delete(self, path: str, **kwargs) -> httpx.Response:
+        """发送 DELETE 请求"""
+        return self._request("DELETE", path, **kwargs)
+
+    # ========== 异步请求方法 ==========
+
+
+    # ========== 响应处理 ==========
+
+    def _parse_response(
+        self,
+        response: httpx.Response,
+        model_class: type[T],
+    ) -> T:
+        """解析响应为 Pydantic 模型
+
+        支持两种响应格式:
+        - 标准格式: {"code": 200, "data": {...}}
+        - 直接返回: {...}
+
+        Args:
+            response: HTTP 响应
+            model_class: Pydantic 模型类
+
+        Returns:
+            解析后的模型实例
+        """
+        data = response.json()
+
+        # 处理标准响应格式
+        if isinstance(data, dict) and "data" in data:
+            data = data["data"]
+
+        return model_class.model_validate(data)
+
+    def _parse_list_response(
+        self,
+        response: httpx.Response,
+        model_class: type[T],
+    ) -> list[T]:
+        """解析列表响应
+
+        Args:
+            response: HTTP 响应
+            model_class: Pydantic 模型类
+
+        Returns:
+            模型实例列表
+        """
+        data = response.json()
+
+        # 处理标准响应格式
+        if isinstance(data, dict) and "data" in data:
+            data = data["data"]
+
+        # 确保是列表
+        if not isinstance(data, list):
+            data = [data]
+
+        return [model_class.model_validate(item) for item in data]
+
+    def _parse_raw_response(self, response: httpx.Response) -> dict[str, Any]:
+        """解析原始 JSON 响应
+
+        Args:
+            response: HTTP 响应
+
+        Returns:
+            原始 JSON 数据
+        """
+        data = response.json()
+
+        # 处理标准响应格式
+        if isinstance(data, dict) and "data" in data:
+            return data["data"]
+
+        return data
+
+
+__all__ = ["BaseAPI"]

xparse_client/_client.py

@@ -0,0 +1,218 @@
+"""XParseClient SDK 主入口
+
+提供 SDK 的统一入口类，支持懒加载 API 模块。
+
+Example:
+    >>> from xparse_client import XParseClient
+    >>>
+    >>> # 创建客户端
+    >>> client = XParseClient(
+    ...     app_id="your-app-id",
+    ...     secret_code="your-secret-code"
+    ... )
+    >>>
+    >>> # 同步解析
+    >>> result = client.parse.partition(file=file_bytes, filename="doc.pdf")
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from ._config import SDKConfiguration
+from ._http import HTTPClient
+
+if TYPE_CHECKING:
+    from .api.extract import Extract
+    from .api.local import Local
+    from .api.parse import Parse
+    from .api.pipeline import PipelineAPI
+    from .api.workflows import Workflows
+
+
+class XParseClient:
+    """xParse SDK 主入口类
+
+    提供统一的 API 访问入口，支持懒加载。
+
+    Attributes:
+        parse: Parse API（文档解析）
+        extract: Extract API（信息抽取）
+        pipeline: Pipeline API（自定义流水线）
+        local: Local API（本地批处理）
+        workflows: Workflows API（远程批处理）
+
+    Example:
+        >>> # 方式1: 直接传参
+        >>> client = XParseClient(
+        ...     app_id="your-app-id",
+        ...     secret_code="your-secret-code"
+        ... )
+        >>>
+        >>> # 方式2: 从环境变量
+        >>> client = XParseClient.from_env()
+        >>>
+        >>> # 单文件处理
+        >>> result = client.parse.partition(file=file_bytes, filename="doc.pdf")
+        >>>
+        >>> # 服务端异步任务（非客户端异步）
+        >>> job = client.parse.create_async_job(file=file_bytes, filename="doc.pdf")
+        >>> result = client.parse.wait_for_result(job_id=job.job_id)
+    """
+
+    # API 模块映射: 属性名 -> (模块路径, 类名)
+    _API_MAP: dict[str, tuple] = {
+        "parse": ("xparse_client.api.parse", "Parse"),
+        "extract": ("xparse_client.api.extract", "Extract"),
+        "pipeline": ("xparse_client.api.pipeline", "PipelineAPI"),
+        "local": ("xparse_client.api.local", "Local"),
+        "workflows": ("xparse_client.api.workflows", "Workflows"),
+        # v2 版本添加:
+        # "sources": ("xparse_client.api.sources", "Sources"),
+        # "destinations": ("xparse_client.api.destinations", "Destinations"),
+        # "jobs": ("xparse_client.api.jobs", "Jobs"),
+    }
+
+    # 类型注解（帮助 IDE 提供代码补全）
+    parse: Parse
+    extract: Extract
+    pipeline: PipelineAPI
+    local: Local
+    workflows: Workflows
+
+    def __init__(
+        self,
+        app_id: str | None = None,
+        secret_code: str | None = None,
+        *,
+        server_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        config: SDKConfiguration | None = None,
+        http_client: HTTPClient | None = None,
+    ) -> None:
+        """初始化 XParseClient
+
+        Args:
+            app_id: TextIn 应用 ID
+            secret_code: TextIn 密钥
+            server_url: 服务器地址（默认 https://api.textin.com）
+            timeout: 请求超时时间（秒）
+            max_retries: 最大重试次数
+            config: 自定义 SDKConfiguration（如果提供，会忽略其他参数）
+            http_client: 自定义 HTTPClient（用于测试）
+
+        Raises:
+            ConfigurationError: 配置参数无效
+        """
+        # 使用传入的 config 或创建新的
+        if config is not None:
+            self._config = config
+        else:
+            # 构建配置参数
+            config_kwargs: dict[str, Any] = {}
+            if app_id is not None:
+                config_kwargs["app_id"] = app_id
+            if secret_code is not None:
+                config_kwargs["secret_code"] = secret_code
+            if server_url is not None:
+                config_kwargs["server_url"] = server_url
+            if timeout is not None:
+                config_kwargs["timeout"] = timeout
+            if max_retries is not None:
+                config_kwargs["max_retries"] = max_retries
+
+            # 如果没有提供 app_id/secret_code，尝试从环境变量读取
+            if "app_id" not in config_kwargs or "secret_code" not in config_kwargs:
+                self._config = SDKConfiguration.from_env(**config_kwargs)
+            else:
+                self._config = SDKConfiguration(**config_kwargs)
+
+        # 初始化 HTTP 客户端
+        self._http = http_client or HTTPClient(self._config)
+        self._owns_http = http_client is None
+
+        # API 模块缓存
+        self._api_cache: dict[str, Any] = {}
+
+    @classmethod
+    def from_env(cls, **kwargs) -> XParseClient:
+        """从环境变量创建客户端
+
+        环境变量:
+            TEXTIN_APP_ID: 应用 ID
+            TEXTIN_SECRET_CODE: 密钥
+            TEXTIN_SERVER_URL: 服务器地址（可选）
+
+        Args:
+            **kwargs: 其他配置参数
+
+        Returns:
+            XParseClient 实例
+
+        Example:
+            >>> # 设置环境变量后
+            >>> client = XParseClient.from_env()
+        """
+        config = SDKConfiguration.from_env(**kwargs)
+        return cls(config=config)
+
+    def __getattr__(self, name: str) -> Any:
+        """懒加载 API 模块
+
+        当访问 API 属性（如 client.parse）时，动态导入并实例化对应的 API 类。
+
+        Args:
+            name: 属性名
+
+        Returns:
+            API 模块实例
+
+        Raises:
+            AttributeError: 未知的属性名
+        """
+        if name.startswith("_"):
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
+        if name in self._API_MAP:
+            # 检查缓存
+            if name not in self._api_cache:
+                module_path, class_name = self._API_MAP[name]
+                try:
+                    module = importlib.import_module(module_path)
+                    api_class: type = getattr(module, class_name)
+                    self._api_cache[name] = api_class(
+                        self._config,
+                        self._http,
+                    )
+                except ImportError as e:
+                    raise AttributeError(
+                        f"无法加载 API 模块 '{name}': {e}"
+                    ) from e
+
+            return self._api_cache[name]
+
+        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
+    def close(self) -> None:
+        """关闭客户端，释放资源"""
+        if self._owns_http:
+            self._http.close()
+        # 清空 API 缓存
+        self._api_cache.clear()
+
+    def __enter__(self) -> XParseClient:
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    @property
+    def config(self) -> SDKConfiguration:
+        """获取 SDK 配置"""
+        return self._config
+
+
+
+__all__ = ["XParseClient"]

xparse_client/_config.py

@@ -0,0 +1,221 @@
+"""SDK 配置管理
+
+提供 SDK 全局配置类，管理认证信息、服务器地址、超时设置等。
+
+Example:
+    >>> config = SDKConfiguration(
+    ...     app_id="your-app-id",
+    ...     secret_code="your-secret-code",
+    ...     server_url="https://api.textin.com"
+    ... )
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+from .exceptions import ConfigurationError
+
+# 默认配置
+DEFAULT_SERVER_URL = "https://api.textin.com"
+DEFAULT_TIMEOUT = 630.0  # 秒
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BACKOFF_BASE = 2.0
+DEFAULT_BACKOFF_MAX = 60.0
+
+
+@dataclass
+class SDKConfiguration:
+    """SDK 配置类
+
+    管理 SDK 的全局配置，包括认证信息、服务器地址、超时设置等。
+
+    Attributes:
+        app_id: TextIn 应用 ID
+        secret_code: TextIn 密钥
+        server_url: 服务器地址
+        timeout: 请求超时时间（秒）
+        max_retries: 最大重试次数
+        backoff_base: 退避策略基数
+        backoff_max: 退避策略最大等待时间（秒）
+        extra_headers: 额外的请求头
+
+    Example:
+        >>> # 方式1: 直接传参
+        >>> config = SDKConfiguration(
+        ...     app_id="your-app-id",
+        ...     secret_code="your-secret-code"
+        ... )
+        >>>
+        >>> # 方式2: 从环境变量读取
+        >>> config = SDKConfiguration.from_env()
+    """
+
+    app_id: str
+    secret_code: str
+    server_url: str = DEFAULT_SERVER_URL
+    timeout: float = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    backoff_base: float = DEFAULT_BACKOFF_BASE
+    backoff_max: float = DEFAULT_BACKOFF_MAX
+    extra_headers: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """验证配置"""
+        if not self.app_id:
+            raise ConfigurationError(
+                "app_id 不能为空",
+                details={"param": "app_id"},
+            )
+        if not self.secret_code:
+            raise ConfigurationError(
+                "secret_code 不能为空",
+                details={"param": "secret_code"},
+            )
+
+        # 移除 server_url 末尾的斜杠
+        self.server_url = self.server_url.rstrip("/")
+
+        # 验证数值参数
+        if self.timeout <= 0:
+            raise ConfigurationError(
+                "timeout 必须大于 0",
+                details={"param": "timeout", "value": self.timeout},
+            )
+        if self.max_retries < 0:
+            raise ConfigurationError(
+                "max_retries 不能为负数",
+                details={"param": "max_retries", "value": self.max_retries},
+            )
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        app_id_env: str = "TEXTIN_APP_ID",
+        secret_code_env: str = "TEXTIN_SECRET_CODE",
+        server_url_env: str = "TEXTIN_SERVER_URL",
+        **kwargs,
+    ) -> SDKConfiguration:
+        """从环境变量创建配置
+
+        Args:
+            app_id_env: 存储 app_id 的环境变量名
+            secret_code_env: 存储 secret_code 的环境变量名
+            server_url_env: 存储 server_url 的环境变量名
+            **kwargs: 其他配置参数，会覆盖环境变量
+
+        Returns:
+            SDKConfiguration 实例
+
+        Raises:
+            ConfigurationError: 必要的环境变量未设置
+
+        Example:
+            >>> # 设置环境变量
+            >>> # export TEXTIN_APP_ID=your-app-id
+            >>> # export TEXTIN_SECRET_CODE=your-secret-code
+            >>> config = SDKConfiguration.from_env()
+        """
+        app_id = kwargs.pop("app_id", None) or os.environ.get(app_id_env)
+        secret_code = kwargs.pop("secret_code", None) or os.environ.get(secret_code_env)
+        server_url = kwargs.pop("server_url", None) or os.environ.get(
+            server_url_env, DEFAULT_SERVER_URL
+        )
+
+        if not app_id:
+            raise ConfigurationError(
+                f"app_id 未设置，请设置环境变量 {app_id_env} 或传入 app_id 参数",
+                details={"env_var": app_id_env},
+            )
+        if not secret_code:
+            raise ConfigurationError(
+                f"secret_code 未设置，请设置环境变量 {secret_code_env} 或传入 secret_code 参数",
+                details={"env_var": secret_code_env},
+            )
+
+        return cls(
+            app_id=app_id,
+            secret_code=secret_code,
+            server_url=server_url,
+            **kwargs,
+        )
+
+    def get_auth_headers(self) -> dict[str, str]:
+        """获取认证请求头
+
+        Returns:
+            包含认证信息的请求头字典
+        """
+        headers = {
+            "x-ti-app-id": self.app_id,
+            "x-ti-secret-code": self.secret_code,
+        }
+        # 合并额外的请求头
+        headers.update(self.extra_headers)
+        return headers
+
+    def get_base_url(self) -> str:
+        """获取 API 基础 URL
+
+        Returns:
+            API 基础 URL
+        """
+        return self.server_url
+
+
+@dataclass
+class RetryConfiguration:
+    """重试配置
+
+    控制请求重试的行为。
+
+    Attributes:
+        max_retries: 最大重试次数
+        backoff_base: 退避策略基数（秒）
+        backoff_max: 最大退避时间（秒）
+        retry_status_codes: 需要重试的 HTTP 状态码
+    """
+
+    max_retries: int = DEFAULT_MAX_RETRIES
+    backoff_base: float = DEFAULT_BACKOFF_BASE
+    backoff_max: float = DEFAULT_BACKOFF_MAX
+    retry_status_codes: tuple = (429, 500, 502, 503, 504)
+
+    def calculate_backoff(self, attempt: int) -> float:
+        """计算退避时间
+
+        使用指数退避策略: min(backoff_max, backoff_base ** attempt)
+
+        Args:
+            attempt: 当前重试次数（从 0 开始）
+
+        Returns:
+            退避等待时间（秒）
+        """
+        delay = min(self.backoff_max, self.backoff_base ** attempt)
+        return delay
+
+    def should_retry(self, status_code: int, attempt: int) -> bool:
+        """判断是否应该重试
+
+        Args:
+            status_code: HTTP 状态码
+            attempt: 当前重试次数（从 0 开始）
+
+        Returns:
+            是否应该重试
+        """
+        if attempt >= self.max_retries:
+            return False
+        return status_code in self.retry_status_codes
+
+
+__all__ = [
+    "SDKConfiguration",
+    "RetryConfiguration",
+    "DEFAULT_SERVER_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_MAX_RETRIES",
+]