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

qqmusic_api_python-0.6.2/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.6.0
+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.2/docs/reference/modules/private_message.md

@@ -0,0 +1,3 @@
+# PrivateMessageApi
+
+::: modules.private_message.PrivateMessageApi

{qqmusic_api_python-0.6.0 → qqmusic_api_python-0.6.2}/docs/release-notes.md

@@ -1,4 +1,45 @@
 
+## [[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 修复
+
+* **(login)** 修改手机验证码鉴权参数类型为字符串 ([5cfebc6](https://github.com/L-1124/QQMusicApi/commit/5cfebc67cc816e0ca1930f76386fc599215496af)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(client)** 添加连接重试机制参数 ([38134a7](https://github.com/L-1124/QQMusicApi/commit/38134a74cfe9d3b623c46d74136687d9a2731848)) by [@L-1124](https://github.com/L-1124)
+* **(core)** [**breaking**] 移除 `RequestGroup`，支持 `Client.gather` 批量并发请求，重构请求速率限制参数 ([632b6a8](https://github.com/L-1124/QQMusicApi/commit/632b6a85fe509bbbab7bbe6e7ae702e34ef49440)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 添加 Docker 支持 ([b6f4dfc](https://github.com/L-1124/QQMusicApi/commit/b6f4dfc824c45cdba784904fd937495ab15065cc)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 添加 Web 服务路由 ([154d714](https://github.com/L-1124/QQMusicApi/commit/154d714f4bd918ab6b23814f841b154e5b388c94)) by [@L-1124](https://github.com/L-1124) in [#247](https://github.com/L-1124/QQMusicApi/pull/247)
+* [**breaking**] 不再支持配置 `Client` 部分参数并且修改并且初始化参数名 ([c4a7001](https://github.com/L-1124/QQMusicApi/commit/c4a7001a007128eba76b89004504b58be60c6f84)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(algorithms)** [**breaking**] 移除 Web 端请求签名模块 ([21b3179](https://github.com/L-1124/QQMusicApi/commit/21b31794d89efebbf58505a4310dc95ecd9ba7f0)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 重构 API 客户端, 迁移 httpx → niquests ([fc4f1b7](https://github.com/L-1124/QQMusicApi/commit/fc4f1b77f2f001331f38a178a2a16e84279a4549)) by [@L-1124](https://github.com/L-1124)
+* **(exception)** [**breaking**] 重构异常体系 ([3f7ef32](https://github.com/L-1124/QQMusicApi/commit/3f7ef3239f90cbcf3bf8ba64ab1561e89683df52)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
 ## [[0.5.3](https://github.com/L-1124/QQMusicApi/compare/v0.5.2..v0.5.3)] - 2026-05-01
 
 ### Bug 修复

{qqmusic_api_python-0.6.0 → 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.2/examples/private_message.py

@@ -0,0 +1,74 @@
+"""私信只读接口示例."""
+
+import asyncio
+
+from qqmusic_api import Client, Credential
+from qqmusic_api.models.private_message import PrivateMessageSession
+
+MUSICID = 0
+MUSICKEY = ""
+
+credential = Credential(musicid=MUSICID, musickey=MUSICKEY)
+
+
+def format_session_preview(index: int, session: PrivateMessageSession) -> str:
+    """格式化私信会话预览."""
+    user = session.user
+    latest_message = session.new_msg
+    metadata = latest_message.meta_data if latest_message else None
+    latest_text = metadata.content if metadata and metadata.content else latest_message.tips if latest_message else ""
+    return (
+        f"{index}. session_id={session.session_id}, "
+        f"uin={user.uin if user else ''}, "
+        f"nick={user.nick if user else ''}, "
+        f"unread={session.new_msg_cnt}, "
+        f"last={latest_text or '<无文本预览>'}"
+    )
+
+
+async def main() -> None:
+    """运行私信只读接口示例."""
+    async with Client(credential) as client:
+        session_result = await client.private_message.get_sessions(size=10)
+        print(f"会话列表: has_more={session_result.has_more}, count={len(session_result.sessions)}")
+
+        if not session_result.sessions:
+            print("当前账号没有可展示的私信会话。")
+            return
+
+        print("可用会话:")
+        for index, session in enumerate(session_result.sessions, start=1):
+            print(format_session_preview(index, session))
+
+        first_session = session_result.sessions[0]
+        target_user = first_session.user
+        message_result = await client.private_message.get_messages(
+            session_id=first_session.session_id,
+            user_id=target_user.uin if target_user else "",
+            size=20,
+        )
+        print(f"首个会话消息: has_more={message_result.has_more}, count={len(message_result.messages)}")
+
+        entries_result = await client.private_message.get_chat_entries(
+            [1, 2],
+            from_user_type=0,
+            user_id=target_user.uin if target_user else None,
+        )
+        entry_count = sum(len(entries) for entries in entries_result.entries.values())
+        print(f"聊天入口: ret_code={entries_result.ret_code}, entry_count={entry_count}")
+
+        media_msg_ids = [
+            message.id for message in message_result.messages if message.id and message.msg_type in {2, 3, 5, 6}
+        ]
+        if not media_msg_ids:
+            print("当前会话没有可用于预览详情查询的图片或视频消息。")
+            return
+
+        detail_result = await client.private_message.get_media_message_details(
+            first_session.session_id,
+            media_msg_ids[:5],
+        )
+        print(f"媒体消息详情: count={len(detail_result.msg_ids)}")
+
+
+asyncio.run(main())

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

{qqmusic_api_python-0.6.0 → 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
@@ -32,6 +34,7 @@ if TYPE_CHECKING:
     from ..modules.login import LoginApi
     from ..modules.lyric import LyricApi
     from ..modules.mv import MvApi
+    from ..modules.private_message import PrivateMessageApi
     from ..modules.recommend import RecommendApi
     from ..modules.search import SearchApi
     from ..modules.singer import SingerApi
@@ -98,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(),
@@ -107,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":
         """评论模块."""
@@ -114,6 +174,13 @@ class Client:
 
         return CommentApi(self)
 
+    @cached_property
+    def private_message(self) -> "PrivateMessageApi":
+        """私信模块."""
+        from ..modules.private_message import PrivateMessageApi
+
+        return PrivateMessageApi(self)
+
     @cached_property
     def recommend(self) -> "RecommendApi":
         """推荐模块."""
@@ -253,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,
@@ -277,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,
+            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,
@@ -318,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(
@@ -443,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.0 → 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.0 → 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.0 → qqmusic_api_python-0.6.2}/qqmusic_api/models/comment.py

@@ -203,3 +203,23 @@ class MomentCommentResponse(Response):
     hint: str = Field(alias="Hint")
     prev_list_loaded: int = Field(alias="PrevListLoaded")
     map_cm_ext: dict[str, dict[str, Any]] = Field(default_factory=dict, alias="MapCmExt")
+
+
+class AddCommentResponse(Response):
+    """添加评论接口的响应体.
+
+    Attributes:
+        subcode: 响应子代码.
+        msg: 响应消息.
+        id: 新增评论 ID.
+        parent: 父评论 ID.
+        floor: 楼层号.
+        verify_url: 验证码 URL (如果需要).
+    """
+
+    subcode: int = Field(alias="SubCode")
+    msg: str = Field(alias="Msg")
+    id: str = Field(alias="AddedCmId")
+    parent: str = Field(alias="ParentCmId")
+    floor: int = Field(json_schema_extra={"jsonpath": "$.Floor.Num"})
+    verify_url: str = Field(alias="VerifyUrl")