p115client 0.0.5.10.4__py3-none-any.whl → 0.0.5.11__py3-none-any.whl

p115client/tool/iterdir.py

@@ -13,6 +13,7 @@ __all__ = [
     "iter_selected_nodes_using_edit", "iter_selected_nodes_using_star_event", 
     "iter_selected_dirs_using_star", "iter_files_with_dirname", "iter_files_with_path", 
     "iter_files_with_path_by_export_dir", "iter_parents_3_level", "iter_dir_nodes", 
+    "search_for_any_file", 
 ]
 __doc__ = "这个模块提供了一些和目录信息罗列有关的函数"
 
@@ -59,30 +60,6 @@ from .life import iter_life_behavior_once, life_show
 from .util import posix_escape_name, share_extract_payload, unescape_115_charref
 
 
-WEBAPI_BASE_URLS = (
-    "http://webapi.115.com", 
-    "https://webapi.115.com", 
-    "http://webapi.115.com", 
-    "http://115cdn.com/webapi", 
-    "http://webapi.115.com", 
-    "http://115vod.com/webapi", 
-)
-PROAPI_BASE_URLS = (
-    "http://proapi.115.com", 
-    "https://proapi.115.com", 
-    "http://proapi.115.com", 
-    "https://proapi.115.com", 
-)
-APS_BASE_URLS = (
-    "http://115cdn.com/aps", 
-    "http://aps.115.com", 
-    "http://115vod.com/aps", 
-)
-
-_n_get_ancestors = 0
-_n_get_count = 0
-
-
 class DirNode(NamedTuple):
     name: str
     parent_id: int
