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

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.3}/.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.3}/PKG-INFO

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

@@ -1,5 +1,36 @@
 
-## What's Changed
+## [[0.5.2](https://github.com/L-1124/QQMusicApi/compare/v0.5.1..v0.5.2)] - 2026-04-18
+
+### Bug 修复
+
+* `UserFavSonglistResponse`jsonpath错误 ([2c54ebb](https://github.com/L-1124/QQMusicApi/commit/2c54ebb8d21a8ba02bb5b865a7ff0aa9aadcbc0d)) by [@L-1124](https://github.com/L-1124)
+* `GetAlbumSongResponse`上游返回单个歌曲信息报错 ([adbdc40](https://github.com/L-1124/QQMusicApi/commit/adbdc4069f964125ca2228d36014f64893f3e69a)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(core)** 为 ResponsePager 添加 next 与 has_more ([0a63a26](https://github.com/L-1124/QQMusicApi/commit/0a63a264433bf37b5854064aa8ef95edba97adab)) by [@L-1124](https://github.com/L-1124)
+
+### 文档更新
+
+* **(pagination)** 修正分页示例错误 ([c310450](https://github.com/L-1124/QQMusicApi/commit/c31045021034ce130136a17b458091c456998d53)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @renovate[bot] [#240](https://github.com/L-1124/QQMusicApi/pull/240)
+* @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)
 
 ### 文档更新
 
@@ -10,6 +41,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.3}/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.3}/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.3/qqmusic_api/__init__.py

@@ -0,0 +1,52 @@
+"""QQMusic API 公开入口."""
+
+from .core.client import Client
+from .core.exceptions import (
+    ApiError,
+    HTTPError,
+    LoginAccountBannedError,
+    LoginAccountRestrictedError,
+    LoginApiError,
+    LoginAuthCodeError,
+    LoginAuthFailedError,
+    LoginBindRequiredError,
+    LoginCredentialExpiredError,
+    LoginDeviceLimitError,
+    LoginError,
+    LoginExpiredError,
+    LoginRateLimitedError,
+    LoginSecurityRequiredError,
+    NetworkError,
+    NotLoginError,
+    RatelimitedError,
+    SignInvalidError,
+)
+from .core.versioning import Platform
+from .models.request import Credential
+
+__version__ = "0.5.3"
+
+__all__ = [
+    "ApiError",
+    "Client",
+    "Credential",
+    "HTTPError",
+    "LoginAccountBannedError",
+    "LoginAccountRestrictedError",
+    "LoginApiError",
+    "LoginAuthCodeError",
+    "LoginAuthFailedError",
+    "LoginBindRequiredError",
+    "LoginCredentialExpiredError",
+    "LoginDeviceLimitError",
+    "LoginError",
+    "LoginExpiredError",
+    "LoginRateLimitedError",
+    "LoginSecurityRequiredError",
+    "NetworkError",
+    "NotLoginError",
+    "Platform",
+    "RatelimitedError",
+    "SignInvalidError",
+    "__version__",
+]

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.3}/qqmusic_api/core/__init__.py

@@ -7,8 +7,18 @@ from .exceptions import (
     BaseError,
     CredentialError,
     HTTPError,
+    LoginAccountBannedError,
+    LoginAccountRestrictedError,
+    LoginApiError,
+    LoginAuthCodeError,
+    LoginAuthFailedError,
+    LoginBindRequiredError,
+    LoginCredentialExpiredError,
+    LoginDeviceLimitError,
     LoginError,
     LoginExpiredError,
+    LoginRateLimitedError,
+    LoginSecurityRequiredError,
     NetworkError,
     NotLoginError,
     RatelimitedError,
@@ -29,8 +39,18 @@ __all__ = [
     "ClientConfig",
     "CredentialError",
     "HTTPError",
+    "LoginAccountBannedError",
+    "LoginAccountRestrictedError",
+    "LoginApiError",
+    "LoginAuthCodeError",
+    "LoginAuthFailedError",
+    "LoginBindRequiredError",
+    "LoginCredentialExpiredError",
+    "LoginDeviceLimitError",
     "LoginError",
     "LoginExpiredError",
+    "LoginRateLimitedError",
+    "LoginSecurityRequiredError",
     "NetworkError",
     "NotLoginError",
     "Platform",

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.3}/qqmusic_api/core/exceptions.py

@@ -8,8 +8,18 @@ __all__ = [
     "BaseError",
     "CredentialError",
     "HTTPError",
+    "LoginAccountBannedError",
+    "LoginAccountRestrictedError",
+    "LoginApiError",
+    "LoginAuthCodeError",
+    "LoginAuthFailedError",
+    "LoginBindRequiredError",
+    "LoginCredentialExpiredError",
+    "LoginDeviceLimitError",
     "LoginError",
     "LoginExpiredError",
+    "LoginRateLimitedError",
+    "LoginSecurityRequiredError",
     "NetworkError",
     "NotLoginError",
     "RatelimitedError",
@@ -166,8 +176,74 @@ class LoginError(BaseError):
     通常在扫码登录流程中断、超时或网络失败时抛出。
     """
 
-    def __init__(self, message: str = "登录失败", cause: BaseException | None = None):
-        super().__init__(message, cause=cause)
+    def __init__(
+        self,
+        message: str = "登录失败",
+        cause: BaseException | None = None,
+        context: dict[str, Any] | None = None,
+    ):
+        super().__init__(message, context=context, cause=cause)
+
+
+class LoginApiError(LoginError):
+    """登录接口返回的业务错误基类."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: int,
+        data: dict[str, Any] | None = None,
+        action_url: str = "",
+        cause: BaseException | None = None,
+        context: dict[str, Any] | None = None,
+    ):
+        merged_context = dict(context or {})
+        merged_context["code"] = code
+        if data:
+            merged_context["data"] = data
+        if action_url:
+            merged_context["url"] = action_url
+        super().__init__(message, context=merged_context, cause=cause)
+        self.code = code
+        self.data = data or {}
+        self.action_url = action_url
+
+
+class LoginCredentialExpiredError(LoginApiError):
+    """登录刷新凭证不可用或登录态过期."""
+
+
+class LoginAuthFailedError(LoginApiError):
+    """登录认证失败或上游票据不可用."""
+
+
+class LoginSecurityRequiredError(LoginApiError):
+    """登录需要安全验证或人工交互."""
+
+
+class LoginAccountRestrictedError(LoginApiError):
+    """账号登录受限."""
+
+
+class LoginAccountBannedError(LoginApiError):
+    """账号被封禁导致无法登录."""
+
+
+class LoginBindRequiredError(LoginApiError):
+    """登录需要完成账号绑定或设备确认."""
+
+
+class LoginDeviceLimitError(LoginApiError):
+    """登录设备数量超限."""
+
+
+class LoginAuthCodeError(LoginApiError):
+    """手机验证码错误或已失效."""
+
+
+class LoginRateLimitedError(LoginApiError):
+    """登录操作触发频率限制."""
 
 
 class RequestGroupResultMissingError(ApiError):

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.3}/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.3}/qqmusic_api/core/versioning.py

@@ -30,7 +30,7 @@ class VersionProfile:
     qimei_sdk_version: str | None = None
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(slots=True)
 class VersionPolicy:
     """请求版本策略."""
 

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.3}/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.3}/qqmusic_api/models/base.py

