qqmusic-api-python 0.6.8__tar.gz → 0.7.0__tar.gz

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/.dockerignore

@@ -22,5 +22,3 @@ dist
 .prek_cache
 *.toml
 !pyproject.toml
-!web/config.toml
-!web/accounts.toml

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.6.8
+Version: 0.7.0
 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.8 → qqmusic_api_python-0.7.0}/docs/coding.md

@@ -388,7 +388,7 @@ from qqmusic_api import Client
 
 async def test_query_song(client: Client) -> None:
     """测试根据 ID 查询歌曲."""
-    result = await client.song.query_song(["003w2xz20QlUZt"])
+    result = await client.song.query_song([SongQueryInfo(mid="003w2xz20QlUZt")])
     assert result.tracks
     assert result.tracks[0].name
 ```

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/docs/release-notes.md

@@ -1,4 +1,81 @@
 
+## [[0.6.9](https://github.com/L-1124/QQMusicApi/compare/v0.6.8..v0.6.9)] - 2026-07-12
+
+### Bug 修复
+
+* **(web)** 修复凭据刷新异常捕获过宽与 ETag 缓存机制形同虚设的问题 ([305a063](https://github.com/L-1124/QQMusicApi/commit/305a0637f6261b3de3710c504dc8b22ec0ec52b8)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复配置账号由于重置逻辑缺陷被永久标记失效与流式响应并发槽位泄露 ([56f3034](https://github.com/L-1124/QQMusicApi/commit/56f30347a5182380e14febb1b6b1a80debc74ea3)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 避免将 credential 对象盲目混入参数导致 SDK 签名报错 ([fc8b32c](https://github.com/L-1124/QQMusicApi/commit/fc8b32ca1d8d20f16c52f37272798b3688f2848b)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复 KeyedLock finalizer 泄漏与 Redis 序列化 Pydantic 模型问题 ([5440a5e](https://github.com/L-1124/QQMusicApi/commit/5440a5e83b1d110d29f4e1b2eab74f5a8f509847)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修正 songlist 创建与删除路由的 HTTP 方法 ([43c9ce6](https://github.com/L-1124/QQMusicApi/commit/43c9ce6fd0779895afe70a5c7062d7ead0d69957)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复凭据刷新锁与限流器的内存泄漏 ([c5ed6a3](https://github.com/L-1124/QQMusicApi/commit/c5ed6a315e7de680b60b63199350fca276781a46)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复 search 路由声明中 Any 导致的类型检查错误 ([d1aea06](https://github.com/L-1124/QQMusicApi/commit/d1aea0631aeee866cc8b09d1d6a086b07f24e7a9)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复返回 bool 类型时生成的文档和数据格式问题 ([af8550d](https://github.com/L-1124/QQMusicApi/commit/af8550d08038dc8f66be39e28c9d3a905abf7e63)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(web)** 添加 UserApi 的DisLike和favor api ([b1aa67d](https://github.com/L-1124/QQMusicApi/commit/b1aa67d5e6608d722b337c53274b4d91963a008d)) by [@L-1124](https://github.com/L-1124)
+* 新增新碟上架 / MV 分类 / 收藏专辑 / 收藏歌曲接口与推荐新歌地区筛选 ([520c92b](https://github.com/L-1124/QQMusicApi/commit/520c92bd4d3546a20358c0a6daf47f67af8813d8)) by [@jinzhongjia](https://github.com/jinzhongjia) in [#284](https://github.com/L-1124/QQMusicApi/pull/284)
+
+### 功能重构
+
+* **(web)** 收敛配置修改与硬编码路径到配置层 ([0e5950c](https://github.com/L-1124/QQMusicApi/commit/0e5950c9fec28783f081c7d37754de130dcd1950)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 抽取统一的 refresh_and_store 方法消除重复，并补全重试刷新失败时的无效标记逻辑 ([a4a0729](https://github.com/L-1124/QQMusicApi/commit/a4a072984f2dce212885bc240640c9a859d9b0ed)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 移除 songlist 的动态 getattr 分发以恢复类型安全与修复潜在凭据 KeyError ([c1030e1](https://github.com/L-1124/QQMusicApi/commit/c1030e1d867eed8e42957dbf797f548a754796e5)) by [@L-1124](https://github.com/L-1124)
+
+### 性能优化
+
+* **(web)** 启用 SQLite WAL 模式并延迟反序列化随机凭据 ([7d01994](https://github.com/L-1124/QQMusicApi/commit/7d019942ae3812fe286d90eb668dc52318ccabe7)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 缓存路由参数解析以避免重复的 SDK 签名内省 ([61cc5a5](https://github.com/L-1124/QQMusicApi/commit/61cc5a5494afb750149d6689e252cb429e9d109d)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 抽取 app 为会话级 fixture 以大幅降低测试耗时 ([6d13b50](https://github.com/L-1124/QQMusicApi/commit/6d13b50ad42c1bf8f56c596a2fd810cadc23208d)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 移除缓存层与响应中不必要的双重序列化 ([bbc865c](https://github.com/L-1124/QQMusicApi/commit/bbc865c8aa52da6a027064510e94c8fcf8d5ab76)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @jinzhongjia [#284](https://github.com/L-1124/QQMusicApi/pull/284)
+* @github-actions[bot]
+
+## [[0.6.8](https://github.com/L-1124/QQMusicApi/compare/v0.6.7..v0.6.8)] - 2026-07-01
+
+### Bug 修复
+
+* **(web)** 禁用 FastAPI 默认按别名响应，使 JSON 输出与 Python 原生变量名保持一致 ([32459a5](https://github.com/L-1124/QQMusicApi/commit/32459a54c03d8a0a738f1917f9eb19fc6f9ac4ef)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(core)** 新增 SignatureRequiredError 错误码 2000 处理 ([a73313a](https://github.com/L-1124/QQMusicApi/commit/a73313a91549a156358ad9311d0e20d7401b861b)) by [@L-1124](https://github.com/L-1124)
+* **(core)** _ensure_session 添加 24h 保活机制 ([2290a32](https://github.com/L-1124/QQMusicApi/commit/2290a32304bcd9052365f60c67f2d4f6b00e4d7e)) by [@L-1124](https://github.com/L-1124)
+* **(helper)** 新增辅助功能接口 ([eb0c40c](https://github.com/L-1124/QQMusicApi/commit/eb0c40c1461826955a1eb005afb723438730142a)) by [@L-1124](https://github.com/L-1124)
+* **(login)** 支持登出API ([73f2a7e](https://github.com/L-1124/QQMusicApi/commit/73f2a7ee9ad1d48cbec2d6aa9dbf844f44b573c2)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** [**breaking**] 彻底移除 crypt 字段，隐式处理加密状态 ([80edc40](https://github.com/L-1124/QQMusicApi/commit/80edc40e41331f6b5c11146d5daf6eccf344181f)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** [**breaking**] 移除 decrypt 方法，改为默认解密 ([24949c4](https://github.com/L-1124/QQMusicApi/commit/24949c4df8c63b02b35dd69c30e2a8f40d234dfb)) by [@L-1124](https://github.com/L-1124)
+* **(song)** 添加特殊歌曲文件类型 TRY_OGG_640 ([fef7e8c](https://github.com/L-1124/QQMusicApi/commit/fef7e8ceb220aa477ea7d8498f8ebfd240f72cc6)) by [@L-1124](https://github.com/L-1124)
+* **(user)** 新增收藏/取消收藏歌单 API ([7865434](https://github.com/L-1124/QQMusicApi/commit/7865434782dd205815222fe716f52bac9f84aeec)) by [@jinzhongjia](https://github.com/jinzhongjia) in [#281](https://github.com/L-1124/QQMusicApi/pull/281)
+* **(user)** 新增 FeedbackBlack 黑名单 API ([4340554](https://github.com/L-1124/QQMusicApi/commit/4340554aaaafaef175eead7ebced596538bc65e2)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 启用 FastAPI 内置 Swagger UI 和 ReDoc，更新文档地址说明 ([a3245ad](https://github.com/L-1124/QQMusicApi/commit/a3245ad3d3863c7f7eec94352d169a32ba4478c6)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 重构 Dockerfile 为多阶段构建，修复非 root 用户 uv 缓存权限问题 ([00e16a3](https://github.com/L-1124/QQMusicApi/commit/00e16a37b62e989de37232e8af7e77167a28e823)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(core)** 移除 _session_cache 冗余缓存，简化会话验证逻辑 ([0b12b9d](https://github.com/L-1124/QQMusicApi/commit/0b12b9d041a8be24ad84d60bd2ceaed76b81fe92)) by [@L-1124](https://github.com/L-1124)
+* **(models)** [**breaking**] 将所有模型中的 alias 统一替换为 validation_alias，隔离序列化字段名 ([c611b91](https://github.com/L-1124/QQMusicApi/commit/c611b91d607d36327662a80d0e126a6958b21bd5)) by [@L-1124](https://github.com/L-1124)
+* **(modules)** 移除冗余的 _require_login 调用，统一使用 require_login 参数 ([1a666f4](https://github.com/L-1124/QQMusicApi/commit/1a666f45ae968c235066c07e8b3e82096c3fc668)) by [@L-1124](https://github.com/L-1124)
+* **(modules)** 将 _require_login 收敛到 _build_request 的 require_login 参数中 ([d1a92ca](https://github.com/L-1124/QQMusicApi/commit/d1a92ca07d5a98f3f443453e5fc77b8f8c8dc44e)) by [@L-1124](https://github.com/L-1124)
+
+### 文档更新
+
+* **(coding)** 更新需登录接口的编码规范，使用 require_login 参数替代 _require_login ([9e56215](https://github.com/L-1124/QQMusicApi/commit/9e562152ec8039b3045ae6c51006401c93b36a36)) by [@L-1124](https://github.com/L-1124)
+* **(dislike)** 更新不喜欢列表项和响应数据的文档说明 ([5dbf711](https://github.com/L-1124/QQMusicApi/commit/5dbf711e46a69f99940f048504446b9e074fd21f)) by [@L-1124](https://github.com/L-1124)
+* **(login)** 更新二维码和手机验证码登录状态的文档注释 ([f31d4d0](https://github.com/L-1124/QQMusicApi/commit/f31d4d0132cb61a9935ebea92657fcfa6591926c)) by [@L-1124](https://github.com/L-1124)
+* **(readme)** 添加 DeepWiki 相关链接 ([fcea758](https://github.com/L-1124/QQMusicApi/commit/fcea758b80a824cb513a8bdfc8b247da786f5a1e)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @jinzhongjia [#281](https://github.com/L-1124/QQMusicApi/pull/281)
+* @github-actions[bot]
+
 ## [[0.6.7](https://github.com/L-1124/QQMusicApi/compare/v0.6.6..v0.6.7)] - 2026-06-17
 
 ### 功能更新

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/docs/tutorial/download.md

@@ -34,7 +34,7 @@ asyncio.run(main())
 通过 `query_song` 获取歌曲信息后，可从 `pay` 字段判断是否需要付费：
 
 ```python
