qqmusic-api-python 0.5.1__tar.gz → 0.5.2__tar.gz

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/.github/workflows/docs.yml

@@ -53,7 +53,7 @@ jobs:
       - name: Build with zensical
         run: uv run zensical build
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: ./site
 

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.5.1
+Version: 0.5.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.5.1 → qqmusic_api_python-0.5.2}/docs/release-notes.md

@@ -3,6 +3,27 @@
 
 ### 文档更新
 
+* **(pagination)** 修正分页示例错误 ([c310450](https://github.com/L-1124/QQMusicApi/commit/c31045021034ce130136a17b458091c456998d53)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
+## [[0.5.1](https://github.com/L-1124/QQMusicApi/compare/v0.5.0..v0.5.1)] - 2026-04-13
+
+### 功能更新
+
+* 获取歌曲文件支持传入歌曲类型 ([a2ad367](https://github.com/L-1124/QQMusicApi/commit/a2ad3675ac56a501f8e08e761e12c68bf6155a98)) by [@L-1124](https://github.com/L-1124)
+* [**breaking**] 重构歌曲文件获取逻辑，支持获取特殊类型的歌曲文件 ([5e31a48](https://github.com/L-1124/QQMusicApi/commit/5e31a4888cf3d4818b3cd59861ffc4d883c4ca1a)) by [@L-1124](https://github.com/L-1124)
+* 接口请求支持更方便的下一页、换一批请求 ([98693f8](https://github.com/L-1124/QQMusicApi/commit/98693f86995df7a62ca705a46643afffb3306e4a)) by [@L-1124](https://github.com/L-1124) in [#235](https://github.com/L-1124/QQMusicApi/pull/235)
+
+### 功能重构
+
+* **(login)** 优化 MQTT 登录链路并替换 HTTP 重试实现 ([244e000](https://github.com/L-1124/QQMusicApi/commit/244e000c08dce6beb3ab46c7d266c361515b4b20)) by [@L-1124](https://github.com/L-1124) in [#237](https://github.com/L-1124/QQMusicApi/pull/237)
+
+### 文档更新
+
 * **(index)** 修正首页使用示例 ([ebafd9c](https://github.com/L-1124/QQMusicApi/commit/ebafd9cfc119c35e8b7a8fa16cd60abe81657707)) by [@L-1124](https://github.com/L-1124)
 * 添加缺少的模块文档 ([376970e](https://github.com/L-1124/QQMusicApi/commit/376970ececc30e876342548ddacded06e48112d7)) by [@L-1124](https://github.com/L-1124)
 * 更新 index.md ([d8e3668](https://github.com/L-1124/QQMusicApi/commit/d8e3668fdfb8e4766f8cf0cbc0e3bb9eece0bfd0)) by [@L-1124](https://github.com/L-1124)
@@ -10,6 +31,7 @@
 ### 贡献者
 
 * @L-1124
+* @renovate[bot] [#238](https://github.com/L-1124/QQMusicApi/pull/238)
 * @github-actions[bot]
 
 ## [[0.5.0](https://github.com/L-1124/QQMusicApi/compare/v0.4.1..v0.5.0)] - 2026-04-02

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/docs/tutorial/pagination.md

@@ -19,15 +19,42 @@ from qqmusic_api import Client
 async def main() -> None:
     async with Client() as client:
         pager = client.search.search_by_type("周杰伦", num=5).paginate(limit=3)
+        page_number = 1
 
         async for page in pager:
-            print(page.nextpage)
+            print(f"第 {page_number} 页")
             print(len(page.song))
+            page_number += 1
+
+asyncio.run(main())
+```
+
+## Pager 手动逐页拉取
+
+如果你希望自行控制何时请求下一页, 可以配合 `has_more()` 与 `next()` 使用。`has_more()` 只读取分页器当前状态, 不会主动发起网络请求。
+
+> `next()` 与 `async for` 的终止行为一致: 没有更多结果时会抛出 `StopAsyncIteration`。
+
+```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).paginate(limit=2)
+
+        while pager.has_more():
+            page = await pager.next()
+            print(len(page.comments))
 
 
 asyncio.run(main())
 ```
 
+在第一页尚未请求前, 只要分页器未耗尽且未达到 `limit`, `has_more()` 就会返回 `True`。当上游响应已经明确没有下一页, 或者你已经达到 `limit`, `has_more()` 会变为 `False`。
+
 ## Pager 返回值
 
 分页器每次迭代返回的，仍然是该接口原本的响应模型。

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/pyproject.toml

@@ -103,6 +103,9 @@ asyncio_mode = "auto"
 line-length = 120
 extend-exclude = ["docs"]
 
+[tool.pyright]
+typeCheckingMode  = "basic"
+
 [tool.ruff.lint]
 extend-select = [
   "A",

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/qqmusic_api/__init__.py

@@ -14,7 +14,7 @@ from .core.exceptions import (
 from .core.versioning import Platform
 from .models.request import Credential
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 
 __all__ = [
     "ApiError",

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/qqmusic_api/core/pagination.py

@@ -434,18 +434,34 @@ class ResponsePager(_BaseResponseAdvancer[RequestResultT], AsyncIterator[Request
         self._limit = limit
         self._yielded_count = 0
 
+    def _can_advance(self) -> bool:
+        """返回当前分页器是否还能继续产出下一页."""
+        if self._next_request is None:
+            return False
+        if self._limit is None:
+            return True
+        return self._yielded_count < self._limit
+
     def __aiter__(self) -> AsyncIterator[RequestResultT]:
         """返回分页器自身, 以支持 `async for` 迭代."""
         return self
 
     async def __anext__(self) -> RequestResultT:
         """获取并返回下一页响应."""
-        if self._limit is not None and self._yielded_count >= self._limit:
+        if not self._can_advance():
             raise StopAsyncIteration
         response = await self._advance()
         self._yielded_count += 1
         return response
 
+    async def next(self) -> RequestResultT:
+        """获取并返回下一页响应."""
+        return await self.__anext__()
+
+    def has_more(self) -> bool:
+        """返回当前分页器是否还能继续产出下一页."""
+        return self._can_advance()
+
     def _get_meta(self, request: "PaginatedRequest[RequestResultT]") -> PagerMeta:
         """读取分页请求对应的连续翻页元数据."""
         return request.get_pager_meta()

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/qqmusic_api/models/album.py

@@ -1,6 +1,6 @@
 """Album API 返回模型定义."""
 
-from pydantic import Field
+from pydantic import Field, field_validator
 
 from .base import Album, Singer, Song
 from .request import Response
@@ -70,3 +70,9 @@ class GetAlbumSongResponse(Response):
     album_mid: str = Field(alias="albumMid")
     total_num: int = Field(alias="totalNum")
     song_list: list[Song] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.songList[*].songInfo"})
+
+    @field_validator("song_list", mode="before")
+    @classmethod
+    def _coerce_song_list(cls, value: list[dict] | dict) -> list[dict]:
+        """将上游返回的单个歌曲信息统一规整为列表."""
+        return [value] if isinstance(value, dict) else value

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/qqmusic_api/models/user.py

@@ -126,7 +126,7 @@ class UserFavSonglistResponse(Response):
     total: int
     hasmore: int
     hide: bool
-    playlists: list[UserFavSonglistItem] = Field(json_schema_extra={"jsonpath": "$.v_list[*]"})
+    playlists: list[UserFavSonglistItem] = Field(json_schema_extra={"jsonpath": "$.v_list"})
     deleted_ids: list[int] = Field(alias="v_delTids")
     failed_ids: list[int] = Field(alias="v_failTids")
 

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/qqmusic_api/modules/user.py

@@ -46,7 +46,7 @@ class UserApi(ApiModule):
 
         Args:
             euin: 加密后的 UIN.
-            credential: 可选的登录凭证；未传入时优先使用客户端当前凭证，
+            credential: 可选的登录凭证; 未传入时优先使用客户端当前凭证,
                 若客户端凭证不可用则自动使用占位凭证.
         """
         target_credential = self._resolve_placeholder_credential(credential)

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/tests/test_comment.py

@@ -39,13 +39,19 @@ async def test_get_moment_comments(client: Client) -> None:
 
 
 async def test_get_hot_comments_paginate(client: Client) -> None:
-    """测试热评列表分页能力."""
+    """测试热评列表支持手动逐页拉取."""
     pager = client.comment.get_hot_comments(102065756, page_num=1, page_size=5).paginate(limit=2)
-    pages = [page async for page in pager]
 
-    assert len(pages) == 2
-    assert pages[0].comments
-    assert pages[1].comments
+    assert pager.has_more() is True
+    first_page = await pager.next()
+    assert pager.has_more() is True
+    second_page = await pager.next()
+
+    assert first_page.comments
+    assert second_page.comments
+    assert pager.has_more() is False
+    with pytest.raises(StopAsyncIteration):
+        await pager.next()
 
 
 async def test_get_moment_comments_paginate(client: Client) -> None:

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.2}/tests/test_search.py

@@ -60,14 +60,17 @@ async def test_search_by_type_with_int(client: Client) -> None:
 
 
 async def test_search_by_type_paginate(client: Client) -> None:
-    """测试按类型搜索的分页能力."""
-    # 测试分页迭代 (取前两页)
-    pager = client.search.search_by_type("周杰伦", num=5, page=1).paginate()
-    pages = []
-    async for page in pager:
-        pages.append(page)
-        if len(pages) >= 2:
-            break
-
-    assert len(pages) == 2
-    assert pages[0].nextpage == 2
+    """测试搜索分页支持 next 与 has_more."""
+    pager = client.search.search_by_type("周杰伦", num=5, page=1).paginate(limit=2)
+
+    assert pager.has_more() is True
+    first_page = await pager.next()
+    assert pager.has_more() is True
+    second_page = await pager.next()
+
+    assert first_page.song
+    assert second_page.song
+    assert first_page.nextpage == 2
+    assert pager.has_more() is False
+    with pytest.raises(StopAsyncIteration):
+        await pager.next()