qqmusic-api-python 0.8.1__tar.gz → 0.8.2__tar.gz

{qqmusic_api_python-0.8.1 → qqmusic_api_python-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qqmusic-api-python
-Version: 0.8.1
+Version: 0.8.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.8.1 → qqmusic_api_python-0.8.2}/docs/release-notes.md

@@ -1,4 +1,30 @@
 
+## [[0.8.1](https://github.com/L-1124/QQMusicApi/compare/v0.8.0..v0.8.1)] - 2026-10-04
+
+### Bug 修复
+
+* **(core)** 为传输层增加默认请求超时 ([86a2716](https://github.com/L-1124/QQMusicApi/commit/86a2716eddde166edcacfe511d4b9f2090f6a2bd)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 手机验证码路由改为 POST 提交 ([b714255](https://github.com/L-1124/QQMusicApi/commit/b714255b2a9dbef535e709659fd029b49856bbf6)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 参数校验失败响应返回错误详情 ([dee7e18](https://github.com/L-1124/QQMusicApi/commit/dee7e187c26a45b973759f56c7445da635e04740)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(core)** 新增 Credential.is_valid 并收编登录态判断 ([415b3ae](https://github.com/L-1124/QQMusicApi/commit/415b3aef6e3f3b7fc5092653f22c1ce0d5dc31d5)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 补充 py.typed 类型标记 ([2136321](https://github.com/L-1124/QQMusicApi/commit/2136321cf19796e0738f6b91243a650dd99f76a2)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(web)** 复用 Credential.is_valid 移除重复登录态判断 ([f8ec18d](https://github.com/L-1124/QQMusicApi/commit/f8ec18dcf9a559988ff141972b704861a3a5ef5e)) by [@L-1124](https://github.com/L-1124)
+
+### 文档更新
+
+* 修正刷新凭证示例与 Web 服务启动说明 ([83e743b](https://github.com/L-1124/QQMusicApi/commit/83e743b52219471ddb399e21d6a003273f2c0bd2)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
 ## [[0.8.0](https://github.com/L-1124/QQMusicApi/compare/v0.7.3..v0.8.0)] - 2026-10-04
 
 ### Bug 修复

{qqmusic_api_python-0.8.1 → qqmusic_api_python-0.8.2}/pyproject.toml

@@ -86,7 +86,6 @@ web = [
   "fastapi>=0.136.1",
   "griffe>=2.0.2",
   "pydantic-settings[toml]>=2.14.0",
-  "loguru>=0.7.3",
   "uvicorn>=0.46.0",
 ]
 

{qqmusic_api_python-0.8.1 → qqmusic_api_python-0.8.2}/qqmusic_api/__init__.py

@@ -23,7 +23,7 @@ from .core.exceptions import (
 from .core.versioning import Platform
 from .models.request import Credential
 
-__version__ = "0.8.1"
+__version__ = "0.8.2"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.8.1 → qqmusic_api_python-0.8.2}/qqmusic_api/models/singer.py

@@ -234,6 +234,74 @@ class VideoBrief(MV):
     icon_type: int = 0
 
 
+class TabFilterItem(Response):
+    """Tab 筛选条目 (专辑类型 / 视频标签).
+
+    Attributes:
+        id: 筛选项 ID.
+        title: 筛选项名称.
+    """
+
+    id: int = Field(default=-1, validation_alias=AliasChoices("ID", "id"))
+    title: str = Field(default="", validation_alias=AliasChoices("Title", "name"))
+
+
+class TabFilterList(Response):
+    """服务端下发的 Tab 筛选列表.
+
+    Attributes:
+        default_id: 默认选中项 ID.
+        items: 筛选项列表.
+    """
+
+    default_id: int = Field(default=0, validation_alias="DefaultID")
+    items: Annotated[list[TabFilterItem], NoneToEmptyList] = Field(default_factory=list, validation_alias="ItemList")
+
+
+class SongTabInfo(Response):
+    """歌曲 Tab 内容.
+
+    Attributes:
+        songs: 歌曲列表.
+        tag_info_list: 歌曲标签信息列表 (客户端原样透传).
+    """
+
+    songs: Annotated[list[Song], NoneToEmptyList] = Field(
+        default_factory=list, json_schema_extra={"jsonpath": "$.List[*]"}
+    )
+    tag_info_list: Annotated[list[dict[str, Any]], NoneToEmptyList] = Field(
+        default_factory=list, validation_alias="SongTagInfoList"
+    )
+
+
+class AlbumTabInfo(Response):
+    """专辑 Tab 内容.
+
+    Attributes:
+        type_list: 服务端下发的专辑分类筛选列表.
+        albums: 专辑列表.
+    """
+
+    type_list: TabFilterList = Field(default_factory=TabFilterList, validation_alias="TypeList")
+    albums: Annotated[list[AlbumBrief], NoneToEmptyList] = Field(
+        default_factory=list, json_schema_extra={"jsonpath": "$.AlbumList[*]"}
+    )
+
+
+class VideoTabInfo(Response):
+    """视频 Tab 内容.
+
+    Attributes:
+        videos: 视频列表.
+        tag_list: 服务端下发的视频标签筛选列表.
+    """
+
+    videos: Annotated[list[VideoBrief], NoneToEmptyList] = Field(
+        default_factory=list, json_schema_extra={"jsonpath": "$.VideoList[*]"}
+    )
+    tag_list: Annotated[list[TabFilterItem], NoneToEmptyList] = Field(default_factory=list, validation_alias="TagList")
+
+
 class HomepageTabDetailResponse(Response):
     """歌手主页标签详情响应.
 
@@ -241,12 +309,12 @@ class HomepageTabDetailResponse(Response):
         tab_id: 当前标签页 ID.
         has_more: 是否还有更多结果.
         need_show_tab: 是否需要展示标签.
-        order: 排序值.
+        order: 服务端归一化后的排序值.
         tab_list: 标签页元信息列表.
-        introduction_tab: 简介标签内容.
-        song_tab: 歌曲标签内容.
-        album_tab: 专辑标签内容.
-        video_tab: 视频标签内容.
+        song_tab: 歌曲 Tab 内容.
+        album_tab: 专辑 Tab 内容.
+        video_tab: 视频 Tab 内容.
+        introduction_tab: 简介 Tab 内容.
     """
 
     tab_id: str = Field(default="", validation_alias="TabID")
@@ -254,19 +322,13 @@ class HomepageTabDetailResponse(Response):
     need_show_tab: int = Field(default=0, validation_alias="NeedShowTab")
     order: int = Field(default=0, validation_alias="Order")
     tab_list: Annotated[list[TabMeta], NoneToEmptyList] = Field(default_factory=list, validation_alias="TabList")
+    song_tab: SongTabInfo = Field(default_factory=SongTabInfo, validation_alias="SongTab")
+    album_tab: AlbumTabInfo = Field(default_factory=AlbumTabInfo, validation_alias="AlbumTab")
+    video_tab: VideoTabInfo = Field(default_factory=VideoTabInfo, validation_alias="VideoTab")
     introduction_tab: Annotated[list[dict[str, Any]], NoneToEmptyList] = Field(
         default_factory=list,
         json_schema_extra={"jsonpath": "$.IntroductionTab.List"},
     )
-    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):

{qqmusic_api_python-0.8.1 → qqmusic_api_python-0.8.2}/qqmusic_api/modules/singer.py

@@ -1,9 +1,9 @@
 """歌手相关 API."""
 
 from enum import Enum, IntEnum
-from typing import cast
+from typing import Any, Literal, TypedDict, cast, overload
 
-from ..core import Platform
+from ..core import PaginatedCgiRequest, Platform
 from ..core.endpoint import CgiRequestData, cgi_endpoint
 from ..core.pagination import (
     MultiFieldContinuationStrategy,
@@ -91,6 +91,17 @@ class TabType(Enum):
         self.tab_name = tab_name
 
 
+class OrderType(IntEnum):
+    """歌手主页条目排序类型.
+
+    + LATEST: 最新 / 按时间排序 (0)
+    + HOT: 最热 / 按热度排序 (1)
+    """
+
+    LATEST = 0
+    HOT = 1
+
+
 class IndexType(IntEnum):
     """首字母索引枚举."""
 
@@ -124,6 +135,30 @@ class IndexType(IntEnum):
     HASH = 27
 
 
+class AlbumExtension(TypedDict):
+    """专辑 Tab 扩展参数.
+
+    Attributes:
+        IsNeedFilterType: 是否下发分类筛选列表.
+        FilterType: 分类筛选值.
+    """
+
+    IsNeedFilterType: int
+    FilterType: int
+
+
+class VideoExtension(TypedDict):
+    """视频 Tab 扩展参数.
+
+    Attributes:
+        TagID: 视频标签筛选值.
+        IsNeedTagList: 是否下发标签列表.
+    """
+
+    TagID: int
+    IsNeedTagList: int
+
+
 class SingerApi(ApiModule):
     """歌手相关 API."""
 
@@ -224,6 +259,38 @@ class SingerApi(ApiModule):
             param={"SingerMid": mid},
         )
 
+    @overload
+    def get_tab_detail(
+        self,
+        mid: str,
+        tab_type: Literal[TabType.VIDEO],
+        page: int = 1,
+        num: int = 10,
+        order: OrderType | int = OrderType.LATEST,
+        extension: VideoExtension | None = None,
+    ) -> PaginatedCgiRequest[HomepageTabDetailResponse]: ...
+
+    @overload
+    def get_tab_detail(
+        self,
+        mid: str,
+        tab_type: Literal[TabType.ALBUM],
+        page: int = 1,
+        num: int = 10,
+        order: OrderType | int = OrderType.LATEST,
+        extension: AlbumExtension | None = None,
+    ) -> PaginatedCgiRequest[HomepageTabDetailResponse]: ...
+
+    @overload
+    def get_tab_detail(
+        self,
+        mid: str,
+        tab_type: TabType,
+        page: int = 1,
+        num: int = 10,
+        order: OrderType | int = OrderType.LATEST,
+    ) -> PaginatedCgiRequest[HomepageTabDetailResponse]: ...
+
     @cgi_endpoint(
         key="singer.get_tab_detail",
         module="music.UnifiedHomepage.UnifiedHomepageSrv",
@@ -237,6 +304,8 @@ class SingerApi(ApiModule):
         tab_type: TabType,
         page: int = 1,
         num: int = 10,
+        order: OrderType | int = OrderType.LATEST,
+        extension: VideoExtension | AlbumExtension | None = None,
     ) -> CgiRequestData:
         """获取歌手主页特定 Tab 的详情原始数据.
 
@@ -245,16 +314,21 @@ class SingerApi(ApiModule):
             tab_type: Tab 类型.
             page: 页码.
             num: 返回数量.
+            order: 排序方式 (最新 / 最热).
+            extension: Tab 请求扩展参数.
         """
+        param: dict[str, Any] = {
+            "SingerMid": mid,
+            "IsQueryTabDetail": 1,
+            "TabID": tab_type.tab_id,
+            "PageNum": page - 1,
+            "PageSize": num,
+            "Order": int(order),
+        }
+        if extension:
+            param[tab_type.value[1].replace("Tab", "") + "Extension"] = extension
         return CgiRequestData(
-            param={
-                "SingerMid": mid,
-                "IsQueryTabDetail": 1,
-                "TabID": tab_type.tab_id,
-                "PageNum": page - 1,
-                "PageSize": num,
-                "Order": 0,
-            },
+            param=param,
             pager_strategy=PageStrategy[HomepageTabDetailResponse](
                 page_key="PageNum",
                 page_size=num,
@@ -324,16 +398,23 @@ class SingerApi(ApiModule):
         response_model=SingerSongListResponse,
         item_type=Song,
     )
-    def get_songs_list(self, mid: str, num: int = 10, page: int = 1) -> CgiRequestData:
+    def get_songs_list(
+        self,
+        mid: str,
+        num: int = 10,
+        page: int = 1,
+        order: OrderType | int = OrderType.HOT,
+    ) -> CgiRequestData:
         """获取歌手的歌曲列表.
 
         Args:
             mid: 歌手 MID.
             num: 返回歌曲数量.
             page: 分页页码.
+            order: 排序方式.
         """
         return CgiRequestData(
-            param={"singerMid": mid, "order": 1, "number": num, "begin": (page - 1) * num},
+            param={"singerMid": mid, "order": int(order), "number": num, "begin": (page - 1) * num},
             pager_strategy=OffsetStrategy[SingerSongListResponse](
                 offset_key="begin",
                 page_size_key="number",
@@ -350,16 +431,23 @@ class SingerApi(ApiModule):
         response_model=SingerAlbumListResponse,
         item_type=AlbumBrief,
     )
-    def get_album_list(self, mid: str, num: int = 10, page: int = 1) -> CgiRequestData:
+    def get_album_list(
+        self,
+        mid: str,
+        num: int = 10,
+        page: int = 1,
+        order: OrderType | int = OrderType.HOT,
+    ) -> CgiRequestData:
         """获取歌手的专辑列表.
 
         Args:
             mid: 歌手 MID.
             num: 返回专辑数量.
             page: 分页页码.
+            order: 排序方式.
         """
         return CgiRequestData(
-            param={"singerMid": mid, "order": 1, "number": num, "begin": (page - 1) * num},
+            param={"singerMid": mid, "order": int(order), "number": num, "begin": (page - 1) * num},
             pager_strategy=OffsetStrategy[SingerAlbumListResponse](
                 offset_key="begin",
                 page_size_key="number",
@@ -376,16 +464,23 @@ class SingerApi(ApiModule):
         response_model=SingerMvListResponse,
         item_type=VideoBrief,
     )
-    def get_mv_list(self, mid: str, num: int = 10, page: int = 1) -> CgiRequestData:
+    def get_mv_list(
+        self,
+        mid: str,
+        num: int = 10,
+        page: int = 1,
+        order: OrderType | int = OrderType.HOT,
+    ) -> CgiRequestData:
         """获取歌手 MV 列表数据.
 
         Args:
             mid: 歌手 MID.
             num: 返回数量.
             page: 分页页码.
+            order: 排序方式.
         """
         return CgiRequestData(
-            param={"singermid": mid, "order": 1, "count": num, "start": (page - 1) * num},
+            param={"singermid": mid, "order": order, "count": num, "start": (page - 1) * num},
             pager_strategy=OffsetStrategy[SingerMvListResponse](
                 offset_key="start",
                 page_size_key="count",

{qqmusic_api_python-0.8.1 → qqmusic_api_python-0.8.2}/tests/test_singer.py

@@ -82,8 +82,20 @@ async def test_get_tab_detail_song(client: Client) -> None:
         page=1,
         num=10,
     )
-    assert result.song_tab is not None
-    assert result.song_tab
+    assert result.song_tab.songs
+
+
+async def test_get_tab_detail_song_with_order(client: Client) -> None:
+    """测试使用排序参数获取歌手歌曲 Tab 模型."""
+    result = await client.singer.get_tab_detail(
+        mid="0025NhlN2yWrP4",
+        tab_type=TabType.SONG,
+        page=1,
+        num=5,
+        order=1,
+    )
+    assert result.song_tab.songs
+    assert result.order == 1
 
 
 async def test_get_tab_detail_album(client: Client) -> None:
@@ -94,8 +106,21 @@ async def test_get_tab_detail_album(client: Client) -> None:
         page=1,
         num=10,
     )
-    assert result.album_tab is not None
-    assert result.album_tab
+    assert result.album_tab.albums
+    assert result.album_tab.type_list.default_id == 0
+
+
+async def test_get_tab_detail_album_with_filter(client: Client) -> None:
+    """测试携带分类筛选参数获取歌手专辑 Tab, 服务端返回筛选列表."""
+    result = await client.singer.get_tab_detail(
+        mid="000GGDys0yA0Nk",
+        tab_type=TabType.ALBUM,
+        page=1,
+        num=5,
+        extension={"IsNeedFilterType": 1, "FilterType": 2},
+    )
+    assert result.album_tab.type_list.items
+    assert {item.id for item in result.album_tab.type_list.items} == {0, 1, 2, 3, 4}
 
 
 async def test_get_tab_detail_video(client: Client) -> None:
@@ -106,8 +131,19 @@ async def test_get_tab_detail_video(client: Client) -> None:
         page=1,
         num=10,
     )
-    assert result.video_tab is not None
-    assert result.video_tab
+    assert result.video_tab.videos
+
+
+async def test_get_tab_detail_video_with_tag(client: Client) -> None:
+    """测试携带标签参数获取歌手视频 Tab, 服务端返回标签列表."""
+    result = await client.singer.get_tab_detail(
+        mid="000GGDys0yA0Nk",
+        tab_type=TabType.VIDEO,
+        page=1,
+        num=5,
+        extension={"TagID": 0, "IsNeedTagList": 1},
+    )
+    assert result.video_tab.tag_list
 
 
 async def test_get_desc(client: Client) -> None:
@@ -149,6 +185,7 @@ async def test_get_songs_list_with_params(client: Client) -> None:
         mid="0025NhlN2yWrP4",
         num=10,
         page=2,
+        order=1,
     )
     assert result.song_list
     assert len(result.song_list) <= result.total_num
@@ -167,6 +204,7 @@ async def test_get_album_list_with_params(client: Client) -> None:
         mid="0025NhlN2yWrP4",
         num=10,
         page=2,
+        order=1,
     )
     assert result.album_list
 

{qqmusic_api_python-0.8.1 → qqmusic_api_python-0.8.2}/tests/typing/test_client_typing.py

@@ -35,7 +35,7 @@ from qqmusic_api.models.songlist import GetSonglistDetailResponse
 from qqmusic_api.models.top import TopDetailResponse
 from qqmusic_api.models.user import DislikeListData, RelationUser, UserRelationListResponse
 from qqmusic_api.modules.search import SearchType
-from qqmusic_api.modules.singer import TabType
+from qqmusic_api.modules.singer import OrderType, TabType
 from qqmusic_api.modules.song import SongFileInfo
 
 pytestmark = pytest.mark.core
@@ -105,11 +105,15 @@ def test_client_facade_pure_paginated_types():
     tab_req = client.singer.get_tab_detail("001BLpXF2DyJe2", TabType.SONG)
     assert_type(tab_req, PaginatedCgiRequest[HomepageTabDetailResponse])
 
+    tab_song_req = client.singer.get_tab_detail("001BLpXF2DyJe2", TabType.SONG, order=OrderType.HOT)
+    assert_type(tab_song_req, PaginatedCgiRequest[HomepageTabDetailResponse])
+
+    tab_album_req = client.singer.get_tab_detail("001BLpXF2DyJe2", TabType.ALBUM, order=OrderType.LATEST)
+    assert_type(tab_album_req, PaginatedCgiRequest[HomepageTabDetailResponse])
     tab_annotated: PaginatedCgiRequest[HomepageTabDetailResponse] = client.singer.get_tab_detail(
-        "001BLpXF2DyJe2", TabType.SONG
+        "001BLpXF2DyJe2", TabType.SONG, order=0
     )
     assert_type(tab_annotated, PaginatedCgiRequest[HomepageTabDetailResponse])
-
     general_req = client.search.general_search("周杰伦")
     assert_type(general_req, PaginatedCgiRequest[GeneralSearchResponse])