uapi-sdk-python 0.1.1__py3-none-any.whl

uapi/errors.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+from typing import Any, Dict, Optional
+import httpx
+
+class UapiError(Exception):
+    code: str
+    status: int
+    message: str
+    details: Optional[Dict[str, Any]]
+
+    def __init__(self, code: str, status: int, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(f"[{status}] {code}: {message}")
+        self.code = code
+        self.status = status
+        self.message = message
+        self.details = details
+
+
+class ApiErrorError(UapiError):
+    """上游/内部错误 (API_ERROR)"""
+    DEFAULT_STATUS = 502
+
+class AvatarNotFoundError(UapiError):
+    """头像未找到 (AVATAR_NOT_FOUND)"""
+    DEFAULT_STATUS = 404
+
+class ConversionFailedError(UapiError):
+    """转换失败 (CONVERSION_FAILED)"""
+    DEFAULT_STATUS = 400
+
+class FileOpenErrorError(UapiError):
+    """文件打开错误 (FILE_OPEN_ERROR)"""
+    DEFAULT_STATUS = 500
+
+class FileRequiredError(UapiError):
+    """文件必需 (FILE_REQUIRED)"""
+    DEFAULT_STATUS = 400
+
+class InternalServerErrorError(UapiError):
+    """服务器内部错误 (INTERNAL_SERVER_ERROR)"""
+    DEFAULT_STATUS = 500
+
+class InvalidParameterError(UapiError):
+    """请求参数错误 (INVALID_PARAMETER)"""
+    DEFAULT_STATUS = 400
+
+class InvalidParamsError(UapiError):
+    """无效参数 (INVALID_PARAMS)"""
+    DEFAULT_STATUS = 400
+
+class NotFoundError(UapiError):
+    """资源不存在 (NOT_FOUND)"""
+    DEFAULT_STATUS = 404
+
+class NoMatchError(UapiError):
+    """无匹配 (NO_MATCH)"""
+    DEFAULT_STATUS = 404
+
+class NoTrackingDataError(UapiError):
+    """无物流数据 (NO_TRACKING_DATA)"""
+    DEFAULT_STATUS = 404
+
+class PhoneInfoFailedError(UapiError):
+    """手机号信息查询失败 (PHONE_INFO_FAILED)"""
+    DEFAULT_STATUS = 500
+
+class RecognitionFailedError(UapiError):
+    """识别失败 (RECOGNITION_FAILED)"""
+    DEFAULT_STATUS = 404
+
+class RequestEntityTooLargeError(UapiError):
+    """错误 (REQUEST_ENTITY_TOO_LARGE)"""
+    DEFAULT_STATUS = 413
+
+class ServiceBusyError(UapiError):
+    """请求过于频繁 (SERVICE_BUSY)"""
+    DEFAULT_STATUS = 429
+
+class TimezoneNotFoundError(UapiError):
+    """时区未找到 (TIMEZONE_NOT_FOUND)"""
+    DEFAULT_STATUS = 404
+
+class UnauthorizedError(UapiError):
+    """请求未授权 (UNAUTHORIZED)"""
+    DEFAULT_STATUS = 401
+
+class UnsupportedCarrierError(UapiError):
+    """不支持的承运商 (UNSUPPORTED_CARRIER)"""
+    DEFAULT_STATUS = 404
+
+class UnsupportedFormatError(UapiError):
+    """格式不支持 (UNSUPPORTED_FORMAT)"""
+    DEFAULT_STATUS = 400
+
+
+def map_error(r: httpx.Response) -> UapiError:
+    code = None
+    msg = r.text
+    try:
+        data = r.json()
+        code = data.get("code") or data.get("error") or data.get("errCode") or "API_ERROR"
+        msg = data.get("message") or data.get("errMsg") or msg
+        details = data.get("details")
+    except Exception:
+        details = None
+    status = r.status_code
+    cls = _class_by_code(code, status)
+    return cls(code, status, msg, details)
+
+def _class_by_code(code: str, status: int):
+    c = (code or "").upper()
+    mapping = {
+        
+        "API_ERROR": ApiErrorError,
+        
+        "AVATAR_NOT_FOUND": AvatarNotFoundError,
+        
+        "CONVERSION_FAILED": ConversionFailedError,
+        
+        "FILE_OPEN_ERROR": FileOpenErrorError,
+        
+        "FILE_REQUIRED": FileRequiredError,
+        
+        "INTERNAL_SERVER_ERROR": InternalServerErrorError,
+        
+        "INVALID_PARAMETER": InvalidParameterError,
+        
+        "INVALID_PARAMS": InvalidParamsError,
+        
+        "NOT_FOUND": NotFoundError,
+        
+        "NO_MATCH": NoMatchError,
+        
+        "NO_TRACKING_DATA": NoTrackingDataError,
+        
+        "PHONE_INFO_FAILED": PhoneInfoFailedError,
+        
+        "RECOGNITION_FAILED": RecognitionFailedError,
+        
+        "REQUEST_ENTITY_TOO_LARGE": RequestEntityTooLargeError,
+        
+        "SERVICE_BUSY": ServiceBusyError,
+        
+        "TIMEZONE_NOT_FOUND": TimezoneNotFoundError,
+        
+        "UNAUTHORIZED": UnauthorizedError,
+        
+        "UNSUPPORTED_CARRIER": UnsupportedCarrierError,
+        
+        "UNSUPPORTED_FORMAT": UnsupportedFormatError,
+        
+    }
+    return mapping.get(c) or ( {400: InvalidParameterError, 401: UnauthorizedError, 404: NotFoundError, 429: ServiceBusyError, 500: InternalServerError}.get(status) or UapiError )

uapi_sdk_python-0.1.1.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: uapi-sdk-python
+Version: 0.1.1
+Summary: Idiomatic UAPI SDK for Python
+Author-email: UAPI <dev@uapis.cn>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.1
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+
+# uapi-sdk-python
+
+![Banner](https://raw.githubusercontent.com/AxT-Team/uapi-sdk-python/main/banner.png)
+
+[![Python](https://img.shields.io/badge/Python-3.9+-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![Docs](https://img.shields.io/badge/Docs-uapis.cn-2EAE5D?style=flat-square)](https://uapis.cn/)
+[![PyPI](https://img.shields.io/pypi/v/uapi-sdk-python?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/uapi-sdk-python/)
+
+> [!NOTE]
+> 所有接口的 Python 示例都可以在 [UApi](https://uapis.cn/docs/introduction) 的接口文档页面，向下滚动至 **快速启动** 区块后直接复制。
+
+## 快速开始
+
+```bash
+pip install uapi-sdk-python
+```
+
+```python
+from uapi import UapiClient
+
+client = UapiClient("https://uapis.cn/api/v1")
+result = client.social.get_social_qq_userinfo(qq="10001")
+print(result)
+```
+
+## 特性
+
+现在你不再需要反反复复的查阅文档了。
+
+只需在 IDE 中键入 `client.`，所有核心模块——如 `social`、`game`、`image`——即刻同步展现。进一步输入即可直接定位到 `get_social_qq_userinfo` 这样的具体方法，其名称与文档的 `operationId` 严格保持一致，确保了开发过程的直观与高效。
+
+所有方法签名只接受真实且必需的参数。当你在构建请求时，IDE 会即时提示 `qq`、`username` 等键名，这彻底杜绝了在 `dict`/关键字参数中因拼写错误而导致的运行时错误。
+
+针对 401、404、429 等标准 HTTP 响应，SDK 已将其统一映射为具名的异常类型。这些异常均附带 `code`、`status`、`details` 等关键上下文信息，确保你在日志中能第一时间准确、快速地诊断问题。
+
+`UapiClient(base_url, token, timeout)` 默认使用 `httpx` 并自动追加 `Authorization` 头；需要切换环境或调整超时时，只要改一次构造参数即可。
+
+如果你需要查看字段细节或内部逻辑，仓库中的 `./internal` 目录同步保留了由 `openapi-generator` 生成的完整结构体，随时可供参考。
+
+## 错误模型概览
+
+| HTTP 状态码 | SDK 错误类型                                  | 附加信息                                                                          |
+|-------------|----------------------------------------------|------------------------------------------------------------------------------------|
+| 401/403     | `UnauthorizedError`                          | `code`、`status`                                                                   |
+| 404         | `NotFoundError` / `NoMatchError`             | `code`、`status`                                                                   |
+| 400         | `InvalidParameterError` / `InvalidParamsError` | `code`、`status`、`details`                                                        |
+| 429         | `ServiceBusyError`                           | `code`、`status`、`retry_after_seconds`（用于决定何时重试）                        |
+| 5xx         | `InternalServerErrorError` / `ApiErrorError` | `code`、`status`、`details`                                                        |
+| 其他 4xx    | `UapiError`                                  | `code`、`status`、`details`                                                        |
+
+## 其他 SDK
+
+| 语言        | 仓库地址                                                     |
+|-------------|--------------------------------------------------------------|
+| Go          | https://github.com/AxT-Team/uapi-go-sdk                      |
+| Python（当前）      | https://github.com/AxT-Team/uapi-python-sdk                  |
+| TypeScript| https://github.com/AxT-Team/uapi-typescript-sdk           |
+| Browser (TypeScript/JavaScript)| https://github.com/AxT-Team/uapi-browser-sdk        |
+| Java        | https://github.com/AxT-Team/uapi-java-sdk                    |
+| PHP         | https://github.com/AxT-Team/uapi-php-sdk                     |
+| C#          | https://github.com/AxT-Team/uapi-csharp-sdk                  |
+| C++         | https://github.com/AxT-Team/uapi-cpp-sdk                     |
+| Rust        | https://github.com/AxT-Team/uapi-rust-sdk                    |
+
+## 文档
+
+访问 [UApi文档首页](https://uapis.cn/docs/introduction) 并选择任意接口，向下滚动到 **快速启动** 区块即可看到最新的 Python 示例代码。
+

uapi_sdk_python-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+uapi/__init__.py,sha256=3dluUZfyWYYGTWzDBFip0d5YZej6waZiq2ayvJ0RI9o,86
+uapi/client.py,sha256=yaOdgDNUvUnw3bXQPTJyO6paT3KnuPzkv-77Nk9eUPU,88187
+uapi/errors.py,sha256=npeo8-u6-j0IZ4-H50rBuCWAB4kLG6pqpq0rlLX2ANw,4390
+uapi_sdk_python-0.1.1.dist-info/METADATA,sha256=sjyeezSTjL8ybi4-S0605wpiGswlFynsaOthpHYanEY,4801
+uapi_sdk_python-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+uapi_sdk_python-0.1.1.dist-info/top_level.txt,sha256=0TrPOLLMqin88fxqxR9T5piS4dSoyju9HFiPu1oPEUU,5
+uapi_sdk_python-0.1.1.dist-info/RECORD,,

uapi_sdk_python-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

uapi_sdk_python-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+uapi