p115client 0.0.5.12.3__py3-none-any.whl → 0.0.5.13__py3-none-any.whl

p115client/client.py

@@ -59,6 +59,7 @@ from orjson import dumps, loads
 from p115cipher.fast import (
     rsa_encode, rsa_decode, ecdh_encode_token, ecdh_aes_encode, ecdh_aes_decode, make_upload_payload, 
 )
+from p115pickcode import id_to_pickcode
 from property import locked_cacheproperty
 from re import compile as re_compile
 from startfile import startfile, startfile_async # type: ignore
@@ -316,7 +317,7 @@ def cookies_equal(cookies1: None | str, cookies2: None | str, /) -> bool:
         return True
     cks1 = cookies_str_to_dict(cookies1)
     cks2 = cookies_str_to_dict(cookies2)
-    return cks1.get("UID", nan) == cks2.get("UID", nan) and cks1.get("SEID", nan) == cks2.get("SEID", nan)
+    return all(cks1.get(key, nan) == cks2.get(key, nan) for key in ("UID", "SEID"))
 
 
 def convert_digest(digest, /):
@@ -666,26 +667,20 @@ def normalize_attr_web[D: dict[str, Any]](
     if dict_cls is None:
         dict_cls = cast(type[D], dict)
     attr: dict[str, Any] = dict_cls()
-    is_directory = attr["is_dir"] = "fid" not in info
-    if not simple:
-        attr["is_directory"] = is_directory
-    if is_directory:
-        attr["id"] = int(info["cid"])        # cid => category_id
-        attr["parent_id"] = int(info["pid"]) # pid => parent_id
+    is_dir = attr["is_dir"] = "fid" not in info
+    if is_dir:
+        attr["id"] = int(info["cid"])        # category_id
+        attr["parent_id"] = int(info["pid"]) # parent_id
     else:
-        attr["id"] = int(info["fid"])        # fid => file_id
-        attr["parent_id"] = int(info["cid"])
-    attr["name"] = info["n"]
+        attr["id"] = int(info["fid"])        # file_id
+        attr["parent_id"] = int(info["cid"]) # category_id
+    attr["name"] = info.get("n") or info["file_name"]
     attr["sha1"] = info.get("sha") or ""
     attr["size"] = int(info.get("s") or 0)
     if "pc" in info:
         attr["pickcode"] = info["pc"]
-        if not simple:
-            attr["pick_code"] = attr["pickcode"]
-            if "pt" in info:
-                attr["pick_time"] = int(info["pt"] or 0)
-            if "e" in info:
-                attr["pick_expire"] = int(info["e"] or 0)
+    else:
+        attr["pickcode"] = id_to_pickcode(attr["id"], is_dir=is_dir)
     if simple:
         if "c" in info:
             attr["is_collect"] = int(info["c"])
@@ -694,7 +689,8 @@ def normalize_attr_web[D: dict[str, Any]](
         if "te" in info:
             attr["mtime"] = int(info["te"])
     else:
-        attr["ico"] = info.get("ico", "folder" if is_directory else "")
+        attr["pick_code"] = attr["pickcode"]
+        attr["ico"] = info.get("ico", "folder" if is_dir else "")
         if "te" in info:
             attr["mtime"] = attr["user_utime"] = int(info["te"])
         if "tp" in info:
@@ -704,39 +700,37 @@ def normalize_attr_web[D: dict[str, Any]](
         if "tu" in info:
             attr["utime"] = int(info["tu"])
         if t := info.get("t"):
-            if isinstance(t, (int, float)):
-                attr["time"] = t
-            elif t.isdecimal():
-                attr["time"] = int(t)
+            attr["time"] = try_parse_int(t)
         if "fdes" in info:
             val = info["fdes"]
             if isinstance(val, str):
                 attr["desc"] = val
-            attr["has_desc"] = bool(val)
+            attr["has_desc"] = 1 if val else 0
         for key, name in (
             ("aid", "area_id"), 
             ("audio_play_long", "audio_play_long"), 
-            ("c", "violated"), 
             ("c", "is_collect"), 
             ("cc", "cover"), 
+            ("cc", "category_cover"), 
             ("class", "class"), 
             ("current_time", "current_time"), 
-            #("d", "has_desc"), 
+            ("d", "has_desc"), 
             ("dp", "dir_path"), 
+            ("e", "pick_expire"), 
             ("fl", "labels"), 
-            ("hdf", "hidden"), 
             ("hdf", "is_private"), 
             ("is_top", "is_top"), 
             ("ispl", "show_play_long"), 
             ("issct", "is_shortcut"), 
             ("iv", "is_video"), 
             ("last_time", "last_time"), 
-            ("m", "star"), 
             ("m", "is_mark"), 
+            ("m", "star"), 
             ("ns", "name_show"), 
-            #("p", "has_pass"), 
+            ("p", "has_pass"), 
             ("play_long", "play_long"), 
             ("played_end", "played_end"), 
+            ("pt", "pick_time"), 
             ("score", "score"), 
             ("sh", "is_share"), 
             ("sta", "status"), 
@@ -748,6 +742,8 @@ def normalize_attr_web[D: dict[str, Any]](
         if vdi := info.get("vdi"):
             attr["defination"] = vdi
             match vdi:
+                case 1:
+                    attr["defination_str"] = "video-sd"
                 case 2:
                     attr["defination_str"] = "video-hd"
                 case 3:
@@ -760,7 +756,7 @@ def normalize_attr_web[D: dict[str, Any]](
                     attr["defination_str"] = "video-origin"
                 case _:
                     attr["defination_str"] = "video-sd"
-    if is_directory:
+    if is_dir:
         attr["type"] = 0
     elif info.get("iv") or "vdi" in info:
         attr["type"] = 4
@@ -814,18 +810,16 @@ def normalize_attr_app[D: dict[str, Any]](
     if dict_cls is None:
         dict_cls = cast(type[D], dict)
     attr: dict[str, Any] = dict_cls()
-    is_directory = attr["is_dir"] = info["fc"] == "0" # fc => file_category
-    if not simple:
-        attr["is_directory"] = is_directory
-    attr["id"] = int(info["fid"])        # fid => file_id
-    attr["parent_id"] = int(info["pid"]) # pid => parent_id
+    is_dir = attr["is_dir"] = info["fc"] == "0" # file_category
+    attr["id"] = int(info["fid"])          # file_id
+    attr["parent_id"] = int(info["pid"])        # parent_id
     attr["name"] = info["fn"]
     sha1 = attr["sha1"] = info.get("sha1") or ""
     attr["size"] = int(info.get("fs") or 0)
     if "pc" in info:
         attr["pickcode"] = info["pc"]
-        if not simple:
-            attr["pick_code"] = attr["pickcode"]
+    else:
+        attr["pickcode"] = id_to_pickcode(attr["id"], is_dir=is_dir)
     if simple:
         if "ic" in info:
             attr["is_collect"] = int(info["ic"])
@@ -834,6 +828,7 @@ def normalize_attr_app[D: dict[str, Any]](
         if "upt" in info:
             attr["mtime"] = int(info["upt"])
     else:
+        attr["pick_code"] = attr["pickcode"]
         attr["ico"] = info.get("ico", "folder" if attr["is_dir"] else "")
         if "thumb" in info:
             thumb = info["thumb"]
@@ -854,21 +849,19 @@ def normalize_attr_app[D: dict[str, Any]](
             ("def", "defination"),        # 视频清晰度：1:标清 2:高清 3:超清 4:1080P 5:4k 100:原画
             ("def2", "defination2"),      # 视频清晰度：1:标清 2:高清 3:超清 4:1080P 5:4k 100:原画
             ("fatr", "audio_play_long"),  # 音频长度
-            ("fco", "cover"),             # 文件夹封面
-            ("fco", "folder_cover"),      # 文件夹封面
+            ("fco", "cover"),             # 目录封面
+            ("fco", "folder_cover"),      # 目录封面
             ("fdesc", "desc"),            # 文件备注
             ("fl", "labels"),             # 文件标签，得到 1 个字典列表
             ("flabel", "fflabel"),        # 文件标签（一般为空）
             ("fta", "status"),            # 文件状态：0/2:未上传完成，1:已上传完成
             ("ftype", "file_type"),       # 文件类型代码
-            ("ic", "violated"),           # 是否违规
             ("ic", "is_collect"),         # 是否违规
             ("is_top", "is_top"),         # 是否置顶
-            ("ism", "star"),              # 是否星标
             ("ism", "is_mark"),           # 是否星标
-            ("isp", "hidden"),            # 是否加密隐藏（隐藏模式中显示）
+            ("ism", "star"),              # 是否星标（别名）
             ("isp", "is_private"),        # 是否加密隐藏（隐藏模式中显示）
-            ("ispl", "show_play_long"),   # 是否统计文件夹下视频时长
+            ("ispl", "show_play_long"),   # 是否统计目录下视频时长
             ("iss", "is_share"),          # 是否共享
             ("issct", "is_shortcut"),     # 是否在快捷入口
             ("isv", "is_video"),          # 是否为视频
@@ -884,7 +877,7 @@ def normalize_attr_app[D: dict[str, Any]](
         ):
             if key in info:
                 attr[name] = try_parse_int(info[key])
-    if is_directory:
+    if is_dir:
         attr["type"] = 0
     elif (thumb := info.get("thumb")) and thumb.startswith("?"):
         attr["type"] = 2
@@ -942,15 +935,15 @@ def normalize_attr_app2[D: dict[str, Any]](
     attr: dict[str, Any] = dict_cls()
     if "file_id" in info and "parent_id" in info:
         if "file_category" in info:
-            is_directory = not int(info["file_category"])
+            is_dir = not int(info["file_category"])
         else:
-            is_directory = bool(info.get("sha1") or info.get("file_sha1"))
+            is_dir = bool(info.get("sha1") or info.get("file_sha1"))
         attr["id"] = int(info["file_id"])
         attr["parent_id"] = int(info["parent_id"])
         attr["name"] = info["file_name"]
     else:
-        is_directory = "file_id" not in info
-        if is_directory:
+        is_dir = "file_id" not in info
+        if is_dir:
             attr["id"] = int(info["file_id"])
             attr["parent_id"] = int(info["category_id"])
             attr["name"] = info["file_name"]
@@ -958,15 +951,13 @@ def normalize_attr_app2[D: dict[str, Any]](
             attr["id"] = int(info["category_id"])
             attr["parent_id"] = int(info["parent_id"])
             attr["name"] = info["category_name"]
-    attr["is_dir"] = is_directory
-    if not simple:
-        attr["is_directory"] = is_directory
+    attr["is_dir"] = is_dir
     attr["sha1"] = info.get("sha1") or info.get("file_sha1") or ""
     attr["size"] = int(info.get("file_size") or 0)
     if "pick_code" in info:
         attr["pickcode"] = info["pick_code"]
-        if not simple:
-            attr["pick_code"] = attr["pickcode"]
+    else:
+        attr["pickcode"] = id_to_pickcode(attr["id"], is_dir=is_dir)
     if simple:
         if "is_collect" in info:
             attr["is_collect"] = int(info["is_collect"])
@@ -975,7 +966,8 @@ def normalize_attr_app2[D: dict[str, Any]](
         if "user_ptime" in info:
             attr["mtime"] = int(info["user_ptime"])
     else:
-        if is_directory:
+        attr["pick_code"] = attr["pickcode"]
+        if is_dir:
             if "thumb_url" in info:
                 attr["thumb"] = info["thumb_url"]
             if "file_description" in info:
@@ -1004,13 +996,6 @@ def normalize_attr_app2[D: dict[str, Any]](
         attr["ico"] = info.get("ico", "folder" if attr["is_dir"] else "")
         if "fl" in info:
             attr["labels"] = info["fl"]
-        for key, name in (
-            ("is_collect", "violated"), 
-            ("is_mark", "star"), 
-            ("is_private", "hidden"), 
-        ):
-            if key in info:
-                attr[name] = int(info[key] or 0)
         for name in (
             "area_id", 
             "can_delete", 
@@ -1047,7 +1032,9 @@ def normalize_attr_app2[D: dict[str, Any]](
         ):
             if name in info:
                 attr[name] = try_parse_int(info[name])
-    if is_directory:
+        if "is_mark" in attr:
+            attr["star"] = attr["is_mark"]
+    if is_dir:
         attr["type"] = 0
     elif "thumb_url" in info:
         attr["type"] = 2
@@ -1454,7 +1441,7 @@ class ClientRequestMixin:
             headers = IgnoreCaseDict(self.headers)
         headers.update(request_kwargs.get("headers") or {})
         if m := CRE_API_match(url):
-            headers["host"] = m.expand(r"\1.api.115.com")
+            headers.setdefault("host", m.expand(r"\1.api.115.com"))
         request_kwargs["headers"] = headers
         if ecdh_encrypt:
             url = make_url(url, _default_k_ec)
@@ -3259,7 +3246,7 @@ class P115OpenClient(ClientRequestMixin):
                     name=info["file_name"], 
                     size=int(info["file_size"]), 
                     sha1=info["sha1"], 
-                    is_directory=not url, 
+                    is_dir=not url, 
                     headers=resp["headers"], 
                 )
             raise P115FileNotFoundError(
@@ -3534,7 +3521,7 @@ class P115OpenClient(ClientRequestMixin):
             - source: str = <default>
             - sys_dir: int | str = <default> 💡 系统通用目录
             - star: 0 | 1 = <default> 💡 是否星标文件
-            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示文件夹：1:展示 0:不展示
+            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示目录：1:展示 0:不展示
             - suffix: str = <default> 💡 后缀名（优先级高于 `type`）
             - type: int = <default> 💡 文件类型
 
@@ -3784,6 +3771,13 @@ class P115OpenClient(ClientRequestMixin):
 
         GET https://proapi.115.com/open/ufile/search
 
+        .. attention::
+            最多只能取回前 10,000 条数据，也就是 `limit + offset <= 10_000`，不过可以一次性取完
+
+            不过就算正确设置了 `limit` 和 `offset`，并且总数据量大于 `limit + offset`，可能也不足 `limit`，这应该是 bug，也就是说，就算数据总量足够你也取不到足量
+
+            它返回数据中的 `count` 字段的值表示总数据量（即使你只能取前 10,000 条），往往并不准确，最多能当作一个可参考的估计值
+
         .. hint::
             相当于 `P115Client.fs_search_app2`
 
@@ -4250,7 +4244,7 @@ class P115OpenClient(ClientRequestMixin):
             - save_path: str 💡 保存到 `wp_path_id` 对应目录下的相对路径
             - torrent_sha1: str 💡 种子文件的 sha1
             - wanted: str 💡 选择文件进行下载（是数字索引，从 0 开始计数，用 "," 分隔）
-            - wp_path_id: int | str = <default> 💡 保存目标文件夹 id
+            - wp_path_id: int | str = <default> 💡 保存目标目录 id
         """
         api = complete_proapi("/open/offline/add_task_bt ", base_url)
         return self.request(url=api, method="POST", data=payload, async_=async_, **request_kwargs)
@@ -4775,8 +4769,8 @@ class P115OpenClient(ClientRequestMixin):
             - topupload: int = 0 💡 上传调度文件类型调度标记
 
                 -  0: 单文件上传任务标识 1 条单独的文件上传记录
-                -  1: 文件夹任务调度的第 1 个子文件上传请求标识 1 次文件夹上传记录
-                -  2: 文件夹任务调度的其余后续子文件不作记作单独上传的上传记录 
+                -  1: 目录任务调度的第 1 个子文件上传请求标识 1 次目录上传记录
+                -  2: 目录任务调度的其余后续子文件不作记作单独上传的上传记录 
                 - -1: 没有该参数
 
             - sign_key: str = "" 💡 二次验证时读取文件的范围
@@ -6708,7 +6702,7 @@ class P115Client(P115OpenClient):
         if is_open_api:
             headers["cookie"] = ""
         if m := CRE_API_match(url):
-            headers["host"] = m.expand(r"\1.api.115.com")
+            headers.setdefault("host", m.expand(r"\1.api.115.com"))
         if ecdh_encrypt:
             url = make_url(url, _default_k_ec)
             if data:
@@ -7943,7 +7937,7 @@ class P115Client(P115OpenClient):
                     pickcode=pickcode, 
                     name=resp["file_name"], 
                     size=int(resp["file_size"]), 
-                    is_directory=not resp["state"], 
+                    is_dir=not resp["state"], 
                     headers=resp["headers"], 
                 )
         else:
@@ -7962,7 +7956,7 @@ class P115Client(P115OpenClient):
                         url, 
                         pickcode=pickcode, 
                         name=unquote(urlsplit(url).path.rsplit("/", 1)[-1]), 
-                        is_directory=False, 
+                        is_dir=False, 
                         headers=resp["headers"], 
                     )
                 for fid, info in resp["data"].items():
@@ -7979,7 +7973,7 @@ class P115Client(P115OpenClient):
                         name=info["file_name"], 
                         size=int(info["file_size"]), 
                         sha1=info["sha1"], 
-                        is_directory=not url, 
+                        is_dir=not url, 
                         headers=resp["headers"], 
                     )
                 raise P115FileNotFoundError(
@@ -8302,6 +8296,7 @@ class P115Client(P115OpenClient):
         :payload:
             - pick_code: str
             - full_name: str
+            - dl: int = <default>
         """
         api = complete_proapi("/2.0/ufile/extract_down_file", base_url, app)
         headers = request_kwargs.get("headers")
@@ -8520,8 +8515,9 @@ class P115Client(P115OpenClient):
         GET https://webapi.115.com/files/extract_folders
 
         :payload:
-            - pick_code: str
-            - full_dir_name: str
+            - pick_code: str 💡 压缩包文件的提取码
+            - full_dir_name: str 💡 多个用逗号 "," 隔开
+            - full_file_name: str = <default> 💡 多个用逗号 "," 隔开
         """
         api = complete_webapi("/files/extract_folders", base_url=base_url)
         return self.request(url=api, params=payload, async_=async_, **request_kwargs)
@@ -8562,9 +8558,9 @@ class P115Client(P115OpenClient):
         POST https://webapi.115.com/files/extract_folders
 
         :payload:
-            - pick_code: str
-            - full_dir_name: str  💡 多个用逗号 "," 隔开
-            - full_file_name: str 💡 多个用逗号 "," 隔开
+            - pick_code: str 💡 压缩包文件的提取码
+            - full_dir_name: str 💡 多个用逗号 "," 隔开
+            - full_file_name: str = <default> 💡 多个用逗号 "," 隔开
         """
         api = complete_webapi("/files/extract_folders", base_url=base_url)
         return self.request(url=api, method="POST", data=payload, async_=async_, **request_kwargs)
@@ -9924,64 +9920,6 @@ class P115Client(P115OpenClient):
         api = complete_webapi("/files/edit", base_url=base_url)
         return self.request(url=api, method="POST", data=payload, async_=async_, **request_kwargs)
 
-    @overload
-    def fs_edit_app(
-        self, 
-        payload: int | str | tuple[int | str] | list | dict, 
-        /, 
-        app: str = "android", 
-        base_url: bool | str | Callable[[], str] = False, 
-        *, 
-        async_: Literal[False] = False, 
-        **request_kwargs, 
-    ) -> dict:
-        ...
-    @overload
-    def fs_edit_app(
-        self, 
-        payload: int | str | tuple[int | str] | list | dict, 
-        /, 
-        app: str = "android", 
-        base_url: bool | str | Callable[[], str] = False, 
-        *, 
-        async_: Literal[True], 
-        **request_kwargs, 
-    ) -> Coroutine[Any, Any, dict]:
-        ...
-    def fs_edit_app(
-        self, 
-        payload: int | str | tuple[int | str] | list | dict, 
-        /, 
-        app: str = "android", 
-        base_url: bool | str | Callable[[], str] = False, 
-        *, 
-        async_: Literal[False, True] = False, 
-        **request_kwargs, 
-    ) -> dict | Coroutine[Any, Any, dict]:
-        """设置文件或目录（备注、标签等）
-
-        POST https://proapi.115.com/android/files/update
-
-        :payload:
-            - file_id: int | str
-            - file_id[]: int | str
-            - ...
-            - file_id[0]: int | str
-            - file_id[1]: int | str
-            - ...
-            - file_desc: str = <default> 💡 可以用 html
-            - file_label: int | str = <default> 💡 标签 id，多个用逗号 "," 隔开
-            - fid_cover: int | str = <default> 💡 封面图片的文件 id，多个用逗号 "," 隔开，如果要删除，值设为 0 即可
-            - show_play_long: 0 | 1 = <default> 💡 文件名称显示时长
-            - ...
-        """
-        api = complete_proapi("/files/update", base_url, app)
-        if isinstance(payload, (int, str)):
-            payload = {"file_id": payload}
-        elif isinstance(payload, tuple):
-            payload = {f"file_id[i]": p for i, p in enumerate(payload)}
-        return self.request(url=api, method="POST", data=payload, async_=async_, **request_kwargs)
-
     @overload
     def _fs_edit_set(
         self, 
@@ -10485,7 +10423,7 @@ class P115Client(P115OpenClient):
             - source: str = <default>
             - sys_dir: int | str = <default>
             - star: 0 | 1 = <default> 💡 是否星标文件
-            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示文件夹：1:展示 0:不展示
+            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示目录：1:展示 0:不展示
             - suffix: str = <default> 💡 后缀名（优先级高于 `type`）
             - suffix_type: int = <default>
             - type: int = <default> 💡 文件类型
@@ -10627,7 +10565,7 @@ class P115Client(P115OpenClient):
             - source: str = <default>
             - sys_dir: int | str = <default> 💡 系统通用目录
             - star: 0 | 1 = <default> 💡 是否星标文件
-            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示文件夹：1:展示 0:不展示
+            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示目录：1:展示 0:不展示
             - suffix: str = <default> 💡 后缀名（优先级高于 `type`）
             - type: int = <default> 💡 文件类型
 
@@ -10757,7 +10695,7 @@ class P115Client(P115OpenClient):
             - source: str = <default>
             - sys_dir: int | str = <default>
             - star: 0 | 1 = <default> 💡 是否星标文件
-            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示文件夹：1:展示 0:不展示
+            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示目录：1:展示 0:不展示
             - suffix: str = <default> 💡 后缀名（优先级高于 `type`）
             - type: int = <default> 💡 文件类型
 
@@ -10877,7 +10815,7 @@ class P115Client(P115OpenClient):
             - source: str = <default>
             - sys_dir: int | str = <default>
             - star: 0 | 1 = <default> 💡 是否星标文件
-            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示文件夹：1:展示 0:不展示
+            - stdir: 0 | 1 = <default> 💡 筛选文件时，是否显示目录：1:展示 0:不展示
             - suffix: str = <default> 💡 后缀名（优先级高于 `type`）
             - type: int = <default> 💡 文件类型
 
@@ -11125,11 +11063,11 @@ class P115Client(P115OpenClient):
         return self.request(url=api, params=payload, async_=async_, **request_kwargs)
 
     @overload
-    def fs_top_set(
+    def fs_files_update_app(
         self, 
-        payload: int | str | Iterable[int | str] | dict, 
+        payload: int | str | tuple[int | str] | list | dict, 
         /, 
-        top: bool = True, 
+        app: str = "android", 
         base_url: bool | str | Callable[[], str] = False, 
         *, 
         async_: Literal[False] = False, 
@@ -11137,42 +11075,50 @@ class P115Client(P115OpenClient):
     ) -> dict:
         ...
     @overload
-    def fs_top_set(
+    def fs_files_update_app(
         self, 
-        payload: int | str | Iterable[int | str] | dict, 
+        payload: int | str | tuple[int | str] | list | dict, 
         /, 
-        top: bool = True, 
+        app: str = "android", 
         base_url: bool | str | Callable[[], str] = False, 
         *, 
         async_: Literal[True], 
         **request_kwargs, 
     ) -> Coroutine[Any, Any, dict]:
         ...
-    def fs_top_set(
+    def fs_files_update_app(
         self, 
-        payload: int | str | Iterable[int | str] | dict, 
+        payload: int | str | tuple[int | str] | list | dict, 
         /, 
-        top: bool = True, 
+        app: str = "android", 
         base_url: bool | str | Callable[[], str] = False, 
         *, 
         async_: Literal[False, True] = False, 
         **request_kwargs, 
     ) -> dict | Coroutine[Any, Any, dict]:
-        """文件或目录置顶
+        """设置（若干个）文件或目录（名字、备注、标签等）
 
-        POST https://webapi.115.com/files/top
+        POST https://proapi.115.com/android/files/update
 
         :payload:
-            - file_id: int | str 💡 文件或目录的 id，多个用逗号 "," 隔开
-            - top: 0 | 1 = 1
+            - file_id: int | str
+            - file_id[]: int | str
+            - ...
+            - file_id[0]: int | str
+            - file_id[1]: int | str
+            - ...
+            - file_desc: str = <default> 💡 可以用 html
+            - file_label: int | str = <default> 💡 标签 id，多个用逗号 "," 隔开
+            - file_name: str = <default>        💡 文件或目录名
+            - fid_cover: int | str = <default>  💡 封面图片的文件 id，多个用逗号 "," 隔开，如果要删除，值设为 0 即可
+            - show_play_long: 0 | 1 = <default> 💡 文件名称显示时长
+            - ...
         """
-        api = complete_webapi("/files/top", base_url=base_url)
+        api = complete_proapi("/files/update", base_url, app)
         if isinstance(payload, (int, str)):
-            payload = {"file_id": payload, "top": int(top)}
-        elif not isinstance(payload, dict):
-            payload = {"file_id": ",".join(map(str, payload)), "top": int(top)}
-        else:
-            payload = {"top": int(top), **payload}
+            payload = {"file_id": payload}
+        elif isinstance(payload, tuple):
+            payload = {f"file_id[i]": p for i, p in enumerate(payload)}
         return self.request(url=api, method="POST", data=payload, async_=async_, **request_kwargs)
 
     @overload
@@ -11262,6 +11208,61 @@ class P115Client(P115OpenClient):
             payload = {f"show_play_long[{id}]": is_set for id in ids}
         return self.fs_batch_edit(payload, async_=async_, **request_kwargs)
 
+    @overload
+    def fs_folder_update_app(
+        self, 
+        payload: dict, 
+        /, 
+        app: str = "android", 
+        base_url: bool | str | Callable[[], str] = False, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def fs_folder_update_app(
+        self, 
+        payload: dict, 
+        /, 
+        app: str = "android", 
+        base_url: bool | str | Callable[[], str] = False, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def fs_folder_update_app(
+        self, 
+        payload: dict, 
+        /, 
+        app: str = "android", 
+        base_url: bool | str | Callable[[], str] = False, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """设置文件或目录，或者创建目录
+
+        POST https://proapi.115.com/android/folder/update
+
+        .. note::
+            如果提供了 `cid` 和 `name`，则表示对 `cid` 对应的文件或目录进行改名，否则创建目录
+
+        :payload:
+            - name: str 💡 名字
+            - pid: int = 0 💡 在此目录 id 下创建目录
+            - aid: int = 1 💡 area_id
+            - cid: int = <default> 💡 文件或目录的 id，优先级高于 `pid`
+            - user_id: int = <default> 💡 不用管
+            - ...
+        """
+        api = complete_proapi("/folder/update", base_url, app)
+        payload = dict(payload, user_id=self.user_id)
+        payload.setdefault("aid", 1)
+        payload.setdefault("pid", 0)
+        return self.request(url=api, method="POST", data=payload, async_=async_, **request_kwargs)
+
     @overload
     def fs_hide(
         self, 
@@ -11615,7 +11616,7 @@ class P115Client(P115OpenClient):
               - 播放视频: 3
               - 上传: 4
               - ？？: 5
-              - ？？: 6
+              - ？？: 6（似乎是一些在离线、转存等过程中有重名的目录）
               - 接收: 7
               - 移动: 8
 
@@ -11770,7 +11771,7 @@ class P115Client(P115OpenClient):
               - 播放视频: 3
               - 上传: 4
               - ？？: 5
-              - ？？: 6
+              - ？？: 6（似乎是一些在离线、转存等过程中有重名的目录）
               - 接收: 7
               - 移动: 8
 
@@ -11830,7 +11831,7 @@ class P115Client(P115OpenClient):
               - 播放视频: 3
               - 上传: 4
               - ？？: 5
-              - ？？: 6
+              - ？？: 6（似乎是一些在离线、转存等过程中有重名的目录）
               - 接收: 7
               - 移动: 8
         """
@@ -11891,7 +11892,7 @@ class P115Client(P115OpenClient):
               - 播放视频: 3
               - 上传: 4
               - ？？: 5
-              - ？？: 6
+              - ？？: 6（似乎是一些在离线、转存等过程中有重名的目录）
               - 接收: 7
               - 移动: 8
         """
@@ -12763,7 +12764,7 @@ class P115Client(P115OpenClient):
         async_: Literal[False, True] = False, 
         **request_kwargs, 
     ) -> dict | Coroutine[Any, Any, dict]:
-        """为文件或目录设置标签，此接口是对 `fs_edit_app` 的封装
+        """为文件或目录设置标签，此接口是对 `fs_files_update_app` 的封装
 
         .. attention::
             这个接口会把标签列表进行替换，而不是追加
@@ -12991,8 +12992,9 @@ class P115Client(P115OpenClient):
     @overload
     def fs_mkdir_app(
         self, 
-        payload: dict, 
+        payload: dict | str, 
         /, 
+        pid: int = 0, 
         app: str = "android", 
         base_url: bool | str | Callable[[], str] = False, 
         *, 
@@ -13003,8 +13005,9 @@ class P115Client(P115OpenClient):
     @overload
     def fs_mkdir_app(
         self, 
-        payload: dict, 
+        payload: dict | str, 
         /, 
+        pid: int = 0, 
         app: str = "android", 
         base_url: bool | str | Callable[[], str] = False, 
         *, 
@@ -13014,26 +13017,32 @@ class P115Client(P115OpenClient):
         ...
     def fs_mkdir_app(
         self, 
-        payload: dict, 
+        payload: dict | str, 
         /, 
+        pid: int = 0, 
         app: str = "android", 
         base_url: bool | str | Callable[[], str] = False, 
         *, 
         async_: Literal[False, True] = False, 
         **request_kwargs, 
     ) -> dict | Coroutine[Any, Any, dict]:
-        """新建目录
-
-        .. todo::
-            待破解
-
-            - name: str 💡 目录名
+        """新建目录，此接口是对 `fs_folder_update_app` 的封装
 
-        POST https://proapi.115.com/android/1.0/folder/update
+        :payload:
+            - name: str    💡 名字
+            - pid: int = 0 💡 上级目录的 id
         """
-        api = complete_proapi("/folder/update", base_url, app)
-        payload = dict(payload, user_id=self.user_id)
-        return self.request(url=api, method="POST", data=payload, async_=async_, **request_kwargs)
+        if isinstance(payload, str):
+            payload = {"pid": pid, "name": payload}
+        else:
+            payload = {"pid": pid, **payload}
+        return self.fs_folder_update_app(
+            payload, 
+            app=app, 
+            base_url=base_url, 
+            async_=async_, 
+            **request_kwargs, 
+        )
 
     @overload
     def fs_move(
@@ -14612,7 +14621,11 @@ class P115Client(P115OpenClient):
         GET https://webapi.115.com/files/search
 
         .. attention::
-            最多只能取回前 10,000 条数据，也就是 limit + offset <= 10_000
+            最多只能取回前 10,000 条数据，也就是 `limit + offset <= 10_000`，不过可以一次性取完
+
+            不过就算正确设置了 `limit` 和 `offset`，并且总数据量大于 `limit + offset`，可能也不足 `limit`，这应该是 bug，也就是说，就算数据总量足够你也取不到足量
+
+            它返回数据中的 `count` 字段的值表示总数据量（即使你只能取前 10,000 条），往往并不准确，最多能当作一个可参考的估计值
 
             这个接口实际上不支持在查询中直接设置排序，只能由 `P115Client.fs_order_set` 设置
 
@@ -14709,12 +14722,16 @@ class P115Client(P115OpenClient):
         async_: Literal[False, True] = False, 
         **request_kwargs, 
     ) -> dict | Coroutine[Any, Any, dict]:
-        """搜索文件或目录（提示：好像最多只能罗列前 10,000 条数据，也就是 limit + offset <= 10_000）
+        """搜索文件或目录
 
         GET https://proapi.115.com/android/files/search
 
         .. attention::
-            最多只能取回前 10,000 条数据，也就是 limit + offset <= 10_000
+            最多只能取回前 10,000 条数据，也就是 `limit + offset <= 10_000`，不过可以一次性取完
+
+            不过就算正确设置了 `limit` 和 `offset`，并且总数据量大于 `limit + offset`，可能也不足 `limit`，这应该是 bug，也就是说，就算数据总量足够你也取不到足量
+
+            它返回数据中的 `count` 字段的值表示总数据量（即使你只能取前 10,000 条），往往并不准确，最多能当作一个可参考的估计值
 
         :payload:
             - aid: int | str = 1 💡 area_id。1:正常文件 7:回收站文件 12:瞬间文件 120:彻底删除文件、简历附件
@@ -14804,12 +14821,16 @@ class P115Client(P115OpenClient):
         async_: Literal[False, True] = False, 
         **request_kwargs, 
     ) -> dict | Coroutine[Any, Any, dict]:
-        """搜索文件或目录（提示：好像最多只能罗列前 10,000 条数据，也就是 limit + offset <= 10_000）
+        """搜索文件或目录
 
         GET https://proapi.115.com/android/2.0/ufile/search
 
         .. attention::
-            最多只能取回前 10,000 条数据，也就是 limit + offset <= 10_000
+            最多只能取回前 10,000 条数据，也就是 `limit + offset <= 10_000`，不过可以一次性取完
+
+            不过就算正确设置了 `limit` 和 `offset`，并且总数据量大于 `limit + offset`，可能也不足 `limit`，这应该是 bug，也就是说，就算数据总量足够你也取不到足量
+
+            它返回数据中的 `count` 字段的值表示总数据量（即使你只能取前 10,000 条），往往并不准确，最多能当作一个可参考的估计值
 
         :payload:
             - aid: int | str = 1 💡 area_id。1:正常文件 7:回收站文件 12:瞬间文件 120:彻底删除文件、简历附件
@@ -15398,6 +15419,57 @@ class P115Client(P115OpenClient):
             payload = {"sys_dir": payload}
         return self.request(url=api, params=payload, async_=async_, **request_kwargs)
 
+    @overload
+    def fs_top_set(
+        self, 
+        payload: int | str | Iterable[int | str] | dict, 
+        /, 
+        top: bool = True, 
+        base_url: bool | str | Callable[[], str] = False, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def fs_top_set(
+        self, 
+        payload: int | str | Iterable[int | str] | dict, 
+        /, 
+        top: bool = True, 
+        base_url: bool | str | Callable[[], str] = False, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def fs_top_set(
+        self, 
+        payload: int | str | Iterable[int | str] | dict, 
+        /, 
+        top: bool = True, 
+        base_url: bool | str | Callable[[], str] = False, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """文件或目录置顶
+
+        POST https://webapi.115.com/files/top
+
+        :payload:
+            - file_id: int | str 💡 文件或目录的 id，多个用逗号 "," 隔开
+            - top: 0 | 1 = 1
+        """
+        api = complete_webapi("/files/top", base_url=base_url)
+        if isinstance(payload, (int, str)):
+            payload = {"file_id": payload, "top": int(top)}
+        elif not isinstance(payload, dict):
+            payload = {"file_id": ",".join(map(str, payload)), "top": int(top)}
+        else:
+            payload = {"top": int(top), **payload}
+        return self.request(url=api, method="POST", data=payload, async_=async_, **request_kwargs)
+
     @overload
     def fs_video(
         self, 
@@ -19347,11 +19419,11 @@ class P115Client(P115OpenClient):
     ) -> dict | Coroutine[Any, Any, dict]:
         """获取分享链接的某个目录中可下载的文件的列表（只含文件，不含目录，任意深度，简略信息）
 
+        GET https://webapi.115.com/share/downlist
+
         .. attention::
             cid 不能为 0
 
-        GET https://webapi.115.com/share/downlist
-
         :payload:
             - share_code: str
             - receive_code: str
@@ -19396,11 +19468,11 @@ class P115Client(P115OpenClient):
     ) -> dict | Coroutine[Any, Any, dict]:
         """获取分享链接的某个目录中可下载的文件的列表（只含文件，不含目录，任意深度，简略信息）
 
+        GET https://proapi.115.com/app/share/downlist
+
         .. attention::
             cid 不能为 0
 
-        GET https://proapi.115.com/app/share/downlist
-
         :payload:
             - share_code: str
             - receive_code: str
@@ -19502,7 +19574,7 @@ class P115Client(P115OpenClient):
                 name=info["fn"], 
                 size=int(info["fs"]), 
                 sha1=info.get("sha1", ""), 
-                is_directory=not url, 
+                is_dir=not url, 
             )
         if async_:
             async def async_request() -> P115URL:
@@ -19834,7 +19906,7 @@ class P115Client(P115OpenClient):
             - share_code: str
             - receive_code: str
             - file_id: int | str         💡 有多个时，用逗号 "," 分隔
-            - cid: int | str = <default> 💡 这是你网盘的目录 cid
+            - cid: int | str = <default> 💡 这是你网盘的目录 cid，如果不指定则用默认
             - is_check: 0 | 1 = <default>
         """
         api = complete_webapi("/share/receive", base_url=base_url)
@@ -19882,7 +19954,7 @@ class P115Client(P115OpenClient):
             - share_code: str
             - receive_code: str
             - file_id: int | str         💡 有多个时，用逗号 "," 分隔
-            - cid: int | str = <default> 💡 这是你网盘的目录 cid
+            - cid: int | str = <default> 💡 这是你网盘的目录 cid，如果不指定则用默认
             - is_check: 0 | 1 = <default>
         """
         api = complete_proapi("/2.0/share/receive", base_url, app)
@@ -20039,7 +20111,7 @@ class P115Client(P115OpenClient):
         GET https://webapi.115.com/share/search
 
         .. attention::
-            最多只能取回前 10,000 条数据，也就是 limit + offset <= 10_000
+            最多只能取回前 10,000 条数据，也就是 `limit + offset <= 10_000`，不过可以一次性取完
 
         :payload:
             - share_code: str    💡 分享码
@@ -20254,7 +20326,7 @@ class P115Client(P115OpenClient):
                 name=info["fn"], 
                 size=int(info["fs"]), 
                 sha1=info.get("sha1", ""), 
-                is_directory=not url, 
+                is_dir=not url, 
             )
         if async_:
             async def async_request() -> P115URL: