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

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

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

@@ -1,4 +1,45 @@
 
+## [[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 修复
+
+* 传入的platform不生效 ([b19bec5](https://github.com/L-1124/QQMusicApi/commit/b19bec52f044d6508d9506f7111fea6eee5b42de)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(comment)** 支持添加评论和删除评论功能 ([dc5f568](https://github.com/L-1124/QQMusicApi/commit/dc5f5685d31f48b5dd8fc6bfcfdb6fb357884e7e)) by [@L-1124](https://github.com/L-1124)
+* **(private-message)** 新增私信接口模块 ([0ce6c77](https://github.com/L-1124/QQMusicApi/commit/0ce6c77b423c01c684cf86ff7a7ee9ca9a70d9fa)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
 ## [[0.6.0](https://github.com/L-1124/QQMusicApi/compare/v0.5.3..v0.6.0)] - 2026-05-09
 
 ### Bug 修复

{qqmusic_api_python-0.6.1 → qqmusic_api_python-0.6.3}/docs/tutorial/client.md

@@ -94,3 +94,15 @@ async def main():
 asyncio.run(_main())
 
 ```
+
+## 设备信息
+
+可通过 `device_path` 参数指定设备信息文件的路径进行持久化存储：
+
+```python
+client = Client(device_path="device.json")
+```
+
+不传 `device_path` 则仅在内存维护设备状态，重启后丢失。
+
+`Client.credential` 更改时设备信息保持不变。

{qqmusic_api_python-0.6.1 → 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.1"
+__version__ = "0.6.3"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.6.1 → qqmusic_api_python-0.6.3}/qqmusic_api/core/client.py

@@ -1,11 +1,12 @@
 """API 客户端核心实现. 整合网络传输、鉴权与业务模块访问."""
 
-import uuid
 from collections import defaultdict
 from functools import cached_property
 from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
+import anyio
 from niquests import AsyncSession, AsyncTokenBucketLimiter, PreparedRequest
+from niquests.exceptions import RequestException
 from niquests.models import Response
 from niquests.typing import AsyncHookType, ProxyType, TLSClientCertType, TLSVerifyType
 from tarsio import TarsDict
@@ -21,6 +22,7 @@ from .exceptions import (
     CredentialExpiredError,
     GlobalApiError,
     HTTPError,
+    NetworkError,
     RatelimitedError,
 )
 from .request import Request, RequestResultT, _build_result
@@ -99,8 +101,9 @@ class Client:
 
         self._device_store = DeviceManager(device_path)
 
-        self._guid = uuid.uuid4().hex
         self._version_policy: VersionPolicy = DEFAULT_VERSION_POLICY
+        self._session_lock = anyio.Lock()
+        self._session_initialized = False
         self._qimei_manager = QimeiManager(
             device_store=self._device_store,
             app_version=self._version_policy.get_qimei_app_version(),
@@ -108,6 +111,62 @@ class Client:
             session=self._session,
         )
 
+    async def _ensure_session(self) -> None:
+        async with self._session_lock:
+            if self._session_initialized:
+                return
+            device = await self._device_store.get_device()
+            if device.session_uid and device.session_sid:
+                self._session_initialized = True
+                return
+
+            finalcomm = self._version_policy.build_comm(
+                platform=Platform.ANDROID,
+                credential=self.credential,
+                device=device,
+                qimei=cast("dict[str, str]", await self._qimei_manager.get_cached()),
+                guid=device.open_udid,
+            )
+            payload: dict[str, Any] = {
+                "comm": finalcomm,
+                "req_0": {
+                    "module": "music.getSession.session",
+                    "method": "GetSession",
+                    "param": {
+                        "uid": device.session_uid or "",
+                        "vkey": 0,
+                        "caller": 0,
+                    },
+                },
+            }
+            user_agent = await self._get_user_agent(Platform.ANDROID)
+            try:
+                resp = await self._session.post(
+                    "https://u.y.qq.com/cgi-bin/musicu.fcg",
+                    json=payload,
+                    headers={"User-Agent": user_agent},
+                    proxies=self.proxies,
+                    hooks=self.hooks,
+                    cert=self.cert,
+                    verify=self.verify,
+                )
+                await self._session.gather(resp)
+            except RequestException as exc:
+                raise NetworkError(str(exc)) from exc
+            if resp.status_code != 200:
+                raise HTTPError(
+                    f"HTTP 请求状态码异常: {resp.status_code}",
+                    status_code=cast("int", resp.status_code),
+                )
+
+            resp_data = resp.json()
+            session_data = resp_data["req_0"]["data"]["session"]
+            device.session_uid = str(session_data["uid"])
+            device.session_sid = session_data["sid"]
+            device.session_vkey = session_data.get("vkey")
+            await self._device_store.save_device()
+            self._session_initialized = True
+
     @cached_property
     def comment(self) -> "CommentApi":
         """评论模块."""
@@ -261,18 +320,21 @@ class Client:
             headers["User-Agent"] = await self._get_user_agent(platform)
         kwargs["headers"] = headers
 
-        resp = await self._session.request(
-            method,
-            url,
-            **kwargs,
-            proxies=self.proxies,
-            hooks=self.hooks,
-            cert=self.cert,
-            verify=self.verify,
-        )
-        if not lazy:
-            await self._session.gather(resp)
-        return resp
+        try:
+            resp = await self._session.request(
+                method,
+                url,
+                **kwargs,
+                proxies=self.proxies,
+                hooks=self.hooks,
+                cert=self.cert,
+                verify=self.verify,
+            )
+            if not lazy:
+                await self._session.gather(resp)
+            return resp
+        except RequestException as exc:
+            raise NetworkError(str(exc)) from exc
 
     async def request_api(
         self,
@@ -285,39 +347,68 @@ class Client:
         lazy: bool = False,
     ) -> Response:
         """发送 API 请求."""
-        platform = Platform.ANDROID if is_jce else platform or self.platform
+        target_platform = Platform.ANDROID if is_jce else platform or self.platform
+        if target_platform == Platform.ANDROID:
+            await self._ensure_session()
+        device = await self._device_store.get_device()
         finalcomm = self._version_policy.build_comm(
-            platform=platform or self.platform,
+            platform=target_platform,
             credential=credential or self.credential,
-            device=await self._device_store.get_device(),
+            device=device,
             qimei=cast("dict[str, str]", await self._qimei_manager.get_cached())
-            if platform == Platform.ANDROID
+            if target_platform == Platform.ANDROID
             else None,
-            guid=self._guid,
+            guid=device.open_udid,
         )
         if comm:
             finalcomm.update(comm)
 
-        user_agent = await self._get_user_agent(platform)
+        user_agent = await self._get_user_agent(target_platform)
+
+        try:
+            if is_jce:
+                for k, v in finalcomm.items():
+                    if not isinstance(v, str):
+                        finalcomm[k] = str(v)
+                content = JceRequest(
+                    finalcomm,
+                    {
+                        f"req_{idx}": JceRequestItem(
+                            module=req["module"],
+                            method=req["method"],
+                            param=TarsDict(cast("dict[int, Any]", req["param"])),
+                        )
+                        for idx, req in enumerate(data)
+                    },
+                ).encode()
+                resp = await self._session.post(
+                    "http://u.y.qq.com/cgi-bin/musicw.fcg",
+                    data=content,
+                    headers={"User-Agent": user_agent},
+                    proxies=self.proxies,
+                    hooks=self.hooks,
+                    cert=self.cert,
+                    verify=self.verify,
+                )
+                if not lazy:
+                    await self._session.gather(resp)
+                return resp
+
+            payload: dict[str, Any] = {
+                "comm": finalcomm,
+            }
+            params = {}
+            for idx, req in enumerate(data):
+                payload[f"req_{idx}"] = {
+                    "module": req["module"],
+                    "method": req["method"],
+                    "param": req["param"] if req["preserve_bool"] else bool_to_int(req["param"]),
+                }
 
-        if is_jce:
-            for k, v in finalcomm.items():
-                if not isinstance(v, str):
-                    finalcomm[k] = str(v)
-            content = JceRequest(
-                finalcomm,
-                {
-                    f"req_{idx}": JceRequestItem(
-                        module=req["module"],
-                        method=req["method"],
-                        param=TarsDict(cast("dict[int, Any]", req["param"])),
-                    )
-                    for idx, req in enumerate(data)
-                },
-            ).encode()
             resp = await self._session.post(
-                "http://u.y.qq.com/cgi-bin/musicw.fcg",
-                data=content,
+                "https://u.y.qq.com/cgi-bin/musicu.fcg",
+                json=payload,
+                params=params,
                 headers={"User-Agent": user_agent},
                 proxies=self.proxies,
                 hooks=self.hooks,
@@ -326,33 +417,10 @@ class Client:
             )
             if not lazy:
                 await self._session.gather(resp)
-            return resp
-
-        payload: dict[str, Any] = {
-            "comm": finalcomm,
-        }
-        params = {}
-        for idx, req in enumerate(data):
-            payload[f"req_{idx}"] = {
-                "module": req["module"],
-                "method": req["method"],
-                "param": req["param"] if req["preserve_bool"] else bool_to_int(req["param"]),
-            }
 
-        resp = await self._session.post(
-            "https://u.y.qq.com/cgi-bin/musicu.fcg",
-            json=payload,
-            params=params,
-            headers={"User-Agent": user_agent},
-            proxies=self.proxies,
-            hooks=self.hooks,
-            cert=self.cert,
-            verify=self.verify,
-        )
-        if not lazy:
-            await self._session.gather(resp)
-
-        return resp
+            return resp
+        except RequestException as exc:
+            raise NetworkError(str(exc)) from exc
 
     @overload
     async def gather(
@@ -451,7 +519,10 @@ class Client:
                 )
                 batch_responses.append((batch_indices, response_task))
 
-        await self._session.gather(*(resp for _, resp in batch_responses))
+        try:
+            await self._session.gather(*(resp for _, resp in batch_responses))
+        except RequestException as exc:
+            raise NetworkError(str(exc)) from exc
 
         results: list[Any] = [_SENTINEL] * len(requests)
 

{qqmusic_api_python-0.6.1 → qqmusic_api_python-0.6.3}/qqmusic_api/core/request.py

@@ -63,6 +63,7 @@ def _build_result(
         return response_model.model_validate(raw)
     return raw
 
+
 @dataclass(kw_only=True)
 class Request(Generic[RequestResultT]):
     """请求描述符."""

{qqmusic_api_python-0.6.1 → qqmusic_api_python-0.6.3}/qqmusic_api/core/versioning.py

@@ -88,6 +88,8 @@ class VersionPolicy:
                 device.model,
                 device.version.sdk,
                 device.fingerprint,
+                device.session_uid,
+                device.session_sid,
             )
             if platform == Platform.ANDROID
             else (),
@@ -113,7 +115,9 @@ class VersionPolicy:
                 QIMEI36=qimei["q36"] if qimei is not None else "",
                 OpenUDID=guid,
                 udid=guid,
+                uid=device.session_uid,
                 OpenUDID2=guid,
+                sid=device.session_sid,
                 aid=device.android_id,
                 os_ver=device.version.release,
                 phonetype=device.model,

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.1 → 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.1 → 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.1 → qqmusic_api_python-0.6.3}/qqmusic_api/models/recommend.py

@@ -2,7 +2,7 @@
 
 from typing import Any
 
-from pydantic import AliasChoices, Field, model_validator
+from pydantic import AliasChoices, Field
 
 from .base import Song, SongList
 from .request import Response
@@ -69,15 +69,7 @@ class GuessRecommendResponse(Response):
         songs: 推荐歌曲列表.
     """
 
-    songs: list[Song] = Field(default_factory=list, alias="Tracks")
-
-    @model_validator(mode="before")
-    @classmethod
-    def _normalize_tracks(cls, data: Any) -> Any:
-        """将猜你喜欢响应规整为稳定的歌曲列表载荷."""
-        if isinstance(data, dict) and "Tracks" not in data:
-            return {"Tracks": []}
-        return data
+    songs: list[Song] = Field(default_factory=list, alias="tracks")
 
 
 class RadarRecommendResponse(Response):

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

@@ -45,6 +45,8 @@ class CommonParams(BaseModel):
     udid: str | None = Field(default=None)
     aid: str | None = Field(default=None)
     guid: str | None = Field(default=None)
+    uid: str | None = Field(default=None)
+    sid: str | None = Field(default=None)
     os_ver: str | None = Field(default=None)
     phonetype: str | None = Field(default=None)
     devicelevel: str | None = Field(default=None)
@@ -102,6 +104,7 @@ class Credential(BaseModel):
         if "loginType" in data or "login_type" in data:
             return data
 
+        # TODO: 修复没有 musickey 时误判为 QQ 登录的问题
         musickey = data.get("musickey", "")
         inferred_login_type = 1 if isinstance(musickey, str) and musickey.startswith("W_X") else 2
         return {**data, "loginType": inferred_login_type}
@@ -176,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