p123client 0.0.6.10.2__py3-none-any.whl → 0.0.7.1__py3-none-any.whl

p123client/__init__.py

@@ -2,7 +2,7 @@
 # encoding: utf-8
 
 __author__ = "ChenyangGao <https://chenyanggao.github.io>"
-__version__ = (0, 0, 6)
+__version__ = (0, 0, 7)
 
 from .client import *
 from .const import *

p123client/client.py

@@ -22,7 +22,7 @@ from os import fsdecode, fstat, isatty, PathLike
 from os.path import basename
 from pathlib import Path, PurePath
 from re import compile as re_compile, MULTILINE
-from string import digits, ascii_uppercase
+from string import digits, hexdigits, ascii_uppercase
 from sys import _getframe
 from tempfile import TemporaryFile
 from typing import cast, overload, Any, Final, Literal, Self
@@ -1644,7 +1644,7 @@ class P123OpenClient:
 
         :payload:
             - businessType: int = <default> 💡 业务类型：2:转码空间
-            - category: int = <default>     💡 分类代码：0:未知 1:音频 2:视频 3:图片 4:音频 5:其它
+            - category: int = <default>     💡 分类代码：0:未知 1:音频 2:视频 3:图片 4:音频 5:其它 6:保险箱 7:收藏夹
             - lastFileId: int = <default>   💡 上一页的最后一条记录的 FileID，翻页查询时需要填写
             - limit: int = 100              💡 分页大小，最多 100
             - parentFileId: int | str = 0   💡 父目录 id，根目录是 0
@@ -4424,6 +4424,125 @@ class P123OpenClient:
 
     ########## Upload API ##########
 
