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

qqmusic_api_python-0.6.1/CLAUDE.md

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

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

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

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

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

@@ -32,6 +32,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
@@ -114,6 +115,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":
         """推荐模块."""
@@ -279,7 +287,7 @@ class Client:
         """发送 API 请求."""
         platform = Platform.ANDROID if is_jce else platform or self.platform
         finalcomm = self._version_policy.build_comm(
-            platform=platform,
+            platform=platform or self.platform,
             credential=credential or self.credential,
             device=await self._device_store.get_device(),
             qimei=cast("dict[str, str]", await self._qimei_manager.get_cached())

{qqmusic_api_python-0.6.0 → qqmusic_api_python-0.6.1}/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")

qqmusic_api_python-0.6.1/qqmusic_api/models/private_message.py

@@ -0,0 +1,350 @@
+"""私信模块返回模型定义."""
+
+from typing import Any
+
+from pydantic import Field, field_validator, model_validator
+
+from .request import Response
+
+
+class PrivateMessageUser(Response):
+    """私信用户信息.
+
+    Attributes:
+        avatar: 用户头像地址.
+        encrypt_uin: 加密 UIN.
+        uin: 用户 UIN.
+        identity_pic: 身份图标地址.
+        nick: 用户昵称.
+        identity: 身份标识.
+        type: 用户类型.
+        is_concern: 关注状态.
+    """
+
+    avatar: str = ""
+    encrypt_uin: str = ""
+    uin: str = ""
+    identity_pic: str = ""
+    nick: str = ""
+    identity: int = -1
+    type: int = -1
+    is_concern: int = 0
+
+
+class PrivateMessageMetaData(Response):
+    """私信消息元数据.
+
+    Attributes:
+        title: 卡片标题.
+        content: 文本内容或卡片正文.
+        pic: 图片地址.
+        biz_id: 业务 ID.
+        biz_type: 业务类型.
+        url: 跳转链接.
+        width: 媒体宽度.
+        height: 媒体高度.
+        duration: 媒体时长.
+        size: 媒体大小.
+    """
+
+    title: str = ""
+    content: str = ""
+    pic: str = ""
+    biz_id: str = ""
+    biz_type: int = 0
+    url: str = ""
+    width: int = 0
+    height: int = 0
+    duration: int = Field(default=0, alias="Duration")
+    size: int = Field(default=0, alias="Size")
+
+
+class PrivateMessageInfo(Response):
+    """私信消息项.
+
+    Attributes:
+        id: 消息 ID.
+        meta_data: 消息元数据.
+        client_key: 客户端生成的消息键.
+        from_user: 发送方用户信息.
+        time: 消息时间戳.
+        state: 消息状态.
+        result: 发送结果.
+        tips: 提示文案.
+        sequence: 消息序列号.
+        show_type: 展示类型.
+        msg_type: 消息类型.
+        confirm: 确认状态.
+        sort_time: 排序时间戳.
+        complain_tip: 投诉提示文案.
+        complain_url: 投诉跳转链接.
+    """
+
+    id: str = ""
+    meta_data: PrivateMessageMetaData | None = None
+    client_key: str = ""
+    from_user: PrivateMessageUser | None = None
+    time: int = 0
+    state: int = 0
+    result: int = 0
+    tips: str = ""
+    sequence: int = 0
+    show_type: int = 0
+    msg_type: int = 0
+    confirm: int = 0
+    sort_time: int = 0
+    complain_tip: str = Field(default="", alias="complainTip")
+    complain_url: str = Field(default="", alias="complainUrl")
+
+
+class PrivateMessageTailTag(Response):
+    """私信会话尾部标签.
+
+    Attributes:
+        data: 原始标签字段.
+    """
+
+    data: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _wrap_raw_tag(cls, data: Any) -> Any:
+        """保留未建模的标签字段."""
+        if isinstance(data, dict) and "data" not in data:
+            return {"data": data}
+        return data
+
+
+class PrivateMessageSession(Response):
+    """私信会话项.
+
+    Attributes:
+        session_id: 会话 ID.
+        user: 对端用户信息.
+        new_msg: 最新消息.
+        new_msg_cnt: 未读消息数.
+        sort_time: 排序时间戳.
+        url: 会话跳转链接.
+        create_time: 创建时间戳.
+        from_: 会话来源.
+        sm_star_virtual_uin: 超级私信虚拟 UIN.
+        auth: 授权信息.
+        ext: 扩展字段.
+        tail_tags: 尾部标签列表.
+    """
+
+    session_id: str = ""
+    user: PrivateMessageUser | None = None
+    new_msg: PrivateMessageInfo | None = None
+    new_msg_cnt: int = 0
+    sort_time: int = 0
+    url: str = ""
+    create_time: int = Field(default=0, alias="create_time")
+    from_: int = Field(default=0, alias="from")
+    # 服务端字段名拼写如此, 保持 alias 与实际返回一致.
+    sm_star_virtual_uin: str = Field(default="", alias="SmStarVirtaulUin")
+    auth: str = Field(default="", alias="Auth")
+    ext: dict[str, str] = Field(default_factory=dict, alias="Ext")
+    tail_tags: list[PrivateMessageTailTag] = Field(default_factory=list, alias="TailTags")
+
+
+class PrivateSessionListResponse(Response):
+    """私信会话列表响应.
+
+    Attributes:
+        has_more: 是否还有更多会话.
+        msg: 提示文案.
+        new_msg_cnt: 未读消息数.
+        sessions: 会话列表.
+        subcode: 业务子码.
+        setting_guide: 设置引导标记.
+        state: 状态标记.
+        extra: 扩展字段.
+    """
+
+    has_more: int = 0
+    msg: str = ""
+    new_msg_cnt: int = 0
+    sessions: list[PrivateMessageSession] = Field(default_factory=list)
+    subcode: int = 0
+    setting_guide: int = 0
+    state: int = 0
+    extra: dict[str, str] = Field(default_factory=dict)
+
+
+class PrivateMessagePatText(Response):
+    """拍一拍文案信息.
+
+    Attributes:
+        nick: 用户昵称.
+        pat_text: 拍一拍文案.
+    """
+
+    nick: str = Field(default="", alias="Nick")
+    pat_text: str = Field(default="", alias="PatTxt")
+
+
+class PrivateMessageListResponse(Response):
+    """私信消息列表响应.
+
+    Attributes:
+        has_more: 是否还有更多消息.
+        messages: 消息列表.
+        msg: 提示文案.
+        session: 会话信息.
+        subcode: 业务子码.
+        end_msg_seq: 结束消息序列号.
+        attach: 附加字段.
+        pat_interval: 拍一拍间隔.
+        pat_map: 拍一拍文案映射.
+        encrypt_star: 加密明星 UIN.
+        location_tips: 定位提示文案.
+        new_msg_cnt: 新消息数量.
+    """
+
+    has_more: int = 0
+    messages: list[PrivateMessageInfo] = Field(default_factory=list)
+    msg: str = ""
+    session: PrivateMessageSession | None = None
+    subcode: int = 0
+    end_msg_seq: int = 0
+    attach: dict[str, Any] = 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")
+    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):
+    """私信发送响应.
+
+    Attributes:
+        messages: 服务端返回的消息列表.
+        session: 会话信息.
+        tips: 提示文案.
+        identify_url: 实名认证跳转链接.
+        msg: 业务提示.
+        reason: 失败原因码.
+        end_msg_seq: 结束消息序列号.
+        update_time: 更新时间戳.
+    """
+
+    messages: list[PrivateMessageInfo] = Field(default_factory=list)
+    session: PrivateMessageSession | None = None
+    tips: str = ""
+    identify_url: str = ""
+    msg: str = ""
+    reason: int = 0
+    end_msg_seq: int = 0
+    update_time: int = 0
+
+
+class PrivateOperationResponse(Response):
+    """私信写操作响应.
+
+    Attributes:
+        msg: 提示文案.
+        subcode: 业务子码.
+        tips: 失败提示.
+    """
+
+    msg: str = ""
+    subcode: int = 0
+    tips: str = ""
+
+
+class PrivateConfigResponse(Response):
+    """私信配置读取响应.
+
+    Attributes:
+        config_value: 配置值.
+        config_value_str: 配置字符串值.
+        msg: 提示文案.
+    """
+
+    config_value: int = 0
+    config_value_str: str = ""
+    msg: str = ""
+
+
+class PrivateMusicianCardResponse(Response):
+    """音乐人卡片响应.
+
+    Attributes:
+        data: 未建模的卡片原始字段.
+    """
+
+    data: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _wrap_raw_card(cls, data: Any) -> Any:
+        """保留未建模的卡片字段."""
+        if isinstance(data, dict) and "data" not in data:
+            return {"data": data}
+        return data
+
+
+class PrivateEntryItem(Response):
+    """聊天页入口项.
+
+    Attributes:
+        entry_type: 入口类型.
+        icon: 图标地址.
+        title: 标题.
+        skip_scheme: 跳转 Scheme.
+        right_top_tag: 右上角标签.
+        ext: 扩展字段.
+    """
+
+    entry_type: int = Field(default=-1, alias="EntryType")
+    icon: str = Field(default="", alias="Icon")
+    title: str = Field(default="", alias="Title")
+    skip_scheme: str = Field(default="", alias="SkipScheme")
+    right_top_tag: str = Field(default="", alias="RightTopTag")
+    ext: dict[str, str] = Field(default_factory=dict, alias="Ext")
+
+
+class PrivateChatEntriesResponse(Response):
+    """聊天页入口响应.
+
+    Attributes:
+        ret_code: 返回码.
+        ret_msg: 返回文案.
+        entries: 按场景分组的入口列表.
+        can_be_dazi: 是否可成为搭子.
+        dz_data: 未建模的搭子入口字段.
+    """
+
+    ret_code: int = Field(default=0, alias="RetCode")
+    ret_msg: str = Field(default="", alias="RetMsg")
+    entries: dict[int, list[PrivateEntryItem]] = Field(default_factory=dict, alias="Entries")
+    can_be_dazi: bool | None = Field(default=None, alias="CanBeDazi")
+    dz_data: dict[str, Any] = Field(default_factory=dict, alias="DzData")
+
+
+class PrivateMediaMessageDetailsResponse(Response):
+    """图片和视频消息详情响应.
+
+    Attributes:
+        msg_ids: 消息 ID 到消息详情的映射.
+    """
+
+    msg_ids: dict[str, PrivateMessageInfo] = Field(default_factory=dict, alias="MsgIDs")
+
+
+class PrivateSafetyHintResponse(Response):
+    """私信安全提示响应.
+
+    Attributes:
+        hint: 安全提示文案.
+    """
+
+    hint: str = ""

