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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.7.0
+Version: 0.7.1
 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.1}/docs/coding.md

@@ -15,9 +15,9 @@
   -> Request
   -> await request
   -> Client.execute(request)
-  -> Client.request_api(...)  (根据 request.is_jce 分发改用 JCE 或 JSON 协议)
+  -> Client.request_api(...)
   -> Client._build_result(...)
-  -> 返回原始 dict / TarsDict 或 Pydantic 模型
+  -> 返回原始 dict 或 Pydantic 模型
 ```
 
 ### 批量并发请求
@@ -66,6 +66,7 @@ class FooApi(ApiModule):
 # qqmusic_api/core/client.py
 from functools import cached_property
 
+
 class Client:
     @cached_property
     def foo(self) -> "FooApi":
@@ -81,9 +82,9 @@ API 方法返回 `Request` 对象，不直接发起请求。使用 `self._build_
 def get_detail(self, song_id: int):
     """获取歌曲详情."""
     return self._build_request(
-        module="music.songDetail",       # 接口所属模块
-        method="GetDetail",              # 方法名
-        param={"songid": song_id},       # 业务参数
+        module="music.songDetail",  # 接口所属模块
+        method="GetDetail",  # 方法名
+        param={"songid": song_id},  # 业务参数
     )
 ```
 
@@ -103,21 +104,20 @@ async def quick_search(self, keyword: str) -> dict[str, Any]:
 
 ### `_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`             |
+| 参数               | 类型                          | 说明                                                                                                        |
+|--------------------|-------------------------------|-------------------------------------------------------------------------------------------------------------|
+| `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` 参数说明
 
@@ -176,6 +176,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 映射路径，自动从嵌套响应中提取数据：
@@ -239,14 +250,16 @@ def get_vip_info(self, *, credential: Credential | None = None):
 > 若接口需要凭证对象的字段来构建请求参数，
 > 仍可显式调用 `_require_login` 获取凭证对象。
 
-## 翻页与换一批
+## 连续翻页与批次刷新
 
 ### 连续翻页
 
-通过 `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):
@@ -260,23 +273,23 @@ 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):
@@ -286,14 +299,12 @@ def get_related_mv(self, songid: int, last_mvid: str | None = None):
         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 +315,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`                   |
 
 ## 请求签名
 
@@ -372,6 +364,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 +404,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 +432,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.1}/docs/contributing.md

@@ -76,11 +76,19 @@ 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/docs/reference/model/helper.md

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

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

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

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

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

qqmusic_api_python-0.7.1/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.1}/docs/release-notes.md

@@ -1,4 +1,20 @@
 
+## [[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 修复

qqmusic_api_python-0.7.1/docs/tutorial/pagination.md

@@ -0,0 +1,177 @@
+# Pagination
+
+QQMusicApi 提供了统一的分页体系：
+
+* **`PaginatedRequest`**：具备连续翻页与批次刷新能力的请求描述符。既可直接 `await` 获取首批响应，也可通过 `.pager()`
+  手动按需步进，或使用 `.paginate()`、`.collect()` 和 `async for` 进行流式与批量遍历。
+* **`ItemPaginatedRequest`**：具备数据项提取能力的分页扩展类。除具备通用分页方法外，还通过 `.iter_items()` 与
+  `.collect_items()` 实现了跨越页面边界、直接消费单一具体业务元素（如歌曲、专辑等）的功能。
+
+## 1. 单次请求与无状态步进
+
+即使请求具备分页能力，你依然可以像普通请求一样直接 `await` 它，仅拉取单页数据：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        # 仅获取第 1 页数据
+        first_page = await client.album.get_new_album(page=1, num=10)
+        print(len(first_page.albums))
+
+
+asyncio.run(main())
+```
+
+如果你希望配合上一次响应手动构建下一页请求：
+
+```python
+req1 = client.album.get_new_album(page=1, num=10)
+res1 = await req1
+
+# 根据上一次响应获取下一次请求的描述符
+req2 = req1.next_request(res1)
+if req2 is not None:
+    res2 = await req2
+```
+
+## 2. 有状态控制器
+
+通过 `.pager()` 可以创建一个有状态的 `AsyncPager` 控制器：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        pager = client.comment.get_hot_comments(102065756, page_size=5).pager(limit=2)
+
+        while pager.has_more():
+            page = await pager.next()
+            print(len(page.comments))
+
+
+asyncio.run(main())
+```
+
+> `has_more()` 只读取当前分页器的内部状态，不会发起网络请求。`next()` 没有更多数据时会抛出 `StopAsyncIteration`。
+
+## 3. 全量收集与条目平铺
+
+如果你希望直接获取多页响应列表，或者直接获取展平后的所有实体数据项（如所有歌曲或专辑）。为防止无休止拉取带来的耗时与风控风险，强烈建议调用时始终设置合理的
+`limit` 参数：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        req = client.singer.get_album_list(mid="0025NhlN2yWrP4")
+
+        # 收集前 3 页的 Response 响应对象列表
+        pages = await req.collect(limit=3)
+        print(f"共获取 {len(pages)} 页响应")
+
+        # 自动跨页展开提取前 25 个专辑实体
+        albums = await req.collect_items(limit=25)
+        print(f"共收集 {len(albums)} 个专辑实体")
+
+
+asyncio.run(main())
+```
+
+## 4. 异步流式迭代
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        req = client.search.search_by_type("周杰伦", num=5)
+
+        # 方式 1：直接迭代对象本身，等价于 paginate()，连续翻页直至尾页
+        async for page in req:
+            print("当前页歌曲数:", len(page.song))
+            break  # 演示示例：仅处理一页后退出
+
+        # 方式 2：显式限制最大翻页数（推荐在生产环境中为循环设置合理的上限）
+        async for page in req.paginate(limit=2):
+            print("当前页歌曲数:", len(page.song))
+
+        # 方式 3：跨页条目级别迭代（自动展平为实体）
+        async for song in req.iter_items(limit=10):
+            print("歌曲名:", song.name)
+
+
+asyncio.run(main())
+```
+
+## 5. 批次刷新与单批次步进
+
+部分关联或推荐类接口（如歌曲相关 MV、相似歌曲等）并非按传统的页码（Page）或偏移量（Offset）递增，而是 **按批次（Batch）** 持续更新内容。
+
+对于此类以批次刷新为主、常通过单次触发拉取的场景，推荐使用有状态的分页控制器 `.pager()` 配合 `.first()` 与 `.next()`
+精准控制每一批次的获取：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        # 1. 实例化分页控制器
+        pager = client.song.get_related_mv(1114857).pager()
+
+        # 2. 首次加载页面时，拉取首批推荐数据
+        first_batch = await pager.first()
+        print("首批 MV 数量:", len(first_batch.mv))
+
+        # 3. 按需触发：调用 pager.next() 刷新拉取下一个批次
+        if pager.has_more():
+            next_batch = await pager.next()
+            print("下一批 MV 数量:", len(next_batch.mv))
+
+
+asyncio.run(main())
+```
+
+通过 `pager().first()` 与 `pager().next()`，既能在规范的接口契约下享受自动游标维护与防重复终止保护，又能贴合按批次更新的数据消费模式。
+
+## 6. 动态数据项提取
+
+如果你使用的某个 API 返回的请求对象是原生的 `PaginatedRequest`（即 API 层没有预设数据项提取器），你仍然可以通过
+`.with_extractor()` 动态注入一个提取逻辑。这会将请求无缝转换为具备跨页提取能力的 `ItemPaginatedRequest`。
+
+这在处理一些层级较深、或者没有统一结构的响应时非常有用：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        # 这个 API 返回原生的 PaginatedRequest
+        req = client.search.general_search("周杰伦")
+
+        # 动态绑定 extractor
+        # 此时 item_req 类型变为 ItemPaginatedRequest
+        item_req = req.with_extractor(lambda r: r.song.items if r.song else [])
+
+        # 现在你可以非常自然地跨页迭代数据项了！
+        async for song in item_req.iter_items(limit=10):
+            print("提取到的歌曲:", song)
+
+
+asyncio.run(main())
+```

{qqmusic_api_python-0.7.0 → qqmusic_api_python-0.7.1}/prek.toml

@@ -1,14 +1,14 @@
 default_install_hook_types = ["pre-commit", "commit-msg"]
+exclude = '^docs/release-notes\.md$'
 
 [[repos]]
-repo = "https://github.com/pre-commit/pre-commit-hooks"
-rev = "v6.0.0"
+repo = "builtin"
 hooks = [
   { id = "check-added-large-files" },
   { id = "check-merge-conflict" },
   { id = "check-json" },
   { id = "check-toml" },
-  { id = "check-yaml", args = ["--unsafe"] },
+  { id = "check-yaml" },
   { id = "detect-private-key" },
   { id = "end-of-file-fixer", exclude = '^LICENSE|\.(html|csv|txt|svg)$' },
   { id = "pretty-format-json", args = ["--autofix", "--no-ensure-ascii", "--no-sort-keys"] },
@@ -17,7 +17,7 @@ hooks = [
 
 [[repos]]
 repo = "https://github.com/commitizen-tools/commitizen"
-rev = "v4.13.9"
+rev = "v4.17.0"
 hooks = [
   { id = "commitizen", additional_dependencies = ["cz-conventional-gitmoji"] },
 ]
@@ -31,7 +31,7 @@ hooks = [
 
 [[repos]]
 repo = "https://github.com/DavidAnson/markdownlint-cli2"
-rev = "v0.22.0"
+rev = "v0.23.2"
 hooks = [
   { id = "markdownlint-cli2", args = ["--fix"] },
 ]

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

@@ -39,7 +39,6 @@ dependencies = [
   "orjson>=3.10.15",
   "paho-mqtt>=2.1.0",
   "pydantic>=2.13.3",
-  "tarsio>=0.5.1",
   "typing-extensions>=4.12.2",
 ]
 dynamic = ["version"]
@@ -56,7 +55,6 @@ upload = [
 
 [dependency-groups]
 dev = [
-  "tarsio[cli]>=0.5.1",
   "terminal-qrcode>=1.1.0",
   { include-group = "docs" },
   { include-group = "linting" },

{qqmusic_api_python-0.7.0 → qqmusic_api_python-0.7.1}/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.0"
+__version__ = "0.7.1"
 
 __all__ = [
     "ApiDataError",