qqmusic-api-python 0.6.7__tar.gz → 0.6.8__tar.gz

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/.gitignore

@@ -13,6 +13,7 @@ device.json
 # AI
 .ccb/
 docs/superpowers/
+.omo/
 
 # Distribution / packaging
 .Python

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/AGENTS.md

@@ -47,6 +47,27 @@
 * 新增页面必须同步更新 `zensical.toml` 的 `nav`。
 * 文档构建工具实际使用 `zensical`，配置文件是 `zensical.toml`。
 
+## Release workflow
+
+1. 更新 `qqmusic_api/__init__.py` 中的 `__version__` 为待发布版本。
+2. 提交版本号变更：
+
+   ```bash
+   git add qqmusic_api/__init__.py
+   git commit -m "🧹 chore(release): x.x.x"
+   ```
+
+3. 在**该提交上**打 tag 并推送：
+
+   ```bash
+   git tag v0.x.x
+   git push origin v0.x.x
+   ```
+
+4. CI 自动执行：
+   * **release.yml**：`uv build` → `uv publish`（PyPI）→ 创建 GitHub Release（git-cliff 自动生成 release body）
+   * **docs.yml**（release published 后触发）：更新 `docs/release-notes.md` → 导出 `web/requirements.txt` → commit → 构建文档站 → 部署 GitHub Pages
+
 ## Agent behavior
 
 * **核心规约**：遵循 `docs/contributing.md` 中的详细规约。**在执行任务前，必须完整阅读该指南以确保合规。**

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.6.7
+Version: 0.6.8
 Summary: QQ音乐API封装库
 Project-URL: documentation, https://l-1124.github.io/QQMusicApi/
 Project-URL: homepage, https://l-1124.github.io/QQMusicApi/
@@ -37,6 +37,8 @@ Requires-Dist: paho-mqtt>=2.1.0
 Requires-Dist: pydantic>=2.13.3
 Requires-Dist: tarsio>=0.5.1
 Requires-Dist: typing-extensions>=4.12.2
+Provides-Extra: upload
+Requires-Dist: cos-python-sdk-v5>=1.9.44; extra == 'upload'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -56,6 +58,9 @@ Description-Content-Type: text/markdown
     <a href="https://github.com/l-1124/QQMusicApi/actions/workflows/testing.yml">
         <img src="https://github.com/l-1124/QQMusicApi/actions/workflows/testing.yml/badge.svg?branch=main" alt="Testing">
     </a>
+    <a href="https://deepwiki.com/luren-dc/QQMusicApi">
+        <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+    </a>
 </div>
 
 ---

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/README.md

@@ -15,6 +15,9 @@
     <a href="https://github.com/l-1124/QQMusicApi/actions/workflows/testing.yml">
         <img src="https://github.com/l-1124/QQMusicApi/actions/workflows/testing.yml/badge.svg?branch=main" alt="Testing">
     </a>
+    <a href="https://deepwiki.com/luren-dc/QQMusicApi">
+        <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+    </a>
 </div>
 
 ---

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/docs/coding.md

@@ -221,21 +221,24 @@ class Singer(Response):
 
 ### 需登录的接口
 
-需要登录的接口应通过 `_require_login` 校验凭证：
+需要登录的接口通过 `_build_request` 的 `require_login` 参数校验凭证：
 
 ```python
 def get_vip_info(self, *, credential: Credential | None = None):
     """获取 VIP 信息."""
-    target_credential = self._require_login(credential)
     return self._build_request(
         module="VipLogin.VipLoginInter",
         method="vip_login_base",
         param={},
-        credential=target_credential,
+        credential=credential,
         response_model=UserVipInfoResponse,
+        require_login=True,
     )
 ```
 
+> 若接口需要凭证对象的字段来构建请求参数，
+> 仍可显式调用 `_require_login` 获取凭证对象。
+
 ## 翻页与换一批
 
 ### 连续翻页

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/docs/release-notes.md

@@ -1,18 +1,24 @@
 
-## What's Changed
+## [[0.6.7](https://github.com/L-1124/QQMusicApi/compare/v0.6.6..v0.6.7)] - 2026-06-17
 
 ### 功能更新
 