+    @overload
+    def upload_complete(
+        self, 
+        payload: str | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def upload_complete(
+        self, 
+        payload: str | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def upload_complete(
+        self, 
+        payload: str | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """上传完毕
+
+        POST https://open-api.123pan.com/upload/v1/file/upload_complete
+
+        .. admonition:: Reference
+
+            /API列表/文件管理/上传/V1（旧）/上传完毕
+
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/hkdmcmvg437rfu6x
+
+        :payload:
+            - preuploadID: str 💡 预上传 id
+
+        :return:
+            返回的数据说明如下：
+
+            .. code:: python
+
+                {
+                    "async": bool, # 是否需要异步查询上传结果
+                    "completed": bool, # 上传是否完成
+                    "fileID": int, # 上传的文件 id
+                }
+        """
+        api = complete_url("/upload/v1/file/upload_complete", base_url)
+        if not isinstance(payload, dict):
+            payload = {"preuploadID": payload}
+        return self.request(api, "POST", json=payload, async_=async_, **request_kwargs)
+
+    @overload
+    def upload_complete_v2(
+        self, 
+        payload: str | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def upload_complete_v2(
+        self, 
+        payload: str | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def upload_complete_v2(
+        self, 
+        payload: str | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """上传完毕
+
+        POST https://open-api.123pan.com/upload/v2/file/upload_complete
+
+        .. admonition:: Reference
+
+            /API列表/文件管理/上传/V2（推荐）/上传完毕
+
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/fzzc5o8gok517720
+
+        :payload:
+            - preuploadID: str 💡 预上传 id
+
+        :return:
+            返回的数据说明如下：
+
+            .. code:: python
+
+                {
+                    "completed": bool, # 上传是否完成
+                    "fileID": int,     # 上传的文件 id
+                }
+        """
+        api = complete_url("/upload/v2/file/upload_complete", base_url)
+        if not isinstance(payload, dict):
+            payload = {"preuploadID": payload}
+        return self.request(api, "POST", json=payload, async_=async_, **request_kwargs)
+
     @overload
     def upload_create(
         self, 
@@ -4465,9 +4584,17 @@ class P123OpenClient:
             - 开发者上传单文件大小限制 10 GB
             - 不会重名
 
+        .. note::
+            /API列表/文件管理/上传/V1（旧）/💡上传流程说明
+
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/il16qi0opiel4889
+
+            1. 请求创建文件接口，接口返回的 "reuse" 为 "true" 时，表示秒传成功，上传结束。
+            2. 非秒传情况将会返回预上传ID ``preuploadID`` 与分片大小 ``sliceSize``，请将文件根据分片大小切分。            
+
         .. admonition:: Reference
 
-            /API列表/文件管理/上传/V1/创建文件
+            /API列表/文件管理/上传/V1（旧）/创建文件
 
             https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/lrfuu3qe7q1ul8ig
 
@@ -4501,7 +4628,7 @@ class P123OpenClient:
         return self.request(api, "POST", json=payload, async_=async_, **request_kwargs)
 
     @overload
-    def upload_url(
+    def upload_create_v2(
         self, 
         payload: dict, 
         /, 
@@ -4512,7 +4639,7 @@ class P123OpenClient:
     ) -> dict:
         ...
     @overload
-    def upload_url(
+    def upload_create_v2(
         self, 
         payload: dict, 
         /, 
@@ -4522,7 +4649,7 @@ class P123OpenClient:
         **request_kwargs, 
     ) -> Coroutine[Any, Any, dict]:
         ...
-    def upload_url(
+    def upload_create_v2(
         self, 
         payload: dict, 
         /, 
@@ -4531,26 +4658,105 @@ class P123OpenClient:
         async_: Literal[False, True] = False, 
         **request_kwargs, 
     ) -> dict | Coroutine[Any, Any, dict]:
-        """获取上传地址&上传分片
+        """创建文件
 
-        POST https://open-api.123pan.com/upload/v1/file/get_upload_url
+        POST https://open-api.123pan.com/upload/v2/file/create
 
         .. note::
-            有多个分片时，轮流分别根据序号获取下载链接，然后 PUT 方法上传分片。由于上传链接会过期，所以没必要提前获取一大批
+            - 文件名要小于 256 个字符且不能包含以下字符：``"\\/:*?|><``
+            - 文件名不能全部是空格
+            - 开发者上传单文件大小限制 10 GB
+            - 不会重名
+
+        .. note::
+            /API列表/文件管理/上传/V2（推荐）/💡上传流程说明
+
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/xogi45g7okqk7svr#uqhyW
+
+            1. 调用创建文件接口，接口返回的 "reuse" 为 "true" 时，表示秒传成功，上传结束。
+            2. 非秒传情况将会返回预上传ID ``preuploadID`` 与分片大小 ``sliceSize``，请将文件根据分片大小切分。
+            3. 非秒传情况下返回 "servers" 为后续上传文件的对应域名（重要），多个任选其一。            
 
         .. admonition:: Reference
 
-            /API列表/文件管理/上传/V1/获取上传地址&上传分片
+            /API列表/文件管理/上传/V2（推荐）/创建文件
 
-            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/sonz9n085gnz0n3m
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/txow0iqviqsgotfl
 
         :payload:
-            - preuploadID: str 💡 预上传 id
-            - sliceNo: int     💡 分片序号，从 1 开始自增
+            - containDir: "false" | "true" = "false" 💡 上传文件是否包含路径
+            - filename: str 💡 文件名，但 ``containDir`` 为 "true" 时，视为路径
+            - duplicate: 0 | 1 | 2 = 0 💡 处理同名：0: 跳过/报错 1: 保留/后缀编号 2: 替换/覆盖
+            - etag: str 💡 文件 md5
+            - parentFileID: int = 0 💡 父目录 id，根目录是 0
+            - size: int 💡 文件大小，单位：字节
+
+        :return:
+            返回的数据说明如下：
+
+            .. code:: python
+
+                {
+                    "fileID": str, # 上传后的文件 id。当已有相同 ``size`` 和 ``etag`` 的文件时，会发生秒传
+                    "preuploadID": str, # 预上传 id。当 ``reuse`` 为 "true" 时，该字段不存在
+                    "reuse": bool, # 是否秒传，返回 "true" 时表示文件已上传成功
+                    "sliceSize": int, # 分片大小，必须按此大小生成文件分片再上传。当 ``reuse`` 为 "true" 时，该字段不存在
+                    "servers": list[str], # 上传地址，多个任选其一
+                }
         """
-        api = complete_url("/upload/v1/file/get_upload_url", base_url)
+        api = complete_url("/upload/v2/file/create", base_url)
+        payload = dict_to_lower_merge(payload, {
+            "parentFileId": 0, 
+            "containDir": "false", 
+        })
+        if "duplicate" in payload and not payload["duplicate"]:
+            del payload["duplicate"]
         return self.request(api, "POST", json=payload, async_=async_, **request_kwargs)
 
+    @overload
+    def upload_domain(
+        self, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def upload_domain(
+        self, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def upload_domain(
+        self, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """获取上传域名
+
+        GET https://open-api.123pan.com/upload/v2/file/domain
+
+        .. admonition:: Reference
+
+            /API列表/文件管理/上传/V2（推荐）/获取上传域名
+
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/agn8lolktbqie7p9
+
+        :payload:
+            - preuploadID: str 💡 预上传 id
+        """
+        api = complete_url("/upload/v2/file/domain", base_url)
+        return self.request(api, async_=async_, **request_kwargs)
+
     @overload
     def upload_list(
         self, 
@@ -4591,7 +4797,7 @@ class P123OpenClient:
 
         .. admonition:: Reference
 
-            /API列表/文件管理/上传/V1/列举已上传分片（非必需）
+            /API列表/文件管理/上传/V1（旧）/列举已上传分片（非必需）
 
             https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/dd28ws4bfn644cny
 
@@ -4604,69 +4810,229 @@ class P123OpenClient:
         return self.request(api, "POST", json=payload, async_=async_, **request_kwargs)
 
     @overload
-    def upload_complete(
+    def upload_result(
+        self, 
+        payload: str | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def upload_result(
+        self, 
+        payload: str | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def upload_result(
         self, 
         payload: str | dict, 
         /, 
         base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
         *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """异步轮询获取上传结果
+
+        POST https://open-api.123pan.com/upload/v1/file/upload_async_result
+
+        .. admonition:: Reference
+
+            /API列表/文件管理/上传/V1（旧）/异步轮询获取上传结果
+
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/qgcosr6adkmm51h7
+
+        :payload:
+            - preuploadID: str 💡 预上传 id
+
+        :return:
+            返回的数据说明如下：
+
+            .. code:: python
+
+                {
+                    "completed": bool, # 上传合并是否完成，如果为 False，请至少 1 秒后再发起轮询
+                    "fileID": int, # 上传的文件 id
+                }
+        """
+        api = complete_url("/upload/v1/file/upload_async_result", base_url)
+        if not isinstance(payload, dict):
+            payload = {"preuploadID": payload}
+        return self.request(api, "POST", json=payload, async_=async_, **request_kwargs)
+
+    @overload
+    def upload_single(
+        self, 
+        payload: dict, 
+        /, 
+        file: Buffer | SupportsRead[Buffer] | Iterable[Buffer], 
+        base_url: str | Callable[[], str] = "https://openapi-upload.123242.com", 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def upload_single(
+        self, 
+        payload: dict, 
+        /, 
+        file: Buffer | SupportsRead[Buffer] | Iterable[Buffer] | AsyncIterable[Buffer], 
+        base_url: str | Callable[[], str] = "https://openapi-upload.123242.com", 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def upload_single(
+        self, 
+        payload: dict, 
+        /, 
+        file: Buffer | SupportsRead[Buffer] | Iterable[Buffer] | AsyncIterable[Buffer], 
+        base_url: str | Callable[[], str] = "https://openapi-upload.123242.com", 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """单步上传
+
+        POST https://open-api.123pan.com/upload/v2/file/single/create
+
+        .. note::
+            - 文件名要小于 256 个字符且不能包含以下任何字符：``"\\/:*?|><``
+            - 文件名不能全部是空格
+            - 请求头包含 ``Content-Type: multipart/form-data``
+            - 此接口限制开发者上传单文件大小为 1 GB
+            - 上传域名是 ``client.upload_domain_open`` 响应中的域名
+            - 此接口用于实现小文件单步上传一次 HTTP 请求交互即可完成上传
+
+        .. admonition:: Reference
+
+            /API列表/文件管理/上传/V2（推荐）/单步上传
+
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/xhiht1uh3yp92pzc
+
+        :payload:
+            - containDir: "false" | "true" = "false" 💡 上传文件是否包含路径
+            - filename: str 💡 文件名，但 ``containDir`` 为 "true" 时，视为路径
+            - duplicate: 0 | 1 | 2 = 0 💡 处理同名：0: 跳过/报错 1: 保留/后缀编号 2: 替换/覆盖
+            - etag: str 💡 文件 md5
+            - parentFileID: int = 0 💡 父目录 id，根目录是 0
+            - size: int 💡 文件大小，单位：字节
+            - file: Any 💡 分片二进制流（请单独传递 ``file`` 参数）
+
+        :return:
+            返回的数据说明如下：
+
+            .. code:: python
+
+                {
+                    "completed": bool, # 是否上传完成（如果 "completed" 为 "true" 时，则说明上传完成）
+                    "fileID": int, # 文件 ID。当 123 云盘已有该文件,则会发生秒传。此时会将文件 ID 字段返回。唯一
+                }
+        """
+        payload = dict_to_lower_merge(payload, {
+            "parentFileId": "0", 
+            "containDir": "false", 
+        })
+        if "duplicate" in payload and not payload["duplicate"]:
+            del payload["duplicate"]
+        for k, v in payload.items():
+            if not isinstance(v, str):
+                payload[k] = str(v)
+        if async_:
+            headers, request_kwargs["data"] = encode_multipart_data_async(payload, {"file": file})
+        else:
+            headers, request_kwargs["data"] = encode_multipart_data(payload, {"file": file}) # type: ignore
+        request_kwargs["headers"] = {**(request_kwargs.get("headers") or {}), **headers}
+        return self.request(
+            "/upload/v2/file/single/create", 
+            "POST", 
+            base_url=base_url, 
+            async_=async_, 
+            **request_kwargs, 
+        )
+
+    @overload
+    def upload_slice(
+        self, 
+        payload: dict, 
+        /, 
+        slice: Buffer | SupportsRead[Buffer] | Iterable[Buffer], 
+        base_url: str | Callable[[], str] = "https://openapi-upload.123242.com", 
+        *, 
         async_: Literal[False] = False, 
         **request_kwargs, 
     ) -> dict:
         ...
     @overload
-    def upload_complete(
+    def upload_slice(
         self, 
-        payload: str | dict, 
+        payload: dict, 
         /, 
-        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        slice: Buffer | SupportsRead[Buffer] | Iterable[Buffer] | AsyncIterable[Buffer], 
+        base_url: str | Callable[[], str] = "https://openapi-upload.123242.com", 
         *, 
         async_: Literal[True], 
         **request_kwargs, 
     ) -> Coroutine[Any, Any, dict]:
         ...
-    def upload_complete(
+    def upload_slice(
         self, 
-        payload: str | dict, 
+        payload: dict, 
         /, 
-        base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
+        slice: Buffer | SupportsRead[Buffer] | Iterable[Buffer] | AsyncIterable[Buffer], 
+        base_url: str | Callable[[], str] = "https://openapi-upload.123242.com", 
         *, 
         async_: Literal[False, True] = False, 
         **request_kwargs, 
     ) -> dict | Coroutine[Any, Any, dict]:
-        """上传完毕
+        """上传文件文件
 
-        POST https://open-api.123pan.com/upload/v1/file/upload_complete
+        POST https://open-api.123pan.com/upload/v2/file/slice
+
+        .. note::
+            - 上传域名是创建文件接口响应中的 "servers"
+            - 请求头包含 ``Content-Type: multipart/form-data``
 
         .. admonition:: Reference
 
-            /API列表/文件管理/上传/V1/上传完毕
+            /API列表/文件管理/上传/V2（推荐）/上传分片
 
-            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/hkdmcmvg437rfu6x
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/txow0iqviqsgotfl
 
         :payload:
-            - preuploadID: str 💡 预上传 id
-
-        :return:
-            返回的数据说明如下：
-
-            .. code:: python
-
-                {
-                    "async": bool, # 是否需要异步查询上传结果
-                    "completed": bool, # 上传是否完成
-                    "fileID": int, # 上传的文件 id
-                }
+            - preuploadID: str 💡 预上传ID
+            - sliceNo: int     💡 分片序号，从 1 开始自增
+            - sliceMD5: str    💡 当前分片 md5
+            - slice: Any       💡 分片二进制流（请单独传递 ``slice`` 参数）
         """
-        api = complete_url("/upload/v1/file/upload_complete", base_url)
-        if not isinstance(payload, dict):
-            payload = {"preuploadID": payload}
-        return self.request(api, "POST", json=payload, async_=async_, **request_kwargs)
+        payload["sliceNo"] = str(payload.get("sliceNo", 1))
+        if async_:
+            headers, request_kwargs["data"] = encode_multipart_data_async(payload, {"slice": slice})
+        else:
+            headers, request_kwargs["data"] = encode_multipart_data(payload, {"slice": slice}) # type: ignore
+        request_kwargs["headers"] = {**(request_kwargs.get("headers") or {}), **headers}
+        return self.request(
+            "/upload/v2/file/slice", 
+            "POST", 
+            base_url=base_url, 
+            async_=async_, 
+            **request_kwargs, 
+        )
 
     @overload
-    def upload_result(
+    def upload_url(
         self, 
-        payload: str | dict, 
+        payload: dict, 
         /, 
         base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
         *, 
@@ -4675,9 +5041,9 @@ class P123OpenClient:
     ) -> dict:
         ...
     @overload
-    def upload_result(
+    def upload_url(
         self, 
-        payload: str | dict, 
+        payload: dict, 
         /, 
         base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
         *, 
@@ -4685,44 +5051,37 @@ class P123OpenClient:
         **request_kwargs, 
     ) -> Coroutine[Any, Any, dict]:
         ...
-    def upload_result(
+    def upload_url(
         self, 
-        payload: str | dict, 
+        payload: dict, 
         /, 
         base_url: str | Callable[[], str] = DEFAULT_OPEN_BASE_URL, 
         *, 
         async_: Literal[False, True] = False, 
         **request_kwargs, 
     ) -> dict | Coroutine[Any, Any, dict]:
-        """异步轮询获取上传结果
+        """获取上传地址&上传分片
 
-        POST https://open-api.123pan.com/upload/v1/file/upload_async_result
+        POST https://open-api.123pan.com/upload/v1/file/get_upload_url
+
+        .. note::
+            有多个分片时，轮流分别根据序号获取下载链接，然后 PUT 方法上传分片。由于上传链接会过期，所以没必要提前获取一大批
 
         .. admonition:: Reference
 
-            /API列表/文件管理/上传/V1/异步轮询获取上传结果
+            /API列表/文件管理/上传/V1（旧）/获取上传地址&上传分片
 
-            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/qgcosr6adkmm51h7
+            https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/sonz9n085gnz0n3m
 
         :payload:
             - preuploadID: str 💡 预上传 id
-
-        :return:
-            返回的数据说明如下：
-
-            .. code:: python
-
-                {
-                    "completed": bool, # 上传合并是否完成，如果为 False，请至少 1 秒后再发起轮询
-                    "fileID": int, # 上传的文件 id
-                }
+            - sliceNo: int     💡 分片序号，从 1 开始自增
         """
-        api = complete_url("/upload/v1/file/upload_async_result", base_url)
-        if not isinstance(payload, dict):
-            payload = {"preuploadID": payload}
+        api = complete_url("/upload/v1/file/get_upload_url", base_url)
         return self.request(api, "POST", json=payload, async_=async_, **request_kwargs)
 
-    # TODO: 如果已经有 md5 和 大小，则先尝试直接上传，而不是打开文件
+    # TODO: 如果已经有 md5 和 大小，则先尝试直接上传，而不是打开文件，等确定不能妙传，再打开文件
+    # TODO: 支持 v2 接口，以及上传单个文件的接口（可以设定一个参数，是否优先用 upload_single，只要文件大小在 1 GB 内）
     @overload
     def upload_file(
         self, 
@@ -4785,7 +5144,7 @@ class P123OpenClient:
 
         .. admonition:: Reference
 
-            /API列表/文件管理/上传/v1/💡上传流程说明
+            /API列表/文件管理/上传/V1（旧）/💡上传流程说明
 
             https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/il16qi0opiel4889
 
@@ -5150,10 +5509,15 @@ class P123OpenClient:
     transcode_upload_open = transcode_upload
     transcode_video_open = transcode_video
     upload_complete_open = upload_complete
+    upload_complete_v2_open = upload_complete_v2
     upload_create_open = upload_create
+    upload_create_v2_open = upload_create_v2
+    upload_domain_open = upload_domain
     upload_file_open = upload_file
     upload_list_open = upload_list
     upload_result_open = upload_result
+    upload_single_open = upload_single
+    upload_slice_open = upload_slice
     upload_url_open = upload_url
     user_info_open = user_info
 
@@ -5446,7 +5810,7 @@ class P123Client(P123OpenClient):
         """执行一次自动扫码，但并不因此更新 ``self.token``
 
         .. caution::
-            非会员目前只支持同时在线 3 台登录设备
+            非会员目前只支持同时在线 3 台登录设备，VIP 则支持同时在线 10 台
 
         :param platform: 用哪个设备平台扫码
         :param base_url: 接口的基地址
@@ -6668,6 +7032,8 @@ class P123Client(P123OpenClient):
                 - 3: 图片
                 - 4: 音频
                 - 5: 其它
+                - 6: 保险箱
+                - 7: 收藏夹
 
             - dateGranularity: int = <default> 💡 按时间分组展示
 
@@ -7062,6 +7428,98 @@ class P123Client(P123OpenClient):
             **request_kwargs, 
         )
 
+    @overload
+    def fs_safe_box_lock(
+        self, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def fs_safe_box_lock(
+        self, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def fs_safe_box_lock(
+        self, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """锁定保险箱
+
+        POST https://www.123pan.com/api/restful/goapi/v1/file/safe_box/auth/lock
+        """
+        return self.request(
+            "restful/goapi/v1/file/safe_box/auth/lock", 
+            "POST", 
+            base_url=base_url, 
+            async_=async_, 
+            **request_kwargs, 
+        )
+
+    @overload
+    def fs_safe_box_unlock(
+        self, 
+        payload: dict | int | str, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def fs_safe_box_unlock(
+        self, 
+        payload: dict | int | str, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def fs_safe_box_unlock(
+        self, 
+        payload: dict | int | str, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """解锁保险箱
+
+        .. note::
+            保险箱的 id，可以用 ``client.user_info()`` 接口获得，字段为 "SafeBoxFileId"
+
+        POST https://www.123pan.com/api/restful/goapi/v1/file/safe_box/auth/unlockbox
+
+        :payload:
+            - password: int | str 💡 6 位密码
+        """
+        if not isinstance(payload, dict):
+            payload = {"password": payload}
+        return self.request(
+            "restful/goapi/v1/file/safe_box/auth/unlockbox", 
+            "POST", 
+            json=payload, 
+            base_url=base_url, 
+            async_=async_, 
+            **request_kwargs, 
+        )
+
     @overload
     def fs_star(
         self, 
@@ -7903,6 +8361,64 @@ class P123Client(P123OpenClient):
 
     ########## Offline Download API ##########
 
+    @overload
+    def offline_task_abort(
+        self, 
+        payload: int | Iterable[int] | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def offline_task_abort(
+        self, 
+        payload: int | Iterable[int] | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def offline_task_abort(
+        self, 
+        payload: int | Iterable[int] | dict, 
+        /, 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """取消离线下载任务
+
+        POST https://www.123pan.com/api/offline_download/task/abort
+
+        :payload:
+            - task_ids: list[int]   💡 任务 id 列表
+            - is_abort: bool = True 💡 是否取消
+            - all: bool = False     💡 是否全部
+        """
+        if isinstance(payload, int):
+            payload = {"task_ids": [payload]}
+        elif not isinstance(payload, dict):
+            if not isinstance(payload, (list, tuple)):
+                payload = tuple(payload)
+            payload = {"task_ids": payload}
+        payload = cast(dict, payload)
+        payload.setdefault("is_abort", True)
+        payload.setdefault("all", False)
+        return self.request(
+            "offline_download/task/abort", 
+            "POST", 
+            json=payload, 
+            base_url=base_url, 
+            async_=async_, 
+            **request_kwargs, 
+        )
+
     @overload
     def offline_task_delete(
         self, 
@@ -8043,7 +8559,7 @@ class P123Client(P123OpenClient):
     ) -> dict | Coroutine[Any, Any, dict]:
         """解析下载链接
 
-        POST https://www.123pan.com/api/offline_download/task/resolve
+        POST https://www.123pan.com/api/v2/offline_download/task/resolve
 
         :payload:
             - urls: str = <default> 💡 下载链接，多个用 "\\n" 隔开（用于新建链接下载任务）
@@ -8054,7 +8570,7 @@ class P123Client(P123OpenClient):
         elif not isinstance(payload, dict):
             payload = {"urls": "\n".join(payload)}
         return self.request(
-            "offline_download/task/resolve", 
+            "v2/offline_download/task/resolve", 
             "POST", 
             json=payload, 
             base_url=base_url, 
@@ -8062,11 +8578,10 @@ class P123Client(P123OpenClient):
             **request_kwargs, 
         )
 
-    # TODO: 支持接受一个 Iterable[dict | int]，int 视为 id （select_file 为 [0]），dict 视为 resolve 信息
     @overload
     def offline_task_submit(
         self, 
-        payload: dict, 
+        payload: dict | Iterable[dict], 
         /, 
         base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
         *, 
@@ -8077,7 +8592,7 @@ class P123Client(P123OpenClient):
     @overload
     def offline_task_submit(
         self, 
-        payload: dict, 
+        payload: dict | Iterable[dict], 
         /, 
         base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
         *, 
@@ -8087,7 +8602,7 @@ class P123Client(P123OpenClient):
         ...
     def offline_task_submit(
         self, 
-        payload: dict, 
+        payload: dict | Iterable[dict], 
         /, 
         base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
         *, 
@@ -8096,7 +8611,19 @@ class P123Client(P123OpenClient):
     ) -> dict | Coroutine[Any, Any, dict]:
         """提交离线下载任务
 
-        POST https://www.123pan.com/api/offline_download/task/submit
+        POST https://www.123pan.com/api/v2/offline_download/task/submit
+
+        .. note::
+            提交信息来自 ``client.offline_task_resolve()`` 接口的响应，假设响应为 ``resp``，那么
+
+            .. code:: python
+
+                payload = {
+                    "resource_list": [{
+                        "resource_id": resource["id"], 
+                        "select_file_id": [info["id"] for info in resource["files"]], 
+                    } for resource in resp["data"]["list"]]
+                }
 
         :payload:
             - resource_list: list[Task] 💡 资源列表
@@ -8104,14 +8631,21 @@ class P123Client(P123OpenClient):
                 .. code:: python
 
                     File = {
-                        "resource_id": int, 
-                        "select_file": list[int] # 如果是链接下载，则传 [0]，如果BT下载，则传需要下载的文件在列表中的索引的列表
+                        "resource_id": int,          # 资源 id
+                        "select_file_id": list[int], # 此资源内的文件 id
                     }
 
             - upload_dir: int 💡 保存到目录的 id
         """
+        if not isinstance(payload, dict):
+            payload = {
+                "resource_list": [{
+                    "resource_id": resource["id"], 
+                    "select_file_id": [info["id"] for info in resource["files"]], 
+                } for resource in payload]
+            }
         return self.request(
-            "offline_download/task/submit", 
+            "v2/offline_download/task/submit", 
             "POST", 
             json=payload, 
             base_url=base_url, 
@@ -8167,6 +8701,71 @@ class P123Client(P123OpenClient):
             **request_kwargs, 
         )
 
+    @overload
+    def offline_add(
+        self, 
+        /, 
+        url: str | Iterable[str], 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def offline_add(
+        self, 
+        /, 
+        url: str | Iterable[str], 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def offline_add(
+        self, 
+        /, 
+        url: str | Iterable[str], 
+        base_url: str | Callable[[], str] = DEFAULT_BASE_URL, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """添加离线下载任务
+
+        POST https://www.123pan.com/api/offline_download/upload/seed
+
+        :param url: info_hash（只允许单个）、下载链接（多个用 "\n" 分隔）或者多个下载链接的迭代器
+        :param base_url: API 链接的基地址
+        :param async_: 是否异步
+        :param request_kwargs: 其它请求参数
+
+        :return: 接口响应信息
+        """
+        def gen_step():
+            if isinstance(url, str):
+                if len(url) == 40 and not url.strip(hexdigits):
+                    payload: dict = {"info_hash": url}
+                else:
+                    payload = {"urls": url}
+            else:
+                payload = {"urls": "\n".join(url)}
+            resp = yield self.offline_task_resolve(
+                payload, 
+                base_url=base_url, 
+                async_=async_, 
+                **request_kwargs, 
+            )
+            check_response(resp)
+            return self.offline_task_submit(
+                resp["data"]["list"], 
+                base_url=base_url, 
+                async_=async_, 
+                **request_kwargs, 
+            )
+        return run_gen_step(gen_step, async_)
+
     ########## Share API ##########
 
     @overload
@@ -9903,16 +10502,4 @@ with temp_globals():
             except KeyError:
                 CLIENT_API_METHODS_MAP[api] = [name]
 
-
-# TODO: 只有在使用密码登录和client_id登录的情况下，即使 token 失效，也可以重新登录（在有账号和密码的情况下，遇到 401 报错，会自动重新登录（需要加锁））
-# TODO: 新的上传方法需要封装：https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/xogi45g7okqk7svr
-# TODO: 对于某些工具的接口封装，例如 重复文件清理
-# TODO: 同步空间
-# TODO: 直链空间
-# TODO: 图床
-# TODO: 视频转码
-# TODO: 移入保险箱
-# TODO: 申诉和申诉列表
-# TODO: 歌单（以及批量加入歌单）
-# TODO: 最近查看
-# TODO: 消息通知列表和操作
+# TODO: 实现 check_for_relogin 参数，当报错 401，则重新登录（如果用的是 client_id，账号密码 或 refresh_token），调用 client.login()

{p123client-0.0.6.10.2.dist-info → p123client-0.0.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: p123client
-Version: 0.0.6.10.2
+Version: 0.0.7.1
 Summary: Python 123 webdisk client.
 Home-page: https://github.com/ChenyangGao/p123client
 License: MIT
@@ -399,7 +399,7 @@ print(get_downurl(client, "123://torrentgalaxy.db|1976025090|582aa8bfb0ad8e6f512
 
 ### 4. 直链服务
 
-需要先安装 [fastapi](https://pypi.org/project/blacksheep/)
+需要先安装 [blacksheep](https://www.neoteroi.dev/blacksheep/)
 
 ```console
 pip install 'blacksheep[uvicorn]'

p123client-0.0.7.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+LICENSE,sha256=o5242_N2TgDsWwFhPn7yr8YJNF7XsJM5NxUMtcT97bc,1100
+p123client/__init__.py,sha256=lcTiBpyNHH1HN4f1ueacumxkaahBNOUyvNA172UtSOU,214
+p123client/client.py,sha256=RK74Lrxldx7d2dDbLZlexsq6gPKRisR6A08yqC_DY2E,349673
+p123client/const.py,sha256=UYfBrgciCz7RJJPqCX6zwWlMoWiaTUwUU8bpFJyh0sM,348
+p123client/exception.py,sha256=Vn2UlJulY63z3cF7bnTjMlZ6og7gCw1pAA-dswFwKpQ,3174
+p123client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+p123client/tool/__init__.py,sha256=hnOwkk1CKk1CLGlhl6hlUl3BWNdqXdy8sWKXAGmOXHE,18812
+p123client/type.py,sha256=T17OzPQrnIG6w_Hzjc8TF_fFMKa-hQMSn1gff8pVcBc,56
+p123client-0.0.7.1.dist-info/LICENSE,sha256=o5242_N2TgDsWwFhPn7yr8YJNF7XsJM5NxUMtcT97bc,1100
+p123client-0.0.7.1.dist-info/METADATA,sha256=FGry4TF8zhNXf_IiPewQY919FeymlN4vftG-D_R8vCE,14657
+p123client-0.0.7.1.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+p123client-0.0.7.1.dist-info/RECORD,,

p123client-0.0.6.10.2.dist-info/RECORD

@@ -1,12 +0,0 @@
-LICENSE,sha256=o5242_N2TgDsWwFhPn7yr8YJNF7XsJM5NxUMtcT97bc,1100
-p123client/__init__.py,sha256=gfUum-q3f_XuXOk2HpArDAIxAlscZm8Fau1kiNkNFpg,214
-p123client/client.py,sha256=KT2pQ7i1BItsATjhassthRX-6NJvm2FubfNE78sVy5g,329482
-p123client/const.py,sha256=UYfBrgciCz7RJJPqCX6zwWlMoWiaTUwUU8bpFJyh0sM,348
-p123client/exception.py,sha256=Vn2UlJulY63z3cF7bnTjMlZ6og7gCw1pAA-dswFwKpQ,3174
-p123client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-p123client/tool/__init__.py,sha256=hnOwkk1CKk1CLGlhl6hlUl3BWNdqXdy8sWKXAGmOXHE,18812
-p123client/type.py,sha256=T17OzPQrnIG6w_Hzjc8TF_fFMKa-hQMSn1gff8pVcBc,56
-p123client-0.0.6.10.2.dist-info/LICENSE,sha256=o5242_N2TgDsWwFhPn7yr8YJNF7XsJM5NxUMtcT97bc,1100
-p123client-0.0.6.10.2.dist-info/METADATA,sha256=REM9IKAXw4nj8x4ZCKcGY7ew7SIdiDWGUoPrcty-Qdo,14657
-p123client-0.0.6.10.2.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-p123client-0.0.6.10.2.dist-info/RECORD,,