uapi-sdk-python 0.1.5__tar.gz → 0.1.13__tar.gz

{uapi_sdk_python-0.1.5 → uapi_sdk_python-0.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uapi-sdk-python
-Version: 0.1.5
+Version: 0.1.13
 Summary: Idiomatic UAPI SDK for Python
 Author-email: UAPI <dev@uapis.cn>
 Requires-Python: >=3.9
@@ -14,7 +14,7 @@ Requires-Dist: isort; extra == "dev"
 
 # uapi-sdk-python
 
-![Banner](https://raw.githubusercontent.com/uapis/uapi-sdk-python/main/banner.png)
+![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/)

{uapi_sdk_python-0.1.5 → uapi_sdk_python-0.1.13}/README.md

@@ -1,6 +1,6 @@
 # uapi-sdk-python
 
-![Banner](https://raw.githubusercontent.com/uapis/uapi-sdk-python/main/banner.png)
+![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/)

{uapi_sdk_python-0.1.5 → uapi_sdk_python-0.1.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "uapi-sdk-python"
-version = "0.1.5"
+version = "0.1.13"
 description = "Idiomatic UAPI SDK for Python"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -27,5 +27,3 @@ strict = true
 
 [tool.isort]
 profile = "black"
-
-

{uapi_sdk_python-0.1.5 → uapi_sdk_python-0.1.13}/uapi/client.py

@@ -15,7 +15,8 @@ class _Config:
 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 +25,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()
@@ -90,6 +94,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 +436,7 @@ class _ImageApi:
 这个接口会获取 Bing 搜索引擎当天全球同步的每日壁纸，并直接以图片形式返回。你可以用它来做应用的启动页、网站背景，或者任何需要每日更新精美图片的地方。
 
 ## 使用须知
-
-> [!NOTE]
-> **响应格式是图片**
-> 请注意，此接口成功时直接返回图片二进制数据（通常为 `image/jpeg`），而非 JSON 格式。请确保客户端能够正确处理。
-
-我们内置了备用方案：如果从必应官方获取图片失败，系统会尝试返回一张预存的高质量风景图，以保证服务的稳定性。
+此接口成功时直接返回图片二进制数据，通常是 `image/jpeg`，不是 JSON 格式。接入时请按图片响应来处理。
         """
         params = {}
         body = {}
@@ -443,7 +446,7 @@ class _ImageApi:
         return self._http.request("GET", path, params=params, json=body if body else None)
     
     def get_image_motou(self, **kwargs):
-        r"""摸头 GIF
+        r"""生成摸摸头GIF (QQ号)
         想在线rua一下好友的头像吗？这个趣味接口可以满足你。
 
 ## 功能概述
@@ -471,16 +474,7 @@ class _ImageApi:
         无论是网址、文本还是联系方式，通通可以变成一个二维码！这是一个非常灵活的二维码生成工具。
 
 ## 功能概述
-你提供一段文本内容，我们为你生成对应的二维码图片。你可以自定义尺寸，并选择不同的返回格式以适应不同场景。
-
-## 使用须知
-
-> [!IMPORTANT]
-> **关键参数 `format`**
-> 此参数决定了成功响应的内容类型和结构，请务必根据你的需求选择并正确处理响应：
-> - **`image`** (默认): 直接返回 `image/png` 格式的图片二进制数据，适合在 `<img>` 标签中直接使用。
-> - **`json`**: 返回一个包含 Base64 Data URI 的 JSON 对象，适合需要在前端直接嵌入CSS或HTML的场景。
-> - **`json_url`**: 返回一个包含图片临时URL的JSON对象，适合需要图片链接的场景。
+你提供一段文本内容，我们为你生成对应的二维码图片。你可以自定义尺寸、前景色、背景色，还支持透明背景，并选择不同的返回格式以适应不同场景。
         """
         params = {}
         body = {}
@@ -494,6 +488,15 @@ class _ImageApi:
         if "query" == "query" and "format" in kwargs:
             params["format"] = kwargs["format"]
         
+        if "query" == "query" and "transparent" in kwargs:
+            params["transparent"] = kwargs["transparent"]
+        
+        if "query" == "query" and "fgcolor" in kwargs:
+            params["fgcolor"] = kwargs["fgcolor"]
+        
+        if "query" == "query" and "bgcolor" in kwargs:
+            params["bgcolor"] = kwargs["bgcolor"]
+        
         path = "/api/v1/image/qrcode"
         
         return self._http.request("GET", path, params=params, json=body if body else None)
@@ -589,7 +592,7 @@ class _ImageApi:
         return self._http.request("POST", path, params=params, json=body if body else None)
     
     def post_image_motou(self, **kwargs):
-        r"""摸头 GIF (上传)
+        r"""生成摸摸头GIF
         除了使用QQ头像，你还可以通过上传自己的图片或提供图片URL来制作独一无二的摸摸头GIF。
 
 ## 功能概述
@@ -619,13 +622,47 @@ class _ImageApi:
         
         return self._http.request("POST", path, params=params, json=body if body else None)
     
+    def post_image_nsfw(self, **kwargs):
+        r"""图片敏感检测
+        这是一个图片内容审核接口，自动识别图片中的违规内容并返回处理建议。
+
+## 功能概述
+上传图片文件或提供图片URL，接口会自动分析图片内容，返回是否违规、风险等级和处理建议。适合对接到用户上传流程中，实现自动化内容审核。
+
+## 返回字段说明
+- **is_nsfw**: 是否判定为违规内容，`true` 表示违规，`false` 表示正常
+- **nsfw_score**: 违规内容置信度，0-1 之间，越高表示越可能违规
+- **normal_score**: 正常内容置信度，0-1 之间，与 nsfw_score 互补
+- **suggestion**: 处理建议
+  - `pass`: 内容正常，可以直接放行
+  - `review`: 存在风险，建议转人工复核
+  - `block`: 高风险内容，建议直接拦截
+- **risk_level**: 风险等级
+  - `low`: 低风险
+  - `medium`: 中风险
+  - `high`: 高风险
+- **label**: 内容标签，`nsfw` 或 `normal`
+- **confidence**: 模型对当前判断的整体置信度
+- **inference_time_ms**: 模型推理耗时，单位毫秒
+        """
+        params = {}
+        body = {}
+        
+        
+        if "file" in kwargs:
+            body["file"] = kwargs["file"]
+        
+        if "url" in kwargs:
+            body["url"] = kwargs["url"]
+        
+        path = "/api/v1/image/nsfw"
+        
+        return self._http.request("POST", path, params=params, json=body if body else None)
+    
     def post_image_speechless(self, **kwargs):
         r"""生成你们怎么不说话了表情包
         你们怎么不说话了？是不是都在偷偷玩Uapi，求求你们不要玩Uapi了
 
-## 效果展示
-![示例](https://uapis.cn/static/uploads/33580466897f1e5815296f235b582815.png)
-
 ## 使用须知
 - **响应格式**：接口成功时直接返回 `image/png` 格式的二进制数据。
 - **文字内容**：至少需要提供 `top_text`（上方文字）或 `bottom_text`（下方文字）之一。
@@ -715,6 +752,91 @@ class _MiscApi:
         
         return self._http.request("GET", path, params=params, json=body if body else None)
     
+    def get_misc_district(self, **kwargs):
+        r"""Adcode 国内外行政区域查询
+        一个接口，覆盖全球 243 个国家、中国省/市/区/街道四级行政区划，支持关键词搜索、行政编码查询、坐标反查三种查询模式（必须至少传入一种查询参数）。
+
+## 功能概述
+根据用户输入的搜索条件快速查找行政区域信息。例如：中国 > 山东省 > 济南市 > 历下区 > 舜华路街道。
+
+无需注册、无需密钥，直接调用即可获取结构化的行政区域数据。支持三种查询方式：
+- 传 `adcode`，按行政编码精确查询，同时返回下级区划列表
+- 传 `lat` + `lng`，坐标反查附近地点
+- 传 `keywords`，按关键词搜索，支持中英文
+
+## 中国与国际数据差异
+中国数据包含 `adcode`、`citycode` 等字段，支持省/市/区/街道四级逐级查询；国际城市数据不含这些字段，但额外提供 `population`（人口）和 `timezone`（时区）。
+
+> [!NOTE]
+> 部分城市（如东莞、文昌）没有区县层级，市级下方直接显示街道。街道级别的 `adcode` 返回的是所属区县的 `adcode`。
+        """
+        params = {}
+        body = {}
+        
+        if "query" == "query" and "keywords" in kwargs:
+            params["keywords"] = kwargs["keywords"]
+        
+        if "query" == "query" and "adcode" in kwargs:
+            params["adcode"] = kwargs["adcode"]
+        
+        if "query" == "query" and "lat" in kwargs:
+            params["lat"] = kwargs["lat"]
+        
+        if "query" == "query" and "lng" in kwargs:
+            params["lng"] = kwargs["lng"]
+        
+        if "query" == "query" and "level" in kwargs:
+            params["level"] = kwargs["level"]
+        
+        if "query" == "query" and "country" in kwargs:
+            params["country"] = kwargs["country"]
+        
+        if "query" == "query" and "limit" in kwargs:
+            params["limit"] = kwargs["limit"]
+        
+        path = "/api/v1/misc/district"
+        
+        return self._http.request("GET", path, params=params, json=body if body else None)
+    
+    def get_misc_holiday_calendar(self, **kwargs):
+        r"""查询节假日与万年历
+        查询指定日期、月份或年份的万年历与节假日信息。
+
+## 功能概述
+这个接口支持三种查询方式：按天（`date`）、按月（`month`）和按年（`year`）。调用时三者选一个传入即可。
+
+如果你只关心某一类事件，可以通过 `holiday_type` 进行筛选，例如只看法定休假/调休、公历节日、农历节日或节气。
+
+在 `date` 模式下，传 `include_nearby=true` 可以额外返回该日期前后最近的节日；返回数量由 `nearby_limit` 控制，默认 7，最大 30。
+        """
+        params = {}
+        body = {}
+        
+        if "query" == "query" and "date" in kwargs:
+            params["date"] = kwargs["date"]
+        
+        if "query" == "query" and "month" in kwargs:
+            params["month"] = kwargs["month"]
+        
+        if "query" == "query" and "year" in kwargs:
+            params["year"] = kwargs["year"]
+        
+        if "query" == "query" and "timezone" in kwargs:
+            params["timezone"] = kwargs["timezone"]
+        
+        if "query" == "query" and "holiday_type" in kwargs:
+            params["holiday_type"] = kwargs["holiday_type"]
+        
+        if "query" == "query" and "include_nearby" in kwargs:
+            params["include_nearby"] = kwargs["include_nearby"]
+        
+        if "query" == "query" and "nearby_limit" in kwargs:
+            params["nearby_limit"] = kwargs["nearby_limit"]
+        
+        path = "/api/v1/misc/holiday-calendar"
+        
+        return self._http.request("GET", path, params=params, json=body if body else None)
+    
     def get_misc_hotboard(self, **kwargs):
         r"""查询热榜
         想快速跟上网络热点？这个接口让你一网打尽各大主流平台的实时热榜/热搜！
@@ -722,17 +844,19 @@ class _MiscApi:
 ## 功能概述
 你只需要指定一个平台类型，就能获取到该平台当前的热榜数据列表。每个热榜条目都包含标题、热度值和原始链接。非常适合用于制作信息聚合类应用或看板。
 
-## 可选值
-`type` 参数接受多种不同的值，每种值对应一个不同的热榜来源。以下是目前支持的所有值：
+## 三种使用模式
+
+### 默认模式
+只传 `type` 参数，返回该平台当前的实时热榜。
+
+### 时光机模式
+传 `type` + `time` 参数，返回最接近指定时间的热榜快照。如果不可用或无数据，会返回空。
 
-| 分类       | 支持的 type 值 |
-|------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| 视频/社区  | bilibili（哔哩哔哩弹幕网）, acfun（A站弹幕视频网站）, weibo（新浪微博热搜）, zhihu（知乎热榜）, zhihu-daily（知乎日报热榜）, douyin（抖音热榜）, kuaishou（快手热榜）, douban-movie（豆瓣电影榜单）, douban-group（豆瓣小组话题）, tieba（百度贴吧热帖）, hupu（虎扑热帖）, miyoushe（米游社话题榜）, 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（星穹铁道热榜） |
-| 其他       | weread（微信读书热门书籍）, weatheralarm（天气预警信息）, earthquake（地震速报）, history（历史上的今天） |
+### 搜索模式
+传 `type` + `keyword` + `time_start` + `time_end` 参数，在指定时间范围内搜索包含关键词的热榜条目。可选传 `limit` 限制返回数量。
 
+### 数据源列表
+传 `sources=true`，返回所有支持历史数据的平台列表。
         """
         params = {}
         body = {}
@@ -740,10 +864,53 @@ class _MiscApi:
         if "query" == "query" and "type" in kwargs:
             params["type"] = kwargs["type"]
         
+        if "query" == "query" and "time" in kwargs:
+            params["time"] = kwargs["time"]
+        
+        if "query" == "query" and "keyword" in kwargs:
+            params["keyword"] = kwargs["keyword"]
+        
+        if "query" == "query" and "time_start" in kwargs:
+            params["time_start"] = kwargs["time_start"]
+        
+        if "query" == "query" and "time_end" in kwargs:
+            params["time_end"] = kwargs["time_end"]
+        
+        if "query" == "query" and "limit" in kwargs:
+            params["limit"] = kwargs["limit"]
+        
+        if "query" == "query" and "sources" in kwargs:
+            params["sources"] = kwargs["sources"]
+        
         path = "/api/v1/misc/hotboard"
         
         return self._http.request("GET", path, params=params, json=body if body else None)
     
+    def get_misc_lunartime(self, **kwargs):
+        r"""查询农历时间
+        需要在指定时区下查看某个时间点的农历信息？这个接口可以直接返回完整结果。
+
+## 功能概述
+支持传入 Unix 时间戳（秒或毫秒）和 IANA 时区名，返回公历时间、星期、农历年月日、干支、生肖、节气与节日信息。不传 `ts` 时默认使用当前时间，不传 `timezone` 时默认 `Asia/Shanghai`。
+
+## 时区说明
+- 支持标准 IANA 时区，例如 `Asia/Shanghai`、`Asia/Tokyo`
+- 也支持别名：`Shanghai`、`Beijing`
+- 时区非法时返回 400 并提示 `invalid timezone: xxx`
+        """
+        params = {}
+        body = {}
+        
+        if "query" == "query" and "ts" in kwargs:
+            params["ts"] = kwargs["ts"]
+        
+        if "query" == "query" and "timezone" in kwargs:
+            params["timezone"] = kwargs["timezone"]
+        
+        path = "/api/v1/misc/lunartime"
+        
+        return self._http.request("GET", path, params=params, json=body if body else None)
+    
     def get_misc_phoneinfo(self, **kwargs):
         r"""查询手机归属地
         想知道一个手机号码来自哪里？是移动、联通还是电信？这个接口可以告诉你答案。
@@ -823,7 +990,7 @@ graph TD
 > [!WARNING]
 > **接口已过时**：这个接口已被新的 `/convert/unixtime` 取代。新接口功能更强大，支持双向转换。我们建议你迁移到新接口。
 
-[👉 前往新版接口文档](/docs/api-reference/get-convert-unixtime)
+[➡️ 前往新版接口文档](/docs/api-reference/get-convert-unixtime)
         """
         params = {}
         body = {}
@@ -839,9 +1006,6 @@ graph TD
         r"""获取支持的快递公司列表
         不确定系统支持哪些快递公司？这个接口返回完整的支持列表。
 
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
-
 ## 功能概述
 获取系统当前支持的所有快递公司列表，包括每家公司的标准编码（code）和中文名称（name）。
 
@@ -861,9 +1025,6 @@ graph TD
         r"""识别快递公司
         不确定手里的快递单号属于哪家快递公司？这个接口专门做识别，不查物流。
 
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
-
 ## 功能概述
 输入快递单号，系统会根据单号规则快速识别出最可能的快递公司。如果存在多个可能的匹配结果，还会在 `alternatives` 字段中返回备选项，供你参考选择。
 
@@ -886,15 +1047,15 @@ graph TD
         r"""查询快递物流信息
         买了东西想知道快递到哪儿了？这个接口帮你实时追踪物流状态。
 
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
-
 ## 功能概述
-提供一个快递单号，系统会自动识别快递公司并返回完整的物流轨迹信息。支持中通、圆通、韵达、申通、极兔、顺丰、京东、EMS、德邦等60+国内外主流快递公司。
+提供一个快递单号，系统会自动识别快递公司并返回完整的物流轨迹信息。这个接口目前可以查询中通、圆通、韵达、申通、极兔、京东、EMS、德邦等主流快递公司的物流信息。
 
 ## 使用须知
+目前暂不支持顺丰快递单号的物流查询。
+
 - **自动识别**：不知道是哪家快递？系统会根据单号规则自动识别快递公司（推荐使用）
 - **手动指定**：如果已知快递公司，可以传递 `carrier_code` 参数，查询速度会更快
+- **手机尾号验证**：部分快递公司需要验证收件人手机尾号才能查询详细物流，如果返回 `暂无物流信息`，建议尝试传入 `phone` 参数
 - **查询时效**：物流信息实时查询，响应时间通常在1-2秒内
         """
         params = {}
@@ -906,23 +1067,38 @@ graph TD
         if "query" == "query" and "carrier_code" in kwargs:
             params["carrier_code"] = kwargs["carrier_code"]
         
+        if "query" == "query" and "phone" in kwargs:
+            params["phone"] = kwargs["phone"]
+        
         path = "/api/v1/misc/tracking/query"
         
         return self._http.request("GET", path, params=params, json=body if body else None)
     
     def get_misc_weather(self, **kwargs):
         r"""查询天气
-        出门前，查一下天气总是个好习惯。这个接口为你提供精准、实时的天气数据。
+        出门前，查一下天气总是个好习惯。这个接口为你提供精准、实时的天气数据，支持国内和国际城市。
 
 ## 功能概述
-你可以通过城市名称或6位数字的Adcode来查询指定地区的实时天气状况，包括天气现象、温度、湿度、风向和风力等。
+这个接口支持三种查询方式：
+- 可以传 `adcode`，按行政区编码查询（优先级最高）
+- 可以传 `city`，按城市名称查询，支持中文（`北京`）和英文（`Tokyo`）
+- 两个都不传时，按客户端 IP 自动定位查询
 
-## 使用须知
-- **参数优先级**：当你同时提供了 `city` (城市名) 和 `adcode` (城市编码) 两个参数时，系统会 **优先使用 `adcode`** 进行查询，因为它更精确。
-- **查询范围**：为了保证查询的准确性，我们的服务仅支持标准的“省”、“市”、“区/县”级别的行政区划名称查询，不保证能查询到乡镇或具体地点。
+支持 `lang` 参数，可选 `zh`（默认）和 `en`，城市名翻译覆盖 7000+ 城市。
 
-## 错误处理指南
-- **410 Gone**: 这个特殊的错误码意味着你查询的地区无效或不受我们支持。比如你输入了“火星”，或者某个我们无法识别的村庄名称。这个状态码告诉你，这个“资源”是永久性地不可用了。
+## 可选功能模块
+- `extended=true`：扩展气象字段（体感温度、能见度、气压、紫外线、空气质量及污染物分项数据）
+- `forecast=true`：多天预报（最多7天，会额外返回每天的最高温度、最低温度，以及日出日落、风速等详细数据）
+- `hourly=true`：逐小时预报（24小时）
+- `minutely=true`：分钟级降水预报（仅国内城市，精确到2分钟）
+- `indices=true`：18项生活指数（穿衣、紫外线、洗车、运动、花粉等）
+
+## 天气字段说明
+`weather` 是天气现象文本，不是固定枚举。
+
+常见值包括：晴、多云、阴、小雨、中雨、大雨、雷阵雨、小雪、中雪、大雪、雨夹雪、雾、霾、沙尘。
+
+如果你的业务需要稳定的天气分类，建议使用 `weather_code` 进行映射。完整的天气图标代码请参考[天气图标代码表](#enum-list)。
         """
         params = {}
         body = {}
@@ -936,11 +1112,20 @@ graph TD
         if "query" == "query" and "extended" in kwargs:
             params["extended"] = kwargs["extended"]
         
+        if "query" == "query" and "forecast" in kwargs:
+            params["forecast"] = kwargs["forecast"]
+        
+        if "query" == "query" and "hourly" in kwargs:
+            params["hourly"] = kwargs["hourly"]
+        
+        if "query" == "query" and "minutely" in kwargs:
+            params["minutely"] = kwargs["minutely"]
+        
         if "query" == "query" and "indices" in kwargs:
             params["indices"] = kwargs["indices"]
         
-        if "query" == "query" and "forecast" in kwargs:
-            params["forecast"] = kwargs["forecast"]
+        if "query" == "query" and "lang" in kwargs:
+            params["lang"] = kwargs["lang"]
         
         path = "/api/v1/misc/weather"
         
@@ -1042,10 +1227,10 @@ class _NetworkApi:
     
     def get_network_ipinfo(self, **kwargs):
         r"""查询 IP
-        想知道一个IP地址或域名来自地球的哪个角落？这个接口可以帮你定位它。你可以选择使用默认的GeoIP数据库，也可以指定 `source=commercial` 参数来查询更详细的商业级IP归属信息。
+        想知道一个IP地址或域名来自地球的哪个角落？这个接口可以帮你定位它。你可以使用默认数据源，也可以指定 `source=commercial` 参数来查询更详细的商业级IP归属信息。
 
 ## 功能概述
-提供一个公网IPv4、IPv6地址或域名，我们会利用GeoIP数据库查询并返回它的地理位置（国家、省份、城市）、经纬度、以及所属的运营商（ISP）和自治系统（ASN）信息。这在网络安全分析、访问来源统计等领域非常有用。
+提供一个公网IPv4、IPv6地址或域名，我们会查询并返回它的地理位置（国家、省份、城市）、经纬度、以及所属的运营商（ISP）和自治系统（ASN）信息。这在网络安全分析、访问来源统计等领域非常有用。
 
 当使用 `source=commercial` 参数时，接口将调用高性能商业API，提供更精确的市、区、运营商、时区、海拔等信息。请注意，商业查询的响应时间可能会稍长。
         """
@@ -1064,7 +1249,7 @@ class _NetworkApi:
     
     def get_network_myip(self, **kwargs):
         r"""查询我的 IP
-        想知道你自己的出口公网IP是多少吗？这个接口就是你的“网络身份证”。你可以选择使用默认的GeoIP数据库，也可以指定 `source=commercial` 参数来查询更详细的商业级IP归属信息。
+        想知道你自己的出口公网IP是多少吗？这个接口就是你的“网络身份证”。你可以使用默认数据源，也可以指定 `source=commercial` 参数来查询更详细的商业级IP归属信息。
 
 ## 功能概述
 调用此接口，它会返回你（即发起请求的客户端）的公网IP地址，并附带与 `/network/ipinfo` 接口相同的地理位置和网络归属信息。非常适合用于在网页上向用户展示他们自己的IP和地理位置。
@@ -1141,9 +1326,6 @@ class _NetworkApi:
 
 ## 功能概述
 提供一个URL，我们会向它发起一个请求，并返回其HTTP响应状态码。这是一种简单而有效的服务可用性监控方法。
-
-> [!TIP]
-> **性能优化**：为了提高效率并减少对目标服务器的负载，我们实际发送的是 `HEAD` 请求，而不是 `GET` 请求。`HEAD` 请求只会获取响应头，而不会下载整个页面内容，因此速度更快。
         """
         params = {}
         body = {}
@@ -1266,30 +1448,28 @@ class _RandomApi:
 > 如果你需要更精确地控制图片类型，请使用 `/image/random/{category}/{type}` 接口。
 
 ### 支持的主类别与子类别
-- **UapiPro服务器图片**
+- **acg**（二次元动漫）
+    - pc
+    - mb
+- **外部图床精选/混合动漫**
+  - **landscape**: 风景图。
+  - **anime**: 混合了UapiPro服务器的acg和外部图床的general_anime分类下的图片。
+  - **pc_wallpaper**: 电脑壁纸。
+  - **mobile_wallpaper**: 手机壁纸。
+  - **general_anime**: 动漫图。
+  - **ai_drawing**: AI绘画。
+- **其他分类**
+  - **bq**（表情包/趣图）
+    - eciyuan
+    - ikun
+    - xiongmao
+    - waiguoren
+    - maomao
   - **furry**（福瑞）
     - z4k
     - szs8k
     - s4k
     - 4k
-  - **bq**（表情包/趣图）
-    - youshou
-    - xiongmao
-    - waiguoren
-    - maomao
-    - ikun
-    - eciyuan
-  - **acg**（二次元动漫）
-    - pc
-    - mb
-- **外部图床精选图片**
-  - **ai_drawing**: AI绘画。
-  - **general_anime**: 动漫图。
-  - **landscape**: 风景图。
-  - **mobile_wallpaper**: 手机壁纸。
-  - **pc_wallpaper**: 电脑壁纸。
-- **混合动漫**
-  - **anime**: 混合了UapiPro服务器的acg和外部图床的general_anime分类下的图片。
 
 > [!NOTE]
 > 默认全局随机（未指定category参数）时，不会包含ikun和AI绘画（ai_drawing）类别的图片。
@@ -1479,7 +1659,11 @@ class _SocialApi:
 通过视频的 `oid`（通常就是视频的`aid`），你可以分页获取该视频的评论区内容。你可以指定排序方式和分页参数，来精确地获取你需要的数据。
 
 ## 参数说明
-- **`sort` (排序方式)**: `0`=按时间排序, `1`=按点赞数排序, `2`=按回复数排序。默认为按时间排序。
+- **`sort` (排序方式)**
+  - `0` 或 `time`：按时间排序
+  - `1` 或 `like`：按点赞排序
+  - `2` 或 `reply`：按回复数排序
+  - `3` 或 `hot`（也支持 `hottest`、`最热`）：按最热排序
 
 ## 响应体字段说明
 - **`hots` (热门评论)**: 仅在请求第一页时，可能会返回热门评论列表。其结构与 `replies` 中的对象一致。
@@ -1551,10 +1735,7 @@ class _SocialApi:
     
     def get_social_qq_groupinfo(self, **kwargs):
         r"""查询 QQ 群信息
-        想在你的应用里展示QQ群信息？这个接口让你轻松获取群名称、群头像、群简介、成员数量等详细公开信息。它能帮你快速构建社群导航站、群聊推荐系统，或是为你的数据分析工具提供可靠的数据源。
-
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
+        想在你的应用里展示QQ群信息？这个接口让你轻松获取群名称、群头像、群简介、成员数量等详细公开信息。
 
 ## 功能概述
 你只需要提供一个QQ群号（5-12位纯数字），接口就会返回该群的完整公开信息。我们会先验证群号的有效性，确保返回的数据准确可靠。接口响应速度快，数据结构清晰，非常适合集成到各类应用场景中。
@@ -1594,9 +1775,6 @@ class _SocialApi:
         r"""查询 QQ 信息
         这是一个功能丰富的QQ用户信息查询接口，能够获取QQ用户的详细公开信息。
 
-> [!VIP]
-> 我们在近日优化了此接口，速度应该会更加快了。 
-
 ## 功能概述
 通过QQ号查询用户的详细信息，包括基础资料、等级信息、VIP状态等。返回的信息丰富全面，适合用于用户画像分析、社交应用集成等场景。
 
@@ -2067,7 +2245,7 @@ class _TranslateApi:
     
     def get_ai_translate_languages(self, **kwargs):
         r"""AI翻译配置
-        获取AI智能翻译服务支持的完整语言列表、翻译风格选项、上下文场景选项以及性能指标信息。这个接口对于需要在前端动态展示翻译配置选项的应用非常有用，它会返回当前AI翻译服务所支持的所有语言代码、原生名称、翻译风格说明、上下文场景描述，以及服务的性能特征和限制信息。通过此接口，开发者可以构建用户友好的翻译界面，让用户选择合适的翻译参数。
+        获取AI智能翻译服务支持的完整语言列表、翻译风格选项、上下文场景选项以及性能指标信息。
         """
         params = {}
         body = {}
@@ -2078,21 +2256,18 @@ class _TranslateApi:
     
     def post_ai_translate(self, **kwargs):
         r"""AI智能翻译
-        这是一个商业级的AI智能翻译服务，采用最新的神经网络翻译技术和大语言模型，提供远超传统机器翻译的质量。它不仅能够智能处理单个文本翻译，还支持高效的批量文本翻译，并且具备上下文感知、风格适配、格式保留等高级功能。
-
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者深度集成和测试。未来，它将转为付费API，为用户提供更稳定、更智能的翻译服务。
+        这是一个商业级的AI智能翻译服务，采用最新的神经网络翻译技术和大语言模型，提供远超传统机器翻译的质量。
 
 ## 功能概述
 
-- **智能双模式**: 支持单个文本翻译和批量文本翻译的统一接口设计，自动识别请求类型并提供相应的翻译服务。系统会根据输入自动判断是处理单条文本还是批量文本，无需使用不同的接口。
+- **单文本翻译**: 专注处理单条文本翻译，适合需要高质量译文的业务场景。
 - **多风格适配**: 提供随意口语化、专业商务、学术正式、文学艺术四种翻译风格，能够根据不同场景需求调整翻译的语言风格和表达方式。
 - **上下文感知**: 支持通用、商务、技术、医疗、法律、市场营销、娱乐、教育、新闻等九种专业领域的上下文翻译，确保术语准确性和表达地道性。
-- **高质量保证**: 内置质量评估系统，对每次翻译结果进行流畅度、准确度、完整性评分，并提供置信度分数和替代翻译建议。
-- **智能解释**: 提供关键词组翻译注释、文化背景说明和语法结构分析，帮助用户理解翻译逻辑和文化差异。
-- **高效批量**: 批量翻译支持最多50条文本，总计10万字符，配备智能并发控制（1-10并发）和失败重试机制。
-- **快速模式**: 提供快速模式选项，在保证95%+准确率的前提下，响应时间缩短至800ms内，适合实时翻译和聊天应用。
 - **格式保留**: 智能识别并保持原文的格式结构，包括换行、缩进、特殊符号等，确保翻译后的文本保持良好的可读性。
+
+## 支持的语言
+
+我们支持超过100种语言的互译，详见下方参数列表。
         """
         params = {}
         body = {}
@@ -2104,12 +2279,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"]
         
@@ -2122,9 +2291,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)
@@ -2200,25 +2366,23 @@ class _WebparseApi:
     
     def get_web_tomarkdown_async_status(self, **kwargs):
         r"""转换任务状态
-        提交了URL转Markdown任务后，想知道处理进度和结果？这个接口可以帮你实时追踪。
+        提交了网页转 Markdown 任务后，想知道处理进度和结果？用这个接口来查询。
 
 ## 功能概述
+通过任务 ID 查询转换任务的当前状态、处理进度和最终结果。任务结果缓存 30 分钟，期间可重复查询。
 
-通过之前提交任务时获得的任务ID，你可以查询该任务的当前状态、处理进度以及最终结果。任务结果会在缓存中保存30分钟，期间可以重复查询，非常方便。
-
-任务有五种状态：等待处理（pending）时进度为0%；处理中（processing）时进度在10-90%之间；已完成（completed）时进度为100%并返回Markdown内容；失败（failed）时会返回错误信息；超时（timeout）表示任务处理时间超过60秒已被取消。建议采用指数退避策略进行轮询，初始延迟1秒，每次延迟增加20%，最大延迟5秒。当状态为已完成、失败或超时时停止轮询。
-
-系统会自动管理任务生命周期，单个任务最长处理时间为60秒，任务结果保存30分钟后自动清理，每5分钟清理一次过期任务。
+## 任务状态
 
-## 任务状态说明
+| 状态 | 说明 |
+|------|------|
+| `pending` | 等待处理 |
+| `processing` | 处理中 |
+| `completed` | 已完成，可获取结果 |
+| `failed` | 失败 |
+| `timeout` | 超时（超过 60 秒） |
 
-| 状态 | 说明 | 进度 | 轮询建议 |
-|------|------|------|----------|
-| `pending` | 等待处理 | 0% | 立即开始轮询 |
-| `processing` | 处理中 | 10-90% | 每2-5秒轮询一次 |
-| `completed` | 已完成 | 100% | 停止轮询，获取结果 |
-| `failed` | 失败 | 100% | 停止轮询，查看错误信息 |
-| `timeout` | 超时 | 100% | 停止轮询，任务已取消 |
+> [!NOTE]
+> 建议每 2-5 秒轮询一次，当状态为 `completed`、`failed` 或 `timeout` 时停止轮询。
         """
         params = {}
         body = {}
@@ -2235,10 +2399,10 @@ class _WebparseApi:
     
     def get_webparse_extractimages(self, **kwargs):
         r"""提取网页图片
-        想一次性“打包”一个网页上的所有图片吗？这个接口可以帮你实现。
+        想批量获取一个网页上的所有图片链接？这个接口帮你搞定。
 
 ## 功能概述
-你提供一个网页的URL，我们会访问该页面，解析其HTML内容，并提取出所有 `<img>` 标签中的图片链接，然后将这些链接列表返回给你。非常适合用于制作图片采集器或素材下载工具。
+提供一个网页 URL，返回该页面中所有图片的链接列表。适合用于图片采集、素材下载等场景。
         """
         params = {}
         body = {}
@@ -2251,11 +2415,11 @@ class _WebparseApi:
         return self._http.request("GET", path, params=params, json=body if body else None)
     
     def get_webparse_metadata(self, **kwargs):
-        r"""网页元数据
-        当你在应用中需要展示一个链接的预览时（就像微信或Telegram里那样），这个接口能帮你轻松获取所需信息。
+        r"""提取网页元数据
+        想在应用里做链接预览卡片？这个接口帮你一键获取网页的标题、描述、图标等信息。
 
 ## 功能概述
-你提供一个网页的URL，我们会抓取并解析它的 `<head>` 部分，提取出关键的元数据（Metadata），如页面标题（Title）、描述（Description）、关键词（Keywords）以及网站图标（Favicon）等。
+提供一个网页 URL，返回该页面的元数据，包括标题、描述、关键词、Favicon、Open Graph 信息等。非常适合用于生成链接预览卡片或做 SEO 分析。
         """
         params = {}
         body = {}
@@ -2269,20 +2433,13 @@ class _WebparseApi:
     
     def post_web_tomarkdown_async(self, **kwargs):
         r"""网页转 Markdown
-        想要将复杂的网页转换为结构清晰的Markdown？这个接口采用异步处理模式，特别适合处理大型网页、复杂网站或需要长时间处理的转换任务。
+        想把一个网页的内容转成干净的 Markdown 文本？这个异步接口可以帮你搞定，特别适合处理大型或复杂的网页。
 
 ## 功能概述
 
-> [!VIP]
->本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
-
-UAPI Pro平台推出的异步网页转Markdown API能够将任意网页URL转换为结构清晰、格式优美的Markdown文本。提交任务后立即返回任务ID，不会阻塞客户端等待。您可以通过任务ID实时查询转换进度和处理状态，支持长达60秒的处理时间，轻松应对大型网站、需要JS渲染的单页应用等复杂页面。任务结果会缓存30分钟，期间可重复查询，过期任务自动清理无需手动管理。
-
-此API采用先进算法，自动识别并抓取网页主体内容，精准剔除广告、导航栏、页眉页脚等无关元素。完美保留原文的格式，包括标题、列表、代码块、表格、引用、图片等，并输出为兼容性强的GitHub Flavored Markdown (GFM) 格式。同时会自动解析并提取文章标题、作者、发布日期、站点名称等关键元数据，并将其格式化为标准的YAML Front Matter，方便后续处理和CMS集成。
+提交一个网页 URL，我们会自动抓取主体内容，剔除广告、导航栏等干扰元素，并转换为 Markdown 格式。同时会提取标题、作者、发布日期等元数据，生成 YAML Front Matter。
 
-## 使用流程
-
-调用本接口提交URL转换任务后，会立即获得一个唯一的任务ID。随后使用任务ID调用查询接口，获取任务状态和进度。任务完成后，从查询接口的响应中获取Markdown内容。
+任务提交后会立即返回任务 ID，你可以用它来查询处理进度和结果。单个任务最长处理 60 秒，结果缓存 30 分钟。
         """
         params = {}
         body = {}
@@ -2316,28 +2473,17 @@ class _MinGanCiShiBieApi:
     
     def post_sensitive_word_analyze(self, **kwargs):
         r"""分析敏感词
-        分析单个或多个关键词的敏感程度，返回详细的风险评分和分析结果。
-
-> [!VIP]
-> 本API基于先进的分析模型，提供三级缓存策略和并发处理能力。
+        分析单个或多个关键词的敏感程度，返回标准化风险标签与置信度结果。
 
 ## 功能概述
 
 - **模型驱动**: 使用先进的分析模型进行语义分析。
 - **高性能**: 采用三级缓存策略（持久化存储 → 统一缓存 → 模型分析），确保高频请求的响应速度。
 - **并发支持**: 支持批量并发处理，单次最多可分析100个关键词。
-- **详细评分**: 提供色情、辱骂、暴力三个维度的详细风险评分。
-- **变体识别**: 能够自动识别关键词的常见变体形式，如拼音、缩写等。
-
-## 风险评分说明
-
-返回的 `s` 字段包含三个维度的风险评分，范围均为0.0至1.0：
-
-- **s[0] - 色情风险**: 评估内容涉及色情信息的程度。
-- **s[1] - 辱骂/仇恨言论风险**: 评估内容是否包含侮辱性或仇恨性言论。
-- **s[2] - 暴力/威胁风险**: 评估内容是否涉及暴力或威胁信息。
-
-风险等级可参考：0.0-0.3为低风险，0.3-0.7为中等风险，0.7-1.0为高风险。
+- **输入限制**: 单条关键词最多 1,000 字符，总字符数最多 20,000。
+- **标准标签**: 返回 `label` 字段，明确区分 `sensitive` 与 `normal`。
+- **分类清晰**: 返回 `category` 字段，用于标识具体风险类别。
+- **置信度输出**: 返回 `confidence` 字段，范围为0.0到1.0。
 
 ## 响应字段说明
 
@@ -2345,11 +2491,9 @@ class _MinGanCiShiBieApi:
 |------|------|------|
 | `results` | array | 分析结果对象的数组。 |
 | `results[].k` | string | 您在请求中提供的原始关键词。 |
-| `results[].r` | string | 模型对该关键词的分析过程和判断理由的简要说明。 |
-| `results[].s` | array[float] | 一个包含三个浮点数的数组，分别代表[色情, 辱骂, 暴力]三个维度的风险评分。分值范围从0.0到1.0，越高代表风险越大。 |
-| `results[].v` | array[string] | 模型识别出的该关键词的常见变体形式，例如拼音、谐音、缩写等。 |
-| `results[].t` | array[string] | 根据分析结果为关键词附加的分类标签，便于进行程序化处理和过滤。 |
-| `results[].d` | string | 对整体分析结果的一句简短总结，适合直接展示给用户或记录在日志中。 |
+| `results[].label` | string | 核心判断字段：`sensitive`(敏感)、`normal`(正常)。 |
+| `results[].category` | string | 风险分类：`safe`(安全)、`threat`(威胁)、`porn`(色情)、`fraud`(欺诈)、`insult`(辱骂)。 |
+| `results[].confidence` | number | 当前分类的置信度，范围0.0到1.0。 |
 | `total` | integer | 本次请求成功分析的关键词总数。 |
       
         """
@@ -2433,9 +2577,6 @@ UAPI Pro Search 是一个智能搜索引擎，采用机器学习算法对搜索
 - **时间范围过滤**: 支持按天/周/月/年过滤结果
 - **站内搜索**: 支持 `site:` 操作符，在指定网站内搜索
 - **文件类型过滤**: 支持 `filetype:` 操作符，快速找到 PDF、Word 等特定格式文件
-
-> [!VIP]
-> 本API目前处于**限时免费**阶段，我们鼓励开发者集成和测试。未来，它将转为付费API，为用户提供更稳定和强大的服务。
       
         """
         params = {}

uapi_sdk_python-0.1.13/uapi/errors.py

@@ -0,0 +1,335 @@
+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_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
+    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")),
+        )
+
+    return ResponseMeta(
+        request_id=raw_headers.get("x-request-id"),
+        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,
+        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.5 → uapi_sdk_python-0.1.13}/uapi_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uapi-sdk-python
-Version: 0.1.5
+Version: 0.1.13
 Summary: Idiomatic UAPI SDK for Python
 Author-email: UAPI <dev@uapis.cn>
 Requires-Python: >=3.9
@@ -14,7 +14,7 @@ Requires-Dist: isort; extra == "dev"
 
 # uapi-sdk-python
 
-![Banner](https://raw.githubusercontent.com/uapis/uapi-sdk-python/main/banner.png)
+![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/)

uapi_sdk_python-0.1.5/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 )