feat: Mock API (#130)

* add mock mode

* add ut tests and readme

* update readme for mockapi

* update ci yaml

* support 3.9

Author: ponytailer

.github/workflows/ci.yml

@@ -23,9 +23,13 @@ jobs:
           version: "latest"
       - name: Set up Python
         run: uv python install ${{ matrix.python-version }}
+      - name: Verify Python Version
+        run: |
+          uv run python -c "import sys; print(f'Python version: {sys.version}')"
+          uv run python -c "import sys; assert sys.version_info >= (3, 10), f'Python version {sys.version} is less than 3.10'"
       - name: Install Dependencies
         run: uv sync --all-extras
-      - name: Install Dependencies
+      - name: Install Project Dependencies
         run: uv run pip install -r requirements.txt
       - name: Test
         run: uv run pytest tests/ --cov=pydantic_client --cov-report=term-missing:skip-covered --cov-report=xml

.github/workflows/python-publish.yml

@@ -14,13 +14,15 @@ jobs:
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v4
       with:
-        python-version: '3.x'
+        python-version: '3.10'  # 明确指定3.10或更高版本，与项目要求一致
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install build
+        python -c "import sys; print(f'Python version: {sys.version}')"
+        python -c "import sys; assert sys.version_info >= (3, 10), f'Python version {sys.version} is less than 3.10'"
     - name: Build package
       run: python -m build
     - name: Publish package

README.md

@@ -170,6 +170,93 @@ user = client.get_user("123")
 
 ```
 
+## Mock API Responses
+
+You can configure the client to return mock responses instead of making actual API calls. This is useful for testing or development purposes.
+
+### Setting Mock Responses Directly
+
+```python
+from pydantic_client import RequestsWebClient, get
+
+class UserResponse(BaseModel):
+    id: int
+    name: str
+
+class MyClient(RequestsWebClient):
+    @get("/users/{user_id}")
+    def get_user(self, user_id: int) -> UserResponse:
+        pass
+
+# Create client and configure mocks
+client = MyClient(base_url="https://api.example.com")
+client.set_mock_config(mock_config=[
+    {
+        "name": "get_user",
+        "output": {
+            "id": 123,
+            "name": "Mock User"
+        }
+    }
+])
+
+# This will return the mock response without making an actual API call
+user = client.get_user(1)  # Returns UserResponse(id=123, name="Mock User")
+```
+
+### Loading Mock Responses from a JSON File
+
+You can also load mock configurations from a JSON file:
+
+```python
+# Load mock data from a JSON file
+client.set_mock_config(mock_config_path="path/to/mock_data.json")
+```
+
+The JSON file should follow this format:
+
+```json
+[
+    {
+        "name": "get_user",
+        "output": {
+            "id": 123,
+            "name": "Mock User"
+        }
+    },
+    {
+        "name": "list_users",
+        "output": {
+            "users": [
+                {"id": 1, "name": "User 1"},
+                {"id": 2, "name": "User 2"}
+            ]
+        }
+    }
+]
+```
+
+### Setting Mock Responses in Client Configuration
+
+You can also include mock configuration when creating a client from configuration:
+
+```python
+config = {
+    "base_url": "https://api.example.com",
+    "timeout": 10,
+    "mock_config": [
+        {
+            "name": "get_user",
+            "output": {
+                "id": 123,
+                "name": "Mock User"
+            }
+        }
+    ]
+}
+
+client = MyClient.from_config(config)
+```
 
 ### Timing Context Manager
 
@@ -213,6 +300,7 @@ client = MyAPIClient.from_config(config)
 The library automatically validates responses against Pydantic models when specified as return types
 in the method definitions.
 
+
 ## Error Handling
 
 HTTP errors are raised as exceptions by the underlying HTTP client libraries. Make sure to handle

example/example_mock.py

@@ -0,0 +1,133 @@
+"""
+Example for using mock functionality in pydantic-client
+"""
+import logging
+from typing import List, Optional
+from pydantic import BaseModel
+
+from pydantic_client.sync_client import RequestsWebClient
+from pydantic_client.decorators import get, post, patch
+
+# 设置日志格式和级别
+logging.basicConfig(level=logging.INFO, 
+                   format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
+# 定义API响应模型
+class User(BaseModel):
+    name: str
+    age: int
+    email: Optional[str] = None
+
+
+class UserList(BaseModel):
+    users: List[User]
+    total: int
+
+
+# 定义API客户端
+class MockableApiClient(RequestsWebClient):
+    @get("/users")
+    def get_users(self) -> UserList:
+        """获取用户列表"""
+        pass
+    
+    @get("/users/{user_id}")
+    def get_user(self, user_id: int) -> User:
+        """获取单个用户"""
+        pass
+    
+    @post("/users")
+    def create_user(self, user: User) -> User:
+        """创建用户"""
+        pass
+    
+    @patch("/users/{user_id}")
+    def update_user(self, user_id: int, user: User) -> User:
+        """更新用户"""
+        pass
+
+
+def main():
+    # 创建客户端
+    client = MockableApiClient(base_url="https://api.example.com")
+    
+    # 设置mock数据
+    client.set_mock_config(mock_config=[
+        {
+            "name": "get_users",
+            "output": {
+                "users": [
+                    {"name": "张三", "age": 30, "email": "zhangsan@example.com"},
+                    {"name": "李四", "age": 25, "email": "lisi@example.com"}
+                ],
+                "total": 2
+            }
+        },
+        {
+            "name": "get_user",
+            "output": {
+                "name": "张三",
+                "age": 30,
+                "email": "zhangsan@example.com"
+            }
+        },
+        {
+            "name": "create_user",
+            "output": {
+                "name": "王五",
+                "age": 35,
+                "email": "wangwu@example.com"
+            }
+        }
+    ])
+    
+    # 使用API方法 - 将返回mock数据而不是实际发送请求
+    users = client.get_users()
+    print(f"用户列表: {users.users}")
+    print(f"总用户数: {users.total}")
+    
+    user = client.get_user(1)
+    print(f"单个用户: {user.name}, {user.age} 岁")
+    
+    new_user = User(name="王五", age=35, email="wangwu@example.com")
+    created_user = client.create_user(new_user)
+    print(f"创建的用户: {created_user.name}, {created_user.email}")
+    
+    # 没有mock配置的方法会尝试实际API调用
+    # 注意: 下面这行代码会尝试实际发送请求,因为我们没有为update_user设置mock
+    # 在这个示例中会失败,因为我们的API地址不存在
+    # try:
+    #     updated_user = client.update_user(1, new_user)
+    #     print(f"更新的用户: {updated_user.name}")
+    # except Exception as e:
+    #     print(f"API调用失败(预期的行为): {e}")
+
+
+def from_config_example():
+    """演示使用from_config创建带mock配置的客户端"""
+    config = {
+        "base_url": "https://api.example.com",
+        "timeout": 10,
+        "mock_config": [
+            {
+                "name": "get_users",
+                "output": {
+                    "users": [
+                        {"name": "配置张三", "age": 30, "email": "config_zhangsan@example.com"},
+                        {"name": "配置李四", "age": 25, "email": "config_lisi@example.com"}
+                    ],
+                    "total": 2
+                }
+            }
+        ]
+    }
+    
+    client = MockableApiClient.from_config(config)
+    users = client.get_users()
+    print("\n从配置创建的客户端:")
+    print(f"用户列表: {users.users}")
+
+
+if __name__ == "__main__":
+    main()
+    from_config_example()

pydantic_client/async_client.py

@@ -1,9 +1,12 @@
 from typing import Any, Dict, Optional, TypeVar
+import logging
 
 from pydantic import BaseModel
 
 from .base import BaseWebClient, RequestInfo
 
+logger = logging.getLogger(__name__)
+
 try:
     import aiohttp
 except ImportError:
@@ -25,25 +28,30 @@ def __init__(
         super().__init__(base_url, headers, timeout, session, statsd_address)
 
     async def _request(self, request_info: RequestInfo) -> Any:
+        # Check if there's a mock response for this method
+        mock_response = self._get_mock_response(request_info)
+        if mock_response:
+            return mock_response
+
+        import aiohttp
         request_params = self.dump_request_params(request_info)
         response_model = request_params.pop("response_model")
 
         request_params = self.before_request(request_params)
 
-        async with aiohttp.ClientSession() as session:
-            async with session.request(
-                **request_params,
-                timeout=aiohttp.ClientTimeout(total=self.timeout)
-            ) as response:
-                response.raise_for_status()
+        if not self.session:
+            self.session = aiohttp.ClientSession()
+
+        async with self.session.request(**request_params) as response:
+            response.raise_for_status()
 
-                if response_model is str:
-                    return await response.text()
-                elif response_model is bytes:
-                    return await response.content.read()
-                elif not response_model:
-                    return await response.json()
-                return response_model.model_validate(await response.json(), from_attributes=True)
+            if response_model is str:
+                return await response.text()
+            elif response_model is bytes:
+                return await response.content.read()
+            elif not response_model:
+                return await response.json()
+            return response_model.model_validate(await response.json(), from_attributes=True)
 
 
 class HttpxWebClient(BaseWebClient):
@@ -63,6 +71,12 @@ def __init__(
             raise ImportError("please install httpx: `pip install httpx`")
 
     async def _request(self, request_info: RequestInfo) -> Any:
+        # Check if there's a mock response for this method
+        mock_response = self._get_mock_response(request_info)
+        if mock_response:
+            return mock_response
+            
+        # 没有mock数据，继续进行正常请求
         import httpx
         request_params = self.dump_request_params(request_info)
         response_model = request_params.pop("response_model")