fiuai-sdk-python 0.12.0__tar.gz → 0.13.0__tar.gz

{fiuai_sdk_python-0.12.0 → fiuai_sdk_python-0.13.0}/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.13.0] - 2026-05-13
+
+### Fixed
+- `ApiError` 字段 (`code` / `type` / `message` / `detail` / `traceback`) 增加 `field_validator(mode="before")`, 对 frappe 偶发返回的 `list` / `dict` / `None` 类型自动规范化为 `str`, 修复 `ApiError.message=['Contract already exists']` 等 list 形态触发 Pydantic 校验失败导致 `parse_response` 整体崩溃的问题
+- `_normalize_error_dict` 入口对 `type` / `message` / `display_message` / `title` / `code` / `context` 同步用 `_to_text` 兜底规范化, 避免 `_MANDATORY_RE.match(...)` 在拿到非 str 时抛 `TypeError`
+- `parse_response` 加最外层 try/except 兜底, 任何未预期异常都返回结构化 `ApiResponse(error.code=SERVER_ERROR)`, 兑现"绝不抛异常"契约
+- `FiuaiSDK.get_user_profile_info` 解析失败分支错误地把 `str` 赋给 `ApiError` 字段、给没有 setter 的 deprecated property 赋值, 导致二次崩溃, 现改为构造 `ApiError(code=INTERNAL_VALIDATION_ERROR)` 写入 `error/errors`
+- `__version__` 与 `pyproject.toml` 版本号不一致 (`0.11.6` vs `0.12.0`) 统一为 `0.13.0`
+
+### Added
+- `FiuaiSDK._safe_request` 内部统一封装所有 `httpx` 调用, 捕获 `TimeoutException` / `RequestError` / 其他异常, 统一返回 `ApiResponse(error.code=NETWORK_ERROR)` 或 `SERVER_ERROR`, SDK 调用方不再需要捕获 httpx 异常
+- `resp._to_text` 公共兜底 helper, 把任意 (list / dict / None / 其他) 安全规范化为 str
+
 ## [Unreleased]
 
 ### Added

