qqmusic-api-python 0.6.2__tar.gz → 0.6.3__tar.gz

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.6.2
+Version: 0.6.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.6.2 → qqmusic_api_python-0.6.3}/docs/release-notes.md

@@ -1,4 +1,29 @@
 
+## [[0.6.2](https://github.com/L-1124/QQMusicApi/compare/v0.6.1..v0.6.2)] - 2026-06-08
+
+### Bug 修复
+
+* **(core)** 将 niquests 网络异常转换为`NetworkError`抛出" ([ff659c5](https://github.com/L-1124/QQMusicApi/commit/ff659c57dae8ad73db74cb00c5ba092b28f36466)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 修复 ANDROID 会话初始化的循环依赖和缓存失效问题 ([4f9be43](https://github.com/L-1124/QQMusicApi/commit/4f9be437724497a789265ede40368628858aea47)) by [@L-1124](https://github.com/L-1124)
+* **(recommend)** 更新获取猜你喜欢推荐接口，支持传入 Credential, 添加 uid 字段到版本策略 ([81062d0](https://github.com/L-1124/QQMusicApi/commit/81062d0091883abb6904562a4ce5223c295d2b24)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(core)** 添加 getSession 匿名会话初始化和设备 OpenUDID 持久化 ([9a4532e](https://github.com/L-1124/QQMusicApi/commit/9a4532e922d3805ba60bc31b213efddbc4c18702)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 补充评论增删路由及推荐认证支持 ([08c9137](https://github.com/L-1124/QQMusicApi/commit/08c9137cb8adcc4ce29c0843f25b4a160819839b)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(web)** 重构日志系统 ([20fe8c6](https://github.com/L-1124/QQMusicApi/commit/20fe8c62af0477c5bf1e4afd82f08dcd96881031)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 统一代码风格与日志惰性求值 ([4ba0bf0](https://github.com/L-1124/QQMusicApi/commit/4ba0bf06b0e3a88bda6efea699c60ec068b16e91)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 补齐路由辅助函数与应用入口类型注解 ([080b2fe](https://github.com/L-1124/QQMusicApi/commit/080b2fe99969f7256005c5a2f23793cacfd6db85)) by [@L-1124](https://github.com/L-1124)
+* **(web/routing)** 补齐路由类型与参数校验器类型注解 ([bcedc66](https://github.com/L-1124/QQMusicApi/commit/bcedc66bbb34d768957b36493250e067c4714e74)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
 ## [[0.6.1](https://github.com/L-1124/QQMusicApi/compare/v0.6.0..v0.6.1)] - 2026-05-20
 
 ### Bug 修复

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/qqmusic_api/__init__.py

@@ -18,7 +18,7 @@ from .core.exceptions import (
 from .core.versioning import Platform
 from .models.request import Credential
 
-__version__ = "0.6.2"
+__version__ = "0.6.3"
 
 __all__ = [
     "ApiDataError",

qqmusic_api_python-0.6.3/qqmusic_api/models/_validator.py

@@ -0,0 +1,30 @@
+"""Pydantic Validator."""
+
+from typing import Any
+
+from pydantic import BeforeValidator
+
+
+def _none_to_empty_list(value: list[Any] | None) -> list[Any]:
+    """将 ``None`` 规整为空列表."""
+    return [] if value is None else value
+
+
+def _none_to_empty_dict(value: dict[str, Any] | None) -> dict[str, Any]:
+    """将 ``None`` 规整为空字典."""
+    return {} if value is None else value
+
+
+def _none_or_zero_to_empty_str(value: str | int | None) -> str:
+    """将 ``None`` 或 ``0`` 规整为空字符串."""
+    return "" if value in (None, 0) else str(value)
+
+
+#: 将 ``None`` 规整为空列表的 BeforeValidator.
+NoneToEmptyList = BeforeValidator(_none_to_empty_list)
+
+#: 将 ``None`` 规整为空字典的 BeforeValidator.
+NoneToEmptyDict = BeforeValidator(_none_to_empty_dict)
+
+#: 将 ``None`` 或 ``0`` 规整为空字符串的 BeforeValidator.
+NoneOrZeroToEmptyStr = BeforeValidator(_none_or_zero_to_empty_str)

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/qqmusic_api/models/album.py

@@ -1,6 +1,6 @@
 """Album API 返回模型定义."""
 
-from pydantic import Field, field_validator
+from pydantic import Field
 
 from .base import Album, Singer, Song
 from .request import Response
@@ -70,9 +70,3 @@ 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.6.2 → qqmusic_api_python-0.6.3}/qqmusic_api/models/private_message.py

@@ -1,9 +1,10 @@
 """私信模块返回模型定义."""
 
-from typing import Any
+from typing import Annotated, Any
 
-from pydantic import Field, field_validator, model_validator
+from pydantic import Field, model_validator
 
+from ._validator import NoneToEmptyDict
 from .request import Response
 
 
@@ -208,19 +209,13 @@ class PrivateMessageListResponse(Response):
     session: PrivateMessageSession | None = None
     subcode: int = 0
     end_msg_seq: int = 0
-    attach: dict[str, Any] = Field(default_factory=dict, alias="Attach")
+    attach: Annotated[dict[str, Any], NoneToEmptyDict] = Field(default_factory=dict, alias="Attach")
     pat_interval: int = Field(default=0, alias="PatInterval")
-    pat_map: dict[str, PrivateMessagePatText] = Field(default_factory=dict, alias="PatMap")
+    pat_map: Annotated[dict[str, PrivateMessagePatText], NoneToEmptyDict] = Field(default_factory=dict, alias="PatMap")
     encrypt_star: str = Field(default="", alias="EncryptStar")
     location_tips: str = Field(default="", alias="LocationTips")
     new_msg_cnt: int = Field(default=0, alias="NewMsgCnt")
 
-    @field_validator("attach", "pat_map", mode="before")
-    @classmethod
-    def _normalize_nullable_fields(cls, value: Any) -> Any:
-        """将服务端返回的空映射归一为空字典."""
-        return {} if value is None else value
-
 
 class PrivateSendMessageResponse(Response):
     """私信发送响应.

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/qqmusic_api/models/request.py

@@ -179,9 +179,14 @@ class Response(BaseModel):
                 matches = jsonpath_expr.find(data)
 
                 if matches:
-                    if len(matches) == 1:
-                        processed_data[target_key] = matches[0].value
+                    values = [match.value for match in matches]
+                    if "[*]" in jsonpath_expr_str:
+                        # 通配符路径表示提取条目列表, 即使仅命中一条也保持列表,
+                        # 兼容上游在仅有一条数据时直接返回对象而非数组的行为.
+                        processed_data[target_key] = values
+                    elif len(values) == 1:
+                        processed_data[target_key] = values[0]
                     else:
-                        processed_data[target_key] = [match.value for match in matches]
+                        processed_data[target_key] = values
 
         return processed_data

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/qqmusic_api/models/singer.py

@@ -1,9 +1,10 @@
 """Singer API 返回模型定义."""
 
-from typing import Any
+from typing import Annotated, Any
 
-from pydantic import AliasChoices, Field, field_validator
+from pydantic import AliasChoices, Field
 
+from ._validator import NoneOrZeroToEmptyStr, NoneToEmptyList
 from .base import MV, Album, Singer, Song
 from .request import Response
 
@@ -62,16 +63,10 @@ class SingerTagData(Response):
         index: 索引标签列表.
     """
 
-    @field_validator("area", "genre", "sex", "index", mode="before")
-    @classmethod
-    def _coerce_none_list(cls, value: list[TagOption] | None) -> list[TagOption]:
-        """将缺失的标签列表规整为空列表."""
-        return [] if value is None else value
-
-    area: list[TagOption] = Field(default_factory=list)
-    genre: list[TagOption] = Field(default_factory=list)
-    sex: list[TagOption] = Field(default_factory=list)
-    index: list[TagOption] = Field(default_factory=list)
+    area: Annotated[list[TagOption], NoneToEmptyList] = Field(default_factory=list)
+    genre: Annotated[list[TagOption], NoneToEmptyList] = Field(default_factory=list)
+    sex: Annotated[list[TagOption], NoneToEmptyList] = Field(default_factory=list)
+    index: Annotated[list[TagOption], NoneToEmptyList] = Field(default_factory=list)
 
 
 class SingerTypeListResponse(Response):
@@ -179,12 +174,6 @@ class AlbumBrief(Album):
         tags: 标签列表.
     """
 
-    @field_validator("tags", mode="before")
-    @classmethod
-    def _coerce_tags(cls, value: list[str] | None) -> list[str]:
-        """将专辑标签中的空值规整为空列表."""
-        return [] if value is None else value
-
     id: int = Field(default=-1, alias="albumID")
     mid: str = Field(default="", alias="albumMid")
     name: str = Field(default="", alias="albumName")
@@ -193,7 +182,7 @@ class AlbumBrief(Album):
     total_num: int = Field(default=0, alias="totalNum")
     album_type: str = Field(default="", alias="albumType")
     singer_name: str = Field(default="", alias="singerName")
-    tags: list[str] = Field(default_factory=list)
+    tags: Annotated[list[str], NoneToEmptyList] = Field(default_factory=list)
 
 
 class VideoBrief(MV):
@@ -239,24 +228,24 @@ class HomepageTabDetailResponse(Response):
         video_tab: 视频标签内容.
     """
 
-    @field_validator("tab_list", "introduction_tab", "song_tab", "album_tab", "video_tab", mode="before")
-    @classmethod
-    def _coerce_tab_lists(cls, value: list[Any] | None) -> list[Any]:
-        """将标签详情中的空列表占位规整为列表."""
-        return [] if value is None else value
-
     tab_id: str = Field(default="", alias="TabID")
     has_more: int = Field(default=0, alias="HasMore")
     need_show_tab: int = Field(default=0, alias="NeedShowTab")
     order: int = Field(default=0, alias="Order")
-    tab_list: list[TabMeta] = Field(default_factory=list, alias="TabList")
-    introduction_tab: list[dict[str, Any]] = Field(
+    tab_list: Annotated[list[TabMeta], NoneToEmptyList] = Field(default_factory=list, alias="TabList")
+    introduction_tab: Annotated[list[dict[str, Any]], NoneToEmptyList] = Field(
         default_factory=list,
         json_schema_extra={"jsonpath": "$.IntroductionTab.List"},
     )
-    song_tab: list[Song] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.SongTab.List[*]"})
-    album_tab: list[AlbumBrief] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.AlbumTab.AlbumList[*]"})
-    video_tab: list[VideoBrief] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.VideoTab.VideoList[*]"})
+    song_tab: Annotated[list[Song], NoneToEmptyList] = Field(
+        default_factory=list, json_schema_extra={"jsonpath": "$.SongTab.List[*]"}
+    )
+    album_tab: Annotated[list[AlbumBrief], NoneToEmptyList] = Field(
+        default_factory=list, json_schema_extra={"jsonpath": "$.AlbumTab.AlbumList[*]"}
+    )
+    video_tab: Annotated[list[VideoBrief], NoneToEmptyList] = Field(
+        default_factory=list, json_schema_extra={"jsonpath": "$.VideoTab.VideoList[*]"}
+    )
 
 
 class HomepageHeaderResponse(Response):
@@ -315,21 +304,15 @@ class SingerExtraInfo(Response):
         blog_flag: 博客标记.
     """
 
-    @field_validator("area", "identity", "instrument", "genre", "enter", mode="before")
-    @classmethod
-    def _coerce_optional_text(cls, value: str | int | None) -> str:
-        """将上游返回的 0 或空值规整为空字符串."""
-        return "" if value in (None, 0) else str(value)
-
-    area: str = ""
+    area: Annotated[str, NoneOrZeroToEmptyStr] = ""
     desc: str = ""
     tag: str = ""
-    identity: str = ""
-    instrument: str = ""
-    genre: str = ""
+    identity: Annotated[str, NoneOrZeroToEmptyStr] = ""
+    instrument: Annotated[str, NoneOrZeroToEmptyStr] = ""
+    genre: Annotated[str, NoneOrZeroToEmptyStr] = ""
     foreign_name: str = ""
     birthday: str = ""
-    enter: str = ""
+    enter: Annotated[str, NoneOrZeroToEmptyStr] = ""
     blog_flag: int = Field(default=0, alias="blogFlag")
 
 
@@ -345,18 +328,12 @@ class SingerDetail(Response):
         group_info: 组合附加信息.
     """
 
-    @field_validator("group_list", "photos", "group_info", mode="before")
-    @classmethod
-    def _coerce_detail_lists(cls, value: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
-        """将歌手详情中的空列表占位规整为列表."""
-        return [] if value is None else value
-
     basic_info: SingerBasicInfo = Field(alias="basic_info")
     ex_info: SingerExtraInfo = Field(default_factory=SingerExtraInfo, alias="ex_info")
     wiki: str = ""
-    group_list: list[dict[str, Any]] = Field(default_factory=list)
-    photos: list[dict[str, Any]] = Field(default_factory=list)
-    group_info: list[dict[str, Any]] = Field(default_factory=list)
+    group_list: Annotated[list[dict[str, Any]], NoneToEmptyList] = Field(default_factory=list)
+    photos: Annotated[list[dict[str, Any]], NoneToEmptyList] = Field(default_factory=list)
+    group_info: Annotated[list[dict[str, Any]], NoneToEmptyList] = Field(default_factory=list)
 
 
 class SingerDetailResponse(Response):
@@ -402,13 +379,7 @@ class SimilarSingerResponse(Response):
         err_msg: 错误消息.
     """
 
-    @field_validator("singerlist", mode="before")
-    @classmethod
-    def _coerce_similar_list(cls, value: list[SimilarSinger] | None) -> list[SimilarSinger]:
-        """将相似歌手列表中的空值规整为空列表."""
-        return [] if value is None else value
-
-    singerlist: list[SimilarSinger] = Field(default_factory=list)
+    singerlist: Annotated[list[SimilarSinger], NoneToEmptyList] = Field(default_factory=list)
     code: int = 0
     err_msg: str = Field(default="", alias="errMsg")
 
@@ -422,15 +393,11 @@ class SingerSongListResponse(Response):
         song_list: 当前页歌曲列表.
     """
 
-    @field_validator("song_list", mode="before")
-    @classmethod
-    def _coerce_song_list(cls, value: list[Song] | None) -> list[Song]:
-        """将歌曲列表中的空值规整为空列表."""
-        return [] if value is None else value
-
     singer_mid: str = Field(default="", alias="singerMid")
     total_num: int = Field(default=0, alias="totalNum")
-    song_list: list[Song] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.songList[*].songInfo"})
+    song_list: Annotated[list[Song], NoneToEmptyList] = Field(
+        default_factory=list, json_schema_extra={"jsonpath": "$.songList[*].songInfo"}
+    )
 
 
 class SingerAlbumListResponse(Response):
@@ -442,15 +409,9 @@ class SingerAlbumListResponse(Response):
         album_list: 当前页专辑列表.
     """
 
-    @field_validator("album_list", mode="before")
-    @classmethod
-    def _coerce_album_list(cls, value: list[AlbumBrief] | None) -> list[AlbumBrief]:
-        """将专辑列表中的空值规整为空列表."""
-        return [] if value is None else value
-
     singer_mid: str = Field(default="", alias="singerMid")
     total: int = 0
-    album_list: list[AlbumBrief] = Field(default_factory=list, alias="albumList")
+    album_list: Annotated[list[AlbumBrief], NoneToEmptyList] = Field(default_factory=list, alias="albumList")
 
 
 class SingerMvListResponse(Response):
@@ -461,11 +422,5 @@ class SingerMvListResponse(Response):
         mv_list: 当前页 MV 列表.
     """
 
-    @field_validator("mv_list", mode="before")
-    @classmethod
-    def _coerce_mv_list(cls, value: list[VideoBrief] | None) -> list[VideoBrief]:
-        """将 MV 列表中的空值规整为空列表."""
-        return [] if value is None else value
-
     total: int = 0
-    mv_list: list[VideoBrief] = Field(default_factory=list, alias="list")
+    mv_list: Annotated[list[VideoBrief], NoneToEmptyList] = Field(default_factory=list, alias="list")

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/qqmusic_api/models/top.py

@@ -1,7 +1,10 @@
 """Top API 返回模型定义."""
 
-from pydantic import Field, field_validator
+from typing import Annotated
 
+from pydantic import Field
+
+from ._validator import NoneToEmptyList
 from .base import Song
 from .request import Response
 
@@ -105,14 +108,8 @@ class TopDetailResponse(Response):
         index_info_list: 榜单索引信息列表.
     """
 
-    @field_validator("song_tags", "ext_info_list", "index_info_list", mode="before")
-    @classmethod
-    def _coerce_none_list(cls, value: list[dict] | None) -> list[dict]:
-        """将上游返回的空列表占位统一规整为列表."""
-        return [] if value is None else value
-
     info: TopSummary = Field(alias="data")
     songs: list[Song] = Field(alias="songInfoList")
-    song_tags: list[dict] = Field(default_factory=list, alias="songTagInfoList")
-    ext_info_list: list[dict] = Field(default_factory=list, alias="extInfoList")
-    index_info_list: list[dict] = Field(default_factory=list, alias="indexInfoList")
+    song_tags: Annotated[list[dict], NoneToEmptyList] = Field(default_factory=list, alias="songTagInfoList")
+    ext_info_list: Annotated[list[dict], NoneToEmptyList] = Field(default_factory=list, alias="extInfoList")
+    index_info_list: Annotated[list[dict], NoneToEmptyList] = Field(default_factory=list, alias="indexInfoList")

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/qqmusic_api/models/user.py

@@ -1,8 +1,8 @@
 """User API 返回模型定义."""
 
-from typing import Any, cast
+from typing import Any
 
-from pydantic import AliasChoices, Field, field_validator
+from pydantic import AliasChoices, Field
 
 from .base import MV, Album, Singer, SongList
 from .request import Response
@@ -253,6 +253,64 @@ class UserHomepageResponse(Response):
     tab_detail: dict[str, Any] = Field(alias="TabDetail")
 
 
+class VipIdentity(Response):
+    """VIP 信息响应中的会员身份明细块.
+
+    Attributes:
+        vip: 绿钻会员标志.
+        huge_vip: 豪华绿钻会员标志.
+        huge_vip_start: 豪华绿钻生效时间.
+        huge_vip_end: 豪华绿钻到期时间.
+        year_flag: 年费会员标志.
+        huge_year_flag: 豪华年费会员标志.
+        twelve: 十二平台会员标志.
+        twelve_start: 十二平台会员生效时间.
+        twelve_end: 十二平台会员到期时间.
+        child_vip: 儿童会员标志.
+        exp_vip: 体验会员标志.
+        group_vip_flag: 家庭组会员标志.
+        group_vip_start: 家庭组会员生效时间.
+        group_vip_end: 家庭组会员到期时间.
+        cp_lover_flag: 情侣会员标志.
+        cp_lover_start: 情侣会员生效时间.
+        cp_lover_end: 情侣会员到期时间.
+        ad_vip_flag: 广告会员标志.
+        eight: 八平台会员标志.
+        eight_start: 八平台会员生效时间.
+        eight_end: 八平台会员到期时间.
+        level: 会员等级.
+        next_level: 下一会员等级.
+        icon: 官方等级徽章图地址.
+        purchase_url: 会员购买页地址.
+    """
+
+    vip: int = 0
+    huge_vip: int = Field(default=0, alias="HugeVip")
+    huge_vip_start: str = Field(default="", alias="HugeVipStart")
+    huge_vip_end: str = Field(default="", alias="HugeVipEnd")
+    year_flag: int = Field(default=0, alias="yearflag")
+    huge_year_flag: int = Field(default=0, alias="HugeYearFlag")
+    twelve: int = 0
+    twelve_start: str = Field(default="", alias="twelveStart")
+    twelve_end: str = Field(default="", alias="twelveEnd")
+    child_vip: int = Field(default=0, alias="ChildVip")
+    exp_vip: int = Field(default=0, alias="ExpVip")
+    group_vip_flag: int = Field(default=0, alias="GroupVipFlag")
+    group_vip_start: str = Field(default="", alias="GroupVipStart")
+    group_vip_end: str = Field(default="", alias="GroupVipEnd")
+    cp_lover_flag: int = Field(default=0, alias="CPLoverFlag")
+    cp_lover_start: str = Field(default="", alias="CPLoverStart")
+    cp_lover_end: str = Field(default="", alias="CPLoverEnd")
+    ad_vip_flag: int = Field(default=0, alias="AdVipFlag")
+    eight: int = 0
+    eight_start: str = Field(default="", alias="eightStart")
+    eight_end: str = Field(default="", alias="eightEnd")
+    level: int = 0
+    next_level: int = Field(default=0, alias="nextlevel")
+    icon: str = ""
+    purchase_url: str = Field(default="", alias="purchaseUrl")
+
+
 class VipUserInfo(Response):
     """VIP 信息响应中的用户权益摘要块.
 
@@ -280,14 +338,30 @@ class UserVipInfoResponse(Response):
         max_dir_num: 最大歌单数量.
         max_song_num: 最大歌曲数量.
         song_limit_msg: 歌曲上限提示文案.
+        svip: 超级会员标志.
+        star: 星级会员标志.
+        star_start: 星级会员生效时间.
+        star_end: 星级会员到期时间.
+        ystar: 年费星级会员标志.
+        ystar_start: 年费星级会员生效时间.
+        ystar_end: 年费星级会员到期时间.
+        identity: 会员身份明细.
         userinfo: 用户权益摘要.
     """
 
-    auto_down: int = Field(default=0, alias="autoDown")
+    auto_down: int = Field(default=0, validation_alias=AliasChoices("auto_down", "autoDown", "autodown"))
     can_renew: int = Field(default=0, alias="canRenew")
-    max_dir_num: int = Field(default=0, alias="maxDirNum")
-    max_song_num: int = Field(default=0, alias="maxSongNum")
-    song_limit_msg: str = Field(default="", alias="songLimitMsg")
+    max_dir_num: int = Field(default=0, validation_alias=AliasChoices("max_dir_num", "maxDirNum", "maxdirnum"))
+    max_song_num: int = Field(default=0, validation_alias=AliasChoices("max_song_num", "maxSongNum", "maxsongnum"))
+    song_limit_msg: str = Field(default="", validation_alias=AliasChoices("song_limit_msg", "songLimitMsg"))
+    svip: int = 0
+    star: int = 0
+    star_start: str = Field(default="", alias="starstart")
+    star_end: str = Field(default="", alias="starend")
+    ystar: int = 0
+    ystar_start: str = Field(default="", alias="ystarstart")
+    ystar_end: str = Field(default="", alias="ystarend")
+    identity: VipIdentity = Field(default_factory=VipIdentity)
     userinfo: VipUserInfo = Field(default_factory=VipUserInfo)
 
 
@@ -326,19 +400,6 @@ class UserRelationListResponse(Response):
         lock_msg: 锁定提示文案.
     """
 
-    @field_validator("users", mode="before")
-    @classmethod
-    def _coerce_users(
-        cls,
-        value: RelationUser | dict[str, Any] | list[RelationUser] | list[dict[str, Any]] | None,
-    ) -> list[RelationUser | dict[str, Any]]:
-        """将单条关系用户结果规整为列表."""
-        if value is None:
-            return []
-        if isinstance(value, list):
-            return cast("list[RelationUser | dict[str, Any]]", value)
-        return [value]
-
     total: int = Field(default=0, alias="Total")
     users: list[RelationUser] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.List[*]"})
     has_more: bool = Field(default=False, alias="HasMore")
@@ -413,6 +474,6 @@ class UserFavMvResponse(Response):
     """
 
     code: int
-    sub_code: int = Field(alias="subCode")
+    sub_code: int = Field(validation_alias=AliasChoices("subCode", "subcode"))
     msg: str
     mv_list: list[UserFavMvItem] = Field(alias="mvlist")

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/tests/conftest.py

@@ -62,6 +62,20 @@ async def _retry_rate_limited_call(operation: Callable[[], Awaitable[Any]]) -> A
     raise RuntimeError("限流重试流程异常结束")
 
 
+async def _call_with_skip(coro_fn: Callable[[], Awaitable[Any]]) -> Any:
+    """执行 API 调用, 将环境不可用异常转为 pytest.skip."""
+    try:
+        return await _retry_rate_limited_call(coro_fn)
+    except (CredentialInvalidError, CredentialExpiredError) as exc:
+        pytest.skip(str(exc))
+    except RatelimitedError as exc:
+        pytest.skip(f"{exc}。指数退避重试 {len(RATE_LIMIT_RETRY_DELAYS)} 次后仍触发限流")
+    except Exception as exc:
+        if _is_network_timeout_error(exc):
+            pytest.skip(str(exc))
+        raise
+
+
 @pytest.fixture(autouse=True)
 def handle_unavailable_api_errors(monkeypatch: pytest.MonkeyPatch):
     """为测试 API 调用添加限流重试, 并将环境不可用异常转为跳过."""
@@ -69,7 +83,7 @@ def handle_unavailable_api_errors(monkeypatch: pytest.MonkeyPatch):
     original_gather = Client.gather
 
     async def execute_with_rate_limit_retry(client: Client, request: Any) -> Any:
-        return await _retry_rate_limited_call(lambda: original_execute(client, request))
+        return await _call_with_skip(lambda: original_execute(client, request))
 
     async def gather_with_rate_limit_retry(
         client: Client,
@@ -78,7 +92,7 @@ def handle_unavailable_api_errors(monkeypatch: pytest.MonkeyPatch):
         batch_size: int = 20,
         return_exceptions: bool = False,
     ) -> list[Any]:
-        return await _retry_rate_limited_call(
+        return await _call_with_skip(
             lambda: original_gather(
                 client,
                 requests,
@@ -90,16 +104,7 @@ def handle_unavailable_api_errors(monkeypatch: pytest.MonkeyPatch):
     monkeypatch.setattr(Client, "execute", execute_with_rate_limit_retry)
     monkeypatch.setattr(Client, "gather", gather_with_rate_limit_retry)
 
-    try:
-        yield
-    except (CredentialInvalidError, CredentialExpiredError) as exc:
-        pytest.skip(str(exc))
-    except RatelimitedError as exc:
-        pytest.skip(f"{exc}。指数退避重试 {len(RATE_LIMIT_RETRY_DELAYS)} 次后仍触发限流")
-    except Exception as exc:
-        if _is_network_timeout_error(exc):
-            pytest.skip(str(exc))
-        raise
+    return
 
 
 @pytest_asyncio.fixture

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/tests/test_album.py

@@ -16,14 +16,14 @@ async def test_get_detail_by_id(client: Client) -> None:
 
 
 @pytest.mark.parametrize(
-    ("num", "page"),
+    ("mid", "num", "page"),
     [
-        (30, 1),
-        (5, 1),
-        (10, 2),
+        ("001uKKpF1RuJSd", 30, 1),
+        ("001gR6jO1L4MWq", 5, 1),
+        ("0041WVfh2vtlJE", 10, 2),
     ],
 )
-async def test_get_song(client: Client, num: int, page: int) -> None:
+async def test_get_song(client: Client, mid: str, num: int, page: int) -> None:
     """测试获取专辑歌曲列表."""
-    result = await client.album.get_song(100, num=num, page=page)
+    result = await client.album.get_song(mid, num=num, page=page)
     assert result is not None

{qqmusic_api_python-0.6.2 → qqmusic_api_python-0.6.3}/tests/test_user.py

@@ -1,6 +1,9 @@
 """用户模块测试."""
 
+import pytest
+
 from qqmusic_api import Client
+from qqmusic_api.models.user import UserFavMvResponse
 
 
 async def test_get_homepage(client: Client) -> None:
@@ -36,9 +39,18 @@ async def test_relation_response_models_with_login(authenticated_client: Client)
 async def test_get_vip_info_with_login(authenticated_client: Client) -> None:
     """测试获取 VIP 信息模型."""
     result = await authenticated_client.user.get_vip_info()
-    assert result.max_dir_num >= 0
-    assert result.max_song_num >= 0
+    assert result.max_dir_num > 0
+    assert result.max_song_num > 0
     assert result.userinfo.music_level >= 0
+    assert result.svip >= 0
+    assert result.star >= 0
+    assert result.ystar >= 0
+    assert result.identity.vip >= 0
+    assert result.identity.huge_vip >= 0
+    assert result.identity.year_flag >= 0
+    assert result.identity.huge_year_flag >= 0
+    assert result.identity.eight >= 0
+    assert result.identity.level >= 0
 
 
 async def test_get_created_songlist_with_login(authenticated_client: Client) -> None:
@@ -101,3 +113,10 @@ async def test_get_fav_mv_with_login(authenticated_client: Client) -> None:
     assert result.code == 0
     assert result.sub_code == 0
     assert result.mv_list is not None
+
+
+@pytest.mark.parametrize("sub_code_key", ["subCode", "subcode"])
+def test_fav_mv_response_accepts_subcode_spellings(sub_code_key: str) -> None:
+    """测试收藏 MV 响应兼容子返回码键名的两种大小写拼写."""
+    result = UserFavMvResponse.model_validate({"code": 0, sub_code_key: 0, "msg": "", "mvlist": []})
+    assert result.sub_code == 0