@@ -152,7 +129,7 @@ def get_path_to_cid(
     root_id: None | int = None, 
     escape: None | bool | Callable[[str], str] = True, 
     refresh: bool = False, 
-    id_to_dirnode: None | dict[int, tuple[str, int] | DirNode] = None, 
+    id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
     app: str = "web", 
     *, 
     async_: Literal[False] = False, 
@@ -166,7 +143,7 @@ def get_path_to_cid(
     root_id: None | int = None, 
     escape: None | bool | Callable[[str], str] = True, 
     refresh: bool = False, 
-    id_to_dirnode: None | dict[int, tuple[str, int] | DirNode] = None, 
+    id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
     app: str = "web", 
     *, 
     async_: Literal[True], 
@@ -179,7 +156,7 @@ def get_path_to_cid(
     root_id: None | int = None, 
     escape: None | bool | Callable[[str], str] = True, 
     refresh: bool = False, 
-    id_to_dirnode: None | dict[int, tuple[str, int] | DirNode] = None, 
+    id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
     app: str = "web", 
     *, 
     async_: Literal[False, True] = False, 
@@ -215,14 +192,31 @@ def get_path_to_cid(
     escape = cast(None | Callable[[str], str], escape)
     if id_to_dirnode is None:
         id_to_dirnode = ID_TO_DIRNODE_CACHE[client.user_id]
+    elif id_to_dirnode is ...:
+        id_to_dirnode = {}
     def gen_step():
         nonlocal cid
         parts: list[str] = []
         if cid and (refresh or cid not in id_to_dirnode):
-            if app in ("", "web", "desktop", "harmony"):
-                resp = yield client.fs_files({"cid": cid, "limit": 1}, async_=async_, **request_kwargs)
+            if not isinstance(client, P115Client) or app == "open":
+                resp = yield client.fs_files_open(
+                    {"cid": cid, "cur": 1, "nf": 1, "hide_data": 1}, 
+                    async_=async_, 
+                    **request_kwargs, 
+                )
+            elif app in ("", "web", "desktop", "harmony"):
+                resp = yield client.fs_files_aps(
+                    {"cid": cid, "limit": 1, "nf": 1, "star": 1}, 
+                    async_=async_, 
+                    **request_kwargs, 
+                )
             else:
-                resp = yield client.fs_files_app({"cid": cid, "hide_data": 1}, async_=async_, **request_kwargs)
+                resp = yield client.fs_files_app(
+                    {"cid": cid, "cur": 1, "nf": 1, "hide_data": 1}, 
+                    app=app, 
+                    async_=async_, 
+                    **request_kwargs, 
+                )
             check_response(resp)
             if cid and int(resp["path"][-1]["cid"]) != cid:
                 raise FileNotFoundError(ENOENT, cid)
@@ -244,7 +238,7 @@ def get_path_to_cid(
             return "/" + path
         else:
             return path
-    return run_gen_step(gen_step, async_=async_)
+    return run_gen_step(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -252,6 +246,8 @@ def get_file_count(
     client: str | P115Client, 
     cid: int = 0, 
     id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
+    app: str = "web", 
+    use_fs_files: bool = True, 
     *, 
     async_: Literal[False] = False, 
     **request_kwargs, 
@@ -262,6 +258,8 @@ def get_file_count(
     client: str | P115Client, 
     cid: int = 0, 
     id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
+    app: str = "web", 
+    use_fs_files: bool = True, 
     *, 
     async_: Literal[True], 
     **request_kwargs, 
@@ -271,18 +269,19 @@ def get_file_count(
     client: str | P115Client, 
     cid: int = 0, 
     id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
+    app: str = "web", 
+    use_fs_files: bool = True, 
     *, 
     async_: Literal[False, True] = False, 
     **request_kwargs, 
 ) -> int | Coroutine[Any, Any, int]:
     """获取文件总数
 
-    .. caution::
-        我通过一些经验，搭配了多个接口的占比和参数分布，可能不够合理，以后会根据实际情况调整
-
     :param client: 115 客户端或 cookies
     :param cid: 目录 id
     :param id_to_dirnode: 字典，保存 id 到对应文件的 `DirNode(name, parent_id)` 命名元组的字典
+    :param app: 使用某个 app （设备）的接口
+    :param use_fs_files: 使用 `client.fs_files`，否则使用 `client.fs_category_get`
     :param async_: 是否异步
     :param request_kwargs: 其它请求参数
 
@@ -292,75 +291,78 @@ def get_file_count(
         client = P115Client(client, check_for_relogin=True)
     if id_to_dirnode is None:
         id_to_dirnode = ID_TO_DIRNODE_CACHE[client.user_id]
-    n_webapi = len(WEBAPI_BASE_URLS)
-    n_proapi = len(PROAPI_BASE_URLS)
-    n_apsapi = len(APS_BASE_URLS)
-    n_api = n_webapi * 2 + n_proapi * 2 + n_apsapi
-    def get_resp():
-        global _n_get_count
-        n = _n_get_count % n_api
-        if n < n_webapi:
-            _n_get_count += 1
+    def get_resp_of_fs_files(id: int, /):
+        if not isinstance(client, P115Client) or app == "open":
+            return client.fs_files_open(
+                {"cid": id, "hide_data": 1, "show_dir": 0}, 
+                async_=async_, 
+                **request_kwargs, 
+            )
+        elif app in ("", "web", "desktop", "harmony"):
             return client.fs_files(
-                {"cid": cid, "limit": 1, "show_dir": 0}, 
-                base_url=WEBAPI_BASE_URLS[n], 
+                {"cid": id, "limit": 1, "show_dir": 0}, 
                 async_=async_, 
                 **request_kwargs, 
             )
-        n -= n_webapi
-        if n < n_proapi:
-            _n_get_count += 1
+        elif app == "aps":
+            return client.fs_files_aps(
+                {"cid": id, "limit": 1, "show_dir": 0}, 
+                async_=async_, 
+                **request_kwargs, 
+            )
+        else:
             return client.fs_files_app(
-                {"cid": cid, "hide_data": 1, "show_dir": 0}, 
-                base_url=PROAPI_BASE_URLS[n], 
+                {"cid": id, "hide_data": 1, "show_dir": 0}, 
+                app=app, 
                 async_=async_, 
                 **request_kwargs, 
             )
-        n -= n_proapi
-        if n < n_apsapi:
-            _n_get_count += 1
-            return client.fs_files_aps(
-                {"cid": cid, "limit": 1, "show_dir": 0}, 
-                base_url=APS_BASE_URLS[n], 
+    def get_resp_of_category_get(id: int, /):
+        if not isinstance(client, P115Client) or app == "open":
+            return client.fs_info_open(
+                id, 
                 async_=async_, 
                 **request_kwargs, 
             )
-        n -= n_apsapi
-        if n < n_webapi:
-            _n_get_count += 1
+        elif app in ("", "web", "desktop", "harmony", "aps"):
             return client.fs_category_get(
-                cid, 
-                base_url=WEBAPI_BASE_URLS[n], 
+                id, 
+                async_=async_, 
+                **request_kwargs, 
+            )
+        else:
+            return client.fs_category_get_app(
+                id, 
+                app=app, 
                 async_=async_, 
                 **request_kwargs, 
             )
-        n -= n_webapi
-        _n_get_count += 1
-        return client.fs_category_get_app(
-            cid, 
-            base_url=PROAPI_BASE_URLS[n], 
-            async_=async_, 
-            **request_kwargs, 
-        )
     def gen_step():
-        if cid == 0:
+        if not cid:
             resp = yield client.fs_space_summury(async_=async_, **request_kwargs)
             check_response(resp)
             return sum(v["count"] for k, v in resp["type_summury"].items() if k.isupper())
-        resp = yield get_resp()
-        if not resp:
-            raise FileNotFoundError(ENOENT, cid)
-        check_response(resp)
-        resp["cid"] = cid
-        if "path" in resp:
+        if use_fs_files:
+            resp = yield get_resp_of_fs_files(cid)
+            check_response(resp)
             if cid != int(resp["path"][-1]["cid"]):
+                resp["cid"] = cid
                 raise NotADirectoryError(ENOTDIR, resp)
             if id_to_dirnode is not ...:
                 for info in resp["path"][1:]:
                     id_to_dirnode[int(info["cid"])] = DirNode(info["name"], int(info["pid"]))
             return int(resp["count"])
         else:
+            resp = yield get_resp_of_category_get(cid)
+            if not resp:
+                raise FileNotFoundError(ENOENT, cid)
+            if "paths" not in resp:
+                check_response(resp)
+                resp = resp["data"]
+                if not resp:
+                    raise FileNotFoundError(ENOENT, cid)
             if int(resp["file_category"]):
+                resp["cid"] = cid
                 raise NotADirectoryError(ENOTDIR, resp)
             if id_to_dirnode is not ...:
                 pid = 0
@@ -368,14 +370,15 @@ def get_file_count(
                     node = DirNode(info["file_name"], pid)
                     id_to_dirnode[(pid := int(info["file_id"]))] = node
             return int(resp["count"]) - int(resp.get("folder_count") or 0)
-    return run_gen_step(gen_step, async_=async_)
+    return run_gen_step(gen_step, simple=True, async_=async_)
 
 
 @overload
 def get_ancestors(
     client: str | P115Client, 
-    attr: dict, 
+    attr: int | dict, 
     id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
+    app: str = "web", 
     *, 
     async_: Literal[False] = False, 
     **request_kwargs, 
@@ -384,8 +387,9 @@ def get_ancestors(
 @overload
 def get_ancestors(
     client: str | P115Client, 
-    attr: dict, 
+    attr: int | dict, 
     id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
+    app: str = "web", 
     *, 
     async_: Literal[True], 
     **request_kwargs, 
@@ -393,20 +397,19 @@ def get_ancestors(
     ...
 def get_ancestors(
     client: str | P115Client, 
-    attr: dict, 
+    attr: int | dict, 
     id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
+    app: str = "web", 
     *, 
     async_: Literal[False, True] = False, 
     **request_kwargs, 
 ) -> list[dict] | Coroutine[Any, Any, list[dict]]:
     """获取某个节点对应的祖先节点列表（只有 id、parent_id 和 name 的信息）
 
-    .. caution::
-        我通过一些经验，搭配了多个接口的占比和参数分布，可能不够合理，以后会根据实际情况调整
-
     :param client: 115 客户端或 cookies
-    :param attr: 待查询节点的信息（必须有 id 和 parent_id）
+    :param attr: 待查询节点 `id` 或信息（必须有 `id`，可选有 `parent_id`）
     :param id_to_dirnode: 字典，保存 id 到对应文件的 `DirNode(name, parent_id)` 命名元组的字典
+    :param app: 使用某个 app （设备）的接口
     :param async_: 是否异步
     :param request_kwargs: 其它请求参数
 
@@ -424,91 +427,170 @@ def get_ancestors(
         client = P115Client(client, check_for_relogin=True)
     if id_to_dirnode is None:
         id_to_dirnode = ID_TO_DIRNODE_CACHE[client.user_id]
-    n_webapi = len(WEBAPI_BASE_URLS)
-    n_proapi = len(PROAPI_BASE_URLS)
-    n_apsapi = len(APS_BASE_URLS)
-    n_api = n_webapi * 2 + n_proapi * 2 + n_apsapi
-    def get_resp():
-        global _n_get_ancestors
-        n = _n_get_ancestors % n_api
-        if n < n_webapi:
-            _n_get_ancestors += 1
+    def get_resp_of_fs_files(id: int, /):
+        if not isinstance(client, P115Client) or app == "open":
+            return client.fs_files_open(
+                {"cid": id, "cur": 1, "nf": 1, "hide_data": 1}, 
+                async_=async_, 
+                **request_kwargs, 
+            )
+        elif app in ("", "web", "desktop", "harmony"):
             return client.fs_files(
-                {"cid": attr["parent_id"], "limit": 1}, 
-                base_url=WEBAPI_BASE_URLS[n], 
+                {"cid": id, "limit": 1, "nf": 1, "star": 1}, 
                 async_=async_, 
                 **request_kwargs, 
             )
-        n -= n_webapi
-        if n < n_proapi:
-            _n_get_ancestors += 1
+        elif app == "aps":
+            return client.fs_files_aps(
+                {"cid": id, "limit": 1, "nf": 1, "star": 1}, 
+                async_=async_, 
+                **request_kwargs, 
+            )
+        else:
             return client.fs_files_app(
-                {"cid": attr["parent_id"], "hide_data": 1}, 
-                base_url=PROAPI_BASE_URLS[n], 
+                {"cid": id, "cur": 1, "nf": 1, "hide_data": 1}, 
+                app=app, 
                 async_=async_, 
                 **request_kwargs, 
             )
-        n -= n_proapi
-        if n < n_apsapi:
-            _n_get_ancestors += 1
-            return client.fs_files_aps(
-                {"cid": attr["parent_id"], "limit": 1}, 
-                base_url=APS_BASE_URLS[n], 
+    def get_resp_of_category_get(id: int, /):
+        if not isinstance(client, P115Client) or app == "open":
+            return client.fs_info_open(
+                id, 
                 async_=async_, 
                 **request_kwargs, 
             )
-        if attr.get("is_dir", False) or attr.get("is_directory", False):
-            _n_get_ancestors = 0
-            return get_resp()
-        n -= n_apsapi
-        if n < n_webapi:
-            _n_get_ancestors += 1
+        elif app in ("", "web", "desktop", "harmony", "aps"):
             return client.fs_category_get(
-                attr["id"], 
-                base_url=WEBAPI_BASE_URLS[n], 
+                id, 
+                async_=async_, 
+                **request_kwargs, 
+            )
+        else:
+            return client.fs_category_get_app(
+                id, 
+                app=app, 
                 async_=async_, 
                 **request_kwargs, 
             )
-        n -= n_webapi
-        _n_get_ancestors += 1
-        return client.fs_category_get_app(
-            attr["id"], 
-            base_url=PROAPI_BASE_URLS[n], 
-            async_=async_, 
-            **request_kwargs, 
-        )
     def gen_step():
-        if not attr["parent_id"]:
-            return [{"id": 0, "parent_id": 0, "name": ""}]
-        resp = yield get_resp()
-        if not resp:
-            raise FileNotFoundError(ENOENT, attr)
-        check_response(resp)
-        resp["attr"] = attr
         ancestors: list[dict] = [{"id": 0, "parent_id": 0, "name": ""}]
         add_ancestor = ancestors.append
         pid = 0
-        if "path" in resp:
-            if attr["parent_id"] != int(resp["path"][-1]["cid"]):
-                raise FileNotFoundError(ENOENT, resp)
-            for info in resp["path"][1:]:
-                add_ancestor({
-                    "parent_id": pid, 
-                    "id": (pid := int(info["cid"])), 
-                    "name": info["name"], 
-                })
+        is_completed = False
+        if isinstance(attr, dict):
+            fid = cast(int, attr["id"])
+            if not fid:
+                return ancestors
+            is_dir: None | bool = attr.get("is_dir") or attr.get("is_directory")
+            if is_dir is None:
+                if "parent_id" in attr:
+                    cid = cast(int, attr["parent_id"])
+                    resp = yield get_resp_of_fs_files(cid)
+                    if cid != int(resp["path"][-1]["cid"]):
+                        resp["attr"] = attr
+                        raise FileNotFoundError(ENOENT, resp)
+                    for info in resp["path"][1:]:
+                        add_ancestor({
+                            "parent_id": pid, 
+                            "id": (pid := int(info["cid"])), 
+                            "name": info["name"], 
+                        })
+                    if id_to_dirnode is not ...:
+                        for ans in ancestors[1:]:
+                            id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
+                    if "name" in attr:
+                        name = attr["name"]
+                        is_dir = bool(attr.get("is_dir"))
+                    else:
+                        resp = yield client.fs_file_skim(attr["id"], async_=async_, **request_kwargs)
+                        check_response(resp)
+                        name = unescape_115_charref(resp["data"]["file_name"])
+                        is_dir = not resp["data"]["sha1"]
+                    ans = {"id": fid, "parent_id": pid, "name": name}
+                    add_ancestor(ans)
+                    if is_dir and id_to_dirnode is not ...:
+                        id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
+                    is_completed = True
+            elif is_dir:
+                resp = yield get_resp_of_fs_files(fid)
+                if fid != int(resp["path"][-1]["cid"]):
+                    resp["attr"] = attr
+                    raise FileNotFoundError(ENOENT, resp)
+                for info in resp["path"][1:]:
+                    add_ancestor({
+                        "parent_id": pid, 
+                        "id": (pid := int(info["cid"])), 
+                        "name": info["name"], 
+                    })
+                if id_to_dirnode is not ...:
+                    for ans in ancestors[1:]:
+                        id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
+                is_completed = True
+            else:
+                resp = yield get_resp_of_category_get(fid)
+                if not resp:
+                    raise FileNotFoundError(ENOENT, attr)
+                if "paths" not in resp:
+                    check_response(resp)
+                    resp = resp["data"]
+                    if not resp:
+                        raise FileNotFoundError(ENOENT, attr)
+                for info in resp["paths"]:
+                    add_ancestor({
+                        "parent_id": pid, 
+                        "id": (pid := int(info["file_id"])), 
+                        "name": info["file_name"], 
+                    })
+                if id_to_dirnode is not ...:
+                    for ans in ancestors[1:]:
+                        id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
+                ans = {"id": fid, "parent_id": pid, "name": resp["file_name"]}
+                add_ancestor(ans)
+                if not resp.get("sha1") and id_to_dirnode is not ...:
+                    id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
+                is_completed = True
         else:
-            for info in resp["paths"]:
-                add_ancestor({
-                    "parent_id": pid, 
-                    "id": (pid := int(info["file_id"])), 
-                    "name": info["file_name"], 
-                })
-        if id_to_dirnode is not ...:
-            for ans in ancestors[1:]:
-                id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
+            fid = attr
+        if not is_completed:
+            if not fid:
+                return ancestors
+            resp = yield get_resp_of_fs_files(fid)
+            check_response(resp)
+            if fid == int(resp["path"][-1]["cid"]):
+                for info in resp["path"][1:]:
+                    add_ancestor({
+                        "parent_id": pid, 
+                        "id": (pid := int(info["cid"])), 
+                        "name": info["name"], 
+                    })
+                if id_to_dirnode is not ...:
+                    for ans in ancestors[1:]:
+                        id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
+            else:
+                resp = yield get_resp_of_category_get(fid)
+                if not resp:
+                    raise FileNotFoundError(ENOENT, fid)
+                if "paths" not in resp:
+                    check_response(resp)
+                    resp = resp["data"]
+                    if not resp:
+                        raise FileNotFoundError(ENOENT, fid)
+                for info in resp["paths"]:
+                    add_ancestor({
+                        "parent_id": pid, 
+                        "id": (pid := int(info["file_id"])), 
+                        "name": info["file_name"], 
+                    })
+                if id_to_dirnode is not ...:
+                    for ans in ancestors[1:]:
+                        id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
+                ans = {"id": fid, "parent_id": pid, "name": resp["file_name"]}
+                add_ancestor(ans)
+                if not resp.get("sha1") and id_to_dirnode is not ...:
+                    id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
         return ancestors
-    return run_gen_step(gen_step, async_=async_)
+    return run_gen_step(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -516,7 +598,7 @@ def get_ancestors_to_cid(
     client: str | P115Client, 
     cid: int = 0, 
     refresh: bool = False, 
-    id_to_dirnode: None  | dict[int, tuple[str, int] | DirNode] = None, 
+    id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
     app: str = "web", 
     *, 
     async_: Literal[False] = False, 
@@ -528,7 +610,7 @@ def get_ancestors_to_cid(
     client: str | P115Client, 
     cid: int = 0, 
     refresh: bool = False, 
-    id_to_dirnode: None  | dict[int, tuple[str, int] | DirNode] = None, 
+    id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
     app: str = "web", 
     *, 
     async_: Literal[True], 
@@ -539,7 +621,7 @@ def get_ancestors_to_cid(
     client: str | P115Client, 
     cid: int = 0, 
     refresh: bool = False, 
-    id_to_dirnode: None  | dict[int, tuple[str, int] | DirNode] = None, 
+    id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
     app: str = "web", 
     *, 
     async_: Literal[False, True] = False, 
@@ -569,14 +651,31 @@ def get_ancestors_to_cid(
         client = P115Client(client, check_for_relogin=True)
     if id_to_dirnode is None:
         id_to_dirnode = ID_TO_DIRNODE_CACHE[client.user_id]
+    elif id_to_dirnode is ...:
+        id_to_dirnode = {}
     def gen_step():
         nonlocal cid
         parts: list[dict] = []
         if cid and (refresh or cid not in id_to_dirnode):
-            if app in ("", "web", "desktop", "harmony"):
-                resp = yield client.fs_files({"cid": cid, "limit": 1}, async_=async_, **request_kwargs)
+            if not isinstance(client, P115Client) or app == "open":
+                resp = yield client.fs_files_open(
+                    {"cid": cid, "cur": 1, "nf": 1, "hide_data": 1}, 
+                    async_=async_, 
+                    **request_kwargs, 
+                )
+            elif app in ("", "web", "desktop", "harmony"):
+                resp = yield client.fs_files_aps(
+                    {"cid": cid, "limit": 1, "nf": 1, "star": 1}, 
+                    async_=async_, 
+                    **request_kwargs, 
+                )
             else:
-                resp = yield client.fs_files_app({"cid": cid, "hide_data": 1}, async_=async_, **request_kwargs)
+                resp = yield client.fs_files_app(
+                    {"cid": cid, "cur": 1, "nf": 1, "hide_data": 1}, 
+                    app=app, 
+                    async_=async_, 
+                    **request_kwargs, 
+                )
             check_response(resp)
             if cid and int(resp["path"][-1]["cid"]) != cid:
                 raise FileNotFoundError(ENOENT, cid)
@@ -593,7 +692,7 @@ def get_ancestors_to_cid(
             parts.append({"id": 0, "name": "", "parent_id": 0})
             parts.reverse()
         return parts
-    return run_gen_step(gen_step, async_=async_)
+    return run_gen_step(gen_step, simple=True, async_=async_)
 
 
 # TODO: 使用 search 接口以在特定目录之下搜索某个名字，以便减少风控
@@ -605,7 +704,7 @@ def get_id_to_path(
     ensure_file: None | bool = None, 
     is_posixpath: bool = False, 
     refresh: bool = False, 
-    id_to_dirnode: None | dict[int, tuple[str, int] | DirNode] = None, 
+    id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
     app: str = "web", 
     dont_use_getid: bool = False, 
     *, 
@@ -621,7 +720,7 @@ def get_id_to_path(
     ensure_file: None | bool = None, 
     is_posixpath: bool = False, 
     refresh: bool = False, 
-    id_to_dirnode: None | dict[int, tuple[str, int] | DirNode] = None, 
+    id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
     app: str = "web", 
     dont_use_getid: bool = False, 
     *, 
@@ -636,7 +735,7 @@ def get_id_to_path(
     ensure_file: None | bool = None, 
     is_posixpath: bool = False, 
     refresh: bool = False, 
-    id_to_dirnode: None | dict[int, tuple[str, int] | DirNode] = None, 
+    id_to_dirnode: None | EllipsisType | dict[int, tuple[str, int] | DirNode] = None, 
     app: str = "web", 
     dont_use_getid: bool = False, 
     *, 
@@ -788,7 +887,7 @@ def get_id_to_path(
                     if ensure_file is None or ensure_file ^ attr["is_dir"]:
                         return P115ID(attr["id"], attr, about="path")
         raise error
-    return run_gen_step(gen_step, async_=async_)
+    return run_gen_step(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -842,7 +941,7 @@ def get_id_to_pickcode(
         check_response(resp)
         data = resp["data"]
         return P115ID(data["file_id"], data, about="pickcode")
-    return run_gen_step(gen_step, async_=async_)
+    return run_gen_step(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -902,7 +1001,7 @@ def get_id_to_sha1(
             else:
                 raise FileNotFoundError(ENOENT, file_sha1)
         return P115ID(data["file_id"], data, about="sha1", file_sha1=file_sha1)
-    return run_gen_step(gen_step, async_=async_)
+    return run_gen_step(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -954,8 +1053,8 @@ def iter_nodes_skim(
             check_response(resp)
             for a in resp["data"]:
                 a["file_name"] = unescape_115_charref(a["file_name"])
-            yield YieldFrom(resp["data"], identity=True)
-    return run_gen_step_iter(gen_step, async_=async_)
+            yield YieldFrom(resp["data"], may_await=False)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -1092,7 +1191,7 @@ def _iter_fs_files(
                             attr = _overview_attr(info)
                             if attr.is_dir:
                                 id_to_dirnode[attr.id] = DirNode(attr.name, attr.parent_id)
-                    yield YieldFrom(resp["data"], identity=True)
+                    yield YieldFrom(resp["data"], may_await=False)
                 else:
                     for info in resp["data"]:
                         attr = _overview_attr(info)
@@ -1101,10 +1200,10 @@ def _iter_fs_files(
                                 id_to_dirnode[attr.id] = DirNode(attr.name, attr.parent_id)
                         elif ensure_file is False:
                             return
-                        yield Yield(info, identity=True)
+                        yield Yield(info, may_await=False)
         except (StopAsyncIteration, StopIteration):
             pass
-    return run_gen_step_iter(gen_step, async_=async_)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -1493,8 +1592,8 @@ def ensure_attr_path[D: dict](
                         warn(f"{type(e).__module__}.{type(e).__qualname__}: {e} of {attr}", category=P115Warning)
                 attr.setdefault("ancestors", None)
                 attr.setdefault("path", "")
-            yield Yield(attr, identity=True)
-    return run_gen_step_iter(gen_step, async_=async_)
+            yield Yield(attr, may_await=False)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -1976,10 +2075,10 @@ def iterdir(
                         name = escape(name)
                     attr["path"] = dirname + name
                 return attr
-            yield YieldFrom(do_map(process, it), identity=True) # type: ignore
+            yield YieldFrom(do_map(process, it), may_await=False) # type: ignore
         else:
-            yield YieldFrom(do_map(normalize_attr, it), identity=True) # type: ignore
-    return run_gen_step_iter(gen_step, async_=async_)
+            yield YieldFrom(do_map(normalize_attr, it), may_await=False) # type: ignore
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 def iterdir_limited(
@@ -2088,8 +2187,8 @@ def iterdir_limited(
                 attr["path"] = dirname + name
             yield attr
     def gen_step():
-        resp: dict = yield run_gen_step(request, async_=async_)
-        yield YieldFrom(iter_attrs(resp), identity=True)
+        resp: dict = yield run_gen_step(request, simple=True, async_=async_)
+        yield YieldFrom(iter_attrs(resp), may_await=False)
         count = int(resp["count"])
         count_fetched = len(resp["data"])
         if count > count_fetched:
@@ -2117,30 +2216,30 @@ def iterdir_limited(
             count_top = count_top_dirs + count_top_files
             if count <= count_fetched * 2 - count_top:
                 resp = request({"asc": 0, "offset": count_top, "limit": count - count_fetched})
-                yield YieldFrom(iter_attrs(resp), identity=True)
+                yield YieldFrom(iter_attrs(resp), may_await=False)
                 return
             if diff := count_dirs - len(seen_dirs):
                 if diff > count_fetched - count_top_dirs:
                     resp = request({"nf": 1, "offset": len(seen_dirs)})
-                    yield YieldFrom(iter_attrs(resp), identity=True)
+                    yield YieldFrom(iter_attrs(resp), may_await=False)
                     diff = count_dirs - len(seen_dirs)
                 if diff > 0:
                     resp = request({"asc": 0, "nf": 1, "offset": count_top_dirs, "limit": diff})
-                    yield YieldFrom(iter_attrs(resp), identity=True)
+                    yield YieldFrom(iter_attrs(resp), may_await=False)
                     
                     if diff := count_dirs - len(seen_dirs):
                         warn(f"lost {diff} directories: cid={cid}", category=P115Warning)
             if diff := count_files - len(seen_files):
                 if diff > count_fetched - count_top_files:
                     resp = request({"show_dir": 0, "offset": len(seen_files)})
-                    yield YieldFrom(iter_attrs(resp), identity=True)
+                    yield YieldFrom(iter_attrs(resp), may_await=False)
                     diff = count_files - len(seen_files)
                 if diff > 0:
                     resp = request({"asc": 0, "show_dir": 0, "offset": count_top_files, "limit": diff})
-                    yield YieldFrom(iter_attrs(resp), identity=True)
+                    yield YieldFrom(iter_attrs(resp), may_await=False)
                     if diff := count_files - len(seen_files):
                         warn(f"lost {diff} files: cid={cid}", category=P115Warning)
-    return run_gen_step_iter(gen_step, async_=async_)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -2493,9 +2592,9 @@ def iter_files(
                     add_to_cache(attr)
                 else:
                     return attr
-            yield YieldFrom(do_filter(bool, do_map(process, it)), identity=True) # type: ignore
+            yield YieldFrom(do_filter(bool, do_map(process, it)), may_await=False) # type: ignore
         else:
-            yield YieldFrom(do_map(normalize_attr, it), identity=True) # type: ignore
+            yield YieldFrom(do_map(normalize_attr, it), may_await=False) # type: ignore
         if (with_ancestors or with_path) and cache:
             yield YieldFrom(ensure_attr_path(
                 client, 
@@ -2509,8 +2608,8 @@ def iter_files(
                 app=app, 
                 async_=async_, # type: ignore
                 **request_kwargs, 
-            ), identity=True)
-    return run_gen_step_iter(gen_step, async_=async_)
+            ), may_await=False)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -2637,8 +2736,7 @@ def traverse_files(
     def gen_step():
         nonlocal cid
         if auto_splitting_tasks:
-            get_count = partial(
-                get_file_count, 
+            get_count = get_file_count(
                 client, 
                 id_to_dirnode=id_to_dirnode, 
                 **{**request_kwargs, "timeout": auto_splitting_statistics_timeout}
@@ -2674,7 +2772,7 @@ def traverse_files(
                         max_workers=max_workers, 
                         async_=async_, # type: ignore
                         **request_kwargs, 
-                    ), identity=True)
+                    ), may_await=False)
                 else:
                     yield YieldFrom(iter_files(
                         client, 
@@ -2690,7 +2788,7 @@ def traverse_files(
                         max_workers=max_workers, 
                         async_=async_, # type: ignore
                         **request_kwargs, 
-                    ), identity=True)
+                    ), may_await=False)
             else:
                 with with_iter_next(iterdir(
                     client, 
@@ -2715,8 +2813,8 @@ def traverse_files(
                         type > 7 or 
                         type_of_attr(attr) == type
                     ):
-                        yield Yield(attr, identity=True)
-    return run_gen_step_iter(gen_step, async_=async_)
+                        yield Yield(attr, may_await=False)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -2809,8 +2907,8 @@ def iter_dirs(
             )) as get_next:
                 while True:
                     batch = yield get_next
-                    yield YieldFrom(batch, identity=True)
-        it = run_gen_step_iter(gen_step(it), async_=async_)
+                    yield YieldFrom(batch, may_await=False)
+        it = run_gen_step_iter(gen_step(it), simple=True, async_=async_)
     return it
 
 
@@ -3057,12 +3155,12 @@ def iter_image_files(
                 count = int(resp.get("count") or 0)
             if offset != resp["offset"]:
                 break
-            yield YieldFrom(map(normalize, resp["data"]), identity=True)
+            yield YieldFrom(map(normalize, resp["data"]), may_await=False)
             offset += len(resp["data"])
             if offset >= count:
                 break
             payload["offset"] = offset
-    return run_gen_step_iter(gen_step, async_=async_)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -3171,11 +3269,11 @@ def share_iterdir(
                         id_to_dirnode[oattr.id] = DirNode(oattr.name, oattr.parent_id)
                 if normalize_attr is not None:
                     attr = normalize_attr(attr)
-                yield Yield(attr, identity=True)
+                yield Yield(attr, may_await=False)
             payload["offset"] += page_size # type: ignore
             if payload["offset"] >= count: # type: ignore
                 break
-    return run_gen_step_iter(gen_step, async_=async_)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -3273,12 +3371,12 @@ def share_iter_files(
                             "name": info["fn"], 
                             "size": int(info["si"]), 
                             "path": f"/{info['pt']}/{info['fn']}", 
-                        }, identity=True)
+                        }, may_await=False)
                 else:
-                    yield Yield({k: attr[k] for k in ("id", "sha1", "name", "size", "path")}, identity=True)
+                    yield Yield({k: attr[k] for k in ("id", "sha1", "name", "size", "path")}, may_await=False)
         except (StopIteration, StopAsyncIteration):
             pass
-    return run_gen_step(gen_step, async_=async_)
+    return run_gen_step(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -3448,7 +3546,7 @@ def share_get_id_to_path(
                     if ensure_file is None or ensure_file ^ attr["is_dir"]:
                         return P115ID(attr["id"], attr, about="path")
         raise error
-    return run_gen_step(gen_step, async_=async_)
+    return run_gen_step(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -3960,7 +4058,7 @@ def iter_selected_nodes_using_star_event(
                     id_to_dirnode[fid] = DirNode(name, pid)
                 if fid in ids:
                     if not normalize_attr:
-                        yield Yield(event, identity=True)
+                        yield Yield(event, may_await=False)
                     elif normalize_attr is True:
                         attr = {
                             "id": fid, 
@@ -3982,15 +4080,15 @@ def iter_selected_nodes_using_star_event(
                             attr["type"] = 3
                         else:
                             attr["type"] = type_of_attr(attr)
-                        yield Yield(attr, identity=True)
+                        yield Yield(attr, may_await=False)
                     else:
-                        yield Yield(normalize_attr(event), identity=True)
+                        yield Yield(normalize_attr(event), may_await=False)
                     discard(fid)
                     if not ids:
                         break
         except (StopIteration, StopAsyncIteration):
             pass
-    return run_gen_step_iter(gen_step, async_=async_)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -4084,13 +4182,13 @@ def iter_selected_dirs_using_star(
                     break
                 cid = attr["id"]
                 if cid in ids:
-                    yield Yield(info, identity=True)
+                    yield Yield(info, may_await=False)
                     discard(cid)
                     if not ids:
                         break
         except (StopIteration, StopAsyncIteration):
             pass
-    return run_gen_step_iter(gen_step, async_=async_)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -4251,7 +4349,7 @@ def iter_files_with_dirname(
                 resp = yield get_next
                 for attr in resp["data"]:
                     attr.update(pid_to_info[attr["parent_id"]])
-                    yield Yield(attr, identity=True)
+                    yield Yield(attr, may_await=False)
         except (StopIteration, StopAsyncIteration):
             pass
     if with_parents_4_level:
@@ -4264,7 +4362,7 @@ def iter_files_with_dirname(
             it = iter_parents_3_level(
                 client, 
                 iter_unique((async_map if async_ else map)( 
-                    get_pid, run_gen_step_iter(gen_step, async_=async_))), # type: ignore
+                    get_pid, run_gen_step_iter(gen_step, simple=True, async_=async_))), # type: ignore
                 async_=async_, # type: ignore
                 **request_kwargs, 
             )
@@ -4277,9 +4375,9 @@ def iter_files_with_dirname(
             id_to_parents[0] = ("", "", "")
             for attr in files:
                 attr["parents"] = (attr["dir_name"], *id_to_parents[attr["parent_id"]])
-                yield Yield(attr, identity=True)
-        return run_gen_step_iter(gen_step2, async_=async_)
-    return run_gen_step_iter(gen_step, async_=async_)
+                yield Yield(attr, may_await=False)
+        return run_gen_step_iter(gen_step2, simple=True, async_=async_)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -4419,7 +4517,7 @@ def iter_files_with_path(
     _path_already: None | bool = None if path_already else False
     if not path_already:
         from .download import iter_download_nodes
-        def set_path_already(*a):
+        def set_path_already(*_):
             nonlocal _path_already
             _path_already = True
         def fetch_dirs(id: int | str, /):
@@ -4452,7 +4550,7 @@ def iter_files_with_path(
                 )) as get_next:
                     while True:
                         attr = yield get_next
-                        yield run_gen_step(fetch_dirs(attr["pickcode"]), async_=async_)
+                        yield run_gen_step(fetch_dirs(attr["pickcode"]), simple=True, async_=async_)
     if with_ancestors:
         id_to_ancestors: dict[int, list[dict]] = {}
         def get_ancestors(id: int, attr: dict | tuple[str, int] | DirNode, /) -> list[dict]:
@@ -4499,7 +4597,7 @@ def iter_files_with_path(
         add_to_cache = cache.append
         if not path_already:
             if async_:
-                task: Any = create_task(run_gen_step(fetch_dirs(cid), async_=True))
+                task: Any = create_task(run_gen_step(fetch_dirs(cid), simple=True, async_=True))
             else:
                 task = run_as_thread(run_gen_step, fetch_dirs(cid))
             task.add_done_callback(set_path_already)
@@ -4524,16 +4622,16 @@ def iter_files_with_path(
             while True:
                 attr = yield get_next
                 if _path_already is None:
-                    yield Yield(update_path(attr), identity=True)
+                    yield Yield(update_path(attr), may_await=False)
                 elif _path_already:
                     if async_:
                         yield task
                     else:
                         task.result()
                     if cache:
-                        yield YieldFrom(map(update_path, cache), identity=True)
+                        yield YieldFrom(map(update_path, cache), may_await=False)
                         cache.clear()
-                    yield Yield(update_path(attr), identity=True)
+                    yield Yield(update_path(attr), may_await=False)
                     _path_already = None
                 else:
                     add_to_cache(attr)
@@ -4542,8 +4640,8 @@ def iter_files_with_path(
                 yield task
             else:
                 task.result()
-            yield YieldFrom(map(update_path, cache), identity=True)
-    return run_gen_step_iter(gen_step, async_=async_)
+            yield YieldFrom(map(update_path, cache), may_await=False)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -4799,8 +4897,8 @@ def iter_files_with_path_by_export_dir(
                 if escape is not None:
                     name = escape(name)
                 attr["path"] = dir_path + name
-                yield Yield(attr, identity=True)
-    return run_gen_step_iter(gen_step, async_=async_)
+                yield Yield(attr, may_await=False)
+    return run_gen_step_iter(gen_step, simple=True, async_=async_)
 
 
 @overload
@@ -4891,7 +4989,7 @@ def iter_parents_3_level(
     ids = (async_filter if async_ else filter)(None, ids) # type: ignore
     return flatten(
         batch_map(
-            lambda ids, /: run_gen_step(get_parents(ids), async_=async_), 
+            lambda ids, /: run_gen_step(get_parents(ids), simple=True, async_=async_), 
             chunked(ids, 1150), 
             max_workers=max_workers, 
         ), 
@@ -4971,7 +5069,7 @@ def iter_dir_nodes(
                         id_to_dirnode[id] = DirNode(name, parent_id)
                     yield Yield(
                         {"id": id, "parent_id": parent_id, "name": name}, 
-                        identity=True, 
+                        may_await=False, 
                     )
         else:
             with with_iter_next(iterdir(
@@ -4990,11 +5088,90 @@ def iter_dir_nodes(
                             "parent_id": attr["parent_id"], 
                             "name": attr["name"], 
                         }, 
-                        identity=True, 
+                        may_await=False, 
                     )
                     yield YieldFrom(
-                        run_gen_step_iter(gen_step(attr["pickcode"]), async_=async_), 
-                        identity=True, 
+                        run_gen_step_iter(gen_step(attr["pickcode"]), simple=True, async_=async_), 
+                        may_await=False, 
                     )
-    return run_gen_step_iter(gen_step(cid or 0), async_=async_)
+    return run_gen_step_iter(gen_step(cid or 0), simple=True, async_=async_)
+
+
+@overload
+def search_for_any_file(
+    client: str | P115Client, 
+    cid: int = 0, 
+    search_value: str = ".", 
+    suffix: str = "", 
+    type: int = 99, 
+    app: str = "web", 
+    *, 
+    async_: Literal[False] = False, 
+    **request_kwargs, 
+) -> bool:
+    ...
+@overload
+def search_for_any_file(
+    client: str | P115Client, 
+    cid: int = 0, 
+    search_value: str = ".", 
+    suffix: str = "", 
+    type: int = 99, 
+    app: str = "web", 
+    *, 
+    async_: Literal[True], 
+    **request_kwargs, 
+) -> Coroutine[Any, Any, bool]:
+    ...
+def search_for_any_file(
+    client: str | P115Client, 
+    cid: int = 0, 
+    search_value: str = ".", 
+    suffix: str = "", 
+    type: int = 99, 
+    app: str = "web", 
+    *, 
+    async_: Literal[False, True] = False, 
+    **request_kwargs, 
+) -> bool | Coroutine[Any, Any, bool]:
+    """搜索以判断是否存在某种文件
+
+    :param client: 115 客户端或 cookies
+    :param cid: 目录 id
+    :param search_value: 搜索关键词，搜索到的文件名必须包含这个字符串
+    :param suffix: 后缀名（优先级高于 type）
+    :param type: 文件类型
+
+        - 1: 文档
+        - 2: 图片
+        - 3: 音频
+        - 4: 视频
+        - 5: 压缩包
+        - 6: 应用
+        - 7: 书籍
+        - 99: 仅文件
+
+    :param app: 使用某个 app （设备）的接口
+    :param async_: 是否异步
+    :param request_kwargs: 其它请求参数
+
+    :return: 是否存在某种文件
+    """
+    if isinstance(client, str):
+        client = P115Client(client, check_for_relogin=True)
+    if not isinstance(client, P115Client) or app == "open":
+        fs_search: Callable = client.fs_search_open
+    elif app in ("", "web", "desktop", "harmony"):
+        fs_search = partial(client.fs_search, app=app)
+    else:
+        fs_search = client.fs_search_app
+    def gen_step():
+        resp = yield fs_search(
+            {"cid": cid, "limit": 1, "search_value": search_value, "suffix": suffix, "type": type}, 
+            async_=async_, 
+            **request_kwargs, 
+        )
+        check_response(resp)
+        return bool(resp["data"])
+    return run_gen_step(gen_step, simple=True, async_=async_)