uapi-sdk-python 0.1.10__tar.gz → 0.1.14__tar.gz

{uapi_sdk_python-0.1.10 → uapi_sdk_python-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uapi-sdk-python
-Version: 0.1.10
+Version: 0.1.14
 Summary: Idiomatic UAPI SDK for Python
 Author-email: UAPI <dev@uapis.cn>
 Requires-Python: >=3.9
@@ -32,11 +32,13 @@ 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")
+client = UapiClient("https://uapis.cn", "YOUR_API_KEY")
+result = client.misc.get_misc_hotboard(type="weibo")
 print(result)
 ```
 
+这个接口默认只要传 `type` 就可以拿当前热榜。`time`、`keyword`、`time_start`、`time_end`、`limit`、`sources` 都是按场景再传的可选参数。
+
 > [!TIP]
 > 请使用与运行脚本相同的 Python 解释器安装依赖，例如执行 `python -m pip install uapi-sdk-python` 后再运行 `python main.py`。在 VS Code / Pyright 中若提示 “Import uapi could not be resolved”，将解释器切换到当前虚拟环境即可恢复补全。
 
@@ -54,6 +56,60 @@ print(result)
 
 如果你需要查看字段细节或内部逻辑，仓库中的 `./internal` 目录同步保留了由 `openapi-generator` 生成的完整结构体，随时可供参考。
 
+## 响应元信息
+
+每次请求完成后，SDK 会自动把响应 Header 解析成结构化的 `ResponseMeta`，你不用自己拆原始字符串。
+
+成功时可以通过 `client.last_response_meta` 读取，失败时可以通过 `err.meta` 读取，两条路径拿到的是同一套字段。
+
+```python
+from uapi import UapiClient, UapiError
+
+client = UapiClient("https://uapis.cn", "YOUR_API_KEY")
+
+# 成功路径
+client.social.get_social_qq_userinfo(qq="10001")
+meta = client.last_response_meta
+if meta:
+    print("这次请求原价:", meta.credits_requested or 0, "积分")
+    print("这次实际扣费:", meta.credits_charged or 0, "积分")
+    print("特殊计价:", meta.credits_pricing or "原价")
+    print("余额剩余:", meta.balance_remaining_cents or 0, "分")
+    print("资源包剩余:", meta.quota_remaining_credits or 0, "积分")
+    print("当前有效额度桶:", meta.active_quota_buckets or 0)
+    print("额度用空即停:", meta.stop_on_empty)
+    print("Key QPS:", meta.billing_key_rate_remaining or 0, "/", meta.billing_key_rate_limit or 0, meta.billing_key_rate_unit or "req")
+    print("Request ID:", meta.request_id)
+
+# 失败路径
+try:
+    client.social.get_social_qq_userinfo(qq="10001")
+except UapiError as err:
+    if err.meta:
+        print("Retry-After 秒数:", err.meta.retry_after_seconds)
+        print("Retry-After 原始值:", err.meta.retry_after_raw)
+        print("访客 QPS:", err.meta.visitor_rate_remaining or 0, "/", err.meta.visitor_rate_limit or 0)
+        print("Request ID:", err.meta.request_id)
+```
+
+常用字段一览：
+
+| 字段 | 说明 |
+|------|------|
+| `credits_requested` | 这次请求原本要扣多少积分，也就是请求价 |
+| `credits_charged` | 这次请求实际扣了多少积分 |
+| `credits_pricing` | 特殊计价原因，例如缓存半价 `cache-hit-half-price` |
+| `balance_remaining_cents` | 账户余额剩余（分） |
+| `quota_remaining_credits` | 资源包剩余积分 |
+| `active_quota_buckets` | 当前还有多少个有效额度桶参与计费 |
+| `stop_on_empty` | 额度耗尽后是否直接停止服务 |
+| `retry_after_seconds` / `retry_after_raw` | 限流后的等待时长；当服务端返回 HTTP 时间字符串时看 `retry_after_raw` |
+| `request_id` | 请求唯一 ID，排障时使用 |
+| `billing_key_rate_limit` / `billing_key_rate_remaining` | Billing Key 当前 QPS 规则的上限与剩余 |
+| `billing_ip_rate_limit` / `billing_ip_rate_remaining` | Billing Key 单 IP 当前 QPS 规则的上限与剩余 |
+| `visitor_rate_limit` / `visitor_rate_remaining` | 访客当前 QPS 规则的上限与剩余 |
+| `rate_limit_policies` / `rate_limits` | 完整结构化限流策略数据 |
+
 ## 进阶实践
 
 ### 缓存与幂等
@@ -62,7 +118,7 @@ print(result)
 from functools import lru_cache
 from uapi import UapiClient
 
-client = UapiClient("https://uapis.cn/api/v1", token="<TOKEN>")
+client = UapiClient("https://uapis.cn", token="YOUR_API_KEY")
 
 @lru_cache(maxsize=128)
 def cached_lookup(qq: str):
@@ -73,34 +129,19 @@ user = cached_lookup("10001")
 
 也可以在 FastAPI / Django 项目里配合 Redis，将 SDK 的响应序列化后写入缓存，命中即直接返回。
 
-### 注入自定义 httpx.Client
+### 调整超时与环境
 
 ```python
-import httpx
-from httpx import Auth
 from uapi import UapiClient
 
-class StaticToken(Auth):
-    def __init__(self, token: str):
-        self.token = token
-    def auth_flow(self, request):
-        request.headers["Authorization"] = f"Bearer {self.token}"
-        yield request
-
-http_client = httpx.Client(
-    timeout=5,
-    transport=httpx.HTTPTransport(retries=3),
-    event_hooks={"request": [lambda request: print("->", request.url)]},
-)
-
 client = UapiClient(
-    "https://uapis.cn/api/v1",
-    client=http_client,
-    auth=StaticToken("<TOKEN>"),
+    "https://uapis.cn",
+    token="YOUR_API_KEY",
+    timeout=5.0,
 )
 ```
 
-通过自定义 `client` / `transport` / `auth`，可以无缝植入代理、重试策略或 APM 埋点。
+如果你需要切换到别的环境，直接改 `base_url` 就可以；如果你只想缩短等待时间，传 `timeout` 就够了。
 
 ## 错误模型概览
 

{uapi_sdk_python-0.1.10 → uapi_sdk_python-0.1.14}/README.md

@@ -18,11 +18,13 @@ 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")
+client = UapiClient("https://uapis.cn", "YOUR_API_KEY")
+result = client.misc.get_misc_hotboard(type="weibo")
 print(result)
 ```
 
+这个接口默认只要传 `type` 就可以拿当前热榜。`time`、`keyword`、`time_start`、`time_end`、`limit`、`sources` 都是按场景再传的可选参数。
+
 > [!TIP]
 > 请使用与运行脚本相同的 Python 解释器安装依赖，例如执行 `python -m pip install uapi-sdk-python` 后再运行 `python main.py`。在 VS Code / Pyright 中若提示 “Import uapi could not be resolved”，将解释器切换到当前虚拟环境即可恢复补全。
 
@@ -40,6 +42,60 @@ print(result)
 
 如果你需要查看字段细节或内部逻辑，仓库中的 `./internal` 目录同步保留了由 `openapi-generator` 生成的完整结构体，随时可供参考。
 
+## 响应元信息
+
+每次请求完成后，SDK 会自动把响应 Header 解析成结构化的 `ResponseMeta`，你不用自己拆原始字符串。
+
+成功时可以通过 `client.last_response_meta` 读取，失败时可以通过 `err.meta` 读取，两条路径拿到的是同一套字段。
+
+```python
+from uapi import UapiClient, UapiError
+
+client = UapiClient("https://uapis.cn", "YOUR_API_KEY")
+
+# 成功路径
+client.social.get_social_qq_userinfo(qq="10001")
+meta = client.last_response_meta
+if meta:
+    print("这次请求原价:", meta.credits_requested or 0, "积分")
+    print("这次实际扣费:", meta.credits_charged or 0, "积分")
+    print("特殊计价:", meta.credits_pricing or "原价")
+    print("余额剩余:", meta.balance_remaining_cents or 0, "分")
+    print("资源包剩余:", meta.quota_remaining_credits or 0, "积分")
+    print("当前有效额度桶:", meta.active_quota_buckets or 0)
+    print("额度用空即停:", meta.stop_on_empty)
+    print("Key QPS:", meta.billing_key_rate_remaining or 0, "/", meta.billing_key_rate_limit or 0, meta.billing_key_rate_unit or "req")
+    print("Request ID:", meta.request_id)
+
+# 失败路径
+try:
+    client.social.get_social_qq_userinfo(qq="10001")
+except UapiError as err:
+    if err.meta:
+        print("Retry-After 秒数:", err.meta.retry_after_seconds)
+        print("Retry-After 原始值:", err.meta.retry_after_raw)
+        print("访客 QPS:", err.meta.visitor_rate_remaining or 0, "/", err.meta.visitor_rate_limit or 0)
+        print("Request ID:", err.meta.request_id)
+```
+
+常用字段一览：
+
+| 字段 | 说明 |
+|------|------|
+| `credits_requested` | 这次请求原本要扣多少积分，也就是请求价 |
+| `credits_charged` | 这次请求实际扣了多少积分 |
+| `credits_pricing` | 特殊计价原因，例如缓存半价 `cache-hit-half-price` |
+| `balance_remaining_cents` | 账户余额剩余（分） |
+| `quota_remaining_credits` | 资源包剩余积分 |
+| `active_quota_buckets` | 当前还有多少个有效额度桶参与计费 |
+| `stop_on_empty` | 额度耗尽后是否直接停止服务 |
+| `retry_after_seconds` / `retry_after_raw` | 限流后的等待时长；当服务端返回 HTTP 时间字符串时看 `retry_after_raw` |
+| `request_id` | 请求唯一 ID，排障时使用 |
+| `billing_key_rate_limit` / `billing_key_rate_remaining` | Billing Key 当前 QPS 规则的上限与剩余 |
+| `billing_ip_rate_limit` / `billing_ip_rate_remaining` | Billing Key 单 IP 当前 QPS 规则的上限与剩余 |
+| `visitor_rate_limit` / `visitor_rate_remaining` | 访客当前 QPS 规则的上限与剩余 |
+| `rate_limit_policies` / `rate_limits` | 完整结构化限流策略数据 |
+
 ## 进阶实践
 
 ### 缓存与幂等
@@ -48,7 +104,7 @@ print(result)
 from functools import lru_cache
 from uapi import UapiClient
 
-client = UapiClient("https://uapis.cn/api/v1", token="<TOKEN>")
+client = UapiClient("https://uapis.cn", token="YOUR_API_KEY")
 
 @lru_cache(maxsize=128)
 def cached_lookup(qq: str):
@@ -59,34 +115,19 @@ user = cached_lookup("10001")
 
 也可以在 FastAPI / Django 项目里配合 Redis，将 SDK 的响应序列化后写入缓存，命中即直接返回。
 
-### 注入自定义 httpx.Client
+### 调整超时与环境
 
 ```python
-import httpx
-from httpx import Auth
 from uapi import UapiClient
 
-class StaticToken(Auth):
-    def __init__(self, token: str):
-        self.token = token
-    def auth_flow(self, request):
-        request.headers["Authorization"] = f"Bearer {self.token}"
-        yield request
-
-http_client = httpx.Client(
-    timeout=5,
-    transport=httpx.HTTPTransport(retries=3),
-    event_hooks={"request": [lambda request: print("->", request.url)]},
-)
-
 client = UapiClient(
-    "https://uapis.cn/api/v1",
-    client=http_client,
-    auth=StaticToken("<TOKEN>"),
+    "https://uapis.cn",
+    token="YOUR_API_KEY",
+    timeout=5.0,
 )
 ```
 
-通过自定义 `client` / `transport` / `auth`，可以无缝植入代理、重试策略或 APM 埋点。
+如果你需要切换到别的环境，直接改 `base_url` 就可以；如果你只想缩短等待时间，传 `timeout` 就够了。
 
 ## 错误模型概览
 

{uapi_sdk_python-0.1.10 → uapi_sdk_python-0.1.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "uapi-sdk-python"
-version = "0.1.10"
+version = "0.1.14"
 description = "Idiomatic UAPI SDK for Python"
 readme = "README.md"
 requires-python = ">=3.9"

{uapi_sdk_python-0.1.10 → uapi_sdk_python-0.1.14}/uapi/client.py

@@ -12,10 +12,18 @@ class _Config:
     token: Optional[str] = None
     timeout: float = 15.0
 
+
+def _normalize_base_url(base_url: str) -> str:
+    normalized = base_url.rstrip("/")
+    if normalized.endswith("/api/v1"):
+        normalized = normalized[: -len("/api/v1")]
+    return normalized
+
 class _HTTP:
     def __init__(self, cfg: _Config):
         self._cfg = cfg
-        self._client = httpx.Client(timeout=cfg.timeout)
+        self._client = httpx.Client(timeout=cfg.timeout, trust_env=False)
+        self.last_response_meta: Optional[ResponseMeta] = None
 
     def request(self, method: str, path: str, *, params: Dict[str, Any] | None = None, json: Any | None = None, headers: Dict[str, str] | None = None):
         url = self._cfg.base_url.rstrip("/") + path
@@ -24,7 +32,10 @@ class _HTTP:
             headers["Authorization"] = f"Bearer {self._cfg.token}"
         r = self._client.request(method, url, params=params, json=json, headers=headers)
         if r.status_code >= 400:
-            raise map_error(r)
+            err = map_error(r)
+            self.last_response_meta = err.meta
+            raise err
+        self.last_response_meta = extract_meta(r.headers)
         # try json else bytes
         try:
             return r.json()
@@ -39,7 +50,7 @@ class UapiClient:
     """
 
     def __init__(self, base_url: str, token: str | None = None, timeout: float = 15.0):
-        self._http = _HTTP(_Config(base_url, token, timeout))
+        self._http = _HTTP(_Config(_normalize_base_url(base_url), token, timeout))
         # 动态挂载每个 Tag 的 API 门面
         _clipzy_zai_xian_jian_tie_ban = _ClipzyZaiXianJianTieBanApi(self._http)
         self.clipzy_zai_xian_jian_tie_ban = _clipzy_zai_xian_jian_tie_ban
@@ -90,6 +101,10 @@ class UapiClient:
         self.zhi_neng_sou_suo = _zhi_neng_sou_suo
         setattr(self, "智能搜索", _zhi_neng_sou_suo)
 
+    @property
+    def last_response_meta(self) -> Optional[ResponseMeta]:
+        return self._http.last_response_meta
+
 
 class _ClipzyZaiXianJianTieBanApi:
     def __init__(self, http: _HTTP):
@@ -428,12 +443,7 @@ class _ImageApi:
 这个接口会获取 Bing 搜索引擎当天全球同步的每日壁纸，并直接以图片形式返回。你可以用它来做应用的启动页、网站背景，或者任何需要每日更新精美图片的地方。
 
 ## 使用须知
-
-> [!NOTE]
-> **响应格式是图片**
-> 请注意，此接口成功时直接返回图片二进制数据（通常为 `image/jpeg`），而非 JSON 格式。请确保客户端能够正确处理。
-
-我们内置了备用方案：如果从必应官方获取图片失败，系统会尝试返回一张预存的高质量风景图，以保证服务的稳定性。
+此接口成功时直接返回图片二进制数据，通常是 `image/jpeg`，不是 JSON 格式。接入时请按图片响应来处理。
         """
         params = {}
         body = {}
@@ -472,21 +482,6 @@ class _ImageApi:
 
 ## 功能概述
 你提供一段文本内容，我们为你生成对应的二维码图片。你可以自定义尺寸、前景色、背景色，还支持透明背景，并选择不同的返回格式以适应不同场景。
-
-## 使用须知
-
-> [!IMPORTANT]
-> **关键参数 `format`**
-> 此参数决定了成功响应的内容类型和结构，请务必根据你的需求选择并正确处理响应：
-> - **`image`** (默认): 直接返回 `image/png` 格式的图片二进制数据，适合在 `<img>` 标签中直接使用。
-> - **`json`**: 返回一个包含 Base64 Data URI 的 JSON 对象，适合需要在前端直接嵌入CSS或HTML的场景。
-> - **`json_url`**: 返回一个包含图片临时URL的JSON对象，适合需要图片链接的场景。
-
-> [!TIP]
-> **颜色参数说明**
-> - 颜色参数使用十六进制格式（如 `#FF0000`）
-> - URL 中需要对 `#` 进行编码，即 `%23`（例如：`fgcolor=%23FF0000`）
-> - 当 `transparent=true` 时，`bgcolor` 参数会被忽略
         """
         params = {}
         body = {}
@@ -638,9 +633,6 @@ class _ImageApi:
         r"""图片敏感检测
         这是一个图片内容审核接口，自动识别图片中的违规内容并返回处理建议。
 
-> [!VIP]
-> 此接口限时免费开放，无需企业认证即可使用。
-
 ## 功能概述
 上传图片文件或提供图片URL，接口会自动分析图片内容，返回是否违规、风险等级和处理建议。适合对接到用户上传流程中，实现自动化内容审核。
 
@@ -872,19 +864,6 @@ class _MiscApi:
 
 ### 数据源列表
 传 `sources=true`，返回所有支持历史数据的平台列表。
-
-## 可选值
-`type` 参数接受多种不同的值，每种值对应一个不同的热榜来源。以下是目前支持的所有值：
-
-| 分类       | 支持的 type 值 |
-|------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| 视频/社区  | bilibili（哔哩哔哩弹幕网）, acfun（A站弹幕视频网站）, weibo（新浪微博热搜）, zhihu（知乎热榜）, zhihu-daily（知乎日报热榜）, douyin（抖音热榜）, kuaishou（快手热榜）, douban-movie（豆瓣电影榜单）, douban-group（豆瓣小组话题）, tieba（百度贴吧热帖）, hupu（虎扑热帖）, ngabbs（NGA游戏论坛热帖）, v2ex（V2EX技术社区热帖）, 52pojie（吾爱破解热帖）, hostloc（全球主机交流论坛）, coolapk（酷安热榜） |
-| 新闻/资讯  | baidu（百度热搜）, thepaper（澎湃新闻热榜）, toutiao（今日头条热榜）, qq-news（腾讯新闻热榜）, sina（新浪热搜）, sina-news（新浪新闻热榜）, netease-news（网易新闻热榜）, huxiu（虎嗅网热榜）, ifanr（爱范儿热榜） |
-| 技术/IT    | sspai（少数派热榜）, ithome（IT之家热榜）, ithome-xijiayi（IT之家·喜加一栏目）, juejin（掘金社区热榜）, jianshu（简书热榜）, guokr（果壳热榜）, 36kr（36氪热榜）, 51cto（51CTO热榜）, csdn（CSDN博客热榜）, nodeseek（NodeSeek 技术社区）, hellogithub（HelloGitHub 项目推荐） |
-| 游戏       | lol（英雄联盟热帖）, genshin（原神热榜）, honkai（崩坏3热榜）, starrail（星穹铁道热榜） |
-| 音乐       | netease-music（网易云音乐热歌榜）, qq-music（QQ音乐热歌榜） |
-| 其他       | weread（微信读书热门书籍）, weatheralarm（天气预警信息）, earthquake（地震速报）, history（历史上的今天） |
-
         """
         params = {}
         body = {}
@@ -1034,9 +1013,6 @@ graph TD
         r"""获取支持的快递公司列表
         不确定系统支持哪些快递公司？这个接口返回完整的支持列表。
 
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
-
 ## 功能概述
 获取系统当前支持的所有快递公司列表，包括每家公司的标准编码（code）和中文名称（name）。
 
@@ -1056,9 +1032,6 @@ graph TD
         r"""识别快递公司
         不确定手里的快递单号属于哪家快递公司？这个接口专门做识别，不查物流。
 
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
-
 ## 功能概述
 输入快递单号，系统会根据单号规则快速识别出最可能的快递公司。如果存在多个可能的匹配结果，还会在 `alternatives` 字段中返回备选项，供你参考选择。
 
@@ -1081,16 +1054,15 @@ graph TD
         r"""查询快递物流信息
         买了东西想知道快递到哪儿了？这个接口帮你实时追踪物流状态。
 
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
-
 ## 功能概述
-提供一个快递单号，系统会自动识别快递公司并返回完整的物流轨迹信息。支持中通、圆通、韵达、申通、极兔、顺丰、京东、EMS、德邦等60+国内外主流快递公司。
+提供一个快递单号，系统会自动识别快递公司并返回完整的物流轨迹信息。这个接口目前可以查询中通、圆通、韵达、申通、极兔、京东、EMS、德邦等主流快递公司的物流信息。
 
 ## 使用须知
+目前暂不支持顺丰快递单号的物流查询。
+
 - **自动识别**：不知道是哪家快递？系统会根据单号规则自动识别快递公司（推荐使用）
 - **手动指定**：如果已知快递公司，可以传递 `carrier_code` 参数，查询速度会更快
-- **手机尾号验证**：部分快递公司需要验证收件人手机尾号才能查询详细物流，如果返回「暂无物流信息」，建议尝试传入 `phone` 参数
+- **手机尾号验证**：部分快递公司需要验证收件人手机尾号才能查询详细物流，如果返回 `暂无物流信息`，建议尝试传入 `phone` 参数
 - **查询时效**：物流信息实时查询，响应时间通常在1-2秒内
         """
         params = {}
@@ -1123,9 +1095,9 @@ graph TD
 
 ## 可选功能模块
 - `extended=true`：扩展气象字段（体感温度、能见度、气压、紫外线、空气质量及污染物分项数据）
-- `forecast=true`：多天预报（最多7天，含日出日落、风速等详细数据）
+- `forecast=true`：多天预报（最多7天，会额外返回每天的最高温度、最低温度，以及日出日落、风速等详细数据）
 - `hourly=true`：逐小时预报（24小时）
-- `minutely=true`：分钟级降水预报（仅国内城市）
+- `minutely=true`：分钟级降水预报（仅国内城市，精确到2分钟）
 - `indices=true`：18项生活指数（穿衣、紫外线、洗车、运动、花粉等）
 
 ## 天气字段说明
@@ -1133,7 +1105,7 @@ graph TD
 
 常见值包括：晴、多云、阴、小雨、中雨、大雨、雷阵雨、小雪、中雪、大雪、雨夹雪、雾、霾、沙尘。
 
-如果你的业务需要稳定分类，建议结合 `weather_code` 做自己的映射归类。
+如果你的业务需要稳定的天气分类，建议使用 `weather_code` 进行映射。完整的天气图标代码请参考[天气图标代码表](#enum-list)。
         """
         params = {}
         body = {}
@@ -1770,10 +1742,7 @@ class _SocialApi:
     
     def get_social_qq_groupinfo(self, **kwargs):
         r"""查询 QQ 群信息
-        想在你的应用里展示QQ群信息？这个接口让你轻松获取群名称、群头像、群简介、成员数量等详细公开信息。它能帮你快速构建社群导航站、群聊推荐系统，或是为你的数据分析工具提供可靠的数据源。
-
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
+        想在你的应用里展示QQ群信息？这个接口让你轻松获取群名称、群头像、群简介、成员数量等详细公开信息。
 
 ## 功能概述
 你只需要提供一个QQ群号（5-12位纯数字），接口就会返回该群的完整公开信息。我们会先验证群号的有效性，确保返回的数据准确可靠。接口响应速度快，数据结构清晰，非常适合集成到各类应用场景中。
@@ -1813,9 +1782,6 @@ class _SocialApi:
         r"""查询 QQ 信息
         这是一个功能丰富的QQ用户信息查询接口，能够获取QQ用户的详细公开信息。
 
-> [!VIP]
-> 我们在近日优化了此接口，速度应该会更加快了。 
-
 ## 功能概述
 通过QQ号查询用户的详细信息，包括基础资料、等级信息、VIP状态等。返回的信息丰富全面，适合用于用户画像分析、社交应用集成等场景。
 
@@ -2299,19 +2265,16 @@ class _TranslateApi:
         r"""AI智能翻译
         这是一个商业级的AI智能翻译服务，采用最新的神经网络翻译技术和大语言模型，提供远超传统机器翻译的质量。
 
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者深度集成和测试。未来，它将转为付费API，为用户提供更稳定、更智能的翻译服务。
-
 ## 功能概述
 
-- **智能双模式**: 支持单个文本翻译和批量文本翻译的统一接口设计，自动识别请求类型并提供相应的翻译服务。系统会根据输入自动判断是处理单条文本还是批量文本，无需使用不同的接口。
+- **单文本翻译**: 专注处理单条文本翻译，适合需要高质量译文的业务场景。
 - **多风格适配**: 提供随意口语化、专业商务、学术正式、文学艺术四种翻译风格，能够根据不同场景需求调整翻译的语言风格和表达方式。
 - **上下文感知**: 支持通用、商务、技术、医疗、法律、市场营销、娱乐、教育、新闻等九种专业领域的上下文翻译，确保术语准确性和表达地道性。
-- **高质量保证**: 内置质量评估系统，对每次翻译结果进行流畅度、准确度、完整性评分，并提供置信度分数和替代翻译建议。
-- **智能解释**: 提供关键词组翻译注释、文化背景说明和语法结构分析，帮助用户理解翻译逻辑和文化差异。
-- **高效批量**: 批量翻译支持最多50条文本，总计10万字符，配备智能并发控制（1-10并发）和失败重试机制。
-- **快速模式**: 提供快速模式选项，在保证95%+准确率的前提下，响应时间缩短至800ms内，适合实时翻译和聊天应用。
 - **格式保留**: 智能识别并保持原文的格式结构，包括换行、缩进、特殊符号等，确保翻译后的文本保持良好的可读性。
+
+## 支持的语言
+
+我们支持超过100种语言的互译，详见下方参数列表。
         """
         params = {}
         body = {}
@@ -2323,12 +2286,6 @@ class _TranslateApi:
         if "context" in kwargs:
             body["context"] = kwargs["context"]
         
-        if "fast_mode" in kwargs:
-            body["fast_mode"] = kwargs["fast_mode"]
-        
-        if "max_concurrency" in kwargs:
-            body["max_concurrency"] = kwargs["max_concurrency"]
-        
         if "preserve_format" in kwargs:
             body["preserve_format"] = kwargs["preserve_format"]
         
@@ -2341,9 +2298,6 @@ class _TranslateApi:
         if "text" in kwargs:
             body["text"] = kwargs["text"]
         
-        if "texts" in kwargs:
-            body["texts"] = kwargs["texts"]
-        
         path = "/api/v1/ai/translate"
         
         return self._http.request("POST", path, params=params, json=body if body else None)
@@ -2490,9 +2444,6 @@ class _WebparseApi:
 
 ## 功能概述
 
-> [!VIP]
-> 本 API 目前处于**限时免费**阶段，未来将转为付费服务。
-
 提交一个网页 URL，我们会自动抓取主体内容，剔除广告、导航栏等干扰元素，并转换为 Markdown 格式。同时会提取标题、作者、发布日期等元数据，生成 YAML Front Matter。
 
 任务提交后会立即返回任务 ID，你可以用它来查询处理进度和结果。单个任务最长处理 60 秒，结果缓存 30 分钟。
@@ -2531,14 +2482,12 @@ class _MinGanCiShiBieApi:
         r"""分析敏感词
         分析单个或多个关键词的敏感程度，返回标准化风险标签与置信度结果。
 
-> [!VIP]
-> 本API基于先进的分析模型，提供三级缓存策略和并发处理能力。
-
 ## 功能概述
 
 - **模型驱动**: 使用先进的分析模型进行语义分析。
 - **高性能**: 采用三级缓存策略（持久化存储 → 统一缓存 → 模型分析），确保高频请求的响应速度。
 - **并发支持**: 支持批量并发处理，单次最多可分析100个关键词。
+- **输入限制**: 单条关键词最多 1,000 字符，总字符数最多 20,000。
 - **标准标签**: 返回 `label` 字段，明确区分 `sensitive` 与 `normal`。
 - **分类清晰**: 返回 `category` 字段，用于标识具体风险类别。
 - **置信度输出**: 返回 `confidence` 字段，范围为0.0到1.0。
@@ -2635,9 +2584,6 @@ UAPI Pro Search 是一个智能搜索引擎，采用机器学习算法对搜索
 - **时间范围过滤**: 支持按天/周/月/年过滤结果
 - **站内搜索**: 支持 `site:` 操作符，在指定网站内搜索
 - **文件类型过滤**: 支持 `filetype:` 操作符，快速找到 PDF、Word 等特定格式文件
-
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
       
         """
         params = {}
@@ -2669,4 +2615,3 @@ UAPI Pro Search 是一个智能搜索引擎，采用机器学习算法对搜索
         
         return self._http.request("POST", path, params=params, json=body if body else None)
     
-

uapi_sdk_python-0.1.14/uapi/errors.py

@@ -0,0 +1,374 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Optional
+import httpx
+
+@dataclass
+class RateLimitPolicyEntry:
+    name: str
+    quota: Optional[int] = None
+    unit: Optional[str] = None
+    window_seconds: Optional[int] = None
+
+@dataclass
+class RateLimitStateEntry:
+    name: str
+    remaining: Optional[int] = None
+    unit: Optional[str] = None
+    reset_after_seconds: Optional[int] = None
+
+@dataclass
+class ResponseMeta:
+    request_id: Optional[str] = None
+    retry_after_raw: Optional[str] = None
+    retry_after_seconds: Optional[int] = None
+    debit_status: Optional[str] = None
+    credits_requested: Optional[int] = None
+    credits_charged: Optional[int] = None
+    credits_pricing: Optional[str] = None
+    active_quota_buckets: Optional[int] = None
+    stop_on_empty: Optional[bool] = None
+    rate_limit_policy_raw: Optional[str] = None
+    rate_limit_raw: Optional[str] = None
+    rate_limit_policies: Dict[str, RateLimitPolicyEntry] = field(default_factory=dict)
+    rate_limits: Dict[str, RateLimitStateEntry] = field(default_factory=dict)
+    balance_limit_cents: Optional[int] = None
+    balance_remaining_cents: Optional[int] = None
+    quota_limit_credits: Optional[int] = None
+    quota_remaining_credits: Optional[int] = None
+    visitor_quota_limit_credits: Optional[int] = None
+    visitor_quota_remaining_credits: Optional[int] = None
+    billing_key_rate_limit: Optional[int] = None
+    billing_key_rate_remaining: Optional[int] = None
+    billing_key_rate_unit: Optional[str] = None
+    billing_key_rate_window_seconds: Optional[int] = None
+    billing_key_rate_reset_after_seconds: Optional[int] = None
+    billing_ip_rate_limit: Optional[int] = None
+    billing_ip_rate_remaining: Optional[int] = None
+    billing_ip_rate_unit: Optional[str] = None
+    billing_ip_rate_window_seconds: Optional[int] = None
+    billing_ip_rate_reset_after_seconds: Optional[int] = None
+    visitor_rate_limit: Optional[int] = None
+    visitor_rate_remaining: Optional[int] = None
+    visitor_rate_unit: Optional[str] = None
+    visitor_rate_window_seconds: Optional[int] = None
+    visitor_rate_reset_after_seconds: Optional[int] = None
+    raw_headers: Dict[str, str] = field(default_factory=dict)
+
+class UapiError(Exception):
+    code: str
+    status: int
+    message: str
+    details: Any
+    payload: Any
+    meta: Optional[ResponseMeta]
+
+    def __init__(
+        self,
+        code: str,
+        status: int,
+        message: str,
+        details: Any = None,
+        payload: Any = None,
+        meta: Optional[ResponseMeta] = None,
+    ):
+        super().__init__(f"[{status}] {code}: {message}")
+        self.code = code
+        self.status = status
+        self.message = message
+        self.details = details
+        self.payload = payload
+        self.meta = meta
+
+
+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 InsufficientCreditsError(UapiError):
+    """账户积分不足 (INSUFFICIENT_CREDITS)"""
+    DEFAULT_STATUS = 402
+
+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
+
+class VisitorMonthlyQuotaExhaustedError(UapiError):
+    """访客月度免费额度已用尽 (VISITOR_MONTHLY_QUOTA_EXHAUSTED)"""
+    DEFAULT_STATUS = 429
+
+
+def _default_code(status: int) -> str:
+    if status == 400:
+        return "INVALID_PARAMETER"
+    if status == 401:
+        return "UNAUTHORIZED"
+    if status == 402:
+        return "INSUFFICIENT_CREDITS"
+    if status == 404:
+        return "NOT_FOUND"
+    if status == 413:
+        return "REQUEST_ENTITY_TOO_LARGE"
+    if status == 429:
+        return "SERVICE_BUSY"
+    if status >= 500:
+        return "INTERNAL_SERVER_ERROR"
+    return "API_ERROR"
+
+def _parse_int(value: Optional[str]) -> Optional[int]:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+def _parse_bool(value: Optional[str]) -> Optional[bool]:
+    if value is None:
+        return None
+    lowered = value.strip().lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    return None
+
+def _unquote(value: str) -> str:
+    text = value.strip()
+    if len(text) >= 2 and text[0] == '"' and text[-1] == '"':
+        return text[1:-1]
+    return text
+
+def _parse_structured_items(raw: Optional[str]) -> list[tuple[str, Dict[str, str]]]:
+    if not raw:
+        return []
+    items: list[tuple[str, Dict[str, str]]] = []
+    for chunk in [part.strip() for part in raw.split(",") if part.strip()]:
+        segments = [segment.strip() for segment in chunk.split(";") if segment.strip()]
+        if not segments:
+            continue
+        name = _unquote(segments[0])
+        params: Dict[str, str] = {}
+        for segment in segments[1:]:
+            if "=" not in segment:
+                continue
+            key, value = segment.split("=", 1)
+            params[key.strip()] = _unquote(value)
+        items.append((name, params))
+    return items
+
+def extract_meta(headers: Mapping[str, str]) -> ResponseMeta:
+    raw_headers = {str(key).lower(): str(value) for key, value in headers.items()}
+    rate_limit_policies: Dict[str, RateLimitPolicyEntry] = {}
+    rate_limits: Dict[str, RateLimitStateEntry] = {}
+
+    for name, params in _parse_structured_items(raw_headers.get("ratelimit-policy")):
+        rate_limit_policies[name] = RateLimitPolicyEntry(
+            name=name,
+            quota=_parse_int(params.get("q")),
+            unit=params.get("uapi-unit"),
+            window_seconds=_parse_int(params.get("w")),
+        )
+
+    for name, params in _parse_structured_items(raw_headers.get("ratelimit")):
+        rate_limits[name] = RateLimitStateEntry(
+            name=name,
+            remaining=_parse_int(params.get("r")),
+            unit=params.get("uapi-unit"),
+            reset_after_seconds=_parse_int(params.get("t")),
+        )
+
+    billing_key_rate_policy = rate_limit_policies.get("billing-key-rate")
+    billing_key_rate_state = rate_limits.get("billing-key-rate")
+    billing_ip_rate_policy = rate_limit_policies.get("billing-ip-rate")
+    billing_ip_rate_state = rate_limits.get("billing-ip-rate")
+    visitor_rate_policy = rate_limit_policies.get("visitor-rate")
+    visitor_rate_state = rate_limits.get("visitor-rate")
+
+    return ResponseMeta(
+        request_id=raw_headers.get("x-request-id"),
+        retry_after_raw=raw_headers.get("retry-after"),
+        retry_after_seconds=_parse_int(raw_headers.get("retry-after")),
+        debit_status=raw_headers.get("uapi-debit-status"),
+        credits_requested=_parse_int(raw_headers.get("uapi-credits-requested")),
+        credits_charged=_parse_int(raw_headers.get("uapi-credits-charged")),
+        credits_pricing=raw_headers.get("uapi-credits-pricing"),
+        active_quota_buckets=_parse_int(raw_headers.get("uapi-quota-active-buckets")),
+        stop_on_empty=_parse_bool(raw_headers.get("uapi-stop-on-empty")),
+        rate_limit_policy_raw=raw_headers.get("ratelimit-policy"),
+        rate_limit_raw=raw_headers.get("ratelimit"),
+        rate_limit_policies=rate_limit_policies,
+        rate_limits=rate_limits,
+        balance_limit_cents=rate_limit_policies.get("billing-balance").quota if "billing-balance" in rate_limit_policies else None,
+        balance_remaining_cents=rate_limits.get("billing-balance").remaining if "billing-balance" in rate_limits else None,
+        quota_limit_credits=rate_limit_policies.get("billing-quota").quota if "billing-quota" in rate_limit_policies else None,
+        quota_remaining_credits=rate_limits.get("billing-quota").remaining if "billing-quota" in rate_limits else None,
+        visitor_quota_limit_credits=rate_limit_policies.get("visitor-quota").quota if "visitor-quota" in rate_limit_policies else None,
+        visitor_quota_remaining_credits=rate_limits.get("visitor-quota").remaining if "visitor-quota" in rate_limits else None,
+        billing_key_rate_limit=billing_key_rate_policy.quota if billing_key_rate_policy else None,
+        billing_key_rate_remaining=billing_key_rate_state.remaining if billing_key_rate_state else None,
+        billing_key_rate_unit=billing_key_rate_policy.unit if billing_key_rate_policy and billing_key_rate_policy.unit is not None else (billing_key_rate_state.unit if billing_key_rate_state else None),
+        billing_key_rate_window_seconds=billing_key_rate_policy.window_seconds if billing_key_rate_policy else None,
+        billing_key_rate_reset_after_seconds=billing_key_rate_state.reset_after_seconds if billing_key_rate_state else None,
+        billing_ip_rate_limit=billing_ip_rate_policy.quota if billing_ip_rate_policy else None,
+        billing_ip_rate_remaining=billing_ip_rate_state.remaining if billing_ip_rate_state else None,
+        billing_ip_rate_unit=billing_ip_rate_policy.unit if billing_ip_rate_policy and billing_ip_rate_policy.unit is not None else (billing_ip_rate_state.unit if billing_ip_rate_state else None),
+        billing_ip_rate_window_seconds=billing_ip_rate_policy.window_seconds if billing_ip_rate_policy else None,
+        billing_ip_rate_reset_after_seconds=billing_ip_rate_state.reset_after_seconds if billing_ip_rate_state else None,
+        visitor_rate_limit=visitor_rate_policy.quota if visitor_rate_policy else None,
+        visitor_rate_remaining=visitor_rate_state.remaining if visitor_rate_state else None,
+        visitor_rate_unit=visitor_rate_policy.unit if visitor_rate_policy and visitor_rate_policy.unit is not None else (visitor_rate_state.unit if visitor_rate_state else None),
+        visitor_rate_window_seconds=visitor_rate_policy.window_seconds if visitor_rate_policy else None,
+        visitor_rate_reset_after_seconds=visitor_rate_state.reset_after_seconds if visitor_rate_state else None,
+        raw_headers=raw_headers,
+    )
+
+def _pick_details(data: Any) -> Any:
+    if not isinstance(data, dict):
+        return None
+    if "details" in data:
+        return data["details"]
+    if "quota" in data:
+        return data["quota"]
+    if "docs" in data:
+        return data["docs"]
+    return None
+
+def map_error(r: httpx.Response) -> UapiError:
+    code = None
+    msg = r.text
+    data: Any = None
+    try:
+        data = r.json()
+        code = data.get("code") or data.get("error") or data.get("errCode") or _default_code(r.status_code)
+        msg = data.get("message") or data.get("errMsg") or msg
+    except Exception:
+        code = _default_code(r.status_code)
+    status = r.status_code
+    meta = extract_meta(r.headers)
+    cls = _class_by_code(code, status)
+    return cls(code, status, msg, _pick_details(data), data, meta)
+
+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,
+        
+        "INSUFFICIENT_CREDITS": InsufficientCreditsError,
+        
+        "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,
+        
+        "VISITOR_MONTHLY_QUOTA_EXHAUSTED": VisitorMonthlyQuotaExhaustedError,
+        
+    }
+    return mapping.get(c) or ({
+        400: InvalidParameterError,
+        401: UnauthorizedError,
+        402: InsufficientCreditsError,
+        404: NotFoundError,
+        429: ServiceBusyError,
+        500: InternalServerErrorError,
+    }.get(status) or UapiError)

{uapi_sdk_python-0.1.10 → uapi_sdk_python-0.1.14}/uapi_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uapi-sdk-python
-Version: 0.1.10
+Version: 0.1.14
 Summary: Idiomatic UAPI SDK for Python
 Author-email: UAPI <dev@uapis.cn>
 Requires-Python: >=3.9
@@ -32,11 +32,13 @@ 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")
+client = UapiClient("https://uapis.cn", "YOUR_API_KEY")
+result = client.misc.get_misc_hotboard(type="weibo")
 print(result)
 ```
 
+这个接口默认只要传 `type` 就可以拿当前热榜。`time`、`keyword`、`time_start`、`time_end`、`limit`、`sources` 都是按场景再传的可选参数。
+
 > [!TIP]
 > 请使用与运行脚本相同的 Python 解释器安装依赖，例如执行 `python -m pip install uapi-sdk-python` 后再运行 `python main.py`。在 VS Code / Pyright 中若提示 “Import uapi could not be resolved”，将解释器切换到当前虚拟环境即可恢复补全。
 
@@ -54,6 +56,60 @@ print(result)
 
 如果你需要查看字段细节或内部逻辑，仓库中的 `./internal` 目录同步保留了由 `openapi-generator` 生成的完整结构体，随时可供参考。
 
+## 响应元信息
+
+每次请求完成后，SDK 会自动把响应 Header 解析成结构化的 `ResponseMeta`，你不用自己拆原始字符串。
+
+成功时可以通过 `client.last_response_meta` 读取，失败时可以通过 `err.meta` 读取，两条路径拿到的是同一套字段。
+
+```python
+from uapi import UapiClient, UapiError
+
+client = UapiClient("https://uapis.cn", "YOUR_API_KEY")
+
+# 成功路径
+client.social.get_social_qq_userinfo(qq="10001")
+meta = client.last_response_meta
+if meta:
+    print("这次请求原价:", meta.credits_requested or 0, "积分")
+    print("这次实际扣费:", meta.credits_charged or 0, "积分")
+    print("特殊计价:", meta.credits_pricing or "原价")
+    print("余额剩余:", meta.balance_remaining_cents or 0, "分")
+    print("资源包剩余:", meta.quota_remaining_credits or 0, "积分")
+    print("当前有效额度桶:", meta.active_quota_buckets or 0)
+    print("额度用空即停:", meta.stop_on_empty)
+    print("Key QPS:", meta.billing_key_rate_remaining or 0, "/", meta.billing_key_rate_limit or 0, meta.billing_key_rate_unit or "req")
+    print("Request ID:", meta.request_id)
+
+# 失败路径
+try:
+    client.social.get_social_qq_userinfo(qq="10001")
+except UapiError as err:
+    if err.meta:
+        print("Retry-After 秒数:", err.meta.retry_after_seconds)
+        print("Retry-After 原始值:", err.meta.retry_after_raw)
+        print("访客 QPS:", err.meta.visitor_rate_remaining or 0, "/", err.meta.visitor_rate_limit or 0)
+        print("Request ID:", err.meta.request_id)
+```
+
+常用字段一览：
+
+| 字段 | 说明 |
+|------|------|
+| `credits_requested` | 这次请求原本要扣多少积分，也就是请求价 |
+| `credits_charged` | 这次请求实际扣了多少积分 |
+| `credits_pricing` | 特殊计价原因，例如缓存半价 `cache-hit-half-price` |
+| `balance_remaining_cents` | 账户余额剩余（分） |
+| `quota_remaining_credits` | 资源包剩余积分 |
+| `active_quota_buckets` | 当前还有多少个有效额度桶参与计费 |
+| `stop_on_empty` | 额度耗尽后是否直接停止服务 |
+| `retry_after_seconds` / `retry_after_raw` | 限流后的等待时长；当服务端返回 HTTP 时间字符串时看 `retry_after_raw` |
+| `request_id` | 请求唯一 ID，排障时使用 |
+| `billing_key_rate_limit` / `billing_key_rate_remaining` | Billing Key 当前 QPS 规则的上限与剩余 |
+| `billing_ip_rate_limit` / `billing_ip_rate_remaining` | Billing Key 单 IP 当前 QPS 规则的上限与剩余 |
+| `visitor_rate_limit` / `visitor_rate_remaining` | 访客当前 QPS 规则的上限与剩余 |
+| `rate_limit_policies` / `rate_limits` | 完整结构化限流策略数据 |
+
 ## 进阶实践
 
 ### 缓存与幂等
@@ -62,7 +118,7 @@ print(result)
 from functools import lru_cache
 from uapi import UapiClient
 
-client = UapiClient("https://uapis.cn/api/v1", token="<TOKEN>")
+client = UapiClient("https://uapis.cn", token="YOUR_API_KEY")
 
 @lru_cache(maxsize=128)
 def cached_lookup(qq: str):
@@ -73,34 +129,19 @@ user = cached_lookup("10001")
 
 也可以在 FastAPI / Django 项目里配合 Redis，将 SDK 的响应序列化后写入缓存，命中即直接返回。
 
-### 注入自定义 httpx.Client
+### 调整超时与环境
 
 ```python
-import httpx
-from httpx import Auth
 from uapi import UapiClient
 
-class StaticToken(Auth):
-    def __init__(self, token: str):
-        self.token = token
-    def auth_flow(self, request):
-        request.headers["Authorization"] = f"Bearer {self.token}"
-        yield request
-
-http_client = httpx.Client(
-    timeout=5,
-    transport=httpx.HTTPTransport(retries=3),
-    event_hooks={"request": [lambda request: print("->", request.url)]},
-)
-
 client = UapiClient(
-    "https://uapis.cn/api/v1",
-    client=http_client,
-    auth=StaticToken("<TOKEN>"),
+    "https://uapis.cn",
+    token="YOUR_API_KEY",
+    timeout=5.0,
 )
 ```
 
-通过自定义 `client` / `transport` / `auth`，可以无缝植入代理、重试策略或 APM 埋点。
+如果你需要切换到别的环境，直接改 `base_url` 就可以；如果你只想缩短等待时间，传 `timeout` 就够了。
 
 ## 错误模型概览
 

uapi_sdk_python-0.1.10/uapi/errors.py

@@ -1,153 +0,0 @@
-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: InternalServerErrorError}.get(status) or UapiError )