xparse-client 0.2.19__py3-none-any.whl → 0.3.0b3__py3-none-any.whl

tests/unit/test_base.py

@@ -0,0 +1,437 @@
+"""BaseAPI 测试
+
+测试 xparse_client._base 模块的 BaseAPI 基类。
+
+运行方式:
+    pytest tests/unit/test_base.py -v
+"""
+
+
+import httpx
+import pytest
+import respx
+from pydantic import BaseModel
+
+from xparse_client._base import BaseAPI
+from xparse_client._config import SDKConfiguration
+from xparse_client._http import HTTPClient
+
+# ============================================================================
+# 测试用 Pydantic 模型
+# ============================================================================
+
+class SampleModel(BaseModel):
+    """测试用模型"""
+    id: str
+    name: str
+    value: int = 0
+
+
+class ConcreteAPI(BaseAPI):
+    """用于测试的具体 API 类"""
+    pass
+
+
+# ============================================================================
+# Fixtures
+# ============================================================================
+
+@pytest.fixture
+def config():
+    """创建测试配置"""
+    return SDKConfiguration(
+        app_id="test_app",
+        secret_code="test_secret",
+        server_url="https://api.test.com"
+    )
+
+
+@pytest.fixture
+def http_client(config):
+    """创建测试 HTTP 客户端"""
+    return HTTPClient(config)
+
+
+@pytest.fixture
+def api(config, http_client):
+    """创建测试 API 实例"""
+    return ConcreteAPI(config, http_client)
+
+
+# ============================================================================
+# 初始化测试
+# ============================================================================
+
+def test_base_api_initialization(config, http_client):
+    """测试 BaseAPI 初始化"""
+    api = ConcreteAPI(config, http_client)
+
+    assert api._config == config
+    assert api._http == http_client
+    assert api._base_path == "/api/xparse"
+
+
+# ============================================================================
+# HTTP 请求方法测试
+# ============================================================================
+
+@respx.mock
+def test_base_api_get_request(api):
+    """测试 _get 方法"""
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json={"success": True})
+    )
+
+    response = api._get("/test")
+
+    assert response.status_code == 200
+    assert response.json() == {"success": True}
+
+
+@respx.mock
+def test_base_api_post_request(api):
+    """测试 _post 方法"""
+    respx.post("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json={"success": True})
+    )
+
+    response = api._post("/test", json={"data": "value"})
+
+    assert response.status_code == 200
+    assert response.json() == {"success": True}
+
+
+@respx.mock
+def test_base_api_put_request(api):
+    """测试 _put 方法"""
+    respx.put("https://api.test.com/api/xparse/test/123").mock(
+        return_value=httpx.Response(200, json={"success": True})
+    )
+
+    response = api._put("/test/123", json={"data": "updated"})
+
+    assert response.status_code == 200
+
+
+@respx.mock
+def test_base_api_delete_request(api):
+    """测试 _delete 方法"""
+    respx.delete("https://api.test.com/api/xparse/test/123").mock(
+        return_value=httpx.Response(204)
+    )
+
+    response = api._delete("/test/123")
+
+    assert response.status_code == 204
+
+
+@respx.mock
+def test_base_api_request_with_params(api):
+    """测试带查询参数的请求"""
+    respx.get("https://api.test.com/api/xparse/test?page=1&limit=10").mock(
+        return_value=httpx.Response(200, json={"items": []})
+    )
+
+    response = api._get("/test", params={"page": 1, "limit": 10})
+
+    assert response.status_code == 200
+
+
+@respx.mock
+def test_base_api_request_with_headers(api):
+    """测试带自定义请求头的请求"""
+    route = respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json={})
+    )
+
+    api._get("/test", headers={"X-Custom-Header": "value"})
+
+    # 验证请求头
+    assert route.called
+    request = route.calls.last.request
+    assert "X-Custom-Header" in request.headers
+    assert request.headers["X-Custom-Header"] == "value"
+
+
+@respx.mock
+def test_base_api_request_with_timeout(api):
+    """测试带超时的请求"""
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json={})
+    )
+
+    # 不会抛出异常
+    response = api._get("/test", timeout=5.0)
+    assert response.status_code == 200
+
+
+# ============================================================================
+# 响应解析测试
+# ============================================================================
+
+@respx.mock
+def test_parse_response_standard_format(api):
+    """测试解析标准格式响应 {"code": 200, "data": {...}}"""
+    response_data = {
+        "code": 200,
+        "data": {
+            "id": "123",
+            "name": "test",
+            "value": 42
+        }
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+    result = api._parse_response(response, SampleModel)
+
+    assert isinstance(result, SampleModel)
+    assert result.id == "123"
+    assert result.name == "test"
+    assert result.value == 42
+
+
+@respx.mock
+def test_parse_response_direct_format(api):
+    """测试解析直接返回格式 {...}"""
+    response_data = {
+        "id": "123",
+        "name": "test",
+        "value": 42
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+    result = api._parse_response(response, SampleModel)
+
+    assert isinstance(result, SampleModel)
+    assert result.id == "123"
+
+
+@respx.mock
+def test_parse_response_with_default_values(api):
+    """测试解析响应使用模型默认值"""
+    response_data = {
+        "code": 200,
+        "data": {
+            "id": "123",
+            "name": "test"
+            # value 缺失，应使用默认值 0
+        }
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+    result = api._parse_response(response, SampleModel)
+
+    assert result.value == 0
+
+
+@respx.mock
+def test_parse_list_response_standard_format(api):
+    """测试解析标准格式的列表响应"""
+    response_data = {
+        "code": 200,
+        "data": [
+            {"id": "1", "name": "first", "value": 10},
+            {"id": "2", "name": "second", "value": 20},
+        ]
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+    result = api._parse_list_response(response, SampleModel)
+
+    assert isinstance(result, list)
+    assert len(result) == 2
+    assert all(isinstance(item, SampleModel) for item in result)
+    assert result[0].id == "1"
+    assert result[1].id == "2"
+
+
+@respx.mock
+def test_parse_list_response_direct_format(api):
+    """测试解析直接返回的列表"""
+    response_data = [
+        {"id": "1", "name": "first", "value": 10},
+        {"id": "2", "name": "second", "value": 20},
+    ]
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+    result = api._parse_list_response(response, SampleModel)
+
+    assert len(result) == 2
+
+
+@respx.mock
+def test_parse_list_response_single_item_as_list(api):
+    """测试解析单个对象为列表"""
+    response_data = {
+        "code": 200,
+        "data": {"id": "1", "name": "single", "value": 10}
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+    result = api._parse_list_response(response, SampleModel)
+
+    # 单个对象应该被包装成列表
+    assert isinstance(result, list)
+    assert len(result) == 1
+    assert result[0].id == "1"
+
+
+@respx.mock
+def test_parse_list_response_empty_list(api):
+    """测试解析空列表"""
+    response_data = {
+        "code": 200,
+        "data": []
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+    result = api._parse_list_response(response, SampleModel)
+
+    assert isinstance(result, list)
+    assert len(result) == 0
+
+
+@respx.mock
+def test_parse_raw_response_standard_format(api):
+    """测试解析原始响应（标准格式）"""
+    response_data = {
+        "code": 200,
+        "data": {
+            "key1": "value1",
+            "key2": 123,
+            "nested": {"inner": "data"}
+        }
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+    result = api._parse_raw_response(response)
+
+    assert result == response_data["data"]
+    assert result["key1"] == "value1"
+    assert result["nested"]["inner"] == "data"
+
+
+@respx.mock
+def test_parse_raw_response_direct_format(api):
+    """测试解析原始响应（直接格式）"""
+    response_data = {
+        "key1": "value1",
+        "key2": 123
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+    result = api._parse_raw_response(response)
+
+    assert result == response_data
+
+
+# ============================================================================
+# 路径构造测试
+# ============================================================================
+
+@respx.mock
+def test_base_api_path_construction(api):
+    """测试 API 路径构造"""
+    route = respx.get("https://api.test.com/api/xparse/v1/resource/123").mock(
+        return_value=httpx.Response(200, json={})
+    )
+
+    api._get("/v1/resource/123")
+
+    assert route.called
+
+
+@respx.mock
+def test_base_api_path_without_leading_slash(api):
+    """测试路径不以斜杠开头"""
+    route = respx.get("https://api.test.com/api/xparseresource").mock(
+        return_value=httpx.Response(200, json={})
+    )
+
+    api._get("resource")
+
+    assert route.called
+
+
+# ============================================================================
+# 错误处理测试
+# ============================================================================
+
+@respx.mock
+def test_parse_response_validation_error(api):
+    """测试响应数据验证错误"""
+    response_data = {
+        "code": 200,
+        "data": {
+            "id": "123"
+            # name 缺失且没有默认值，应该抛出验证错误
+        }
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+
+    from pydantic import ValidationError
+    with pytest.raises(ValidationError):
+        api._parse_response(response, SampleModel)
+
+
+@respx.mock
+def test_parse_list_response_validation_error(api):
+    """测试列表响应中的验证错误"""
+    response_data = {
+        "code": 200,
+        "data": [
+            {"id": "1", "name": "valid", "value": 10},
+            {"id": "2"}  # name 缺失
+        ]
+    }
+
+    respx.get("https://api.test.com/api/xparse/test").mock(
+        return_value=httpx.Response(200, json=response_data)
+    )
+
+    response = api._get("/test")
+
+    from pydantic import ValidationError
+    with pytest.raises(ValidationError):
+        api._parse_list_response(response, SampleModel)

tests/unit/test_client.py

@@ -0,0 +1,110 @@
+"""XParseClient 测试"""
+
+import pytest
+
+from xparse_client import XParseClient
+from xparse_client._config import SDKConfiguration
+
+
+class TestXParseClient:
+    """XParseClient 测试"""
+
+    def test_create_with_credentials(self, app_id, secret_code):
+        """测试使用凭证创建客户端"""
+        client = XParseClient(
+            app_id=app_id,
+            secret_code=secret_code,
+        )
+        assert client.config.app_id == app_id
+        assert client.config.secret_code == secret_code
+
+    def test_create_with_config(self, app_id, secret_code):
+        """测试使用配置对象创建客户端"""
+        config = SDKConfiguration(
+            app_id=app_id,
+            secret_code=secret_code,
+        )
+        client = XParseClient(config=config)
+        assert client.config is config
+
+    def test_create_with_custom_settings(self, app_id, secret_code, server_url):
+        """测试自定义设置"""
+        client = XParseClient(
+            app_id=app_id,
+            secret_code=secret_code,
+            server_url=server_url,
+            timeout=60.0,
+            max_retries=5,
+        )
+        assert client.config.server_url == server_url
+        assert client.config.timeout == 60.0
+        assert client.config.max_retries == 5
+
+    def test_from_env(self, app_id, secret_code, monkeypatch):
+        """测试从环境变量创建"""
+        monkeypatch.setenv("TEXTIN_APP_ID", app_id)
+        monkeypatch.setenv("TEXTIN_SECRET_CODE", secret_code)
+
+        client = XParseClient.from_env()
+        assert client.config.app_id == app_id
+        assert client.config.secret_code == secret_code
+
+    def test_lazy_load_parse_api(self, app_id, secret_code):
+        """测试懒加载 Parse API"""
+        client = XParseClient(
+            app_id=app_id,
+            secret_code=secret_code,
+        )
+
+        # 访问 parse 属性应该返回 Parse 实例
+        parse_api = client.parse
+        assert parse_api is not None
+
+        # 再次访问应该返回同一个实例（缓存）
+        assert client.parse is parse_api
+
+    def test_lazy_load_extract_api(self, app_id, secret_code):
+        """测试懒加载 Extract API"""
+        client = XParseClient(
+            app_id=app_id,
+            secret_code=secret_code,
+        )
+        extract_api = client.extract
+        assert extract_api is not None
+
+    def test_lazy_load_pipeline_api(self, app_id, secret_code):
+        """测试懒加载 Pipeline API"""
+        client = XParseClient(
+            app_id=app_id,
+            secret_code=secret_code,
+        )
+        pipeline_api = client.pipeline
+        assert pipeline_api is not None
+
+    def test_unknown_attribute(self, app_id, secret_code):
+        """测试访问未知属性"""
+        client = XParseClient(
+            app_id=app_id,
+            secret_code=secret_code,
+        )
+        with pytest.raises(AttributeError):
+            _ = client.unknown_api
+
+    def test_context_manager(self, app_id, secret_code):
+        """测试上下文管理器"""
+        with XParseClient(app_id=app_id, secret_code=secret_code) as client:
+            assert client is not None
+
+    def test_close(self, app_id, secret_code):
+        """测试关闭客户端"""
+        client = XParseClient(
+            app_id=app_id,
+            secret_code=secret_code,
+        )
+        # 预热 API 缓存
+        _ = client.parse
+        assert len(client._api_cache) > 0
+
+        # 关闭应该清空缓存
+        client.close()
+        assert len(client._api_cache) == 0

tests/unit/test_config.py

@@ -0,0 +1,160 @@
+"""配置类测试"""
+
+import pytest
+
+from xparse_client._config import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_SERVER_URL,
+    DEFAULT_TIMEOUT,
+    RetryConfiguration,
+    SDKConfiguration,
+)
+from xparse_client.exceptions import ConfigurationError
+
+
+class TestSDKConfiguration:
+    """SDK 配置测试"""
+
+    def test_basic_config(self, app_id, secret_code):
+        """测试基本配置"""
+        config = SDKConfiguration(
+            app_id=app_id,
+            secret_code=secret_code,
+        )
+        assert config.app_id == app_id
+        assert config.secret_code == secret_code
+        assert config.server_url == DEFAULT_SERVER_URL
+        assert config.timeout == DEFAULT_TIMEOUT
+        assert config.max_retries == DEFAULT_MAX_RETRIES
+
+    def test_custom_config(self, app_id, secret_code):
+        """测试自定义配置"""
+        config = SDKConfiguration(
+            app_id=app_id,
+            secret_code=secret_code,
+            server_url="https://custom.api.com",
+            timeout=60.0,
+            max_retries=5,
+        )
+        assert config.server_url == "https://custom.api.com"
+        assert config.timeout == 60.0
+        assert config.max_retries == 5
+
+    def test_trailing_slash_removed(self, app_id, secret_code):
+        """测试移除末尾斜杠"""
+        config = SDKConfiguration(
+            app_id=app_id,
+            secret_code=secret_code,
+            server_url="https://api.com/",
+        )
+        assert config.server_url == "https://api.com"
+
+    def test_missing_app_id(self, secret_code):
+        """测试缺少 app_id"""
+        with pytest.raises(ConfigurationError) as exc_info:
+            SDKConfiguration(app_id="", secret_code=secret_code)
+        assert "app_id" in str(exc_info.value)
+
+    def test_missing_secret_code(self, app_id):
+        """测试缺少 secret_code"""
+        with pytest.raises(ConfigurationError) as exc_info:
+            SDKConfiguration(app_id=app_id, secret_code="")
+        assert "secret_code" in str(exc_info.value)
+
+    def test_invalid_timeout(self, app_id, secret_code):
+        """测试无效的 timeout"""
+        with pytest.raises(ConfigurationError) as exc_info:
+            SDKConfiguration(
+                app_id=app_id,
+                secret_code=secret_code,
+                timeout=-1,
+            )
+        assert "timeout" in str(exc_info.value)
+
+    def test_invalid_max_retries(self, app_id, secret_code):
+        """测试无效的 max_retries"""
+        with pytest.raises(ConfigurationError) as exc_info:
+            SDKConfiguration(
+                app_id=app_id,
+                secret_code=secret_code,
+                max_retries=-1,
+            )
+        assert "max_retries" in str(exc_info.value)
+
+    def test_get_auth_headers(self, app_id, secret_code):
+        """测试获取认证头"""
+        config = SDKConfiguration(
+            app_id=app_id,
+            secret_code=secret_code,
+        )
+        headers = config.get_auth_headers()
+        assert headers["x-ti-app-id"] == app_id
+        assert headers["x-ti-secret-code"] == secret_code
+
+    def test_extra_headers(self, app_id, secret_code):
+        """测试额外请求头"""
+        config = SDKConfiguration(
+            app_id=app_id,
+            secret_code=secret_code,
+            extra_headers={"X-Custom": "value"},
+        )
+        headers = config.get_auth_headers()
+        assert headers["X-Custom"] == "value"
+
+    def test_from_env(self, app_id, secret_code, monkeypatch):
+        """测试从环境变量创建配置"""
+        monkeypatch.setenv("TEXTIN_APP_ID", app_id)
+        monkeypatch.setenv("TEXTIN_SECRET_CODE", secret_code)
+
+        config = SDKConfiguration.from_env()
+        assert config.app_id == app_id
+        assert config.secret_code == secret_code
+
+    def test_from_env_missing(self, monkeypatch):
+        """测试环境变量缺失"""
+        monkeypatch.delenv("TEXTIN_APP_ID", raising=False)
+        monkeypatch.delenv("TEXTIN_SECRET_CODE", raising=False)
+
+        with pytest.raises(ConfigurationError):
+            SDKConfiguration.from_env()
+
+
+class TestRetryConfiguration:
+    """重试配置测试"""
+
+    def test_default_config(self):
+        """测试默认配置"""
+        config = RetryConfiguration()
+        assert config.max_retries == DEFAULT_MAX_RETRIES
+        assert 429 in config.retry_status_codes
+        assert 500 in config.retry_status_codes
+
+    def test_calculate_backoff(self):
+        """测试退避时间计算"""
+        config = RetryConfiguration(backoff_base=2.0, backoff_max=60.0)
+
+        # 第0次重试: 2^0 = 1
+        assert config.calculate_backoff(0) == 1.0
+        # 第1次重试: 2^1 = 2
+        assert config.calculate_backoff(1) == 2.0
+        # 第2次重试: 2^2 = 4
+        assert config.calculate_backoff(2) == 4.0
+        # 第6次重试: 2^6 = 64 > 60，所以返回 60
+        assert config.calculate_backoff(6) == 60.0
+
+    def test_should_retry(self):
+        """测试是否应该重试"""
+        config = RetryConfiguration(max_retries=3)
+
+        # 可重试状态码
+        assert config.should_retry(429, 0) is True
+        assert config.should_retry(500, 0) is True
+        assert config.should_retry(503, 0) is True
+
+        # 不可重试状态码
+        assert config.should_retry(400, 0) is False
+        assert config.should_retry(401, 0) is False
+        assert config.should_retry(404, 0) is False
+
+        # 超过最大重试次数
+        assert config.should_retry(500, 3) is False