@@ -19,7 +19,7 @@ _PHOTO_NEW_SIZE_SEGMENTS: Final[dict[int, str]] = {
 
 
 def _normalize_cover_size(size: CoverSize) -> str:
-    """返回 APK `photo_new` 模板使用的尺寸片段."""
+    """返回 `photo_new` 模板使用的尺寸片段."""
     try:
         return _PHOTO_NEW_SIZE_SEGMENTS[size]
     except KeyError as exc:
@@ -27,7 +27,7 @@ def _normalize_cover_size(size: CoverSize) -> str:
 
 
 def _build_photo_new_cover_url(kind: str, mid: str, size: CoverSize) -> str:
-    """按 APK `photo_new` 规则拼接封面链接."""
+    """按 `photo_new` 规则拼接封面链接."""
     normalized_mid = mid.strip()
     if not normalized_mid:
         return ""
@@ -200,7 +200,7 @@ class SongList(Response):
     picurl: str = Field(default="", validation_alias=AliasChoices("picurl", "cover", "logo", "picUrl"))
     desc: str = Field(default="", validation_alias=AliasChoices("desc", "description"))
     songnum: int = Field(default=0, validation_alias=AliasChoices("songnum", "songNum", "song_cnt"))
-    listennum: int | str = Field(default=0, validation_alias=AliasChoices("listennum", "playCnt", "play_cnt"))
+    listennum: int = Field(default=0, validation_alias=AliasChoices("listennum", "playCnt", "play_cnt"))
 
 
 class Song(Response):

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.3}/qqmusic_api/models/request.py

@@ -53,6 +53,10 @@ class CommonParams(BaseModel):
     format: str | None = Field(default=None)
     in_charset: str | None = Field(default=None, alias="inCharset")
     out_charset: str | None = Field(default=None, alias="outCharset")
+    # [Web] 通知开关
+    notice: int | None = Field(default=None)
+    # [Web] 新设备码开关
+    need_new_code: int | None = Field(default=None)
 
 
 class Credential(BaseModel):
@@ -95,7 +99,7 @@ class Credential(BaseModel):
         if not isinstance(data, dict):
             return data
 
-        if data.get("loginType") or data.get("login_type"):
+        if "loginType" in data or "login_type" in data:
             return data
 
         musickey = data.get("musickey", "")

{qqmusic_api_python-0.5.1 → qqmusic_api_python-0.5.3}/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")