-song = await client.song.query_song(["003w2xz20QlUZt"])
+song = await client.song.query_song([SongQueryInfo(mid="003w2xz20QlUZt")])
 track = song.tracks[0]
 
 # pay_play: 1=需要付费播放, 0=免费
@@ -72,7 +72,7 @@ for info in urls.data:
 `query_song` 返回的 `file` 字段包含各音质的文件大小，值为 `0` 表示该音质不存在：
 
 ```python
-song = await client.song.query_song(["003w2xz20QlUZt"])
+song = await client.song.query_song([SongQueryInfo(mid="003w2xz20QlUZt")])
 track = song.tracks[0]
 
 file = track.file

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/__init__.py

@@ -22,7 +22,7 @@ from .core.exceptions import (
 from .core.versioning import Platform
 from .models.request import Credential
 
-__version__ = "0.6.8"
+__version__ = "0.7.0"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/core/client.py

@@ -7,12 +7,11 @@ from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
 import anyio
 import orjson as json
-from niquests import AsyncSession, AsyncTokenBucketLimiter, PreparedRequest
+from niquests import AsyncSession, AsyncTokenBucketLimiter, PreparedRequest, RetryConfiguration
 from niquests.exceptions import RequestException
 from niquests.models import Response
 from niquests.typing import AsyncHookType, ProxyType, TLSClientCertType, TLSVerifyType
 from tarsio import TarsDict
-from urllib3.util.retry import Retry
 
 from ..algorithms import zzc_sign
 from ..models.request import Credential, JceRequest, JceRequestItem, JceResponse, JceResponseItem, RequestItem
@@ -86,7 +85,7 @@ class Client:
             multiplexed=True,
             hooks=AsyncTokenBucketLimiter(rate=rate or 10, capacity=capacity or 50),
             happy_eyeballs=True,
-            retries=Retry(
+            retries=RetryConfiguration(
                 total=connect_retries or 2,
                 connect=connect_retries or 2,
                 read=0,

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/models/album.py

@@ -70,3 +70,52 @@ class GetAlbumSongResponse(Response):
     album_mid: str = Field(validation_alias="albumMid")
     total_num: int = Field(validation_alias="totalNum")
     song_list: list[Song] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.songList[*].songInfo"})
+
+
+class NewAlbumItem(Album):
+    """新碟上架列表中的单张专辑摘要.
+
+    Attributes:
+        singers: 专辑署名歌手列表.
+        release_time: 发行日期, 格式通常为 YYYY-MM-DD.
+        type: 专辑类型.
+        area: 地区标识.
+        genre: 流派标识.
+        language: 语种标识.
+    """
+
+    singers: list[Singer] = Field(default_factory=list)
+    release_time: str = ""
+    type: int = 0
+    area: int = 0
+    genre: int = 0
+    language: int = 0
+
+
+class GetNewAlbumResponse(Response):
+    """新碟上架接口的响应体.
+
+    Attributes:
+        total: 该地区下新碟总数.
+        albums: 当前页新碟列表.
+    """
+
+    total: int = 0
+    albums: list[NewAlbumItem] = Field(default_factory=list)
+
+
+class AlbumFavWriteResponse(Response):
+    """收藏 / 取消收藏专辑的写操作响应.
+
+    Attributes:
+        result: 操作结果码, 0 表示成功.
+        failed_album_id: 操作失败的专辑 ID 列表, 全部成功时为空.
+    """
+
+    result: int = 0
+    failed_album_id: list[int] = Field(default_factory=list, validation_alias="v_failedAlbumId")
+
+    @property
+    def success(self) -> bool:
+        """是否操作成功 (result 为 0 且无失败项)."""
+        return self.result == 0 and not self.failed_album_id

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/models/base.py

@@ -18,21 +18,17 @@ _PHOTO_NEW_SIZE_SEGMENTS: Final[dict[int, str]] = {
 }
 
 
-def _normalize_cover_size(size: CoverSize) -> str:
-    """返回 `photo_new` 模板使用的尺寸片段."""
-    try:
-        return _PHOTO_NEW_SIZE_SEGMENTS[size]
-    except KeyError as exc:
-        raise ValueError("not supported size") from exc
-
-
 def _build_photo_new_cover_url(kind: str, mid: str, size: CoverSize) -> str:
     """按 `photo_new` 规则拼接封面链接."""
     normalized_mid = mid.strip()
     if not normalized_mid:
         return ""
 
-    return f"https://y.gtimg.cn/music/photo_new/{kind}{_normalize_cover_size(size)}M000{normalized_mid}.jpg"
+    try:
+        cover_size = _PHOTO_NEW_SIZE_SEGMENTS[size]
+        return f"https://y.gtimg.cn/music/photo_new/{kind}{cover_size}M000{normalized_mid}.jpg"
+    except KeyError as exc:
+        raise ValueError("not supported size") from exc
 
 
 class Singer(Response):

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/models/mv.py

@@ -4,7 +4,7 @@ from typing import Any
 
 from pydantic import Field
 
-from .base import MV
+from .base import MV, Singer
 from .request import Response
 
 
@@ -116,3 +116,35 @@ class GetMvUrlsResponse(Response):
     """
 
     data: dict[str, MvUrlSet] = Field(json_schema_extra={"jsonpath": "$"})
+
+
+class MvListItem(MV):
+    """MV 分类列表中的单个 MV 摘要.
+
+    Attributes:
+        singers: 歌手列表.
+        subtitle: MV 副标题.
+        playcnt: 播放量.
+        pubdate: 发布时间戳.
+        duration: 时长 (秒).
+        picurl: 封面图片地址.
+    """
+
+    singers: list[Singer] = Field(default_factory=list)
+    subtitle: str = ""
+    playcnt: int = 0
+    pubdate: int = 0
+    duration: int = 0
+    picurl: str = ""
+
+
+class GetMvListResponse(Response):
+    """MV 分类列表接口的响应体.
+
+    Attributes:
+        total: 该分类条件下的 MV 总数.
+        items: 当前页 MV 列表.
+    """
+
+    total: int = 0
+    items: list[MvListItem] = Field(default_factory=list, validation_alias="list")

qqmusic_api_python-0.7.0/qqmusic_api/modules/album.py

@@ -0,0 +1,117 @@
+"""专辑相关 API."""
+
+from typing import Any
+
+from ..core.pagination import OffsetStrategy, PagerMeta, ResponseAdapter
+from ..models.album import (
+    AlbumFavWriteResponse,
+    GetAlbumDetailResponse,
+    GetAlbumSongResponse,
+    GetNewAlbumResponse,
+)
+from ..models.request import Credential
+from ._base import ApiModule
+
+
+class AlbumApi(ApiModule):
+    """专辑相关 API."""
+
+    def get_detail(self, value: int | str):
+        """获取专辑详细信息.
+
+        Args:
+            value: 专辑 ID 或 MID.
+        """
+        param: dict[str, Any] = {}
+        if isinstance(value, int) or (isinstance(value, str) and value.isdecimal()):
+            param["albumId"] = int(value)
+        else:
+            param["albumMId"] = value
+
+        return self._build_request(
+            module="music.musichallAlbum.AlbumInfoServer",
+            method="GetAlbumDetail",
+            param=param,
+            response_model=GetAlbumDetailResponse,
+        )
+
+    def get_song(self, value: int | str, num: int = 10, page: int = 1):
+        """获取专辑歌曲列表.
+
+        Args:
+            value: 专辑 ID 或 MID.
+            num: 返回结果数量.
+            page: 页码.
+        """
+        param: dict[str, Any] = {
+            "begin": num * (page - 1),
+            "num": num,
+        }
+        if isinstance(value, int) or (isinstance(value, str) and value.isdecimal()):
+            param["albumId"] = int(value)
+        else:
+            param["albumMid"] = value
+
+        return self._build_request(
+            module="music.musichallAlbum.AlbumSongList",
+            method="GetAlbumSongList",
+            param=param,
+            response_model=GetAlbumSongResponse,
+            pager_meta=PagerMeta(
+                strategy=OffsetStrategy(offset_key="begin", page_size_key="num"),
+                adapter=ResponseAdapter(total="total_num", count=lambda response: len(response.song_list)),
+            ),
+        )
+
+    def get_new_album(self, area: int = 1, num: int = 20, page: int = 1):
+        """获取新碟上架列表.
+
+        Args:
+            area: 地区. 1=内地, 2=港台, 3=欧美, 4=韩国, 5=日本, 6=其他.
+            num: 每页返回的专辑数量.
+            page: 页码, 从 1 开始.
+        """
+        return self._build_request(
+            module="newalbum.NewAlbumServer",
+            method="get_new_album_info",
+            param={"area": area, "num": num, "start": num * (page - 1)},
+            response_model=GetNewAlbumResponse,
+            pager_meta=PagerMeta(
+                strategy=OffsetStrategy(offset_key="start", page_size_key="num"),
+                adapter=ResponseAdapter(total="total", count=lambda response: len(response.albums)),
+            ),
+        )
+
+    def fav_album(self, album_id: int | list[int], *, credential: Credential | None = None):
+        """收藏专辑到当前登录用户.
+
+        Args:
+            album_id: 专辑 ID, 支持单个或列表.
+            credential: 登录凭证.
+        """
+        ids = [album_id] if isinstance(album_id, int) else album_id
+        return self._build_request(
+            module="music.musicasset.AlbumFavWrite",
+            method="FavAlbum",
+            param={"v_albumId": ids},
+            credential=credential,
+            require_login=True,
+            response_model=AlbumFavWriteResponse,
+        )
+
+    def del_fav_album(self, album_id: int | list[int], *, credential: Credential | None = None):
+        """取消收藏专辑.
+
+        Args:
+            album_id: 专辑 ID, 支持单个或列表.
+            credential: 登录凭证.
+        """
+        ids = [album_id] if isinstance(album_id, int) else album_id
+        return self._build_request(
+            module="music.musicasset.AlbumFavWrite",
+            method="CancelFavAlbum",
+            param={"v_albumId": ids},
+            credential=credential,
+            require_login=True,
+            response_model=AlbumFavWriteResponse,
+        )

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/modules/lyric.py

@@ -16,6 +16,7 @@ class LyricApi(ApiModule):
         qrc: bool = False,
         trans: bool = False,
         roma: bool = False,
+        song_type: int = 1,
     ):
         """获取歌词原始数据.
 
@@ -24,6 +25,7 @@ class LyricApi(ApiModule):
             qrc: 是否获取逐字歌词 (逐字歌词可能需要特定权限).
             trans: 是否获取翻译.
             roma: 是否获取罗马音.
+            song_type: 歌曲类型.
         """
         params: dict[str, Any] = {
             "crypt": 1,
@@ -34,9 +36,10 @@ class LyricApi(ApiModule):
             "roma_t": 0,
             "trans": trans,
             "trans_t": 0,
-            "type": 1,
+            "type": song_type,
         }
         params.update(self._build_query_common_params())
+
         if isinstance(value, int) or (isinstance(value, str) and value.isdecimal()):
             params["songId"] = int(value)
         else:

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/modules/mv.py

@@ -1,6 +1,7 @@
 """MV 相关 API."""
 
-from ..models.mv import GetMvDetailResponse, GetMvUrlsResponse
+from ..core.pagination import OffsetStrategy, PagerMeta, ResponseAdapter
+from ..models.mv import GetMvDetailResponse, GetMvListResponse, GetMvUrlsResponse
 from ..utils.common import get_guid
 from ._base import ApiModule
 
@@ -68,3 +69,31 @@ class MvApi(ApiModule):
             },
             response_model=GetMvUrlsResponse,
         )
+
+    def get_mv_list(
+        self,
+        area: int = 15,
+        version: int = 7,
+        order: int = 0,
+        num: int = 10,
+        page: int = 1,
+    ):
+        """获取 MV 分类列表.
+
+        Args:
+            area: 地区 ID. 15=全部, 8=内地, 5=港台, 6=欧美, 7=韩国, 4=日本.
+            version: 类型 ID. 7=全部, 8=MV, 13=现场, 14=翻唱, 15=舞蹈, 16=影视, 17=综艺, 18=儿歌.
+            order: 排序方式. 0=最新, 1=最热.
+            num: 每页返回数量.
+            page: 页码, 从 1 开始.
+        """
+        return self._build_request(
+            module="MvService.MvInfoProServer",
+            method="GetAllocMvInfo",
+            param={"area": area, "version": version, "order": order, "start": num * (page - 1), "size": num},
+            response_model=GetMvListResponse,
+            pager_meta=PagerMeta(
+                strategy=OffsetStrategy(offset_key="start", page_size_key="size"),
+                adapter=ResponseAdapter(total="total", count=lambda response: len(response.items)),
+            ),
+        )

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/modules/recommend.py

@@ -146,9 +146,13 @@ class RecommendApi(ApiModule):
             ),
         )
 
-    def get_recommend_newsong(self):
-        """获取推荐新歌."""
-        data = {"type": 5}
+    def get_recommend_newsong(self, type: int = 5):  # noqa: A002
+        """获取推荐新歌.
+
+        Args:
+            type: 地区/语种筛选. 1=内地, 2=欧美, 3=日本, 4=韩国, 5=最新, 6=港台.
+        """
+        data = {"type": type}
         return self._build_request(
             "newsong.NewSongServer",
             "get_new_song_info",

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/modules/song.py

@@ -177,36 +177,64 @@ class SongFileInfo(NamedTuple):
     media_mid: str | None = None
 
 
+class SongQueryInfo(NamedTuple):
+    """歌曲查询信息.
+
+    Attributes:
+        id: 歌曲 ID.
+        mid: 歌曲 MID.
+        song_type: 歌曲类型.
+    """
+
+    id: int | None = None
+    mid: str | None = None
+    song_type: int | None = None
+
+
 class SongApi(ApiModule):
     """歌曲相关 API 模块类."""
 
     _GET_SONG_URLS_MAX_MID = 100
     _SONG_URL_FALLBACK_DOMAIN = "https://isure.stream.qqmusic.qq.com/"
 
-    def query_song(self, value: list[int] | list[str]):
-        """根据 id 或 mid 获取歌曲信息.
+    def query_song(
+        self,
+        song_info: list[SongQueryInfo],
+    ):
+        """批量获取歌曲信息.
 
         Args:
-            value: 歌曲 ID 列表或 MID 列表.
+            song_info: SongQueryInfo 列表.
 
         Raises:
-            ValueError: 如果 `value` 为空.
+            ValueError: 如果 `song_info` 为空, 或参数不匹配.
         """
-        if not value:
-            raise ValueError("value 不能为空")
+        if not song_info:
+            raise ValueError("song_info 不能为空")
+
+        ids, mids, types = [], [], []
+        for item in song_info:
+            if (item.id is None) == (item.mid is None):
+                raise ValueError("SongQueryInfo 必须提供 id 或 mid 且不能同时提供")
+
+            if item.id is not None:
+                ids.append(item.id)
+            else:
+                mids.append(item.mid)
+            types.append(item.song_type or 0)
+
         params: dict[str, Any] = {
-            "types": [0 for _ in range(len(value))],
-            "modify_stamp": [0 for _ in range(len(value))],
             "ctx": 0,
             "client": 1,
+            "types": types,
+            "modify_stamp": [0] * len(types),
         }
-        numeric_values = [isinstance(item, int) or (isinstance(item, str) and item.isdecimal()) for item in value]
-        if all(numeric_values):
-            params["ids"] = [int(v) for v in value]
-        elif any(numeric_values):
-            raise ValueError("value 不能混合歌曲 ID 与 MID")
-        else:
-            params["mids"] = [str(v) for v in value]
+
+        if ids:
+            params["ids"] = ids
+        if mids:
+            params["mids"] = mids
+
         return self._build_request(
             module="music.trackInfo.UniformRuleCtrl",
             method="CgiGetTrackInfo",

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.7.0}/qqmusic_api/modules/songlist.py

@@ -175,3 +175,43 @@ class SonglistApi(ApiModule):
             if e.code == 80092:
                 return False
             raise
+
+    async def like_song(
+        self,
+        song_info: list[tuple[int, int]],
+        *,
+        credential: Credential | None = None,
+    ) -> bool:
+        """收藏歌曲到 "我喜欢" 歌单.
+
+        Note:
+            "我喜欢" 歌单的目录 ID 固定为 201, 本方法即以 dirid=201 调用 `add_songs`.
+
+        Args:
+            song_info: 歌曲信息列表, 每项为 `(song_id, song_type)`.
+            credential: 登录凭证.
+
+        Returns:
+            操作成功与否 (歌曲已在 "我喜欢" 中也返回 True).
+        """
+        return await self.add_songs(201, song_info, credential=credential)
+
+    async def unlike_song(
+        self,
+        song_info: list[tuple[int, int]],
+        *,
+        credential: Credential | None = None,
+    ) -> bool:
+        """从 "我喜欢" 歌单移除歌曲.
+
+        Note:
+            "我喜欢" 歌单的目录 ID 固定为 201, 本方法即以 dirid=201 调用 `del_songs`.
+
+        Args:
+            song_info: 歌曲信息列表, 每项为 `(song_id, song_type)`.
+            credential: 登录凭证.
+
+        Returns:
+            操作成功与否 (歌曲不在 "我喜欢" 中也返回 True).
+        """
+        return await self.del_songs(201, song_info, credential=credential)