{fiuai_sdk_python-0.12.0 → fiuai_sdk_python-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiuai_sdk_python
-Version: 0.12.0
+Version: 0.13.0
 Summary: FiuAI Python SDK - 企业级AI服务集成开发工具包
 Project-URL: Homepage, https://github.com/fiuai/fiuai-sdk-python
 Project-URL: Documentation, https://github.com/fiuai/fiuai-sdk-python#readme

{fiuai_sdk_python-0.12.0 → fiuai_sdk_python-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fiuai_sdk_python"
-version = "0.12.0"
+version = "0.13.0"
 description = "FiuAI Python SDK - 企业级AI服务集成开发工具包"
 readme = "README.md"
 requires-python = ">=3.12"

{fiuai_sdk_python-0.12.0 → fiuai_sdk_python-0.13.0}/src/fiuai_sdk_python/__init__.py

@@ -18,7 +18,7 @@ from .error_code import (
 )
 from .resp import ApiError, ApiResponse, parse_response
 
-__version__ = "0.11.6"
+__version__ = "0.13.0"
 
 __all__ = [
     'FiuaiSDK',

{fiuai_sdk_python-0.12.0 → fiuai_sdk_python-0.13.0}/src/fiuai_sdk_python/client.py

@@ -10,7 +10,8 @@ from logging import getLogger
 from .type import UserProfile
 from .profile import UserProfileInfo
 from .auth import AuthHeader
-from .resp import parse_response, ApiResponse
+from .resp import ApiError, ApiResponse, _build_network_error_response, parse_response
+from .error_code import FiuaiErrorCode
 from .context import get_current_headers
 
 
@@ -220,11 +221,12 @@ class FiuaiSDK(object):
    
     def get_avaliable_company(self, page: int=1, page_size: int=20, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        r = self.client.get(self.url + "/api/method/fiuai.network.doctype.company.company.get_available_companies", 
-                           params={"page": page, "page_size": page_size}, 
-                           headers=headers)
-        
-        return self.post_process(r)
+        return self._safe_request(
+            "GET",
+            self.url + "/api/method/fiuai.network.doctype.company.company.get_available_companies",
+            params={"page": page, "page_size": page_size},
+            headers=headers,
+        )
     
     def swith_company(self, tenant: str = "", company: str = "") -> ApiResponse:
 
@@ -266,37 +268,60 @@ class FiuaiSDK(object):
             user_id = self.headers.x_fiuai_user
 
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + f"/api/v2/internal/user/profile/{user_id}", headers=headers)
-
-        profile_response = self.post_process(res)
+        profile_response = self._safe_request(
+            "GET",
+            self.url + f"/api/v2/internal/user/profile/{user_id}",
+            headers=headers,
+        )
 
-        if profile_response.is_success():
-            try:
-                profile_response.data = UserProfileInfo.model_validate(profile_response.data)
-            except Exception as e:
-                profile_response.error = str(e)
-                profile_response.error_code = "PROFILE_FORMAT_ERROR"
-                return profile_response
-            return profile_response
-        else:
+        if not profile_response.is_success():
             return profile_response
 
+        try:
+            profile_response.data = UserProfileInfo.model_validate(profile_response.data)
+        except Exception as e:
+            logger.warning("UserProfileInfo parse failed for user=%s: %s", user_id, e)
+            err = ApiError(
+                code=FiuaiErrorCode.INTERNAL_VALIDATION_ERROR.value,
+                type="ProfileFormatError",
+                message="用户信息格式异常，请联系管理员",
+                detail=str(e),
+                http_status_code=profile_response.status_code,
+            )
+            profile_response.api_success = False
+            profile_response.error = err
+            profile_response.errors = [err]
+            profile_response.data = None
+        return profile_response
+
 
    
     def internal_post_req(self, uri, postdata={}, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/' + uri.lstrip('/'), data=postdata, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/' + uri.lstrip('/'),
+            data=postdata,
+            headers=headers,
+        )
 
     def internal_get_req(self, uri, params={}, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + '/api/v2/internal/' + uri.lstrip('/'), params=params, headers=headers)
-        return self.post_process(res)
-    
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/' + uri.lstrip('/'),
+            params=params,
+            headers=headers,
+        )
+
     def internal_create(self, data={}, auto_submit: bool = False, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/create', data={"data":json.dumps(data, ensure_ascii=False), "auto_submit": auto_submit}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/create',
+            data={"data": json.dumps(data, ensure_ascii=False), "auto_submit": auto_submit},
+            headers=headers,
+        )
 
     def internal_get(self, doctype, name, fields=None, filters=None, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         d = {
@@ -308,8 +333,12 @@ class FiuaiSDK(object):
         if filters:
             d["filters"] = json.dumps(filters)
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + '/api/v2/internal/doctype/get', params=d, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/doctype/get',
+            params=d,
+            headers=headers,
+        )
 
     def get_decrypted_password(
         self,
@@ -321,12 +350,12 @@ class FiuaiSDK(object):
         """从 Frappe __Auth 读取 Password 类型字段明文 (internal get_password)."""
         params = {"doctype": doctype, "name": name, "fieldname": fieldname}
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(
+        resp = self._safe_request(
+            "GET",
             self.url + "/api/v2/internal/doctype/get_password",
             params=params,
             headers=headers,
         )
-        resp = self.post_process(res)
         if resp.is_success() and resp.data and isinstance(resp.data, dict):
             pw = resp.data.get("password")
             return pw if isinstance(pw, str) else None
@@ -346,76 +375,169 @@ class FiuaiSDK(object):
         if order_by:
             d["order_by"] = order_by
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(
-            self.url + '/api/v2/internal/doctype/get_list', 
-            params=d, 
-            headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/doctype/get_list',
+            params=d,
+            headers=headers,
+        )
 
-    
     def internal_update(self, data={}, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/update', data={"data":json.dumps(data, ensure_ascii=False)}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/update',
+            data={"data": json.dumps(data, ensure_ascii=False)},
+            headers=headers,
+        )
 
     def internal_delete(self, doctype, name, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/delete', data={"doctype": doctype, "name":name}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/delete',
+            data={"doctype": doctype, "name": name},
+            headers=headers,
+        )
 
     def internal_submit(self, doctype, name, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/submit', data={"doctype": doctype, "name":name}, headers=headers)
-        return self.post_process(res)
-    
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/submit',
+            data={"doctype": doctype, "name": name},
+            headers=headers,
+        )
+
     def internal_cancel(self, doctype, name, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/cancel', data={"doctype": doctype, "name":name}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/cancel',
+            data={"doctype": doctype, "name": name},
+            headers=headers,
+        )
 
 
     ######## 特殊接口 ########
     def get_meta(self, doctype: str, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + '/api/v2/internal/doctype/meta/' + doctype, headers=headers)
-      
-        return self.post_process(res)
-    
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/doctype/meta/' + doctype,
+            headers=headers,
+        )
 
     def get_ontology_event(self, event_id: str, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + '/api/v2/internal/ontology/event/' + event_id, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/ontology/event/' + event_id,
+            headers=headers,
+        )
 
     def get_ontology_event_list(self, event_filter: Dict[str, Any], extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
-
         headers = self._get_merged_headers(extra_headers)
-
-        ### url encode 可能 的 list 或者 dict 值
-        
-
-        res = self.client.get(self.url + '/api/v2/internal/ontology/event', params={"event_filter": quote(json.dumps(event_filter, ensure_ascii=False))}, headers=headers)
-      
-        return self.post_process(res)
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/ontology/event',
+            params={"event_filter": quote(json.dumps(event_filter, ensure_ascii=False))},
+            headers=headers,
+        )
 
     def add_ontology_event(self, data: Dict[str, Any], extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/ontology/event/add', data={"data": json.dumps(data, ensure_ascii=False)}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/ontology/event/add',
+            data={"data": json.dumps(data, ensure_ascii=False)},
+            headers=headers,
+        )
 
     def update_ontology_event(self, data: Dict[str, Any], extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
-
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/ontology/event', data={"data": json.dumps(data, ensure_ascii=False)}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/ontology/event',
+            data={"data": json.dumps(data, ensure_ascii=False)},
+            headers=headers,
+        )
 
     def batch_add_ontology_event(self, data: List[Dict[str, Any]], extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/ontology/event/batch_add', data={"data": json.dumps(data, ensure_ascii=False)}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/ontology/event/batch_add',
+            data={"data": json.dumps(data, ensure_ascii=False)},
+            headers=headers,
+        )
 
    
     ######## 数据处理 ########
+    def _safe_request(self, method: str, url: str, **kwargs) -> ApiResponse:
+        """统一的 HTTP 请求封装, 兜底捕获 httpx 网络异常.
+
+        SDK 对外契约: 永远返回 ``ApiResponse``, 不抛 httpx 异常. 调用方只需读
+        ``resp.is_success()`` / ``resp.error.code`` 即可分流业务/网络错误.
+
+        Args:
+            method: HTTP 方法, "GET" / "POST" (大小写不敏感)
+            url: 完整请求 URL
+            **kwargs: 透传给 ``httpx.Client.{get,post}`` 的参数
+
+        Returns:
+            ApiResponse: 结构化响应. 网络异常时 ``error.code`` 为
+            ``NETWORK_ERROR`` / ``SERVER_ERROR``.
+        """
+        method_upper = method.upper()
+        try:
+            if method_upper == "GET":
+                res = self.client.get(url, **kwargs)
+            elif method_upper == "POST":
+                res = self.client.post(url, **kwargs)
+            else:
+                logger.error("Unsupported HTTP method: %s", method)
+                return _build_network_error_response(
+                    code=FiuaiErrorCode.SERVER_ERROR,
+                    message=f"Unsupported HTTP method: {method}",
+                    status_code=500,
+                    http_success=False,
+                )
+        except httpx.TimeoutException as e:
+            logger.warning("HTTP timeout: %s %s, detail=%s", method_upper, url, e)
+            return _build_network_error_response(
+                code=FiuaiErrorCode.NETWORK_ERROR,
+                message="请求超时，请稍后重试",
+                status_code=504,
+                http_success=False,
+                detail=str(e),
+            )
+        except httpx.RequestError as e:
+            logger.warning(
+                "HTTP request error: %s %s, type=%s, detail=%s",
+                method_upper,
+                url,
+                type(e).__name__,
+                e,
+            )
+            return _build_network_error_response(
+                code=FiuaiErrorCode.NETWORK_ERROR,
+                message=f"网络异常: {type(e).__name__}",
+                status_code=502,
+                http_success=False,
+                detail=str(e),
+            )
+        except Exception as e:
+            logger.exception("Unexpected HTTP error: %s %s", method_upper, url)
+            return _build_network_error_response(
+                code=FiuaiErrorCode.SERVER_ERROR,
+                message="请求执行异常",
+                status_code=500,
+                http_success=False,
+                detail=str(e),
+            )
+        return self.post_process(res)
+
     def post_process(self, response) -> ApiResponse:
         """
         处理API响应，使用结构化的错误处理系统

{fiuai_sdk_python-0.12.0 → fiuai_sdk_python-0.13.0}/src/fiuai_sdk_python/resp.py

@@ -26,12 +26,13 @@ HTTP 响应规整化.
 内部 helper 拆到 ``_resp_helpers.py`` (单文件 < 400 行规约).
 """
 
+import json
 import logging
 import warnings
 from typing import Any, Dict, List, Optional
 
 from httpx import Response
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from . import _resp_helpers as _h
 from .error_code import (
@@ -44,6 +45,40 @@ from .error_parsers import parse_error_context
 logger = logging.getLogger(__name__)
 
 
+def _to_text(value: Any) -> str:
+    """把任意值安全规范化成字符串.
+
+    设计目标: 上游 (frappe / 网关) 偶尔会把本该是 str 的字段返回 list/dict/None
+    (例如 ``message=['Contract already exists']``), 直接进 Pydantic 会校验失败.
+    本 helper 兜底处理:
+    - None / 空白 -> ""
+    - list -> "; ".join(各元素递归 _to_text)
+    - dict -> 优先取 message/title, 否则 json.dumps
+    - 其他 -> str(value)
+    """
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        parts: List[str] = []
+        for item in value:
+            text = _to_text(item)
+            if text and text.strip():
+                parts.append(text)
+        return "; ".join(parts)
+    if isinstance(value, dict):
+        for key in ("message", "title", "detail"):
+            candidate = value.get(key)
+            if candidate:
+                return _to_text(candidate)
+        try:
+            return json.dumps(value, ensure_ascii=False)
+        except Exception:
+            return str(value)
+    return str(value)
+
+
 # 历史调试样例, 保留作为协议参考 (frappe v2 errors + messages 双源结构):
 # {
 #   'errors': [{
@@ -84,6 +119,36 @@ class ApiError(BaseModel):
     http_status_code: int = Field(default=500, description="HTTP 状态码")
     traceback: Optional[str] = Field(default=None, description="异常 traceback (仅 dev)")
 
+    @field_validator("code", "type", "message", mode="before")
+    @classmethod
+    def _coerce_required_text(cls, value: Any, info: Any) -> str:
+        """str 必填字段的兜底规范化: list/dict/None 也不会触发 Pydantic 校验失败.
+
+        - code 为 None/空 时回退到 ``FiuaiErrorCode.UNKNOWN.value``, 保住错误码语义
+        - message/type 为 None 时降级为空字符串
+        """
+        if value is None or (isinstance(value, str) and not value):
+            if info.field_name == "code":
+                return FiuaiErrorCode.UNKNOWN.value
+            return ""
+        if isinstance(value, str):
+            return value
+        text = _to_text(value)
+        if not text and info.field_name == "code":
+            return FiuaiErrorCode.UNKNOWN.value
+        return text
+
+    @field_validator("detail", "traceback", mode="before")
+    @classmethod
+    def _coerce_optional_text(cls, value: Any) -> Optional[str]:
+        """Optional[str] 字段保留 None 语义, 但 list/dict 仍兜底成 str."""
+        if value is None:
+            return None
+        if isinstance(value, str):
+            return value
+        text = _to_text(value)
+        return text or None
+
 
 class ApiResponse(BaseModel):
     """API 响应结构体.
@@ -172,18 +237,20 @@ def _normalize_error_dict(raw_error: Dict[str, Any], http_status_code: int) -> A
     if not isinstance(raw_error, dict):
         raw_error = {}
 
-    exception_type = (raw_error.get("type") or "").strip()
-    raw_message = raw_error.get("message") or ""
-    display_message = raw_error.get("display_message") or ""
-    title = raw_error.get("title") or ""
+    exception_type = _to_text(raw_error.get("type")).strip()
+    raw_message = _to_text(raw_error.get("message"))
+    display_message = _to_text(raw_error.get("display_message"))
+    title = _to_text(raw_error.get("title"))
 
-    code_str = raw_error.get("code")
+    code_value = raw_error.get("code")
+    code_str = _to_text(code_value).strip() if code_value is not None else ""
     if not code_str:
         code_str = exception_to_code(exception_type).value
         if code_str == FiuaiErrorCode.UNKNOWN.value:
             code_str = status_code_to_code(http_status_code).value
 
-    context = raw_error.get("context") or {}
+    raw_context = raw_error.get("context")
+    context: Dict[str, Any] = raw_context if isinstance(raw_context, dict) else {}
     if not context and exception_type and raw_message:
         context = parse_error_context(exception_type, raw_message)
 
@@ -336,6 +403,22 @@ def parse_response(response: Optional[Response]) -> ApiResponse:
     Returns:
         ApiResponse: 结构化的 API 响应, 一定不会抛异常
     """
+    try:
+        return _parse_response_impl(response)
+    except Exception as e:
+        logger.exception("parse_response unexpected failure")
+        fallback_status = getattr(response, "status_code", 0) or 500
+        return _build_network_error_response(
+            code=FiuaiErrorCode.SERVER_ERROR,
+            message="SDK 解析响应时发生未预期错误，请联系管理员",
+            status_code=fallback_status,
+            http_success=False,
+            detail=str(e),
+        )
+
+
+def _parse_response_impl(response: Optional[Response]) -> ApiResponse:
+    """``parse_response`` 主体实现, 任何异常由外层 ``parse_response`` 统一兜底."""
     if response is None:
         return _build_network_error_response(
             code=FiuaiErrorCode.API_NO_RESPONSE,