qqmusic-api-python 0.7.2__tar.gz → 0.7.3__tar.gz

{qqmusic_api_python-0.7.2 → qqmusic_api_python-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: qqmusic-api-python
-Version: 0.7.2
+Version: 0.7.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.7.2 → qqmusic_api_python-0.7.3}/docs/release-notes.md

@@ -1,4 +1,28 @@
 
+## [[0.7.2](https://github.com/L-1124/QQMusicApi/compare/v0.7.1..v0.7.2)] - 2026-08-05
+
+### Bug 修复
+
+* **(routing)** 修复 add_api_route tags 参数类型不匹配 ([ee98436](https://github.com/L-1124/QQMusicApi/commit/ee984368c19bca4d164475c272b49fa136566e9e)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(search)** 为 quick_search/complete/get_hotkey 添加响应模型 ([b97549f](https://github.com/L-1124/QQMusicApi/commit/b97549fea31f3de9ce68904df932a6c4d73aff45)) by [@L-1124](https://github.com/L-1124)
+* **(singer)** 支持 get_desc 接口详细数据控制参数 ([8a8c7f1](https://github.com/L-1124/QQMusicApi/commit/8a8c7f14262e5b08dc46073e84e43fc43508f392)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(core)** [**breaking**] 统一请求调度引擎 ([8b71333](https://github.com/L-1124/QQMusicApi/commit/8b71333835891f851a70354c313c614f558ff8e0)) by [@L-1124](https://github.com/L-1124) in [#301](https://github.com/L-1124/QQMusicApi/pull/301)
+
+### 文档更新
+
+* 更新 lyric.py 中的错误 docstring ([8ec78ce](https://github.com/L-1124/QQMusicApi/commit/8ec78ce3f16805ebe470b8308a96fef925cf8e56)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
 ## [[0.7.1](https://github.com/L-1124/QQMusicApi/compare/v0.7.0..v0.7.1)] - 2026-08-02
 
 ### Bug 修复

qqmusic_api_python-0.7.3/examples/singer_name_special_display.py

@@ -0,0 +1,22 @@
+"""获取歌手名称透明 PNG, 演示有图片和无特殊展示两种结果."""
+
+import asyncio
+
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    """请求真实歌手名称展示信息并输出 JSON."""
+    async with Client() as client:
+        for mid in ("000qrPik2w6lDr", "0025NhlN2yWrP4"):
+            result = await client.singer.get_name_special_display(mid)
+            print(f"\nMID: {mid}")
+            print(result.model_dump_json(indent=2))
+            if result.display_type == 2 and result.pic_file:
+                print(f"PNG: {result.pic_file}")
+            else:
+                print(f"无名称图片, 使用文字: {result.name}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{qqmusic_api_python-0.7.2 → qqmusic_api_python-0.7.3}/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.2"
+__version__ = "0.7.3"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.7.2 → qqmusic_api_python-0.7.3}/qqmusic_api/models/singer.py

@@ -248,6 +248,31 @@ class HomepageTabDetailResponse(Response):
     )
 
 
+class SingerNameSpecialDisplayResponse(Response):
+    """歌手名称特殊展示信息.
+
+    Attributes:
+        display_type: 展示类型, 2 表示名称图片, 0 表示无特殊展示.
+        pic_file: 透明 PNG 地址, 无名称图片时为空字符串.
+        signature_name_overlap_ratio: 上游返回的签名与名称重叠比例.
+        name: 歌手名称.
+    """
+
+    display_type: int = Field(
+        default=0,
+        json_schema_extra={"jsonpath": "$.Info.Singer.SingerNameSpecialDisplay.DisplayType"},
+    )
+    pic_file: str = Field(
+        default="",
+        json_schema_extra={"jsonpath": "$.Info.Singer.SingerNameSpecialDisplay.PicFile"},
+    )
+    signature_name_overlap_ratio: float = Field(
+        default=0.0,
+        json_schema_extra={"jsonpath": "$.Info.Singer.SingerNameSpecialDisplay.SignatureNameOverlapRatio"},
+    )
+    name: str = Field(default="", json_schema_extra={"jsonpath": "$.Info.Singer.Name"})
+
+
 class HomepageHeaderResponse(Response):
     """歌手主页头部响应.
 

{qqmusic_api_python-0.7.2 → qqmusic_api_python-0.7.3}/qqmusic_api/modules/singer.py

@@ -17,6 +17,7 @@ from ..models.singer import (
     SingerDetailResponse,
     SingerIndexPageResponse,
     SingerMvListResponse,
+    SingerNameSpecialDisplayResponse,
     SingerSongListResponse,
     SingerTypeListResponse,
 )
@@ -208,6 +209,24 @@ class SingerApi(ApiModule):
             platform=Platform.ANDROID,
         )
 
+    def get_name_special_display(self, mid: str):
+        """获取歌手名称透明 PNG 展示信息.
+
+        返回歌手名称、展示类型、图片地址和重叠比例.
+        无名称图片时, 返回 display_type=0 和空 pic_file.
+
+        Args:
+            mid: 歌手 MID.
+        """
+        return self._build_cgi(
+            module="music.UnifiedHomepage.UnifiedHomepageSrv",
+            method="GetHomepageHeader",
+            param={"SingerMid": mid},
+            response_model=SingerNameSpecialDisplayResponse,
+            platform=Platform.ANDROID,
+            comm={"cv": 20_080_000, "v": 20_080_000},
+        )
+
     def get_tab_detail(
         self,
         mid: str,

{qqmusic_api_python-0.7.2 → qqmusic_api_python-0.7.3}/qqmusic_api/modules/song.py

@@ -283,8 +283,11 @@ class SongApi(ApiModule):
             credential: 凭据对象.
 
         Raises:
-            ValueError: 当 `mid` 数量超过上限时抛出.
+            ValueError: 当 `mid` 数量超过上限时抛出. 超限时上游返回错误且无结果, 故提前拒绝.
         """
+        if len(file_info) > self._GET_SONG_URLS_MAX_MID:
+            raise ValueError(f"mid 数量不能超过 {self._GET_SONG_URLS_MAX_MID}, 当前为 {len(file_info)}")
+
         encrypted = isinstance(file_type, EncryptedSongFileType)
         module, method = (
             ("music.vkey.GetVkey", "UrlGetVkey") if not encrypted else ("music.vkey.GetEVkey", "CgiGetEVkey")

{qqmusic_api_python-0.7.2 → qqmusic_api_python-0.7.3}/tests/test_singer.py

@@ -1,5 +1,9 @@
 """歌手模块测试."""
 
+from urllib.parse import urlparse
+
+import pytest
+
 from qqmusic_api import Client
 from qqmusic_api.modules.singer import AreaType, GenreType, IndexType, SexType, TabType
 
@@ -51,6 +55,26 @@ async def test_get_info(client: Client) -> None:
     assert result.base_info.name
 
 
+@pytest.mark.parametrize(
+    ("mid", "name", "display_type"),
+    [("000qrPik2w6lDr", "Taylor Swift", 2), ("0025NhlN2yWrP4", "周杰伦", 0)],
+)
+async def test_get_name_special_display(client: Client, mid: str, name: str, display_type: int) -> None:
+    """测试真实歌手名称图片与无特殊展示的返回结果."""
+    result = await client.singer.get_name_special_display(mid)
+
+    assert result.name == name
+    assert result.display_type == display_type
+    assert isinstance(result.signature_name_overlap_ratio, float)
+    if display_type == 2:
+        url = urlparse(result.pic_file)
+        assert url.scheme == "https"
+        assert url.netloc
+        assert url.path.endswith(".png")
+    else:
+        assert result.pic_file == ""
+
+
 async def test_get_tab_detail_wiki(client: Client) -> None:
     """测试获取歌手 Wiki Tab 详情模型."""
     result = await client.singer.get_tab_detail(

{qqmusic_api_python-0.7.2 → qqmusic_api_python-0.7.3}/tests/test_song.py

@@ -52,6 +52,13 @@ async def test_get_song_urls(client: Client, file_type: SongFileType | Encrypted
     assert len(result.data) == 1
 
 
+def test_get_song_urls_exceed_limit(client: Client) -> None:
+    """测试获取歌曲链接超出 mid 数量上限时抛出异常."""
+    oversized = [SongFileInfo(mid="003w2xz20QlUZt")] * (client.song._GET_SONG_URLS_MAX_MID + 1)
+    with pytest.raises(ValueError, match="mid 数量不能超过"):
+        client.song.get_song_urls(oversized)
+
+
 @pytest.mark.parametrize("value", [100, "003w2xz20QlUZt"])
 async def test_get_detail(client: Client, value: int | str) -> None:
     """测试获取歌曲详情."""

{qqmusic_api_python-0.7.2 → qqmusic_api_python-0.7.3}/web/requirements.txt

@@ -906,19 +906,19 @@ pymdown-extensions==11.0.1 \
     # via
     #   mkdocstrings
     #   zensical
-pyrefly==1.1.1 \
-    --hash=sha256:2150b450ee6a6bcbe69b2d45d9a4ebc934a609e1abcf65e490433f38eb873d84 \
-    --hash=sha256:4e0430f3ef69c8ac73505fd6584db70ed504665a9f0816fef7f723de510f26cb \
-    --hash=sha256:5ffd8a8ed62fe4e6bf0afe1837d1bad149bb3b9f80e928ef248c96b836db3742 \
-    --hash=sha256:6deda959f8603a7dbdf112c48983e2275b2903cf33c8c739ed65d7e71a4fd520 \
-    --hash=sha256:83baf0db71e172665db1fca0ced50b8f7773f5192ca57e8ac6773a772b6d2fc5 \
-    --hash=sha256:a6342d87c52b04f72156da04f554c4d57f3616f2b32d1763969efb22d05a1407 \
-    --hash=sha256:b50d4510e4f8aaea79e2c4b343a4d7a060c9451c0b2aa9bfe10d7ca1ef33d68d \
-    --hash=sha256:c08b814ad03175e9cf47111390537161828b472044c39ab3320252b3ac6b2edd \
-    --hash=sha256:d50cad97f19fc893b04deff7239626cffff5dd27ffb29b7d303a1b770247b208 \
-    --hash=sha256:d6b238e1362622d47a6eb5af704fd8b613c94e8c303386efd6350e3da59fecc8 \
-    --hash=sha256:f330cf039ef3da3b910c84f3a7e431f0cf8d0c1d2dad26491d6cadf3c7cd4759 \
-    --hash=sha256:f4b8595f91885bc8b5e3c282ab68d1df21201668a84e6508b1e15f2feec0bb8d
+pyrefly==1.2.0 \
+    --hash=sha256:25822ea9505f589ea8a725e4268b475132fb89e038fbf092e446510443ac142a \
+    --hash=sha256:368aaf7eee4f511ddc0f8e564cf14e01ab2f10b0db9105c6d5b153bf498d07bf \
+    --hash=sha256:3a90bb8df39dfbac74b1f3b2e9d7c526b8f80568884c3944d955023a73ebf61e \
+    --hash=sha256:5485f960fc2481617068c918335c39ab1507ef90b6b5bd35bf57726e60e73185 \
+    --hash=sha256:5de7b2ad2bba5c8055181681a84b74143eac2234a48ba5d1b7ed7e7a722b02bd \
+    --hash=sha256:756f669b5555090f5c1a4fef30db1785fabe657764f7e4e6dc88994dfb8ca82d \
+    --hash=sha256:7f46d983ac49ddd2b043694960a01dc6a19a5cfd8eec609d6bd9c42866f91b4e \
+    --hash=sha256:8a8964c224ccc4882730130955815de21ff443c1ac3f0b90685b19bf63848170 \
+    --hash=sha256:8c90751de8506d938e8f802659c74cf35bd7a0036510ee6c634a38eebb280bfa \
+    --hash=sha256:90efe75e17491ef5d636e10469e9278d7d0256b3b4c5e1f4750069bf3ae0f5d1 \
+    --hash=sha256:d52d5da7bc65fb7675fbaa80eda879d4f8787c494f04cac21603330d3abbdbbe \
+    --hash=sha256:e3465812ce5ef4781fb592edbf2724547296f0a3124be115d73c7e8b2401862d
 pytest==9.1.1 \
     --hash=sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313 \
     --hash=sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c
@@ -1095,25 +1095,25 @@ requests==2.34.2 \
     --hash=sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0 \
     --hash=sha256:f288924cae4e29463698d6d60bc6a4da69c89185ad1e0bcc4104f584e960b9ed
     # via cos-python-sdk-v5
-ruff==0.16.0 \
-    --hash=sha256:0ff4a79ce3ec0172f3241943835de1c4cb4e2dcd07f0f8c2d02603dbbbee4b17 \
-    --hash=sha256:14296fedcd2705c77ab8235439278bbb38f285cf7da5528b00b3e330c3d4872d \
-    --hash=sha256:28ea2b7df8ebf7f9da6b7d47b230ab48f387c0a29be3b474c4d0740e197bb9af \
-    --hash=sha256:33a3dfac8c35f81498dea9181bccc2f4c4bc8f1521a1dd9406e77643e0f0fb09 \
-    --hash=sha256:3c954b1d580bfa035b41654f7858cc7e71d5fc3ac5b723dd62bd9133830ed522 \
-    --hash=sha256:429c117f022bf481fabd9d551e7a3952b24c65e6ef44337ea09d90bebef14472 \
-    --hash=sha256:48044c678e9cb8698246c99b14aaccfa6601dea7379eb48a6f8f73f7a6d86cd0 \
-    --hash=sha256:4f11a8d11010301d0a398a2fdef67691feca7294da6aef55e2150e8fa2cd520b \
-    --hash=sha256:6e364e5ed22ed8dc05082fd78e35308618260907ac2d3c1d637b2e682415b6c9 \
-    --hash=sha256:7aa0959bad8eb8bef50340154fc9b58678dae31fa4293afa38b44b6e552c0213 \
-    --hash=sha256:7fab76fa065c873f41ff744347c6e77bcc3dfec4bcc754dc26b63d23c0f7f5fb \
-    --hash=sha256:a5237a0bda500d30d81b8e07a6973a5cbc772864cbf746ae2f4e8a2e01c9f4ed \
-    --hash=sha256:a9b50c55e263103586b3dcf5f73d479eb8cb5fdb6098fec59a62891dab653717 \
-    --hash=sha256:d327b8fc113a1d4421a04f3839d3752057c8dd1ee320223a6f3f52d04ada462a \
-    --hash=sha256:e01c21d10eb1b29f47b7454e1f4056db9a3f0260c646aa88457c610291db9f81 \
-    --hash=sha256:e460aafd5495ec89efaa6ced2e4a9a581116451e1c88b9d37ef497e0f8e93982 \
-    --hash=sha256:e5115729eb08c585e5121978ba5d5b60caeae394ce21b9fb5e6cd33a1c6c9b1e \
-    --hash=sha256:e95c448fca1fb2a18372a9440926c5a6ee789639bb975c72e7ae6d0b04218ab4
+ruff==0.16.1 \
+    --hash=sha256:07bf434b1c95f4e093be4532068ef4fcf00924eb2ade8796075980902d6fd54a \
+    --hash=sha256:09b05e8b90c2cb06ad63464350e7a45e8e44a2dfe52072ebfba6666ca8d3f596 \
+    --hash=sha256:24e9c631573cbca9d20f1283f8f479b2afa4a8503504822bd71a293889f16743 \
+    --hash=sha256:26e9ca5c9bc3971f20d3cf18a957f52ffd6a5f6564ff15c4912a144dcac22494 \
+    --hash=sha256:30affbcedf59ad5703d9c91f82266e02b47739f797e1a7b6e158e5526a6dae38 \
+    --hash=sha256:39897739f112253ee4fdd2e8aa9a4f9ded99fb2be367d5f31dfa4ded6025584c \
+    --hash=sha256:4d5f2ed10f8242d83fc08d521301089364e3375375705356f20c0e31606ef3ef \
+    --hash=sha256:58edb313b88f0c5460a26adf5f39a37a3be789494a15e3e411e35fa78b89f9a0 \
+    --hash=sha256:67e1e1e3fa4f0c82f0e36d4cd61e661f6e7a6196cb1aa92fe0828fa7b8f257cd \
+    --hash=sha256:82ae3c0c0d74daf17b968a10b7b3bb3ef297ab7de0c1f749646b25e690ccb150 \
+    --hash=sha256:a4665b309891f83f3e3c25447935f1213e9abbd4b5640af7a1f2def9f8d413c1 \
+    --hash=sha256:b0d1e1393b7648079e13669de1c1f4fde06d4583e84d8fd5c1551e0a77a2aa75 \
+    --hash=sha256:b41bdd48fb420987a9b5212e4957c26ad4abce401fa9ea9d4d85843727945f4f \
+    --hash=sha256:d31765e131295b8445caf301e3e8a85b34d1b9b211b4109b7ba457888b051806 \
+    --hash=sha256:dbaadaac38c70239f056d306b7476f246b0bf000fa6b3876402acbf5b227eaf8 \
+    --hash=sha256:e0d4c20532fca4f7fa609369161d968dd28f65d83dabbd61d8e9c7edbf7001f6 \
+    --hash=sha256:fde5a99e2f97479af66edd6622c6d5a2a7592c77cf4153d9e4428f5eeb55b60c \
+    --hash=sha256:fedad7c801dabd3fb9741d76aca39246e6ddd9ca446a015875207bf19f1e6bc7
 six==1.17.0 \
     --hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274 \
     --hash=sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81

{qqmusic_api_python-0.7.2 → qqmusic_api_python-0.7.3}/web/src/routes/singer.py

@@ -8,6 +8,7 @@ from qqmusic_api.models.singer import (
     SingerDetailResponse,
     SingerIndexPageResponse,
     SingerMvListResponse,
+    SingerNameSpecialDisplayResponse,
     SingerSongListResponse,
     SingerTypeListResponse,
 )
@@ -53,6 +54,14 @@ ROUTES: tuple[WebRoute, ...] = (
         cache=PUBLIC_300,
     ),
     R("singer", "get_info", "/singer/{mid}/info", HomepageHeaderResponse, params=MID, cache=PUBLIC_300),
+    R(
+        "singer",
+        "get_name_special_display",
+        "/singer/{mid}/name-special-display",
+        SingerNameSpecialDisplayResponse,
+        params=MID,
+        cache=PUBLIC_600,
+    ),
     R(
         "singer",
         "get_mv_list",