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

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

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

@@ -1,4 +1,20 @@
 
+## [[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.2}/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.2}/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.2"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.6.1 → qqmusic_api_python-0.6.2}/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.2}/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.2}/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.1 → qqmusic_api_python-0.6.2}/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.2}/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}

{qqmusic_api_python-0.6.1 → qqmusic_api_python-0.6.2}/qqmusic_api/modules/login.py

@@ -10,7 +10,7 @@ from typing import Any
 from uuid import uuid4
 
 import anyio
-from niquests.exceptions import HTTPError, ReadTimeout
+from niquests.exceptions import HTTPError, ReadTimeout, RequestException
 
 from ..core import (
     ApiDataError,
@@ -501,6 +501,8 @@ class LoginApi(ApiModule):
             )
         except ReadTimeout:
             return QRLoginResult(event=QRCodeLoginEvents.SCAN)
+        except RequestException as exc:
+            raise NetworkError(str(exc)) from exc
 
         match = _WX_STATUS_RE.search(response.text or "")
         if not match:

{qqmusic_api_python-0.6.1 → qqmusic_api_python-0.6.2}/qqmusic_api/modules/recommend.py

@@ -17,6 +17,7 @@ from ..models.recommend import (
     RecommendNewSongResponse,
     RecommendSonglistResponse,
 )
+from ..models.request import Credential
 from ._base import ApiModule
 
 
@@ -82,8 +83,12 @@ class RecommendApi(ApiModule):
             ),
         )
 
-    def get_guess_recommend(self):
-        """获取猜你喜欢推荐."""
+    def get_guess_recommend(self, *, credential: Credential | None = None):
+        """获取猜你喜欢推荐.
+
+        Tips:
+            请求平台非 `Platform.ANDROID` 时, 需要提供有效的 `Credential`.
+        """
         data = {
             "id": 99,
             "num": 5,
@@ -96,6 +101,7 @@ class RecommendApi(ApiModule):
             "get_radio_track",
             data,
             response_model=GuessRecommendResponse,
+            credential=credential,
         )
 
     def get_radar_recommend(self, page: int = 1):

{qqmusic_api_python-0.6.1 → qqmusic_api_python-0.6.2}/qqmusic_api/utils/device.py

@@ -85,6 +85,10 @@ class Device:
     vendor_os_name: str = "qmapi"
     qimei: str | None = None
     qimei36: str | None = None
+    session_uid: str | None = None
+    session_sid: str | None = None
+    session_vkey: str | None = None
+    open_udid: str = field(default_factory=lambda: uuid4().hex)
 
 
 class DeviceManager:

{qqmusic_api_python-0.6.1 → qqmusic_api_python-0.6.2}/qqmusic_api/utils/qimei.py

@@ -15,7 +15,6 @@ from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric import padding
 from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
 from niquests import AsyncSession
-from niquests.exceptions import RequestException
 
 from .common import calc_md5
 from .device import Device, DeviceManager
@@ -30,7 +29,6 @@ MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDEIxgwoutfwoJxcGQeedgP7FG9qaIuS0qzfR8gWkrk
 -----END PUBLIC KEY-----"""
 SECRET = "ZdJqM15EeO2zWc08"
 APP_KEY = "0AND0HD6FE4HY80F"
-DEFAULT_QIMEI = "6c9d3cd110abca9b16311cee10001e717614"
 CHANNEL_ID = "10003505"
 PACKAGE_ID = "com.tencent.qqmusic"
 HEX_CHARS = "0123456789abcdef"
@@ -71,17 +69,12 @@ class QimeiManager:
         async with self._lock:
             if self._cache is not None:
                 return self._cache
-
             device = await self._device_store.get_device()
             if device.qimei and device.qimei36:
                 self._cache = QimeiResult(q16=device.qimei, q36=device.qimei36)
                 return self._cache
 
-            try:
-                self._cache = await self._request_qimei(device)
-            except Exception:
-                self._cache = QimeiResult(q16=DEFAULT_QIMEI, q36=DEFAULT_QIMEI)
-
+            self._cache = await self._request_qimei(device)
             with contextlib.suppress(Exception):
                 await self._device_store.apply_qimei(
                     self._cache.get("q16") or "",
@@ -90,34 +83,38 @@ class QimeiManager:
             return self._cache
 
     async def _request_qimei(self, device: Device) -> QimeiResult:
-        """请求新的 QIMEI 信息."""
-        try:
-            _, headers, request_json = await to_thread.run_sync(
-                _build_qimei_request,
-                device,
-                self._app_version,
-                self._sdk_version,
-            )
-
-            client = self._session
-            res = await client.post(
-                "https://api.tencentmusic.com/tme/trpc/proxy",
-                headers=headers,
-                json=request_json,
-            )
-            res.raise_for_status()
-
-            if res.content is None:
-                return QimeiResult(q16=DEFAULT_QIMEI, q36=DEFAULT_QIMEI)
-
-            qimei_data: dict[str, str] = json.loads(json.loads(res.content).get("data", "{}")).get("data", {})
-
-            if not qimei_data or "q36" not in qimei_data or "q16" not in qimei_data:
-                return QimeiResult(q16=DEFAULT_QIMEI, q36=DEFAULT_QIMEI)
-
-            return QimeiResult(q16=qimei_data["q16"], q36=qimei_data["q36"])
-        except (RequestException, json.JSONDecodeError, KeyError, ValueError):
-            return QimeiResult(q16=DEFAULT_QIMEI, q36=DEFAULT_QIMEI)
+        """请求新的 QIMEI 信息.
+
+        Raises:
+            RuntimeError: QIMEI 服务端返回空内容或缺少必要字段时.
+            RequestException: 网络请求失败时.
+            json.JSONDecodeError: 响应解析失败时.
+        """
+        _, headers, request_json = await to_thread.run_sync(
+            _build_qimei_request,
+            device,
+            self._app_version,
+            self._sdk_version,
+        )
+
+        client = self._session
+        res = await client.post(
+            "https://api.tencentmusic.com/tme/trpc/proxy",
+            headers=headers,
+            json=request_json,
+        )
+        await self._session.gather(res)
+        res.raise_for_status()
+
+        if res.content is None:
+            raise RuntimeError("QIMEI response content is empty")
+
+        qimei_data: dict[str, str] = json.loads(json.loads(res.content).get("data", "{}")).get("data", {})
+
+        if not qimei_data or "q36" not in qimei_data or "q16" not in qimei_data:
+            raise RuntimeError(f"QIMEI response missing required fields: {qimei_data}")
+
+        return QimeiResult(q16=qimei_data["q16"], q36=qimei_data["q36"])
 
 
 def rsa_encrypt(content: bytes) -> bytes: