qqmusic-api-python 0.7.1__tar.gz → 0.7.2__tar.gz

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/AGENTS.md

@@ -23,9 +23,12 @@
 
 ## Testing rules
 
-* **专注 Modules 层**：测试重心放在 `modules` 层，将其视为黑盒。采用基于数据驱动（`@pytest.mark.parametrize`）的函数式测试方法，将输入参数与期望结果的特征断言解耦。
-* **真实网络请求（No Mock）**：禁止 Mock 底层网络请求或核心组装逻辑。必须直接与真实的 QQ 音乐 API 交互，以验证接口连通性、参数拼装和数据模型（Models）解析的正确性。
-* **优雅处理限流（Rate Limit）**：由于采用真实网络请求，当触发上游 API 的风控或频率限制异常时，必须使用自定义装饰器捕获该异常并调用 `pytest.skip()` 安全跳过，严禁因此导致测试失败。
+* **双重视角测试**：测试按层级分为 Modules 与 Core 两类视角，均以黑盒方式覆盖可观察行为：
+    * **Modules 层（集成测试）**：测试重心，视为黑盒，采用基于数据驱动（`@pytest.mark.parametrize`）的函数式测试方法，将输入参数与期望结果的特征断言解耦。
+    * **Core 层（单元测试）**：必要的核心逻辑测试，覆盖请求分组、批量合并、参数拼装、异常转换、分页推进等纯逻辑，不发起任何网络请求，保证测试确定性与快速性。
+* **Modules 层真实网络请求（No Mock）**：禁止 Mock 底层网络请求或核心组装逻辑。必须直接与真实的 QQ 音乐 API 交互，以验证接口连通性、参数拼装和数据模型（Models）解析的正确性。
+* **Core 层桩数据（Stub Only）**：仅允许使用自定义桩（如 `DummyResponse`、`MockClient`）驱动被测逻辑，禁止 Mock 被测对象自身的内部行为；不得依赖真实网络。
+* **优雅处理限流（Rate Limit）**：由于 Modules 层采用真实网络请求，当触发上游 API 的风控或频率限制异常时，必须使用自定义装饰器捕获该异常并调用 `pytest.skip()` 安全跳过，严禁因此导致测试失败。
 * **平铺函数写法**：摒弃测试类（`class TestXXX`），强制采用平铺的独立纯函数（Flat Functions）编写测试用例，通过 fixtures 注入依赖，保证测试的独立性。
 * 测试用例必须包含单行中文 docstring，且 docstring 内部必须使用英文标点符号。
 * 优先在现有的测试文件中添加用例，仅在测试全新模块时才允许创建新的测试文件。

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.7.1
+Version: 0.7.2
 Summary: QQ音乐API封装库
 Project-URL: documentation, https://l-1124.github.io/QQMusicApi/
 Project-URL: homepage, https://l-1124.github.io/QQMusicApi/

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/docs/coding.md

@@ -11,12 +11,13 @@
 
 ```text
 模块方法
-  -> self._build_request(...)
-  -> Request
+  -> self._build_cgi(...) / self._build_http(...)
+  -> BaseRequest 描述符
   -> await request
   -> Client.execute(request)
-  -> Client.request_api(...)
-  -> Client._build_result(...)
+  -> ApiContext 注入环境与凭证
+  -> Session.post(...) / Session.request(...)
+  -> Request._parse_response(...)
   -> 返回原始 dict 或 Pydantic 模型
 ```
 
@@ -24,18 +25,18 @@
 
 ```text
 多个模块方法
-  -> self._build_request(...)
-  -> Request 列表
+  -> self._build_cgi(...)
+  -> BaseRequest 描述符列表
     -> Client.gather(requests)
-    -> 按协议、平台、公共参数和凭证分组
+    -> 按协议、平台、公共参数和凭证配置键自动分组
     -> 每组按 batch_size 拆分为批量请求
-    -> 依次调用 Client.request_api(..., lazy=True) 生成响应任务
-    -> 使用客户端内部的 multiplexed AsyncSession 并发执行这些任务（self._session.gather）
-    -> 按 req_n 解析每个响应项
-    -> 按输入顺序返回结果
+    -> 依次发起合并的多参 CGI 请求（req_0, req_1...）
+    -> 使用客户端内部的 Session 并发执行这些任务（self._session.gather）
+    -> 统一解包解析每个响应项
+    -> 按输入顺序返回结果列表
 ```
 
