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

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

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

@@ -1,4 +1,90 @@
 
+## [[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 修复
+
+* **(core)** 修复请求分页提取器的参数克隆冲突 ([e74d00b](https://github.com/L-1124/QQMusicApi/commit/e74d00b6cc6274676adb9855902234c6a9a9fcb1)) by [@L-1124](https://github.com/L-1124)
+* **(tests)** 修复 disable_parse 移除后的测试残留并清理装饰性框线 ([39fc259](https://github.com/L-1124/QQMusicApi/commit/39fc259bdeefb3fd9f740d678a380da59e98f8da)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 未捕获异常统一返回 JSON 形状的 500 响应 ([95e5ab4](https://github.com/L-1124/QQMusicApi/commit/95e5ab44c79e7503df969677e5848b5b376efafa)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 屏蔽上游 5xx 异常细节并修正凭证快照的阻塞调用 ([2d384b0](https://github.com/L-1124/QQMusicApi/commit/2d384b021d0082dc2715c84884b36d29801ca342)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复池凭证过期判定与刷新未同锁导致的重复登录 ([4426508](https://github.com/L-1124/QQMusicApi/commit/442650810e9fe43d0a646b4dfc8f76696dbb55e5)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复调用方 Cookie 凭证被刷新并写回共享池的问题 ([4aeab21](https://github.com/L-1124/QQMusicApi/commit/4aeab216a26b873707c817457321b225a8e9d169)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(core)** Android comm 参数补充注入 traceid ([84cc613](https://github.com/L-1124/QQMusicApi/commit/84cc6131a1cd44939d63edcdde5b3b554211bc88)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 提升全局 Android 协议版本为 20.9.0.8 ([6ce5d7e](https://github.com/L-1124/QQMusicApi/commit/6ce5d7ef6c45cea392173c33e493d98f0f3d2913)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 引入声明式 Endpoint 与无客户端网关 ([116e7fd](https://github.com/L-1124/QQMusicApi/commit/116e7fdb701f6d261ac913c3636b56f188c17ced)) by [@L-1124](https://github.com/L-1124) in [#304](https://github.com/L-1124/QQMusicApi/pull/304)
+* **(core)** 优化 comm 参数与设备标识语义 ([072011a](https://github.com/L-1124/QQMusicApi/commit/072011a5f5d9d60181148d79981701862906d6dc)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 解耦设备缓存并完善并发控制 ([2eb66c4](https://github.com/L-1124/QQMusicApi/commit/2eb66c4c1651d6f525015c8c4bf6cb72e963c814)) by [@L-1124](https://github.com/L-1124)
+* **(core)** [**breaking**] 引入统一请求内核与显式流式读取 ([bc09d1c](https://github.com/L-1124/QQMusicApi/commit/bc09d1c60b1ffb093255938d63fa5a197af9939f)) by [@L-1124](https://github.com/L-1124) in [#303](https://github.com/L-1124/QQMusicApi/pull/303)
+* **(device)** 完善 Android 设备档案生成 ([4c67b50](https://github.com/L-1124/QQMusicApi/commit/4c67b50bfd4a03fde786e63b4fef0a587f3f4d12)) by [@L-1124](https://github.com/L-1124)
+* **(device)** 优化设备生成与 QIMEI 参数 ([f207f82](https://github.com/L-1124/QQMusicApi/commit/f207f8281e63da2b4fac4391dd7dbe10c527d68d)) by [@L-1124](https://github.com/L-1124)
+* **(sound_power)** 新增音响力与听歌榜模块及 Web 路由 ([514fc3f](https://github.com/L-1124/QQMusicApi/commit/514fc3f4f1357d0b73d95f6fd37f65ec9b6d86b7)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 缓存未命中引入请求合并与上游失败标记熔断 ([807421d](https://github.com/L-1124/QQMusicApi/commit/807421db284db78e034d3abb1948228462d7d6e5)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(album)** 迁移 AlbumApi 端点至 @cgi_endpoint 并更新 Web 路由 ([7522cea](https://github.com/L-1124/QQMusicApi/commit/7522ceadc69c4be3a3aa188b45f9f3d752109797)) by [@L-1124](https://github.com/L-1124)
+* **(comment)** 迁移 CommentApi 端点至 @cgi_endpoint 并更新 Web 路由 ([1565743](https://github.com/L-1124/QQMusicApi/commit/1565743030dc6bed7c2574ffc37ecb4aec93a919)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 让 CgiRequestData.param 默认为空字典并移除冗余空参数 ([55f7b01](https://github.com/L-1124/QQMusicApi/commit/55f7b014ea4b118d2520278db8ffda900a871bf2)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 彻底移除 disable_parse 选项并更新端点声明范式文档 ([5cf1a06](https://github.com/L-1124/QQMusicApi/commit/5cf1a0645f7fec6523ec05a725ab1ef161d577d1)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 彻底分离端点元数据与运行期覆盖契约 ([46a1a2e](https://github.com/L-1124/QQMusicApi/commit/46a1a2e143698bbf77e3c8b318ff334c491f4755)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 为端点装饰器增加分页类型重载与通用契约校验 ([f443e65](https://github.com/L-1124/QQMusicApi/commit/f443e6561ff5331d7023d2b538a9ace9dd1e8d6e)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** 迁移 LyricApi 端点至 @cgi_endpoint 并更新 Web 路由 ([e12ae87](https://github.com/L-1124/QQMusicApi/commit/e12ae875b1170d3eb7fbcf7724a801439807166f)) by [@L-1124](https://github.com/L-1124)
+* **(modules)** 为各模块端点声明 item_type 与 pager 契约并清理测试 ([8308052](https://github.com/L-1124/QQMusicApi/commit/8308052cfeee23c8bb78425d28d0bc6d997d8375)) by [@L-1124](https://github.com/L-1124)
+* **(mv)** 迁移 MvApi 端点至 @cgi_endpoint 并更新 Web 路由 ([d2e383c](https://github.com/L-1124/QQMusicApi/commit/d2e383cbcb8e304931afc04bf76167cce365cc1d)) by [@L-1124](https://github.com/L-1124)
+* **(recommend)** 迁移 RecommendApi 端点至 @cgi_endpoint 并更新 Web 路由 ([b97c043](https://github.com/L-1124/QQMusicApi/commit/b97c0436907e51a3ca489797e95f37de53cb1dde)) by [@L-1124](https://github.com/L-1124)
+* **(search)** 迁移 SearchApi 端点至 @cgi_endpoint 并更新 Web 路由 ([25fe3eb](https://github.com/L-1124/QQMusicApi/commit/25fe3ebeac8f65119d7b5ab3bc3f3e681c4a1b01)) by [@L-1124](https://github.com/L-1124)
+* **(singer)** [**breaking**] 移除 get_name_special_display 并合并至 get_info ([e293aa3](https://github.com/L-1124/QQMusicApi/commit/e293aa320f316ae9e654f90503c8a4b9186b0b91)) by [@L-1124](https://github.com/L-1124)
+* **(singer)** 迁移 SingerApi 端点至 @cgi_endpoint 并更新 Web 路由 ([79af270](https://github.com/L-1124/QQMusicApi/commit/79af2704002f53f29024eb0aabd82d9917b798d4)) by [@L-1124](https://github.com/L-1124)
+* **(song)** 迁移 SongApi 端点至 @cgi_endpoint 并更新 Web 路由 ([8c08868](https://github.com/L-1124/QQMusicApi/commit/8c08868cd72c633ac023635fcf4f28c58a25576d)) by [@L-1124](https://github.com/L-1124)
+* **(songlist)** 迁移 SonglistApi 端点至 @cgi_endpoint 并更新 Web 路由 ([ba50d18](https://github.com/L-1124/QQMusicApi/commit/ba50d1864e69d91e6ce896cf47085745e93bed7a)) by [@L-1124](https://github.com/L-1124)
+* **(top)** 迁移 TopApi 端点至 @cgi_endpoint 并更新 Web 路由 ([e2a1fee](https://github.com/L-1124/QQMusicApi/commit/e2a1fee9c7a3d5193a3b2a37b6f6b4a6bf5348de)) by [@L-1124](https://github.com/L-1124)
+* **(user)** 迁移 UserApi 端点至 @cgi_endpoint 并更新 Web 路由 ([49921f6](https://github.com/L-1124/QQMusicApi/commit/49921f600cb9ede33990bffa1d85ef502c985896)) by [@L-1124](https://github.com/L-1124)
+* **(web)** [**breaking**] 优化 web 端参数声明，减少冗余 ([ba95861](https://github.com/L-1124/QQMusicApi/commit/ba95861ee9391f5b5f60f89caa8d4de4af160c8b)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 在路由注册器中增加 Web 模块白名单校验 ([9b0bc65](https://github.com/L-1124/QQMusicApi/commit/9b0bc6590ab597db25b5da378298dfd2a6817881)) by [@L-1124](https://github.com/L-1124)
+
+### 性能优化
+
+* **(qimei)** 优化设备特征计算与静态参数缓存 ([e19fdf2](https://github.com/L-1124/QQMusicApi/commit/e19fdf2f2e8f25a2b3bb24c03b7db16b90a832f6)) by [@L-1124](https://github.com/L-1124)
+
+### 文档更新
+
+* **(coding)** 补充声明式端点撰写指南并更新架构概览与调用流程 ([866bffb](https://github.com/L-1124/QQMusicApi/commit/866bffb6b20ef37ba81b36c7476164f9a8b8e556)) by [@L-1124](https://github.com/L-1124)
+* **(examples)** 新增音响力查询与听歌时长上报示例 ([a408059](https://github.com/L-1124/QQMusicApi/commit/a40805982fd53c2db45db1e878aa9ab6934141af)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
 ## [[0.7.3](https://github.com/L-1124/QQMusicApi/compare/v0.7.2..v0.7.3)] - 2026-09-13
 
 ### Bug 修复

{qqmusic_api_python-0.8.0 → qqmusic_api_python-0.8.2}/docs/tutorial/credential.md

@@ -40,7 +40,7 @@ asyncio.run(main())
 
 ## 单次请求覆盖
 
-如果你不想把凭证绑定到整个 `Client`，需要 `Crential` 的接口都支持使用 `credential` 参数进行单次请求覆盖。
+如果你不想把凭证绑定到整个 `Client`，需要登录态的接口都支持使用 `credential` 参数进行单次请求覆盖。
 
 ```python
 import asyncio
@@ -76,7 +76,7 @@ async def main() -> None:
             refresh_token="xxx",
             access_token="xxx",
         )
-        await credential.refresh(client)
+        credential = await client.login.refresh_credential(credential)
         print(credential.musicid, credential.musickey)
 
 asyncio.run(main())

{qqmusic_api_python-0.8.0 → qqmusic_api_python-0.8.2}/docs/tutorial/web.md

@@ -1,11 +1,11 @@
-# Web 服务
+# QQMusic API Web 服务
 
 Web 服务将 QQMusicApi 暴露为 HTTP API。
 
 ## 1. 安装
 
 ```bash
-git clone https://github.com/luren-dc/QQMusicApi
+git clone https://github.com/L-1124/QQMusicApi
 cd QQMusicApi
 uv sync --group web
 ```
@@ -15,12 +15,12 @@ uv sync --group web
 ## 2. 启动服务
 
 ```bash
-uv run python web/run.py
+uv run --no-sync web/run.py
 ```
 
 ## 3. 查看 API 文档
 
-打开 [http://localhost:8000/docs](http://localhost:8000/docs) 可以查看所有可用接口。
+默认监听 `127.0.0.1:8080`。打开 [http://localhost:8080/docs](http://localhost:8080/docs) 可以查看所有可用接口，Swagger UI 与 ReDoc 分别位于 `/swagger` 与 `/redoc`。
 
 ## 4. 认证方式
 

{qqmusic_api_python-0.8.0 → 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.0 → 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.0"
+__version__ = "0.8.2"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.8.0 → qqmusic_api_python-0.8.2}/qqmusic_api/core/executor.py

@@ -126,7 +126,7 @@ class CgiExecutor:
                     results[call.index] = exc
                     continue
                 raise
-            if request.require_login and not bool(call.scope.credential.musicid and call.scope.credential.musickey):
+            if request.require_login and not call.scope.credential.is_valid():
                 exc = CredentialInvalidError("请求需要登录, 未提供有效的登录凭证")
                 if return_exceptions:
                     results[call.index] = exc

{qqmusic_api_python-0.8.0 → qqmusic_api_python-0.8.2}/qqmusic_api/core/transport.py

@@ -11,7 +11,13 @@ from niquests import AsyncSession, AsyncTokenBucketLimiter, RetryConfiguration
 from niquests import PreparedRequest as NiquestsPreparedRequest
 from niquests.exceptions import RequestException, Timeout
 from niquests.models import Response
-from niquests.typing import AsyncHookType, ProxyType, TLSClientCertType, TLSVerifyType
+from niquests.typing import (
+    AsyncHookType,
+    ProxyType,
+    TimeoutType,
+    TLSClientCertType,
+    TLSVerifyType,
+)
 
 from .exceptions import NetworkError, TimeoutNetworkError
 
@@ -321,6 +327,7 @@ class NiquestsTransport:
         rate: float = 10,
         capacity: float = 50,
         connect_retries: int = 2,
+        timeout: TimeoutType = (10, 60),
         proxies: ProxyType | None = None,
         cert: TLSClientCertType | None = None,
         verify: TLSVerifyType | None = None,
@@ -350,6 +357,7 @@ class NiquestsTransport:
         self.cert = cert
         self.verify = verify
         self.hooks = hooks
+        self.timeout = timeout
         self._max_concurrency = max_concurrency
         self._capacity = _CapacityLimiter(max_concurrency)
         self._closed = False
@@ -406,10 +414,12 @@ class NiquestsTransport:
         try:
             for position, request in enumerate(chunk):
                 try:
+                    kwargs = dict(request.kwargs)
+                    kwargs.setdefault("timeout", self.timeout)
                     response = await self._client.request(
                         request.method,
                         request.url,
-                        **dict(request.kwargs),
+                        **kwargs,
                         proxies=self.proxies,
                         hooks=self.hooks,
                         cert=self.cert,
@@ -480,10 +490,12 @@ class NiquestsTransport:
         response: Response | None = None
         try:
             try:
+                stream_kwargs = dict(request.kwargs)
+                stream_kwargs.setdefault("timeout", self.timeout)
                 response = await self._client.request(
                     request.method,
                     request.url,
-                    **dict(request.kwargs),
+                    **stream_kwargs,
                     stream=True,
                     proxies=self.proxies,
                     hooks=self.hooks,

{qqmusic_api_python-0.8.0 → qqmusic_api_python-0.8.2}/qqmusic_api/models/request.py

@@ -118,6 +118,10 @@ class Credential(BaseModel):
         current_time = int(time.time())
         return current_time >= self.musickey_create_time + self.key_expires_in
 
+    def is_valid(self) -> bool:
+        """检查凭据是否包含可用登录态 (musicid 与 musickey 均有效)."""
+        return self.musicid > 0 and bool(self.musickey)
+
 
 class RequestItem(TypedDict):
     """请求项."""

{qqmusic_api_python-0.8.0 → 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.0 → 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.0 → qqmusic_api_python-0.8.2}/qqmusic_api/modules/user.py

@@ -44,7 +44,7 @@ class UserApi(ApiModule):
         if credential is not None:
             return credential
         current = self._executor.credential
-        if current.musicid and current.musickey:
+        if current.is_valid():
             return current
         return self.PLACEHOLDER_CREDENTIAL