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

{qqmusic_api_python-0.7.0 → qqmusic_api_python-0.7.2}/.github/workflows/docs.yml

@@ -19,22 +19,22 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
         with:
           fetch-depth: 0
           token: ${{ secrets.GH_TOKEN }}
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v6
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d  # v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9  # v7
         with:
           enable-cache: true
           python-version: 3.12
       - name: Install the project
         run: uv sync --group docs
       - name: Generate release-notes
-        uses: orhun/git-cliff-action@v4
+        uses: orhun/git-cliff-action@f50e11560dce63f7c33227798f90b924471a88b5  # v4
         with:
           config: cliff.toml
           args: --verbose --strip all
@@ -55,7 +55,7 @@ jobs:
       - name: Build with zensical
         run: uv run zensical build
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v5
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
         with:
           path: ./site
 
@@ -68,4 +68,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5

{qqmusic_api_python-0.7.0 → qqmusic_api_python-0.7.2}/.github/workflows/release.yml

@@ -15,13 +15,13 @@ jobs:
     outputs:
       release_body: ${{ steps.git-cliff.outputs.content }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
         with:
           fetch-depth: 0
           token: ${{ secrets.GH_TOKEN }}
       - name: Generate release body
         id: git-cliff
-        uses: orhun/git-cliff-action@v4
+        uses: orhun/git-cliff-action@f50e11560dce63f7c33227798f90b924471a88b5  # v4
         with:
           args: -vv --latest --strip all
 
@@ -32,11 +32,11 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
         with:
           token: ${{ secrets.GH_TOKEN }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9  # v7
         with:
           enable-cache: true
       - name: Install the project
@@ -51,11 +51,11 @@ jobs:
     needs: [generate-release-body, publish]
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
         with:
           token: ${{ secrets.GH_TOKEN }}
       - name: Release
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228  # v3
         with:
           body: ${{ needs.generate-release-body.outputs.release_body }}
           tag_name: ${{ github.ref_name }}

{qqmusic_api_python-0.7.0 → qqmusic_api_python-0.7.2}/.github/workflows/testing.yml

@@ -10,9 +10,9 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9  # v7
         with:
           enable-cache: true
           python-version: "3.10"

{qqmusic_api_python-0.7.0 → 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.0 → qqmusic_api_python-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.7.0
+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/
@@ -35,7 +35,6 @@ Requires-Dist: niquests[speedups]>=3.18.7
 Requires-Dist: orjson>=3.10.15
 Requires-Dist: paho-mqtt>=2.1.0
 Requires-Dist: pydantic>=2.13.3
-Requires-Dist: tarsio>=0.5.1
 Requires-Dist: typing-extensions>=4.12.2
 Provides-Extra: upload
 Requires-Dist: cos-python-sdk-v5>=1.9.44; extra == 'upload'

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

@@ -11,31 +11,32 @@
 
 ```text
 模块方法
-  -> self._build_request(...)
-  -> Request
+  -> self._build_cgi(...) / self._build_http(...)
+  -> BaseRequest 描述符
   -> await request
   -> Client.execute(request)
-  -> Client.request_api(...)  (根据 request.is_jce 分发改用 JCE 或 JSON 协议)
-  -> Client._build_result(...)
-  -> 返回原始 dict / TarsDict 或 Pydantic 模型
+  -> ApiContext 注入环境与凭证
+  -> Session.post(...) / Session.request(...)
+  -> Request._parse_response(...)
+  -> 返回原始 dict 或 Pydantic 模型
 ```
 
 ### 批量并发请求
 
 ```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},
@@ -66,6 +67,7 @@ class FooApi(ApiModule):
 # qqmusic_api/core/client.py
 from functools import cached_property
 
+
 class Client:
     @cached_property
     def foo(self) -> "FooApi":
@@ -75,84 +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(
-        module="music.songDetail",       # 接口所属模块
-        method="GetDetail",              # 方法名
-        param={"songid": song_id},       # 业务参数
+    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`        | 覆盖本次请求的平台                                        |
-| `is_jce`         | `bool`                      | 是否作为 JCE (Tars) 二进制协议发送                        |
-| `preserve_bool`  | `bool`                      | 是否保留布尔值原样（默认转为 0/1 整型）                   |
-| `sign`           | `bool`                      | 是否对请求进行签名                                        |
-| `pager_meta`     | `PagerMeta` 或 `None`       | 分页元数据，提供后返回 `PaginatedRequest`                 |
-| `refresh_meta`   | `RefreshMeta` 或 `None`     | 换一批元数据，提供后返回 `RefreshableRequest`             |
-
-### `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)
 ```
 
 ## 响应模型
@@ -176,6 +172,17 @@ class MyResponse(Response):
 
 `Response` 基类配置了 `frozen=True`（不可变）和 `extra="ignore"`（忽略多余字段）。
 
+!!! warning "Pydantic 默认值规范"
+
+    定义模型时应避免使用 `None` 作为隐式兜底默认值。如果字段可选或为空，应当使用显式的空标量，或通过 `Field(default_factory=...)` 声明：
+    ```python
+    class Album(Response):
+        name: str = ""
+        publish_time: str = ""
+        # 列表必须使用 default_factory
+        singers: list[Singer] = Field(default_factory=list)
+    ```
+
 ### JSONPath 字段映射
 
 可以通过 `Field(json_schema_extra={"jsonpath": ...})` 声明字段的 JSONPath 映射路径，自动从嵌套响应中提取数据：
@@ -221,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={},
@@ -236,22 +243,24 @@ def get_vip_info(self, *, credential: Credential | None = None):
     )
 ```
 
-> 若接口需要凭证对象的字段来构建请求参数，
-> 仍可显式调用 `_require_login` 获取凭证对象。
+> 若接口需要凭证对象的属性（如 `musicid` 等）来构建请求内联参数，
+> 仍可通过 `credential = credential or self._client.credential` 获取并显式验证其有效性。
 
-## 翻页与换一批
+## 连续翻页与批次刷新
 
 ### 连续翻页
 
-通过 `pager_meta` 声明连续翻页能力，返回的请求对象会暴露 `.paginate()`：
+通过 `pager_strategy` 声明连续翻页能力，建议配合显示 Generic 标注（形如
+`OffsetStrategy[GetSonglistDetailResponse]`）以确保静态类型检查与类型推断的准确性，并通过 `.with_extractor()`
+链式调用绑定实体数据项的提取逻辑：
 
 ```python
-from ..core.pagination import OffsetStrategy, PagerMeta, ResponseAdapter
+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={
@@ -260,40 +269,38 @@ def get_detail(self, songlist_id: int, num: int = 10, page: int = 1):
             "song_num": num,
         },
         response_model=GetSonglistDetailResponse,
-        pager_meta=PagerMeta(
-            strategy=OffsetStrategy(offset_key="song_begin", page_size_key="song_num"),
-            adapter=ResponseAdapter(
-                has_more_flag="hasmore",
-                total="total",
-                count=lambda response: len(response.songs),
-            ),
+        pager_strategy=OffsetStrategy[GetSonglistDetailResponse](
+            offset_key="song_begin",
+            page_size_key="song_num",
+            has_more_extractor=lambda response: bool(response.hasmore),
+            total_extractor=lambda response: response.total,
+            count_extractor=lambda response: len(response.songs),
         ),
-    )
+    ).with_extractor(lambda response: response.songs)
 ```
 
-### 换一批
+### 批次刷新 (Batch Refresh)
 
-通过 `refresh_meta` 声明换一批能力，返回的请求对象会暴露 `.refresh()`：
+批次刷新（Batch Refresh）是一种针对推荐或关联接口、支持游标复位与防循环重复游标的特殊游标分页，同样通过 `pager_strategy` 声明：
 
 ```python
-from ..core.pagination import BatchRefreshStrategy, RefreshMeta, ResponseAdapter
+from ..core.pagination import BatchRefreshStrategy
+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},
         response_model=GetRelatedMvResponse,
-        refresh_meta=RefreshMeta(
-            strategy=BatchRefreshStrategy(refresh_key="lastmvid"),
-            adapter=ResponseAdapter(
-                has_more_flag="has_more",
-                cursor=lambda response: response.mv[-1].id if response.mv else None,
-            ),
+        pager_strategy=BatchRefreshStrategy[GetRelatedMvResponse](
+            refresh_key="lastmvid",
+            cursor_extractor=lambda response: response.mv[-1].id if response.mv else None,
+            has_more_extractor=lambda response: bool(response.has_more),
         ),
-    )
+    ).with_extractor(lambda response: response.mv)
 ```
 
 ### 内置策略速查
@@ -304,26 +311,7 @@ def get_related_mv(self, songid: int, last_mvid: str | None = None):
 | `OffsetStrategy`                 |   偏移量滑窗 | `offset_key` + `page_size_key`  |
 | `CursorStrategy`                 | 响应游标回写 | `cursor_key`                    |
 | `MultiFieldContinuationStrategy` |   多字段续翻 | 自定义 `build_next_params` 函数 |
-| `BatchRefreshStrategy`           |       换一批 | `refresh_key`                   |
-
-`pager_meta` 与 `refresh_meta` 不能同时声明。
-
-## JCE (Tars) 协议
-
-部分接口使用 JCE 二进制协议而非 JSON。通过 `is_jce=True` 启用：
-
-```python
-def get_something(self):
-    """获取数据 (JCE 协议)."""
-    return self._build_request(
-        module="music.foo.Svc",
-        method="GetSomething",
-        param={0: "value"},  # JCE 使用整数 key
-        is_jce=True,
-    )
-```
-
-JCE 协议的响应会自动解码为 `TarsDict`。
+| `BatchRefreshStrategy`           |     批次刷新 | `refresh_key`                   |
 
 ## 请求签名
 
@@ -332,7 +320,7 @@ JCE 协议的响应会自动解码为 `TarsDict`。
 ```python
 def get_sheet(self, mid: str):
     """获取曲谱."""
-    return self._build_request(
+    return self._build_cgi(
         module="music.mir.SheetMusicSvr",
         method="GetMoreSheetMusic",
         param={"songMid": mid},
@@ -348,7 +336,7 @@ def get_sheet(self, mid: str):
 
 ```python
 # 合并到自动生成的 comm 中（默认行为）
-self._build_request(
+self._build_cgi(
     ...,
     comm={"extra_key": "value"},
 )
@@ -357,7 +345,7 @@ self._build_request(
 使用 `override_comm=True` 完全替代自动生成的参数：
 
 ```python
-self._build_request(
+self._build_cgi(
     ...,
     comm={
         "g_tk": 5381,
@@ -372,6 +360,20 @@ self._build_request(
 )
 ```
 
+## 异常处理
+
+在抛出或处理异常时，应使用项目统一的基于领域驱动（DDD）风格的异常类（继承自 `BaseApiException` 或 `ApiException`
+）。在包装底层异常时，必须使用原生异常链（`raise ... from exc`）保留堆栈追踪：
+
+```python
+from ..core.exceptions import ApiDataError
+
+try:
+    ...
+except KeyError as e:
+    raise ApiDataError("无法解析歌曲信息") from e
+```
+
 ## 编写测试
 
 测试文件放在 `tests/` 下，按模块命名（如 `test_song.py`）。
@@ -398,8 +400,15 @@ async def test_query_song(client: Client) -> None:
 ```python
 @pytest.mark.parametrize("page", [1, 2])
 async def test_general_search(client: Client, page: int) -> None:
-    """测试综合搜索翻页."""
-    result = await client.search.general_search("周杰伦", page=page)
+    """测试综合搜索翻页逻辑."""
+    try:
+        result = await client.search.general_search("周杰伦", page=page)
+    except Exception as e:
+        # 示例：优雅处理网络风控或限流 (需根据实际异常类型调整)
+        if "limit" in str(e).lower() or "risk" in str(e).lower():
+            pytest.skip(f"Triggered rate limit or risk control: {e}")
+        raise
+
     assert result.song.items is not None
 ```
 
@@ -419,7 +428,7 @@ async def test_get_vip_info(authenticated_client: Client) -> None:
 ```python
 async def test_search_paginate(client: Client) -> None:
     """测试搜索分页."""
-    pager = client.search.search_by_type("周杰伦", num=5).paginate(limit=2)
+    pager = client.search.search_by_type("周杰伦", num=5).pager(limit=2)
 
     assert pager.has_more() is True
     first_page = await pager.next()

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

@@ -80,7 +80,7 @@ uv run mkdocs serve
 
 * 注释内容包括：模块注释、类注释、函数注释、参数类型注释、返回值注释
 * 注释风格遵循 [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
-* 测试函数应包含单行中文 docstring（英文标点）
+* 测试用例必须包含 **单行中文 docstring**，且内部必须使用 **英文标点符号**。
 
 ## 文档规范
 

qqmusic_api_python-0.7.2/docs/reference/model/helper.md

@@ -0,0 +1,3 @@
+# helper
+
+::: models.helper

qqmusic_api_python-0.7.2/docs/reference/model/private_message.md

@@ -0,0 +1,3 @@
+# private_message
+
+::: models.private_message

qqmusic_api_python-0.7.2/docs/reference/modules/helper.md

@@ -0,0 +1,3 @@
+# HelperApi
+
+::: modules.helper.HelperApi

qqmusic_api_python-0.7.2/docs/reference/modules/helper_utils.md

@@ -0,0 +1,3 @@
+# HelperUtils
+
+::: modules.helper_utils

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

@@ -1,4 +1,62 @@
 
+## [[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 修复
+
+* fix retry import path ([75d0693](https://github.com/L-1124/QQMusicApi/commit/75d069344a07c6713b4a616ed6304ca6dc1b740a)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(lyric)** 支持指定特殊歌曲类型(song_type)查询歌词 ([1b0aae0](https://github.com/L-1124/QQMusicApi/commit/1b0aae0db3ee6876b3a77b8d1ce3057b4b3c9cd5)) by [@L-1124](https://github.com/L-1124)
+* **(song)** [**breaking**] 重构歌曲查询支持 SongQueryInfo 与 Web POST 批量路由 ([4cbb2c6](https://github.com/L-1124/QQMusicApi/commit/4cbb2c6e993d58db71494ce31809a144bfc33be4)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
 ## [[0.6.9](https://github.com/L-1124/QQMusicApi/compare/v0.6.8..v0.6.9)] - 2026-07-12
 
 ### Bug 修复