-`gather` 的分组边界由 `Request._group_key` 决定。只有协议类型、显式平台、公共参数和凭证相同的请求才会合并到同一个批量请求中。
+`gather` 的分组边界由 `BaseRequest._group_key` 决定。只有协议类型、显式平台、公共参数和凭证相同的请求才会安全地合并到同一个批量请求中。
 
 ## 编写新的 API
 
@@ -55,7 +56,7 @@ class FooApi(ApiModule):
 
     def get_something(self, id: int):
         """获取某项数据."""
-        return self._build_request(
+        return self._build_cgi(
             module="music.foo.Svc",
             method="GetSomething",
             param={"id": id},
@@ -76,83 +77,78 @@ class Client:
 
 ### 添加新的请求方法
 
-API 方法返回 `Request` 对象，不直接发起请求。使用 `self._build_request(...)` 工厂方法构建：
+API 方法返回 `BaseRequest` 描述符对象，并不立即发起请求。对于标准 CGI 风格的 RPC 请求，使用 `self._build_cgi(...)` 工厂方法构建：
 
 ```python
 def get_detail(self, song_id: int):
     """获取歌曲详情."""
-    return self._build_request(
+    return self._build_cgi(
         module="music.songDetail",  # 接口所属模块
         method="GetDetail",  # 方法名
         param={"songid": song_id},  # 业务参数
     )
 ```
 
-对于非标准 CGI 接口（如直接 GET 请求），使用 `self._request(...)`：
+对于非标准 CGI 接口（如直接 GET 请求、获取网页或二维码），使用 `self._build_http(...)`：
 
 ```python
 async def quick_search(self, keyword: str) -> dict[str, Any]:
     """快速搜索 (直接返回解析后的 JSON 数据)."""
-    resp = await self._request(
+    resp = await self._build_http(
         "GET",
         "https://c.y.qq.com/splcloud/fcgi-bin/smartbox_new.fcg",
         params={"key": keyword},
     )
-    resp.raise_for_status()
-    return resp.json()["data"]
+    return resp["data"]
 ```
 
-### `_build_request` 参数说明
-
-| 参数               | 类型                          | 说明                                                                                                        |
-|--------------------|-------------------------------|-------------------------------------------------------------------------------------------------------------|
-| `module`           | `str`                         | 接口所属模块名                                                                                              |
-| `method`           | `str`                         | 方法名                                                                                                      |
-| `param`            | `dict`                        | 业务参数                                                                                                    |
-| `response_model`   | `type[BaseModel]` 或 `None`   | 响应模型，为 None 时返回原始 dict                                                                           |
-| `comm`             | `dict` 或 `None`              | 附加的公共参数                                                                                              |
-| `override_comm`    | `bool`                        | 为 True 时 `comm` 完全替代自动生成的参数；为 False 时合并                                                   |
-| `credential`       | `Credential` 或 `None`        | 覆盖本次请求的凭证                                                                                          |
-| `platform`         | `Platform` 或 `None`          | 覆盖本次请求的平台                                                                                          |
-| `preserve_bool`    | `bool`                        | 是否保留布尔值原样（默认转为 0/1 整型）                                                                     |
-| `sign`             | `bool`                        | 是否对请求进行签名                                                                                          |
-| `pager_strategy`   | `PagerStrategy` 或 `None`     | 分页策略，提供后返回 `PaginatedRequest`；可链式调用 `.with_extractor()` 提升为 `ItemPaginatedRequest`       |
-| `refresh_strategy` | `RefresherStrategy` 或 `None` | 换一批策略，提供后返回 `RefreshableRequest`；可链式调用 `.with_extractor()` 提升为 `ItemRefreshableRequest` |
-
-### `client.request` 参数说明
-
-`client.request` 是底层 HTTP 请求方法，自动装配凭证 Cookies 和平台 User-Agent：
-
-| 参数         | 类型                   |                                                                              说明 |
-|--------------|------------------------|----------------------------------------------------------------------------------:|
-| `method`     | `str`                  |                                                   HTTP 方法，如 `"GET"`、`"POST"` |
-| `url`        | `str`                  |                                                                          请求地址 |
-| `credential` | `Credential` 或 `None` |                                            覆盖本次请求的凭证，默认使用客户端凭证 |
-| `platform`   | `Platform` 或 `None`   |                                            覆盖本次请求的平台，默认使用客户端平台 |
-| `lazy`       | `bool`                 |                                                  是否延迟发送请求（用于批量并发） |
-| `**kwargs`   |                        | 透传给底层 `niquests` 的参数（`params`、`json`、`data`、`headers`、`cookies` 等） |
+### `_build_cgi` 参数说明
+
+| 参数             | 类型                        | 说明                                                                                                        |
+|------------------|-----------------------------|-------------------------------------------------------------------------------------------------------------|
+| `module`         | `str`                       | 接口所属模块名                                                                                              |
+| `method`         | `str`                       | 方法名                                                                                                      |
+| `param`          | `dict`                      | 业务参数                                                                                                    |
+| `response_model` | `type[BaseModel]` 或 `None` | 响应模型，为 None 时返回原始 dict                                                                           |
+| `comm`           | `dict` 或 `None`            | 附加的公共参数                                                                                              |
+| `override_comm`  | `bool`                      | 为 True 时 `comm` 完全替代自动生成的参数；为 False 时合并                                                   |
+| `credential`     | `Credential` 或 `None`      | 覆盖本次请求的凭证                                                                                          |
+| `platform`       | `Platform` 或 `None`        | 覆盖本次请求的平台                                                                                          |
+| `preserve_bool`  | `bool`                      | 是否保留布尔值原样（默认转为 0/1 整型）                                                                     |
+| `sign`           | `bool`                      | 是否对请求进行签名                                                                                          |
+| `require_login`  | `bool`                      | 是否在执行时强制校验用户登录态                                                                              |
+| `pager_strategy` | `PagerStrategy` 或 `None`   | 分页策略，提供后返回 `PaginatedCgiRequest`；可链式调用 `.with_extractor()` 提升为 `ItemPaginatedCgiRequest` |
+
+### `_build_http` 参数说明
+
+`_build_http` 用于构建标准 HTTP 请求描述符，自动装配凭证 Cookies 和平台 User-Agent：
+
+| 参数            | 类型                   |                                                                              说明 |
+|-----------------|------------------------|----------------------------------------------------------------------------------:|
+| `method`        | `str`                  |                                                   HTTP 方法，如 `"GET"`、`"POST"` |
+| `url`           | `str`                  |                                                                          请求地址 |
+| `credential`    | `Credential` 或 `None` |                                            覆盖本次请求的凭证，默认使用客户端凭证 |
+| `disable_parse` | `bool`                 |                      为 True 时不解析 JSON，直接返回原始 `niquests.Response` 对象 |
+| `**kwargs`      |                        | 透传给底层 `niquests` 的参数（`params`、`json`、`data`、`headers`、`cookies` 等） |
 
 !!! note
 
-    `client.request` 返回的是原始 `niquests.Response` 对象，需要手动解析响应。而 `_build_request` 返回的 `Request` 对象支持 `await`，会自动完成响应验证和模型解析。
+    `_build_cgi` 返回 `CgiRequest`，`_build_http` 返回 `HttpRequest`，两者均继承自 `BaseRequest`。它们都支持直接被 `await` 以触发网络请求并自动完成响应验证和模型解析。
 
 常见用法：
 
 ```python
 # GET 请求
-resp = await client.request("GET", "https://example.com/api", params={"key": "value"})
+req = self._build_http("GET", "https://example.com/api", params={"key": "value"})
 
 # POST JSON
-resp = await client.request("POST", "https://example.com/api", json={"key": "value"})
-
-# POST form data
-resp = await client.request("POST", "https://example.com/api", data={"key": "value"})
-
-# 自定义 headers
-resp = await client.request("GET", "https://example.com/api", headers={"X-Custom": "value"})
+req = self._build_http("POST", "https://example.com/api", json={"key": "value"})
 
 # 覆盖凭证
-resp = await client.request("GET", "https://example.com/api", credential=my_credential)
+req = self._build_http("GET", "https://example.com/api", credential=my_credential)
+
+# 返回原始 Response 而非解析 JSON
+req = self._build_http("GET", "https://example.com/api", disable_parse=True)
 ```
 
 ## 响应模型
@@ -232,12 +228,12 @@ class Singer(Response):
 
 ### 需登录的接口
 
-需要登录的接口通过 `_build_request` 的 `require_login` 参数校验凭证：
+需要登录的接口通过 `_build_cgi` 的 `require_login` 参数校验凭证：
 
 ```python
 def get_vip_info(self, *, credential: Credential | None = None):
     """获取 VIP 信息."""
-    return self._build_request(
+    return self._build_cgi(
         module="VipLogin.VipLoginInter",
         method="vip_login_base",
         param={},
@@ -247,8 +243,8 @@ def get_vip_info(self, *, credential: Credential | None = None):
     )
 ```
 
-> 若接口需要凭证对象的字段来构建请求参数，
-> 仍可显式调用 `_require_login` 获取凭证对象。
+> 若接口需要凭证对象的属性（如 `musicid` 等）来构建请求内联参数，
+> 仍可通过 `credential = credential or self._client.credential` 获取并显式验证其有效性。
 
 ## 连续翻页与批次刷新
 
@@ -264,7 +260,7 @@ from ..core.pagination import OffsetStrategy
 
 def get_detail(self, songlist_id: int, num: int = 10, page: int = 1):
     """获取歌单详情."""
-    return self._build_request(
+    return self._build_cgi(
         module="music.srfDissInfo.DissInfo",
         method="CgiGetDiss",
         param={
@@ -294,7 +290,7 @@ from ..models.base import MV
 
 def get_related_mv(self, songid: int, last_mvid: str | None = None):
     """获取歌曲相关 MV."""
-    return self._build_request(
+    return self._build_cgi(
         module="MvService.MvInfoProServer",
         method="GetSongRelatedMv",
         param={"songid": str(songid), "songtype": 1, "lastmvid": last_mvid or 0},
@@ -324,7 +320,7 @@ def get_related_mv(self, songid: int, last_mvid: str | None = None):
 ```python
 def get_sheet(self, mid: str):
     """获取曲谱."""
-    return self._build_request(
+    return self._build_cgi(
         module="music.mir.SheetMusicSvr",
         method="GetMoreSheetMusic",
         param={"songMid": mid},
@@ -340,7 +336,7 @@ def get_sheet(self, mid: str):
 
 ```python
 # 合并到自动生成的 comm 中（默认行为）
-self._build_request(
+self._build_cgi(
     ...,
     comm={"extra_key": "value"},
 )
@@ -349,7 +345,7 @@ self._build_request(
 使用 `override_comm=True` 完全替代自动生成的参数：
 
 ```python
-self._build_request(
+self._build_cgi(
     ...,
     comm={
         "g_tk": 5381,
@@ -373,7 +369,7 @@ self._build_request(
 from ..core.exceptions import ApiDataError
 
 try:
-# ...
+    ...
 except KeyError as e:
     raise ApiDataError("无法解析歌曲信息") from e
 ```

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/docs/contributing.md

@@ -76,19 +76,11 @@ uv run mkdocs serve
 * Lint 使用 [Ruff](https://docs.astral.sh/ruff/)
 * 类型检查使用 `pyrefly`
 
-## 测试规范
-
-* **专注 Modules 层**：测试重心放在 `modules` 层，将其视为黑盒。采用基于数据驱动（`@pytest.mark.parametrize`）的函数式测试方法。
-* **真实网络请求（No Mock）**：禁止 Mock 底层网络请求或核心组装逻辑。必须直接与真实的 QQ 音乐 API 交互。
-* **优雅处理限流**：触发上游 API 风控或频率限制异常时，必须捕获异常并调用 `pytest.skip()` 安全跳过，严禁导致测试失败。
-* **平铺函数写法**：摒弃测试类（`class TestXXX`），强制采用独立纯函数（Flat Functions）。
-* **无需过度清理**：对于获取、查询类操作，验证连通性与模型解析即可。
-
 ## 代码注释
 
 * 注释内容包括：模块注释、类注释、函数注释、参数类型注释、返回值注释
 * 注释风格遵循 [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
-* 测试用例必须包含**单行中文 docstring**，且内部必须使用**英文标点符号**。
+* 测试用例必须包含 **单行中文 docstring**，且内部必须使用 **英文标点符号**。
 
 ## 文档规范
 

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/docs/release-notes.md

@@ -1,4 +1,46 @@
 
+## [[0.7.1](https://github.com/L-1124/QQMusicApi/compare/v0.7.0..v0.7.1)] - 2026-08-02
+
+### Bug 修复
+
+* **(Song)** 移除 SongApi 中不必要的参数说明 ([e4b02c7](https://github.com/L-1124/QQMusicApi/commit/e4b02c7b0c4ccc8b7310701985bb5c6d62e21f4f)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 使用 context.credential 修复 adapter 凭证读取 KeyError ([261326e](https://github.com/L-1124/QQMusicApi/commit/261326eec051e7f444296b5c461e7412c4b25bb9)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复 404 响应不符合 RESTful 规范的问题 ([9658bd5](https://github.com/L-1124/QQMusicApi/commit/9658bd54b45c8eeab75f651ba26b16e1fd1126ce)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复 Web 模块代码质量与性能问题 ([329f822](https://github.com/L-1124/QQMusicApi/commit/329f822776376aad7bd6b3ede3e9dd9e5730c77c)) by [@L-1124](https://github.com/L-1124)
+
+### Dep-bump
+
+* **(deps)** update dependencies via uv lock --upgrade ([943ed52](https://github.com/L-1124/QQMusicApi/commit/943ed522e8bf6d385e3a0abb77663255ea57ea25)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(comment)** 支持设置评论业务类型与子类型 ([ea6095c](https://github.com/L-1124/QQMusicApi/commit/ea6095ce89772798154cf85785a2d72ee9a57ac4)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** 支持获取 AI 歌词词典 ([44e81f0](https://github.com/L-1124/QQMusicApi/commit/44e81f0521d73934a3bedacc3ec64870549c5f9c)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** 支持获取多风格翻译歌词 ([43d6429](https://github.com/L-1124/QQMusicApi/commit/43d64299a3e57779859f4ba5f876f0b11198e2ab)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** 支持获取助唱标注歌词及信息 ([3166fea](https://github.com/L-1124/QQMusicApi/commit/3166feabf77e223b82dca6922f4e09dd5eed0a15)) by [@L-1124](https://github.com/L-1124)
+* **(search)** 支持彩铃搜索类型 RINGTONE 与彩铃文件类型 RingSongFileType ([6c2118c](https://github.com/L-1124/QQMusicApi/commit/6c2118ccdd6e1e4eed9dd49d82b12bf63664630d)) by [@L-1124](https://github.com/L-1124)
+* **(search)** 类型搜索支持选择器 ([e097442](https://github.com/L-1124/QQMusicApi/commit/e097442d2a7e86f7f77bef016416554591370f41)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 引入 AuthPolicy.OPTIONAL 并对齐 SDK 凭证策略 ([ea29202](https://github.com/L-1124/QQMusicApi/commit/ea29202766ebc9a309c7fb3db495c246323289f7)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 优化枚举参数在 OpenAPI 文档中的说明展示 ([075a1ed](https://github.com/L-1124/QQMusicApi/commit/075a1ed9d964d374b4d34759b7d5f1a3fed937fc)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 支持 list[BaseModel] 类型的 JSON Query 参数解析 ([9dd26ee](https://github.com/L-1124/QQMusicApi/commit/9dd26eeff3871c1a4990c58b23d497737e547ed2)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(core)** [**breaking**] 重构并统一分页体系 ([cb41e16](https://github.com/L-1124/QQMusicApi/commit/cb41e16e62e9967010663a94db846dd205d45d1b)) by [@L-1124](https://github.com/L-1124) in [#299](https://github.com/L-1124/QQMusicApi/pull/299)
+* **(core)** [**breaking**] 移除未使用的 JCE 协议支持 ([dca6c7c](https://github.com/L-1124/QQMusicApi/commit/dca6c7cb623942f02d7cad44b986a8c7fbc91858)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** [**breaking**] 统一 song_id 为 songid ([e6d2a0b](https://github.com/L-1124/QQMusicApi/commit/e6d2a0baae21a3528115635b43a24781b9671017)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 引入 Adapter 注册表机制解耦路由声明 ([8b573c6](https://github.com/L-1124/QQMusicApi/commit/8b573c6a4da79e691762ccf9d81390730260b13c)) by [@L-1124](https://github.com/L-1124)
+
+### 文档更新
+
+* **(api)** 补充缺失的 API 模块和数据模型文档映射 ([8fe6095](https://github.com/L-1124/QQMusicApi/commit/8fe6095b154b35406fa2587e585d1f82373720ac)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @mirkosalvato1-ctrl
+* @github-actions[bot]
+
 ## [[0.7.0](https://github.com/L-1124/QQMusicApi/compare/v0.6.9..v0.7.0)] - 2026-07-22
 
 ### Bug 修复

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/docs/tutorial/client.md

@@ -61,6 +61,48 @@ results = await client.gather(
 
 此时失败项会以异常对象的形式出现在对应位置，成功项仍返回正常的响应模型。
 
+默认情况下 `return_exceptions=False`，任一请求执行期间发生异常时，`gather()` 会中断并抛出 `ExceptionGroup`
+（`BaseExceptionGroup` 的子类），其余尚未完成的并发请求会被取消。即使 **只有一个**请求失败，异常也会被包装成异常组抛出（通常包含触发失败的那个异常；当多个请求在同一轮取消/竞争中各自抛出新异常时，异常组可能包含多个）。
+
+`except*` 需要 Python 3.11+；在 3.10 上可从 `exceptiongroup` 兼容包导入 `BaseExceptionGroup`。若不需要区分并发错误，也可以保留
+`return_exceptions=True`，再对结果中的异常对象逐一处理。
+
+=== "Python 3.11+"
+
+    使用 `except*` 按异常类型直接捕获:
+
+    ```python
+    try:
+        results = await client.gather([...])
+    except* NetworkError as exc_group:
+        for exc in exc_group.exceptions:
+            print(f"网络错误: {exc}")
+    except* CgiApiException as exc_group:
+        for exc in exc_group.exceptions:
+            print(f"接口错误: {exc}")
+    ```
+
+=== "Python 3.10"
+
+    Python 3.10 没有内置异常组, 从 `exceptiongroup` 兼容包导入后, 用普通 `except` 即可捕获:
+
+    ```python
+    from exceptiongroup import BaseExceptionGroup
+
+    try:
+        results = await client.gather([...])
+    except BaseExceptionGroup as exc_group:
+        for exc in exc_group.exceptions:
+            if isinstance(exc, NetworkError):
+                print(f"网络错误: {exc}")
+            elif isinstance(exc, CgiApiException):
+                print(f"接口错误: {exc}")
+    ```
+
+> 注意：默认 `return_exceptions=False` 时，一旦抛出异常组，本次 `gather` 将立即终止且 **不会返回任何结果**
+> ——已成功的请求其结果也会一并丢弃，尚未执行的请求会被取消，异常组中也拿不到它们的异常。若需要保留成功项的结果、只对失败项单独处理，请使用
+> `return_exceptions=True`。
+
 ## 全局凭证
 
 如果你的场景需要登录，可以在初始化 `Client` 时直接注入 `Credential`：
@@ -92,11 +134,11 @@ asyncio.run(main())
 
 支持的平台：
 
-| 平台 | `Platform` 值 | 说明 |
-| ------ | -------------- | ------ |
+| 平台    | `Platform` 值      | 说明                 |
+|---------|--------------------|----------------------|
 | Android | `Platform.ANDROID` | 默认，大部分接口使用 |
-| Desktop | `Platform.DESKTOP` | QQ 音乐桌面端 |
-| Web | `Platform.WEB` | QQ 音乐网页端 |
+| Desktop | `Platform.DESKTOP` | QQ 音乐桌面端        |
+| Web     | `Platform.WEB`     | QQ 音乐网页端        |
 
 !!! note
 

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/docs/tutorial/pagination.md

@@ -2,9 +2,9 @@
 
 QQMusicApi 提供了统一的分页体系：
 
-* **`PaginatedRequest`**：具备连续翻页与批次刷新能力的请求描述符。既可直接 `await` 获取首批响应，也可通过 `.pager()`
+* **`PaginatedCgiRequest`**：具备连续翻页与批次刷新能力的 CGI 请求描述符。既可直接 `await` 获取首批响应，也可通过 `.pager()`
   手动按需步进，或使用 `.paginate()`、`.collect()` 和 `async for` 进行流式与批量遍历。
-* **`ItemPaginatedRequest`**：具备数据项提取能力的分页扩展类。除具备通用分页方法外，还通过 `.iter_items()` 与
+* **`ItemPaginatedCgiRequest`**：具备数据项提取能力的分页扩展类。除具备通用分页方法外，还通过 `.iter_items()` 与
   `.collect_items()` 实现了跨越页面边界、直接消费单一具体业务元素（如歌曲、专辑等）的功能。
 
 ## 1. 单次请求与无状态步进
@@ -149,8 +149,8 @@ asyncio.run(main())
 
 ## 6. 动态数据项提取
 
-如果你使用的某个 API 返回的请求对象是原生的 `PaginatedRequest`（即 API 层没有预设数据项提取器），你仍然可以通过
-`.with_extractor()` 动态注入一个提取逻辑。这会将请求无缝转换为具备跨页提取能力的 `ItemPaginatedRequest`。
+如果你使用的某个 API 返回的请求对象是原生的 `PaginatedCgiRequest`（即 API 层没有预设数据项提取器），你仍然可以通过
+`.with_extractor()` 动态注入一个提取逻辑。这会将请求无缝转换为具备跨页提取能力的 `ItemPaginatedCgiRequest`。
 
 这在处理一些层级较深、或者没有统一结构的响应时非常有用：
 
@@ -161,11 +161,11 @@ from qqmusic_api import Client
 
 async def main() -> None:
     async with Client() as client:
-        # 这个 API 返回原生的 PaginatedRequest
+        # 这个 API 返回原生的 PaginatedCgiRequest
         req = client.search.general_search("周杰伦")
 
         # 动态绑定 extractor
-        # 此时 item_req 类型变为 ItemPaginatedRequest
+        # 此时 item_req 类型变为 ItemPaginatedCgiRequest
         item_req = req.with_extractor(lambda r: r.song.items if r.song else [])
 
         # 现在你可以非常自然地跨页迭代数据项了！

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/pyproject.toml

@@ -115,6 +115,9 @@ addopts = ["-rxXs"]
 pythonpath = ["."]
 testpaths = ["tests"]
 asyncio_mode = "auto"
+markers = [
+  "core: Core 层单元测试, 使用桩数据驱动, 不发起真实网络请求",
+]
 
 [tool.ruff]
 line-length = 120

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/qqmusic_api/__init__.py

@@ -22,7 +22,7 @@ from .core.exceptions import (
 from .core.versioning import Platform
 from .models.request import Credential
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.7.1 → qqmusic_api_python-0.7.2}/qqmusic_api/core/__init__.py

@@ -19,7 +19,7 @@ from .exceptions import (
     NetworkError,
     RatelimitedError,
 )
-from .request import Request
+from .request import BaseRequest, CgiRequest, HttpRequest, ItemPaginatedCgiRequest, PaginatedCgiRequest
 from .versioning import DEFAULT_VERSION_POLICY, Platform, VersionPolicy, VersionProfile
 
 __all__ = [
@@ -27,22 +27,26 @@ __all__ = [
     "ApiDataError",
     "ApiException",
     "BaseApiException",
+    "BaseRequest",
     "CgiApiException",
+    "CgiRequest",
     "Client",
     "CredentialExpiredError",
     "CredentialInvalidError",
     "CredentialRefreshError",
     "GlobalApiError",
     "HTTPError",
+    "HttpRequest",
+    "ItemPaginatedCgiRequest",
     "LoginAccountRestrictedError",
     "LoginAuthExpiredError",
     "LoginDeviceLimitError",
     "LoginError",
     "LoginRateLimitError",
     "NetworkError",
+    "PaginatedCgiRequest",
     "Platform",
     "RatelimitedError",
-    "Request",
     "VersionPolicy",
     "VersionProfile",
 ]