+* **(login)** 新增登录异常子类和错误码映射 ([0ef9645](https://github.com/L-1124/QQMusicApi/commit/0ef9645806c9778cfa6214dd60fa56644568c276)) by [@jinzhongjia](https://github.com/jinzhongjia) in [#269](https://github.com/L-1124/QQMusicApi/pull/269)
+* **(qimei)** 增加 24 小时过期重新获取逻辑 ([05aed29](https://github.com/L-1124/QQMusicApi/commit/05aed29096dff31b7d0cbb26ccc66ec50da38bdc)) by [@L-1124](https://github.com/L-1124)
 * **(web)** 添加 has_sheet 路由 ([9e7a143](https://github.com/L-1124/QQMusicApi/commit/9e7a1439ff597ae43a4ef99d88ec08ee32889b9a)) by [@L-1124](https://github.com/L-1124)
 
 ### 文档更新
 
+* **(coding)** 重写 API 编写指南，补充开发细节 ([9db46de](https://github.com/L-1124/QQMusicApi/commit/9db46def73ec6c2d9826c4a15bc2eb7ba9ed0f37)) by [@L-1124](https://github.com/L-1124)
+* 为固定请求平台的 API 补充 docstring 说明 ([aba712e](https://github.com/L-1124/QQMusicApi/commit/aba712e56a7485b4184941480c05f370cd53c548)) by [@L-1124](https://github.com/L-1124)
 * 完善快速开始文档并新增多篇核心教程 ([d6143cd](https://github.com/L-1124/QQMusicApi/commit/d6143cdc047ebeb4963b061680a21103ba3d58d4)) by [@L-1124](https://github.com/L-1124)
 
 ### 贡献者
 
 * @L-1124
+* @jinzhongjia [#269](https://github.com/L-1124/QQMusicApi/pull/269)
 * @github-actions[bot]
+* @renovate[bot]
 
 ## [[0.6.6](https://github.com/L-1124/QQMusicApi/compare/v0.6.5..v0.6.6)] - 2026-06-13
 

qqmusic_api_python-0.6.8/examples/upload_file.py

@@ -0,0 +1,33 @@
+"""辅助功能文件上传示例."""
+
+import asyncio
+
+from qqmusic_api import Client
+from qqmusic_api.modules.helper_utils import UploadFileSession
+
+
+async def main() -> None:
+    """文件上传示例."""
+    file_to_upload = ""
+
+    async with Client() as client:
+        session = UploadFileSession(
+            api=client.helper,
+            bus_id="songlist",  # 歌单封面
+            max_concurrency=3,
+        )
+
+        object_infos = await session.upload([file_to_upload])
+        print(f"总计成功上传 {len(object_infos)} 个文件!")
+        for info in object_infos:
+            print(f"存储桶: {info.storage.bucket.name}")
+            print(f"区域:   {info.storage.bucket.region}")
+            print(f"对象键: {info.storage.object_key}")
+            print(f"CDN 地址: {info.url.cdn_url}")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("\n用户取消操作")

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/pyproject.toml

@@ -49,6 +49,11 @@ documentation = "https://l-1124.github.io/QQMusicApi/"
 homepage = "https://l-1124.github.io/QQMusicApi/"
 repository = "https://github.com/l-1124/QQMusicApi"
 
+[project.optional-dependencies]
+upload = [
+    "cos-python-sdk-v5>=1.9.44",
+]
+
 [dependency-groups]
 dev = [
   "tarsio[cli]>=0.5.1",
@@ -56,6 +61,7 @@ dev = [
   { include-group = "docs" },
   { include-group = "linting" },
   { include-group = "testing" },
+  { include-group = "helper" },
 ]
 docs = [
   "docstring-inheritance>=3.0.0",
@@ -65,6 +71,9 @@ docs = [
   "mkdocstrings-python>=2.0.3",
   "zensical>=0.0.30",
 ]
+helper = [
+    "cos-python-sdk-v5>=1.9.44",
+]
 linting = [
   "prek>=0.3.5",
   "pyrefly>=0.56.0",

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/qqmusic_api/__init__.py

@@ -22,7 +22,7 @@ from .core.exceptions import (
 from .core.versioning import Platform
 from .models.request import Credential
 
-__version__ = "0.6.7"
+__version__ = "0.6.8"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/qqmusic_api/core/client.py

@@ -17,7 +17,7 @@ from urllib3.util.retry import Retry
 from ..algorithms import zzc_sign
 from ..models.request import Credential, JceRequest, JceRequestItem, JceResponse, JceResponseItem, RequestItem
 from ..utils.common import bool_to_int
-from ..utils.device import DeviceManager
+from ..utils.device import Device, DeviceManager
 from ..utils.qimei import QimeiManager
 from .exceptions import (
     ApiDataError,
@@ -27,6 +27,7 @@ from .exceptions import (
     HTTPError,
     NetworkError,
     RatelimitedError,
+    SignatureRequiredError,
 )
 from .request import Request, RequestResultT, _build_result
 from .versioning import DEFAULT_VERSION_POLICY, Platform, VersionPolicy
@@ -34,6 +35,7 @@ from .versioning import DEFAULT_VERSION_POLICY, Platform, VersionPolicy
 if TYPE_CHECKING:
     from ..modules.album import AlbumApi
     from ..modules.comment import CommentApi
+    from ..modules.helper import HelperApi
     from ..modules.login import LoginApi
     from ..modules.lyric import LyricApi
     from ..modules.mv import MvApi
@@ -107,7 +109,6 @@ class Client:
 
         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(),
@@ -116,12 +117,22 @@ class Client:
         )
 
     async def _ensure_session(self) -> None:
+        """获取 `Platform.ANDROID` 会话信息."""
+
+        def _is_session_valid(dev: "Device") -> bool:
+            return (
+                dev.session_save_time is not None
+                and (int(time.time()) - dev.session_save_time) < 86400
+                and bool(dev.session_uid and dev.session_sid)
+            )
+
+        device = await self._device_store.get_device()
+        if _is_session_valid(device):
+            return
+
         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
+            if _is_session_valid(device):
                 return
 
             finalcomm = self._version_policy.build_comm(
@@ -168,8 +179,15 @@ class Client:
             device.session_uid = str(session_data["uid"])
             device.session_sid = session_data["sid"]
             device.session_vkey = session_data.get("vkey")
+            device.session_save_time = int(time.time())
             await self._device_store.save_device()
-            self._session_initialized = True
+
+    @cached_property
+    def helper(self) -> "HelperApi":
+        """辅助模块."""
+        from ..modules.helper import HelperApi
+
+        return HelperApi(self)
 
     @cached_property
     def comment(self) -> "CommentApi":
@@ -604,8 +622,9 @@ class Client:
                 "RequestResultT",
                 {"code": code, "data": data} if request.is_jce else item,
             )
-
         match code:
+            case 2000:
+                raise SignatureRequiredError(code=code, data=data)
             case 2001:
                 raise RatelimitedError(code=code, data=data)
             case 1000 | 104401 | 104400:

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/qqmusic_api/core/exceptions.py

@@ -19,6 +19,7 @@ __all__ = [
     "LoginRateLimitError",
     "NetworkError",
     "RatelimitedError",
+    "SignatureRequiredError",
 ]
 
 
@@ -202,3 +203,10 @@ class LoginRateLimitError(LoginError):
         data: Any = None,
     ):
         super().__init__(message, code=code, data=data)
+
+
+class SignatureRequiredError(CgiApiException):
+    """请求需要签名 (code=2000)."""
+
+    def __init__(self, *, code: int = 2000, data: Any = None) -> None:
+        super().__init__("请求需要签名", code=code, data=data)

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/qqmusic_api/models/album.py

@@ -20,10 +20,10 @@ class AlbumDetail(Album):
     """
 
     subtitle: str = ""
-    time_public: str = Field(default="", alias="publishDate")
+    time_public: str = Field(default="", validation_alias="publishDate")
     desc: str = ""
     language: str = ""
-    album_type: str = Field(default="", alias="albumType")
+    album_type: str = Field(default="", validation_alias="albumType")
     genre: str = ""
     wikiurl: str = ""
 
@@ -38,9 +38,9 @@ class AlbumCompany(Response):
         brief: 公司简介.
     """
 
-    id: int = Field(alias="ID")
+    id: int = Field(validation_alias="ID")
     name: str
-    is_show: int = Field(alias="isShow")
+    is_show: int = Field(validation_alias="isShow")
     brief: str = ""
 
 
@@ -53,7 +53,7 @@ class GetAlbumDetailResponse(Response):
         singers: 专辑署名歌手列表.
     """
 
-    album: AlbumDetail = Field(alias="basicInfo")
+    album: AlbumDetail = Field(validation_alias="basicInfo")
     company: AlbumCompany
     singers: list[Singer] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.singer.singerList"})
 
@@ -67,6 +67,6 @@ class GetAlbumSongResponse(Response):
         song_list: 当前响应携带的专辑歌曲列表.
     """
 
-    album_mid: str = Field(alias="albumMid")
-    total_num: int = Field(alias="totalNum")
+    album_mid: str = Field(validation_alias="albumMid")
+    total_num: int = Field(validation_alias="totalNum")
     song_list: list[Song] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.songList[*].songInfo"})

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.8}/qqmusic_api/models/comment.py

@@ -85,29 +85,29 @@ class CommentItem(Response):
         sub_comments: 子评论列表.
     """
 
-    cmid: str = Field(alias="CmId")
-    seq_no: str = Field(alias="SeqNo")
-    nick: str = Field(alias="Nick")
-    avatar: str = Field(alias="Avatar")
-    encrypt_uin: str = Field(alias="EncryptUin")
-    content: str = Field(alias="Content")
-    pub_time: int = Field(alias="PubTime")
-    praise_num: int = Field(alias="PraiseNum")
-    reply_cnt: int = Field(alias="ReplyCnt")
-    is_praised: int = Field(alias="IsPraised")
-    is_self: int = Field(alias="IsSelf")
-    state: int = Field(alias="State")
-    hot_score: str = Field(alias="HotScore")
-    rec_score: str = Field(alias="RecScore")
-    song_id: int = Field(alias="SongId")
-    song_name: str = Field(alias="SongName")
-    singer_names: str = Field(alias="SingerNames")
-    song_ts_elems: list[dict[str, Any]] = Field(default_factory=list, alias="SongTsElems")
-    hash_tag_list: list[dict[str, Any]] = Field(default_factory=list, alias="HashTagList")
-    little_tails: list[dict[str, Any]] = Field(default_factory=list, alias="LittleTails")
-    icon_list: list[dict[str, Any]] = Field(default_factory=list, alias="IconList")
-    vip_ui: dict[str, Any] = Field(default_factory=dict, alias="VipUI")
-    sub_comments: list[dict[str, Any]] = Field(default_factory=list, alias="SubComments")
+    cmid: str = Field(validation_alias="CmId")
+    seq_no: str = Field(validation_alias="SeqNo")
+    nick: str = Field(validation_alias="Nick")
+    avatar: str = Field(validation_alias="Avatar")
+    encrypt_uin: str = Field(validation_alias="EncryptUin")
+    content: str = Field(validation_alias="Content")
+    pub_time: int = Field(validation_alias="PubTime")
+    praise_num: int = Field(validation_alias="PraiseNum")
+    reply_cnt: int = Field(validation_alias="ReplyCnt")
+    is_praised: int = Field(validation_alias="IsPraised")
+    is_self: int = Field(validation_alias="IsSelf")
+    state: int = Field(validation_alias="State")
+    hot_score: str = Field(validation_alias="HotScore")
+    rec_score: str = Field(validation_alias="RecScore")
+    song_id: int = Field(validation_alias="SongId")
+    song_name: str = Field(validation_alias="SongName")
+    singer_names: str = Field(validation_alias="SingerNames")
+    song_ts_elems: list[dict[str, Any]] = Field(default_factory=list, validation_alias="SongTsElems")
+    hash_tag_list: list[dict[str, Any]] = Field(default_factory=list, validation_alias="HashTagList")
+    little_tails: list[dict[str, Any]] = Field(default_factory=list, validation_alias="LittleTails")
+    icon_list: list[dict[str, Any]] = Field(default_factory=list, validation_alias="IconList")
+    vip_ui: dict[str, Any] = Field(default_factory=dict, validation_alias="VipUI")
+    sub_comments: list[dict[str, Any]] = Field(default_factory=list, validation_alias="SubComments")
 
 
 class CommentListResponse(Response):
@@ -136,13 +136,13 @@ class CommentListResponse(Response):
     has_more: int = Field(json_schema_extra={"jsonpath": "$.CommentList.HasMore"})
     next_offset: int = Field(json_schema_extra={"jsonpath": "$.CommentList.NextOffset"})
     total: int = Field(json_schema_extra={"jsonpath": "$.CommentList.Total"})
-    total_cm_num: int = Field(alias="TotalCmNum")
-    comment_tip: str = Field(alias="CommentTip")
-    comment_h5_page: str = Field(alias="CommentH5Page")
-    has_ts_cm: int = Field(alias="HasTsCm")
-    share_cnt: int = Field(alias="ShareCnt")
-    msg: str = Field(alias="Msg")
-    sub_code: int = Field(alias="SubCode")
+    total_cm_num: int = Field(validation_alias="TotalCmNum")
+    comment_tip: str = Field(validation_alias="CommentTip")
+    comment_h5_page: str = Field(validation_alias="CommentH5Page")
+    has_ts_cm: int = Field(validation_alias="HasTsCm")
+    share_cnt: int = Field(validation_alias="ShareCnt")
+    msg: str = Field(validation_alias="Msg")
+    sub_code: int = Field(validation_alias="SubCode")
 
 
 class MomentCommentItem(Response):
@@ -167,22 +167,22 @@ class MomentCommentItem(Response):
         little_tails: 尾巴挂件列表.
     """
 
-    cmid: str = Field(alias="CmId")
-    seq_no: str = Field(alias="SeqNo")
-    content: str = Field(alias="Content")
-    encrypt_uin: str = Field(alias="EncryptUin")
-    pub_time: int = Field(alias="PubTime")
-    praise_num: int = Field(alias="PraiseNum")
-    reply_cnt: int = Field(alias="ReplyCnt")
-    state: int = Field(alias="State")
-    is_self: int = Field(alias="IsSelf")
-    location: str = Field(alias="Location")
-    phone_type: str = Field(alias="PhoneType")
-    pic: str = Field(alias="Pic")
-    pic_size: str = Field(alias="PicSize")
-    song_ts_elems: list[dict[str, Any]] = Field(default_factory=list, alias="SongTsElems")
-    hash_tag_list: list[dict[str, Any]] = Field(default_factory=list, alias="HashTagList")
-    little_tails: list[dict[str, Any]] = Field(default_factory=list, alias="LittleTails")
+    cmid: str = Field(validation_alias="CmId")
+    seq_no: str = Field(validation_alias="SeqNo")
+    content: str = Field(validation_alias="Content")
+    encrypt_uin: str = Field(validation_alias="EncryptUin")
+    pub_time: int = Field(validation_alias="PubTime")
+    praise_num: int = Field(validation_alias="PraiseNum")
+    reply_cnt: int = Field(validation_alias="ReplyCnt")
+    state: int = Field(validation_alias="State")
+    is_self: int = Field(validation_alias="IsSelf")
+    location: str = Field(validation_alias="Location")
+    phone_type: str = Field(validation_alias="PhoneType")
+    pic: str = Field(validation_alias="Pic")
+    pic_size: str = Field(validation_alias="PicSize")
+    song_ts_elems: list[dict[str, Any]] = Field(default_factory=list, validation_alias="SongTsElems")
+    hash_tag_list: list[dict[str, Any]] = Field(default_factory=list, validation_alias="HashTagList")
+    little_tails: list[dict[str, Any]] = Field(default_factory=list, validation_alias="LittleTails")
 
 
 class MomentCommentResponse(Response):
@@ -198,11 +198,11 @@ class MomentCommentResponse(Response):
     """
 
     comments: list[MomentCommentItem] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.CmList[*]"})
-    has_more: int = Field(alias="HasMore")
-    next_pos: str = Field(default="", alias="NextPos")
-    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")
+    has_more: int = Field(validation_alias="HasMore")
+    next_pos: str = Field(default="", validation_alias="NextPos")
+    hint: str = Field(validation_alias="Hint")
+    prev_list_loaded: int = Field(validation_alias="PrevListLoaded")
+    map_cm_ext: dict[str, dict[str, Any]] = Field(default_factory=dict, validation_alias="MapCmExt")
 
 
 class AddCommentResponse(Response):
@@ -217,9 +217,9 @@ class AddCommentResponse(Response):
         verify_url: 验证码 URL (如果需要).
     """
 
-    subcode: int = Field(alias="SubCode")
-    msg: str = Field(alias="Msg")
-    id: str = Field(alias="AddedCmId")
-    parent: str = Field(alias="ParentCmId")
+    subcode: int = Field(validation_alias="SubCode")
+    msg: str = Field(validation_alias="Msg")
+    id: str = Field(validation_alias="AddedCmId")
+    parent: str = Field(validation_alias="ParentCmId")
     floor: int = Field(json_schema_extra={"jsonpath": "$.Floor.Num"})
-    verify_url: str = Field(alias="VerifyUrl")
+    verify_url: str = Field(validation_alias="VerifyUrl")