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

tests/unit/test_http.py

@@ -0,0 +1,562 @@
+"""HTTP 客户端测试
+
+测试 HTTPClient 的所有功能，包括：
+- 基础请求功能
+- HTTP 状态码错误映射
+- 业务 code 错误处理
+- 重试机制
+- 超时和网络错误
+- Request ID 提取
+- 错误消息格式处理
+"""
+
+import time
+
+import httpx
+import pytest
+import respx
+
+from xparse_client._config import SDKConfiguration
+from xparse_client._http import HTTPClient, raise_for_status
+from xparse_client.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    ValidationError,
+)
+
+
+@pytest.fixture
+def config():
+    """测试用配置"""
+    return SDKConfiguration(
+        app_id="test-app-id",
+        secret_code="test-secret-code",
+        server_url="https://api.test.com",
+    )
+
+
+@pytest.fixture
+def http_client(config):
+    """测试用 HTTP 客户端"""
+    return HTTPClient(config)
+
+
+# ============================================================================
+# 基础功能测试
+# ============================================================================
+
+
+def test_http_client_initialization(config):
+    """测试 HTTPClient 正确初始化"""
+    client = HTTPClient(config)
+
+    assert client.config == config
+    assert client.retry_config is not None
+    assert client._client is not None
+    assert client._owns_client is True
+
+
+@respx.mock
+def test_http_get_request(http_client):
+    """测试 GET 请求"""
+    # Mock 响应
+    respx.get("https://api.test.com/test").mock(
+        return_value=httpx.Response(200, json={"code": 200, "data": "success"})
+    )
+
+    # 执行请求
+    response = http_client.request("GET", "/test")
+
+    # 验证
+    assert response.status_code == 200
+    assert response.json()["data"] == "success"
+
+
+@respx.mock
+def test_http_post_request(http_client):
+    """测试 POST 请求"""
+    # Mock 响应
+    respx.post("https://api.test.com/test").mock(
+        return_value=httpx.Response(200, json={"code": 200, "data": "created"})
+    )
+
+    # 执行请求
+    response = http_client.request("POST", "/test", json={"key": "value"})
+
+    # 验证
+    assert response.status_code == 200
+    assert response.json()["data"] == "created"
+
+    # 验证请求内容
+    request = respx.calls.last.request
+    assert request.method == "POST"
+
+
+@respx.mock
+def test_http_auth_headers_auto_added(http_client):
+    """测试认证头自动添加"""
+    # Mock 响应
+    respx.get("https://api.test.com/test").mock(
+        return_value=httpx.Response(200, json={"code": 200})
+    )
+
+    # 执行请求
+    http_client.request("GET", "/test")
+
+    # 验证请求头
+    request = respx.calls.last.request
+    assert "x-ti-app-id" in request.headers
+    assert request.headers["x-ti-app-id"] == "test-app-id"
+    assert "x-ti-secret-code" in request.headers
+    assert request.headers["x-ti-secret-code"] == "test-secret-code"
+
+
+# ============================================================================
+# HTTP 状态码错误映射测试
+# ============================================================================
+
+
+def test_http_error_400_validation():
+    """HTTP 400 → ValidationError"""
+    response = httpx.Response(
+        400,
+        json={"message": "参数错误"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ValidationError) as exc_info:
+        raise_for_status(response)
+
+    assert "参数错误" in str(exc_info.value)
+    assert exc_info.value.details["status_code"] == 400
+
+
+def test_http_error_401_authentication():
+    """HTTP 401 → AuthenticationError"""
+    response = httpx.Response(
+        401,
+        json={"message": "认证失败"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(AuthenticationError) as exc_info:
+        raise_for_status(response)
+
+    assert "认证失败" in str(exc_info.value)
+    assert exc_info.value.status_code == 401
+
+
+def test_http_error_403_permission_denied():
+    """HTTP 403 → PermissionDeniedError"""
+    response = httpx.Response(
+        403,
+        json={"message": "权限不足"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(PermissionDeniedError) as exc_info:
+        raise_for_status(response)
+
+    assert "权限不足" in str(exc_info.value)
+    assert exc_info.value.status_code == 403
+
+
+def test_http_error_404_not_found():
+    """HTTP 404 → NotFoundError"""
+    response = httpx.Response(
+        404,
+        json={"message": "资源不存在"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(NotFoundError) as exc_info:
+        raise_for_status(response)
+
+    assert "资源不存在" in str(exc_info.value)
+    assert exc_info.value.status_code == 404
+
+
+def test_http_error_429_rate_limit():
+    """HTTP 429 → RateLimitError（含 retry_after 提取）"""
+    response = httpx.Response(
+        429,
+        headers={"Retry-After": "60"},
+        json={"message": "请求频率超限"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(RateLimitError) as exc_info:
+        raise_for_status(response)
+
+    assert "请求频率超限" in str(exc_info.value)
+    assert exc_info.value.status_code == 429
+    assert exc_info.value.retry_after == 60
+
+
+def test_http_error_500_server_error():
+    """HTTP 5xx → ServerError"""
+    response = httpx.Response(
+        500,
+        json={"message": "服务器内部错误"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ServerError) as exc_info:
+        raise_for_status(response)
+
+    assert "服务器内部错误" in str(exc_info.value)
+    assert exc_info.value.status_code == 500
+
+
+# ============================================================================
+# 业务错误测试（重要！）⭐
+# ============================================================================
+
+
+def test_http_200_business_code_400(business_error_response):
+    """HTTP 200 + {"code": 400} → ValidationError"""
+    response = httpx.Response(
+        200,
+        json=business_error_response,
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ValidationError) as exc_info:
+        raise_for_status(response)
+
+    assert "参数错误" in str(exc_info.value)
+    assert exc_info.value.details["request_id"] == "abc123"
+
+
+def test_http_200_business_code_200_success():
+    """HTTP 200 + {"code": 200} → 正常返回"""
+    response = httpx.Response(
+        200,
+        json={"code": 200, "data": "success", "message": "success"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    # 不应该抛出异常
+    raise_for_status(response)
+    assert response.status_code == 200
+
+
+def test_http_200_business_code_401():
+    """HTTP 200 + {"code": 401} → AuthenticationError"""
+    response = httpx.Response(
+        200,
+        json={"code": 401, "message": "认证失败", "x_request_id": "req_123"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(AuthenticationError) as exc_info:
+        raise_for_status(response)
+
+    assert "认证失败" in str(exc_info.value)
+    assert exc_info.value.details["request_id"] == "req_123"
+
+
+def test_http_200_business_code_500():
+    """HTTP 200 + {"code": 500} → ServerError"""
+    response = httpx.Response(
+        200,
+        json={"code": 500, "message": "服务器错误", "x_request_id": "req_456"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ServerError) as exc_info:
+        raise_for_status(response)
+
+    assert "服务器错误" in str(exc_info.value)
+
+
+# ============================================================================
+# 重试机制测试
+# ============================================================================
+
+
+@respx.mock
+def test_http_retry_on_500(http_client):
+    """500 错误自动重试，最终成功"""
+    # Mock 响应：前两次失败，第三次成功
+    route = respx.post("https://api.test.com/test")
+    route.side_effect = [
+        httpx.Response(500, json={"message": "server error"}),  # 第一次失败
+        httpx.Response(500, json={"message": "server error"}),  # 第二次失败
+        httpx.Response(200, json={"code": 200, "data": "success"}),  # 第三次成功
+    ]
+
+    # 执行请求
+    response = http_client.request("POST", "/test", json={})
+
+    # 验证最终成功
+    assert response.status_code == 200
+    assert response.json()["data"] == "success"
+
+    # 验证重试了 3 次
+    assert len(respx.calls) == 3
+
+
+@respx.mock
+def test_http_retry_exponential_backoff(http_client):
+    """验证指数退避时间"""
+    # Mock 响应：前两次失败，第三次成功
+    route = respx.post("https://api.test.com/test")
+    route.side_effect = [
+        httpx.Response(500),
+        httpx.Response(500),
+        httpx.Response(200, json={"code": 200}),
+    ]
+
+    start_time = time.time()
+    response = http_client.request("POST", "/test", json={})
+    elapsed = time.time() - start_time
+
+    # 验证重试延迟约 1s + 2s = 3s（指数退避：2^0, 2^1）
+    assert elapsed >= 3.0
+    assert response.status_code == 200
+
+
+@respx.mock
+def test_http_retry_max_attempts_reached(http_client):
+    """达到最大重试次数后抛出异常"""
+    # Mock 响应：所有请求都失败
+    route = respx.post("https://api.test.com/test")
+    route.side_effect = [
+        httpx.Response(500) for _ in range(10)  # 超过 max_retries
+    ]
+
+    # 应该抛出 ServerError
+    with pytest.raises(ServerError):
+        http_client.request("POST", "/test", json={})
+
+    # 验证调用了 max_retries + 1 次（初始请求 + 重试次数）
+    expected_calls = http_client.retry_config.max_retries + 1
+    assert len(respx.calls) == expected_calls
+
+
+@respx.mock
+def test_http_no_retry_on_400(http_client):
+    """400 错误不重试（客户端错误）"""
+    # Mock 响应：400 错误
+    respx.post("https://api.test.com/test").mock(
+        return_value=httpx.Response(400, json={"message": "bad request"})
+    )
+
+    # 应该立即抛出异常，不重试
+    with pytest.raises(ValidationError):
+        http_client.request("POST", "/test", json={})
+
+    # 验证只调用了 1 次
+    assert len(respx.calls) == 1
+
+
+# ============================================================================
+# 超时和网络错误测试
+# ============================================================================
+
+
+@respx.mock
+def test_http_timeout(http_client):
+    """请求超时 → RequestTimeoutError"""
+    # Mock 超时
+    respx.post("https://api.test.com/test").mock(
+        side_effect=httpx.TimeoutException("Request timeout")
+    )
+
+    # 应该抛出 RequestTimeoutError
+    with pytest.raises(RequestTimeoutError) as exc_info:
+        http_client.request("POST", "/test", json={})
+
+    assert "请求超时" in str(exc_info.value)
+
+
+@respx.mock
+def test_http_connection_error(http_client):
+    """连接失败 → 重试后抛出 APIError"""
+    # Mock 连接错误
+    respx.post("https://api.test.com/test").mock(
+        side_effect=httpx.ConnectError("Connection failed")
+    )
+
+    # 应该抛出 APIError（因为重试后仍失败）
+    with pytest.raises(APIError) as exc_info:
+        http_client.request("POST", "/test", json={})
+
+    assert "请求失败" in str(exc_info.value)
+
+
+# ============================================================================
+# Request ID 和错误消息测试
+# ============================================================================
+
+
+def test_http_request_id_extraction():
+    """从响应头提取 x-request-id"""
+    response = httpx.Response(
+        500,
+        headers={"x-request-id": "test-req-123"},
+        json={"message": "服务器错误"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ServerError) as exc_info:
+        raise_for_status(response)
+
+    # 验证 request_id 被提取
+    assert exc_info.value.details["request_id"] == "test-req-123"
+
+
+def test_http_error_message_json_format():
+    """JSON 格式错误响应的消息提取"""
+    response = httpx.Response(
+        400,
+        json={"message": "参数错误：字段 name 必填"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ValidationError) as exc_info:
+        raise_for_status(response)
+
+    assert "参数错误：字段 name 必填" in str(exc_info.value)
+
+
+def test_http_error_message_json_error_field():
+    """JSON 格式错误响应（使用 error 字段）"""
+    response = httpx.Response(
+        400,
+        json={"error": "Invalid parameter"},
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ValidationError) as exc_info:
+        raise_for_status(response)
+
+    assert "Invalid parameter" in str(exc_info.value)
+
+
+def test_http_error_message_html_format():
+    """HTML 格式错误响应（返回截断文本）"""
+    html_response = "<html><body><h1>500 Internal Server Error</h1></body></html>"
+    response = httpx.Response(
+        500,
+        text=html_response,
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ServerError) as exc_info:
+        raise_for_status(response)
+
+    # 验证错误消息包含 HTML 内容（截断到 500 字符）
+    assert "500 Internal Server Error" in str(exc_info.value)
+
+
+def test_http_error_message_plain_text():
+    """纯文本格式错误响应"""
+    response = httpx.Response(
+        500,
+        text="Internal Server Error",
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ServerError) as exc_info:
+        raise_for_status(response)
+
+    assert "Internal Server Error" in str(exc_info.value)
+
+
+def test_http_error_message_empty_response():
+    """空响应时使用状态码"""
+    response = httpx.Response(
+        500,
+        text="",
+        request=httpx.Request("GET", "https://api.test.com/test"),
+    )
+
+    with pytest.raises(ServerError) as exc_info:
+        raise_for_status(response)
+
+    assert "HTTP 500" in str(exc_info.value)
+
+
+# ============================================================================
+# HTTPClient 便捷方法测试
+# ============================================================================
+
+
+@respx.mock
+def test_http_get_method(http_client):
+    """测试 get() 便捷方法"""
+    respx.get("https://api.test.com/test").mock(
+        return_value=httpx.Response(200, json={"code": 200, "data": "success"})
+    )
+
+    response = http_client.get("/test")
+
+    assert response.status_code == 200
+    assert response.json()["data"] == "success"
+
+
+@respx.mock
+def test_http_post_method(http_client):
+    """测试 post() 便捷方法"""
+    respx.post("https://api.test.com/test").mock(
+        return_value=httpx.Response(200, json={"code": 200, "data": "created"})
+    )
+
+    response = http_client.post("/test", json={"key": "value"})
+
+    assert response.status_code == 200
+    assert response.json()["data"] == "created"
+
+
+@respx.mock
+def test_http_put_method(http_client):
+    """测试 put() 便捷方法"""
+    respx.put("https://api.test.com/test").mock(
+        return_value=httpx.Response(200, json={"code": 200, "data": "updated"})
+    )
+
+    response = http_client.put("/test", json={"key": "new_value"})
+
+    assert response.status_code == 200
+    assert response.json()["data"] == "updated"
+
+
+@respx.mock
+def test_http_delete_method(http_client):
+    """测试 delete() 便捷方法"""
+    respx.delete("https://api.test.com/test").mock(
+        return_value=httpx.Response(200, json={"code": 200, "data": "deleted"})
+    )
+
+    response = http_client.delete("/test")
+
+    assert response.status_code == 200
+    assert response.json()["data"] == "deleted"
+
+
+def test_http_client_close(config):
+    """测试客户端关闭"""
+    client = HTTPClient(config)
+
+    # 关闭客户端
+    client.close()
+
+    # 验证客户端已关闭
+    assert client._client.is_closed
+
+
+def test_http_client_context_manager(config):
+    """测试上下文管理器"""
+    with HTTPClient(config) as client:
+        assert client is not None
+        assert not client._client.is_closed
+
+    # 退出上下文后应该关闭
+    assert client._client.is_closed

xparse_client/__init__.py

@@ -1,6 +1,47 @@
+# ruff: noqa: E402
+"""xparse-client SDK
+
+面向 Agent 和 RAG 的文档处理 Pipeline 客户端。
+
+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 xparse_client.connectors import LocalSource, MilvusDestination
+    >>> from xparse_client.models import PipelineStage, ParseConfig
+    >>>
+    >>> result = client.local.run_workflow(
+    ...     source=LocalSource(directory="./docs"),
+    ...     destination=MilvusDestination(...),
+    ...     stages=[PipelineStage(type="parse", config=ParseConfig())]
+    ... )
+    >>>
+    >>> # 远程工作流（需要服务端支持）
+    >>> workflow = client.workflows.create(
+    ...     name="daily-processing",
+    ...     source_id="src_123",
+    ...     destination_id="dst_456",
+    ...     stages=[...]
+    ... )
+    >>> job_id = client.workflows.run(workflow.workflow_id)
+
+迁移指南:
+    如果你正在使用旧版 Pipeline 类，请参考迁移指南：
+    https://github.com/textin/xparse-client/blob/master/docs/migration-guide.md
+"""
+
 import logging
-from pathlib import Path
 import re
+from pathlib import Path
 
 logging.basicConfig(
     level=logging.INFO,
@@ -8,31 +49,80 @@ logging.basicConfig(
     encoding='utf-8'
 )
 
-from .pipeline.config import ParseConfig, ChunkConfig, EmbedConfig, ExtractConfig, Stage, PipelineStats, PipelineConfig
-from .pipeline.sources import Source, S3Source, LocalSource, FtpSource, SmbSource
-from .pipeline.destinations import Destination, MilvusDestination, QdrantDestination, LocalDestination, S3Destination
-from .pipeline.pipeline import Pipeline, create_pipeline_from_config
+# ============================================================
+# 新版 SDK 入口（v0.3.0+）
+# ============================================================
+
+from ._client import XParseClient
+from ._config import RetryConfiguration, SDKConfiguration
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConnectorError,
+    DestinationError,
+    NotFoundError,
+    PermissionDeniedError,
+    PipelineError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    SourceError,
+    ValidationError,
+    XParseClientError,
+)
+
+# ============================================================
+# 新版模型（推荐使用）
+# ============================================================
+from .models import (
+    AsyncJobResponse,
+    Element,
+    ElementMetadata,
+    ExtractConfig,
+    JobStatusResponse,
+    ParseConfig,
+    ParseResponse,
+    PipelineConfig,
+    PipelineResponse,
+    PipelineStage,
+    PipelineStats,
+)
 
 __all__ = [
+    # 新版 SDK 入口
+    'XParseClient',
+    'SDKConfiguration',
+    'RetryConfiguration',
+
+    # 异常类
+    'XParseClientError',
+    'ConfigurationError',
+    'ValidationError',
+    'APIError',
+    'AuthenticationError',
+    'PermissionDeniedError',
+    'NotFoundError',
+    'RateLimitError',
+    'ServerError',
+    'RequestTimeoutError',
+    'ConnectorError',
+    'SourceError',
+    'DestinationError',
+    'PipelineError',
+
+    # 新版模型
     'ParseConfig',
-    'ChunkConfig',
-    'EmbedConfig',
+    'Element',
+    'ElementMetadata',
+    'ParseResponse',
+    'AsyncJobResponse',
+    'JobStatusResponse',
     'ExtractConfig',
-    'Stage',
+    'PipelineStage',
     'PipelineStats',
     'PipelineConfig',
-    'Source',
-    'S3Source',
-    'LocalSource',
-    'FtpSource',
-    'SmbSource',
-    'Destination',
-    'MilvusDestination',
-    'QdrantDestination',
-    'LocalDestination',
-    'S3Destination',
-    'Pipeline',
-    'create_pipeline_from_config',
+    'PipelineResponse',
 ]
 
 # 自动从 pyproject.toml 读取版本号