{qqmusic_api_python-0.6.0 → qqmusic_api_python-0.6.1}/qqmusic_api/modules/__init__.py

@@ -5,6 +5,7 @@ from .comment import CommentApi
 from .login import LoginApi
 from .lyric import LyricApi
 from .mv import MvApi
+from .private_message import PrivateMessageApi
 from .recommend import RecommendApi
 from .search import SearchApi
 from .singer import SingerApi
@@ -19,6 +20,7 @@ __all__ = [
     "LoginApi",
     "LyricApi",
     "MvApi",
+    "PrivateMessageApi",
     "RecommendApi",
     "SearchApi",
     "SingerApi",

{qqmusic_api_python-0.6.0 → qqmusic_api_python-0.6.1}/qqmusic_api/modules/comment.py

@@ -9,7 +9,9 @@ from ..core.pagination import (
     PaginationParams,
     ResponseAdapter,
 )
-from ..models.comment import CommentCountResponse, CommentListResponse, MomentCommentResponse
+from ..core.versioning import Platform
+from ..models.comment import AddCommentResponse, CommentCountResponse, CommentListResponse, MomentCommentResponse
+from ..models.request import Credential
 from ._base import ApiModule
 
 
@@ -48,6 +50,7 @@ class CommentApi(ApiModule):
         Args:
             biz_id: 歌曲 ID.
         """
+        # 支持 request_list
         data = {
             "request": {
                 "biz_id": str(biz_id),
@@ -194,3 +197,59 @@ class CommentApi(ApiModule):
                 adapter=ResponseAdapter(has_more_flag="has_more", cursor="next_pos"),
             ),
         )
+
+    def add_comment(
+        self,
+        biz_id: int,
+        content: str,
+        reply_cmt_id: str | None = None,
+        credential: Credential | None = None,
+    ):
+        """添加评论.
+
+        Args:
+            biz_id: 歌曲 ID.
+            content: 评论内容.
+            reply_cmt_id: 回复的评论 ID.
+            credential: 登录凭据.
+        """
+        self._require_login(credential)
+        return self._build_request(
+            "music.globalComment.CommentWriteServer",
+            "AddComment",
+            {
+                "Content": content,
+                "BizType": 1,
+                "BizId": str(biz_id),
+                "RepliedCmId": reply_cmt_id,
+            },
+            credential=credential,
+            platform=Platform.ANDROID,
+            response_model=AddCommentResponse,
+        )
+
+    async def delete_comment(
+        self,
+        cm_id: str,
+        credential: Credential | None = None,
+    ) -> bool:
+        """删除评论.
+
+        Args:
+            cm_id: 评论 ID.
+            credential: 登录凭据.
+
+        Returns:
+            是否删除成功,评论不存在也为 True.
+        """
+        self._require_login(credential)
+        data = await self._build_request(
+            "music.globalComment.CommentWriteServer",
+            "DelComment",
+            {
+                "CommentId": cm_id,
+            },
+            platform=Platform.ANDROID,
+            credential=credential,
+        )
+        return data.get("SubCode", 0) == 0