p115client 0.0.5.14__tar.gz → 0.0.5.14.2__tar.gz

{p115client-0.0.5.14 → p115client-0.0.5.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: p115client
-Version: 0.0.5.14
+Version: 0.0.5.14.2
 Summary: Python 115 webdisk client.
 Home-page: https://github.com/ChenyangGao/p115client
 License: MIT
@@ -29,7 +29,7 @@ Requires-Dist: iter_collect (>=0.0.5.1)
 Requires-Dist: multidict
 Requires-Dist: orjson
 Requires-Dist: p115cipher (>=0.0.3)
-Requires-Dist: p115pickcode (>=0.0.3)
+Requires-Dist: p115pickcode (>=0.0.4)
 Requires-Dist: posixpatht (>=0.0.3)
 Requires-Dist: python-argtools (>=0.0.1)
 Requires-Dist: python-asynctools (>=0.1.3)

{p115client-0.0.5.14 → p115client-0.0.5.14.2}/p115client/client.py

@@ -59,7 +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 get_stable_point
+from p115pickcode import get_stable_point, to_id, to_pickcode
 from property import locked_cacheproperty
 from re import compile as re_compile
 from startfile import startfile, startfile_async # type: ignore
@@ -629,29 +629,32 @@ def check_response(resp: dict | Awaitable[dict], /) -> dict | Coroutine[Any, Any
 
 @overload
 def normalize_attr_web(
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: None = None, 
 ) -> dict[str, Any]:
     ...
 @overload
 def normalize_attr_web[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: type[D], 
 ) -> D:
     ...
 def normalize_attr_web[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: None | type[D] = None, 
 ) -> dict[str, Any] | D:
@@ -660,6 +663,7 @@ def normalize_attr_web[D: dict[str, Any]](
     :param info: 原始数据
     :param simple: 只提取少量必要字段 "is_dir", "id", "parent_id", "name", "sha1", "size", "pickcode", "is_collect", "ctime", "mtime", "type"
     :param keep_raw: 是否保留原始数据，如果为 True，则保存到 "raw" 字段
+    :param default: 一些预设值，可被覆盖
     :param dict_cls: 字典类型
 
     :return: 翻译后的 dict 类型数据
@@ -667,6 +671,8 @@ 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()
+    if default:
+        attr.update(default)
     is_dir = attr["is_dir"] = "fid" not in info
     if is_dir:
         attr["id"] = int(info["cid"])        # category_id
@@ -771,29 +777,33 @@ def normalize_attr_web[D: dict[str, Any]](
 
 @overload
 def normalize_attr_app(
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: None = None, 
 ) -> dict[str, Any]:
     ...
 @overload
 def normalize_attr_app[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: type[D], 
 ) -> D:
     ...
 def normalize_attr_app[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
+    *, 
     dict_cls: None | type[D] = None, 
 ) -> dict[str, Any] | D:
     """翻译 `P115Client.fs_files_app` 接口响应的文件信息数据，使之便于阅读
@@ -801,6 +811,7 @@ def normalize_attr_app[D: dict[str, Any]](
     :param info: 原始数据
     :param simple: 只提取少量必要字段 "is_dir", "id", "parent_id", "name", "sha1", "size", "pickcode", "is_collect", "ctime", "mtime", "type"
     :param keep_raw: 是否保留原始数据，如果为 True，则保存到 "raw" 字段
+    :param default: 一些预设值，可被覆盖
     :param dict_cls: 字典类型
 
     :return: 翻译后的 dict 类型数据
@@ -808,8 +819,10 @@ 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()
+    if default:
+        attr.update(default)
     is_dir = attr["is_dir"] = info["fc"] == "0" # file_category
-    attr["id"] = int(info["fid"])          # file_id
+    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 ""
@@ -892,29 +905,33 @@ def normalize_attr_app[D: dict[str, Any]](
 
 @overload
 def normalize_attr_app2(
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: None = None, 
 ) -> dict[str, Any]:
     ...
 @overload
 def normalize_attr_app2[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: type[D], 
 ) -> D:
     ...
 def normalize_attr_app2[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
+    *, 
     dict_cls: None | type[D] = None, 
 ) -> dict[str, Any] | D:
     """翻译 `P115Client.fs_files_app2` 接口响应的文件信息数据，使之便于阅读
@@ -922,6 +939,7 @@ def normalize_attr_app2[D: dict[str, Any]](
     :param info: 原始数据
     :param simple: 只提取少量必要字段 "is_dir", "id", "parent_id", "name", "sha1", "size", "pickcode", "is_collect", "ctime", "mtime", "type"
     :param keep_raw: 是否保留原始数据，如果为 True，则保存到 "raw" 字段
+    :param default: 一些预设值，可被覆盖
     :param dict_cls: 字典类型
 
     :return: 翻译后的 dict 类型数据
@@ -929,6 +947,8 @@ def normalize_attr_app2[D: dict[str, Any]](
     if dict_cls is None:
         dict_cls = cast(type[D], dict)
     attr: dict[str, Any] = dict_cls()
+    if default:
+        attr.update(default)
     if "file_id" in info and "parent_id" in info:
         if "file_category" in info:
             is_dir = not int(info["file_category"])
@@ -1052,29 +1072,32 @@ def normalize_attr_app2[D: dict[str, Any]](
 
 @overload
 def normalize_attr(
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: None = None, 
 ) -> AttrDict[str, Any]:
     ...
 @overload
 def normalize_attr[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: type[D], 
 ) -> D:
     ...
 def normalize_attr[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     simple: bool = False, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
     dict_cls: None | type[D] = None, 
 ) -> AttrDict[str, Any] | D:
@@ -1083,55 +1106,68 @@ def normalize_attr[D: dict[str, Any]](
     :param info: 原始数据
     :param simple: 只提取少量必要字段 "is_dir", "id", "parent_id", "name", "sha1", "size", "pickcode", "is_collect", "ctime", "mtime"
     :param keep_raw: 是否保留原始数据，如果为 True，则保存到 "raw" 字段
+    :param default: 一些预设值，可被覆盖
     :param dict_cls: 字典类型
 
     :return: 翻译后的 dict 类型数据
     """
+    if "fn" in info:
+        call = normalize_attr_app
+    elif "file_id" in info or "category_id" in info:
+        call = normalize_attr_app2
+    else:
+        call = normalize_attr_web
     if dict_cls is None:
-        if "fn" in info:
-            return normalize_attr_app(info, simple=simple, keep_raw=keep_raw, dict_cls=AttrDict)
-        elif "file_id" in info or "category_id" in info:
-            return normalize_attr_app2(info, simple=simple, keep_raw=keep_raw, dict_cls=AttrDict)
-        else:
-            return normalize_attr_web(info, simple=simple, keep_raw=keep_raw, dict_cls=AttrDict)
+        return call(info, simple=simple, keep_raw=keep_raw, default=default, dict_cls=AttrDict)
     else:
-        if "fn" in info:
-            return normalize_attr_app(info, simple=simple, keep_raw=keep_raw, dict_cls=dict_cls)
-        elif "file_id" in info or "category_id" in info:
-            return normalize_attr_app2(info, simple=simple, keep_raw=keep_raw, dict_cls=dict_cls)
-        else:
-            return normalize_attr_web(info, simple=simple, keep_raw=keep_raw, dict_cls=dict_cls)
+        return call(info, simple=simple, keep_raw=keep_raw, default=default, dict_cls=dict_cls)
 
 
 @overload
 def normalize_attr_simple(
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
-    dict_cls: None, 
-) -> dict[str, Any]:
+    dict_cls: None = None, 
+) -> AttrDict[str, Any]:
     ...
 @overload
 def normalize_attr_simple[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
-    dict_cls: type[D] = AttrDict, # type: ignore
+    dict_cls: type[D], 
 ) -> D:
     ...
 def normalize_attr_simple[D: dict[str, Any]](
-    info: Mapping, 
+    info: Mapping[str, Any], 
     /, 
     keep_raw: bool = False, 
+    default: None | Mapping[str, Any] | Iterable[tuple[str, Any]] = None, 
     *, 
-    dict_cls: None | type[D] = AttrDict, # type: ignore
-) -> dict[str, Any] | D:
+    dict_cls: None | type[D] = None, 
+) -> AttrDict[str, Any] | D:
+    """翻译获取自罗列目录、搜索、获取文件信息等接口的数据，使之便于阅读
+
+    .. note::
+        只提取少量必要字段 "is_dir", "id", "parent_id", "name", "sha1", "size", "pickcode", "is_collect", "ctime", "mtime"
+
+    :param info: 原始数据
+    :param keep_raw: 是否保留原始数据，如果为 True，则保存到 "raw" 字段
+    :param default: 一些预设值，可被覆盖
+    :param dict_cls: 字典类型
+
+    :return: 翻译后的 dict 类型数据
+    """
     return normalize_attr(
         info, 
         simple=True, 
         keep_raw=keep_raw, 
+        default=default, 
         dict_cls=dict_cls, 
     )
 
@@ -5407,6 +5443,26 @@ class P115OpenClient(ClientRequestMixin):
     upload_file_open = upload_file
     vip_qr_url_open = vip_qr_url
 
+    to_id = staticmethod(to_id)
+
+    def to_pickcode(
+        self, 
+        id: int | str, 
+        /, 
+        prefix: Literal["a", "b", "c", "d", "e", "fa", "fb", "fc", "fd", "fe"] = "a", 
+    ) -> str:
+        """把可能是 id 或 pickcode 的一律转换成 pickcode
+
+        .. note::
+            规定：空提取码 "" 对应的 id 是 0
+
+        :param id: 可能是 id 或 pickcode
+        :param prefix: 前缀
+
+        :return: pickcode
+        """
+        return to_pickcode(id, self.pickcode_stable_point, prefix=prefix)
+
 
 class P115Client(P115OpenClient):
     """115 的客户端对象
@@ -18473,41 +18529,6 @@ class P115Client(P115OpenClient):
             payload = {"file_id": payload}
         return self.request(url=api, method="POST", data=payload, async_=async_, **request_kwargs)
 
-    @overload
-    def offline_info(
-        self, 
-        /, 
-        base_url: bool | str | Callable[[], str] = False, 
-        *, 
-        async_: Literal[False] = False, 
-        **request_kwargs, 
-    ) -> dict:
-        ...
-    @overload
-    def offline_info(
-        self, 
-        /, 
-        base_url: bool | str | Callable[[], str] = False, 
-        *, 
-        async_: Literal[True], 
-        **request_kwargs, 
-    ) -> Coroutine[Any, Any, dict]:
-        ...
-    def offline_info(
-        self, 
-        /, 
-        base_url: bool | str | Callable[[], str] = False, 
-        *, 
-        async_: Literal[False, True] = False, 
-        **request_kwargs, 
-    ) -> dict | Coroutine[Any, Any, dict]:
-        """获取关于离线的限制的信息，以及 sign 和 time 字段（各个添加任务的接口需要）
-
-        GET https://115.com/?ct=offline&ac=space
-        """
-        api = complete_api("/?ct=offline&ac=space", base_url=base_url)
-        return self.request(url=api, async_=async_, **request_kwargs)
-
     @overload
     def offline_list(
         self, 
@@ -18824,6 +18845,79 @@ class P115Client(P115OpenClient):
             **request_kwargs, 
         )
 
+    @overload
+    def offline_sign(
+        self, 
+        /, 
+        base_url: bool | str | Callable[[], str] = False, 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def offline_sign(
+        self, 
+        /, 
+        base_url: bool | str | Callable[[], str] = False, 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def offline_sign(
+        self, 
+        /, 
+        base_url: bool | str | Callable[[], str] = False, 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """获取 sign 和 time 字段（各个添加任务的接口需要），以及其它信息
+
+        GET https://115.com/?ct=offline&ac=space
+        """
+        api = complete_api("/?ct=offline&ac=space", base_url=base_url)
+        return self.request(url=api, async_=async_, **request_kwargs)
+
+    @overload
+    def offline_sign_app(
+        self, 
+        /, 
+        base_url: bool | str | Callable[[], str] = False, 
+        app: str = "android", 
+        *, 
+        async_: Literal[False] = False, 
+        **request_kwargs, 
+    ) -> dict:
+        ...
+    @overload
+    def offline_sign_app(
+        self, 
+        /, 
+        base_url: bool | str | Callable[[], str] = False, 
+        app: str = "android", 
+        *, 
+        async_: Literal[True], 
+        **request_kwargs, 
+    ) -> Coroutine[Any, Any, dict]:
+        ...
+    def offline_sign_app(
+        self, 
+        /, 
+        base_url: bool | str | Callable[[], str] = False, 
+        app: str = "android", 
+        *, 
+        async_: Literal[False, True] = False, 
+        **request_kwargs, 
+    ) -> dict | Coroutine[Any, Any, dict]:
+        """获取 sign 和 time 字段（各个添加任务的接口需要）
+
+        GET https://proapi.115.com/android/files/offlinesign
+        """
+        api = complete_proapi("/files/offlinesign", base_url, app)
+        return self.request(url=api, async_=async_, **request_kwargs)
+
     @overload
     def offline_task_count(
         self, 

{p115client-0.0.5.14 → p115client-0.0.5.14.2}/p115client/tool/download.py

@@ -41,7 +41,7 @@ from p115client import (
     P115OpenClient, P115URL, 
 )
 from p115client.exception import P115Warning
-from p115pickcode import to_id, to_pickcode
+from p115pickcode import to_id
 
 from .iterdir import (
     get_path_to_cid, iterdir, iter_files, iter_files_with_path, 
@@ -94,15 +94,14 @@ def batch_get_url(
     """
     if isinstance(client, str):
         client = P115Client(client, check_for_relogin=True)
-    stable_point = client.pickcode_stable_point
     if headers := request_kwargs.get("headers"):
         request_kwargs["headers"] = dict(headers, **{"user-agent": user_agent})
     else:
         request_kwargs["headers"] = {"user-agent": user_agent}
     if isinstance(pickcode, (int, str)):
-        pickcode = to_pickcode(pickcode, stable_point)
+        pickcode = client.to_pickcode(pickcode)
     elif not isinstance(pickcode, str):
-        pickcode = ",".join(to_pickcode(pc, stable_point) for pc in pickcode)
+        pickcode = ",".join(map(client.to_pickcode, pickcode))
     if not isinstance(client, P115Client) or app == "open":
         get_download_url: Callable = client.download_url_info_open
     else:
@@ -184,7 +183,6 @@ def iter_url_batches(
     """
     if isinstance(client, str):
         client = P115Client(client, check_for_relogin=True)
-    stable_point = client.pickcode_stable_point
     if headers := request_kwargs.get("headers"):
         request_kwargs["headers"] = dict(headers, **{"user-agent": user_agent})
     else:
@@ -196,7 +194,7 @@ def iter_url_batches(
     if batch_size <= 0:
         batch_size = 1
     def gen_step():
-        for pcs in batched((to_pickcode(pc, stable_point) for pc in pickcodes), batch_size):
+        for pcs in batched(map(client.to_pickcode, pickcodes), batch_size):
             resp = yield get_download_url(
                 ",".join(pcs), 
                 async_=async_, 
@@ -1210,7 +1208,6 @@ def iter_download_nodes(
     """
     if isinstance(client, str):
         client = P115Client(client, check_for_relogin=True)
-    stable_point = client.pickcode_stable_point
     get_base_url = cycle(("http://proapi.115.com", "https://proapi.115.com")).__next__
     if async_:
         if max_workers is None or max_workers <= 0:
@@ -1272,9 +1269,10 @@ def iter_download_nodes(
         async_=async_, 
         **{"base_url": get_base_url, **request_kwargs}, 
     )
+    to_pickcode = client.to_pickcode
     if max_workers == 1:
         def gen_step(pickcode: int | str, /):
-            pickcode = to_pickcode(pickcode, stable_point)
+            pickcode = to_pickcode(pickcode)
             for i in count(1):
                 payload = {"pickcode": pickcode, "page": i}
                 resp = yield get_nodes(payload)
@@ -1324,7 +1322,7 @@ def iter_download_nodes(
                 n = executor._max_workers
                 submit = executor.submit
                 shutdown = lambda: executor.shutdown(False, cancel_futures=True)
-            pickcode = to_pickcode(pickcode, stable_point)
+            pickcode = to_pickcode(pickcode)
             try:
                 sentinel = object()
                 countdown: Callable
@@ -1449,7 +1447,6 @@ def iter_download_files(
     """
     if isinstance(client, str):
         client = P115Client(client, check_for_relogin=True)
-    stable_point = client.pickcode_stable_point
     if id_to_dirnode is None:
         id_to_dirnode = ID_TO_DIRNODE_CACHE[client.user_id]
     elif id_to_dirnode is ...:
@@ -1594,7 +1591,7 @@ def iter_download_files(
             for pickcode in pickcodes:
                 yield YieldFrom(run_gen_step_iter(gen_step(pickcode), async_))
                 ancestors_loaded = False
-    return run_gen_step_iter(gen_step(to_pickcode(cid, stable_point)), async_)
+    return run_gen_step_iter(gen_step(client.to_pickcode(cid)), async_)
 
 
 @overload

{p115client-0.0.5.14 → p115client-0.0.5.14.2}/p115client/tool/fs_files.py

@@ -19,7 +19,7 @@ from time import time
 from typing import cast, overload, Any, Final, Literal
 from warnings import warn
 
-from iterutils import as_gen_step, run_gen_step_iter, Yield
+from iterutils import run_gen_step_iter, Yield
 from p115client import check_response, P115Client, P115OpenClient
 from p115client.client import get_status_code
 from p115client.exception import BusyOSError, DataError, P115Warning

{p115client-0.0.5.14 → p115client-0.0.5.14.2}/p115client/tool/iterdir.py

@@ -20,9 +20,7 @@ __all__ = [
 __doc__ = "这个模块提供了一些和目录信息罗列有关的函数"
 
 # TODO: 再实现 2 个方法，利用 iter_download_nodes，一个有 path，一个没有，可以把某个目录下的所有节点都搞出来，导出时，先导出目录节点，再导出文件节点，但它们是并发执行的，然后必有字段：id, parent_id, pickcode, name, is_dir, sha1 等
-
 # TODO: 路径表示法，应该支持 / 和 > 开头，而不仅仅是 / 开头
-# TODO: 对于路径，增加 top_id 和 relpath 字段，表示搜素目录的 id 和相对于搜索路径的相对路径
 # TODO: get_id* 这类方法，应该放在 attr.py，用来获取某个 id 对应的值（根本还是 get_attr）
 # TODO: 创造函数 get_id, get_parent_id, get_ancestors, get_sha1, get_pickcode, get_path 等，支持多种类型的参数，目前已有的名字太长，需要改造，甚至转为私有，另外这些函数或许可以放到另一个包中，attr.py
 # TODO: 去除掉一些并不便利的办法，然后加上 traverse 和 walk 方法，通过递归拉取（支持深度和广度优先遍历）
@@ -60,7 +58,7 @@ from p115client import (
     P115Client, P115OpenClient, P115OSError, P115Warning, 
 )
 from p115client.type import P115ID
-from p115pickcode import pickcode_to_id, to_id, to_pickcode
+from p115pickcode import pickcode_to_id, to_id
 from posixpatht import path_is_dir_form, splitext, splits
 
 from .attr import type_of_attr
@@ -138,42 +136,50 @@ def _overview_attr(info: Mapping, /) -> OverviewAttr:
     return OverviewAttr(is_dir, id, pid, name, ctime, mtime)
 
 
-def _update_resp_2_id_to_dirnode(
+def _update_resp_ancestors(
     resp: dict, 
-    id_to_dirnode: EllipsisType | MutableMapping[int, tuple[str, int] | DirNode], 
+    id_to_dirnode: None | EllipsisType | MutableMapping[int, tuple[str, int] | DirNode] = None, 
     /, 
     error: None | OSError = FileNotFoundError(ENOENT, "not found"), 
 ) -> dict:
+    list_append = list.append
+    need_update_id_to_dirnode = id_to_dirnode not in (..., None)
     if "path" in 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"]))
+        ancestors = resp["ancestors"] = []
+        start_idx = not resp["path"][0]["cid"]
+        if start_idx:
+            list_append(ancestors, {"id": 0, "parent_id": 0, "name": ""})
+        for info in resp["path"][start_idx:]:
+            id, name, pid = int(info["cid"]), info["name"], int(info["pid"])
+            list_append(ancestors, {"id": id, "parent_id": pid, "name": name})
+            if need_update_id_to_dirnode:
+                id_to_dirnode[id] = DirNode(name, pid) # type: ignore
     else:
+        if resp and "paths" not in resp:
+            check_response(resp)
+            resp = resp["data"]
         if not resp:
             if error is None:
                 return resp
             raise error
-        if "paths" not in resp:
-            check_response(resp)
-            resp = resp["data"]
-            if not resp:
-                if error is None:
-                    return resp
-                raise error
-        if id_to_dirnode is not ...:
-            paths = resp["paths"]
-            info = paths[0]
-            pid = int(info["file_id"])
-            for info in paths[1:]:
-                fid = int(info["file_id"])
-                id_to_dirnode[fid] = DirNode(info["file_name"], pid)
-                pid = fid
-            if not resp["sha1"]:
-                if "file_id" in resp:
-                    fid = int(resp["file_id"])
-                else:
-                    fid = to_id(resp["pick_code"])
-                id_to_dirnode[fid] = DirNode(resp["file_name"], pid)
+        ancestors = resp["ancestors"] = []
+        pid = int(resp["paths"][0]["file_id"])
+        for info in resp["paths"][1:]:
+            id = int(info["file_id"])
+            name = info["file_name"]
+            list_append(ancestors, {"id": id, "parent_id": pid, "name": name})
+            if need_update_id_to_dirnode:
+                id_to_dirnode[id] = DirNode(name, pid) # type: ignore
+            pid = id
+        if not resp["sha1"]:
+            if "file_id" in resp:
+                id = int(resp["file_id"])
+            else:
+                id = to_id(resp["pick_code"])
+            name = resp["file_name"]
+            list_append(ancestors, {"id": id, "parent_id": pid, "name": name})
+            if need_update_id_to_dirnode:
+                id_to_dirnode[id] = DirNode(name, pid) # type: ignore
     return resp
 
 
@@ -405,13 +411,11 @@ def get_file_count(
             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"]))
+            _update_resp_ancestors(resp, id_to_dirnode)
             return int(resp["count"])
         else:
             resp = yield get_resp_of_category_get(cid)
-            resp = _update_resp_2_id_to_dirnode(resp, id_to_dirnode, FileNotFoundError(ENOENT, cid))
+            resp = _update_resp_ancestors(resp, id_to_dirnode, FileNotFoundError(ENOENT, cid))
             if resp["sha1"]:
                 resp["cid"] = cid
                 raise NotADirectoryError(ENOTDIR, resp)
@@ -577,7 +581,7 @@ def get_ancestors(
                 return ancestors
             else:
                 resp = yield get_resp_of_category_get(fid)
-                resp = _update_resp_2_id_to_dirnode(resp, id_to_dirnode)
+                resp = _update_resp_ancestors(resp, id_to_dirnode)
                 for info in resp["paths"]:
                     add_ancestor({
                         "parent_id": pid, 
@@ -607,7 +611,7 @@ def get_ancestors(
                     id_to_dirnode[ans["id"]] = DirNode(ans["name"], ans["parent_id"])
         else:
             resp = yield get_resp_of_category_get(fid)
-            resp = _update_resp_2_id_to_dirnode(resp, id_to_dirnode)
+            resp = _update_resp_ancestors(resp, id_to_dirnode)
             for info in resp["paths"]:
                 add_ancestor({
                     "parent_id": pid, 
@@ -835,7 +839,7 @@ def get_id_to_path(
         if not isinstance(client, P115Client) or app == "open":
             path = ">" + ">".join(patht)
             resp = yield client.fs_info_open(path, async_=async_, **request_kwargs)
-            data = _update_resp_2_id_to_dirnode(resp, id_to_dirnode)
+            data = _update_resp_ancestors(resp, id_to_dirnode)
             return P115ID(data["file_id"], data, about="path", path=path)
         i = 0
         start_parent_id = parent_id
@@ -1312,7 +1316,7 @@ def ensure_attr_path[D: dict](
                     pid = id_to_dirnode[pid][1]
                 if pid and pid not in dangling_id_to_name:
                     resp = yield get_info(pid, async_=async_, **request_kwargs)
-                    resp = _update_resp_2_id_to_dirnode(resp, id_to_dirnode, None)
+                    resp = _update_resp_ancestors(resp, id_to_dirnode, None)
                     if not resp:
                         dangling_id_to_name[pid] = ""
                         yield Yield(attr)
@@ -1506,6 +1510,7 @@ def _iter_fs_files(
     id_to_dirnode: None | EllipsisType | MutableMapping[int, tuple[str, int] | DirNode] = ..., 
     raise_for_changed_count: bool = False, 
     ensure_file: None | bool = None, 
+    hold_top: bool = True, 
     app: str = "android", 
     cooldown: int | float = 0, 
     max_workers: None | int = None, 
@@ -1525,6 +1530,7 @@ def _iter_fs_files(
     id_to_dirnode: None | EllipsisType | MutableMapping[int, tuple[str, int] | DirNode] = ..., 
     raise_for_changed_count: bool = False, 
     ensure_file: None | bool = None, 
+    hold_top: bool = True, 
     app: str = "android", 
     cooldown: int | float = 0, 
     max_workers: None | int = None, 
@@ -1543,6 +1549,7 @@ def _iter_fs_files(
     id_to_dirnode: None | EllipsisType | MutableMapping[int, tuple[str, int] | DirNode] = ..., 
     raise_for_changed_count: bool = False, 
     ensure_file: None | bool = None, 
+    hold_top: bool = True, 
     app: str = "android", 
     cooldown: int | float = 0, 
     max_workers: None | int = None, 
@@ -1565,6 +1572,7 @@ def _iter_fs_files(
         - False: 必须是目录
         - None: 可以是目录或文件
 
+    :param hold_top: 保留顶层目录信息，返回字段增加 "top_id", "top_ancestors"
     :param app: 使用指定 app（设备）的接口
     :param cooldown: 冷却时间，大于 0，则使用此时间间隔执行并发
     :param max_workers: 最大并发数，如果为 None 或 <= 0，则自动确定
@@ -1647,12 +1655,12 @@ def _iter_fs_files(
                 max_workers=max_workers, 
                 **request_kwargs, 
             )
+        top_id = int(payload.get("cid") or 0)
         with with_iter_next(it) as get_next:
             while True:
                 resp = yield get_next()
-                if id_to_dirnode is not ...:
-                    for info in resp["path"][1:]:
-                        id_to_dirnode[int(info["cid"])] = DirNode(info["name"], int(info["pid"]))
+                _update_resp_ancestors(resp, id_to_dirnode)
+                ancestors = resp["ancestors"]
                 for info in resp["data"]:
                     if normalize_attr is None:
                         attr: dict | OverviewAttr = _overview_attr(info)
@@ -1667,6 +1675,9 @@ def _iter_fs_files(
                         continue
                     if with_dirname:
                         info["dirname"] = pid_to_name[attr["parent_id"]]
+                    if hold_top:
+                        info["top_id"] = top_id
+                        info["top_ancestors"] = ancestors
                     yield Yield(info)
     return run_gen_step_iter(gen_step, async_)
 
@@ -2294,7 +2305,6 @@ def iter_files_with_path(
         raise ValueError("please set the non-zero value of suffix or type")
     if isinstance(client, str):
         client = P115Client(client, check_for_relogin=True)
-    stable_point = client.pickcode_stable_point
     if isinstance(escape, bool):
         if escape:
             from posixpatht import escape
@@ -2377,7 +2387,7 @@ def iter_files_with_path(
             if id:
                 yield through(iter_download_nodes(
                     client, 
-                    to_pickcode(id, stable_point), 
+                    client.to_pickcode(id), 
                     files=False, 
                     id_to_dirnode=id_to_dirnode, 
                     max_workers=None, 
@@ -2516,7 +2526,6 @@ def iter_files_with_path_skim(
     from .download import iter_download_nodes
     if isinstance(client, str):
         client = P115Client(client, check_for_relogin=True)
-    stable_point = client.pickcode_stable_point
     if isinstance(escape, bool):
         if escape:
             from posixpatht import escape
@@ -2561,6 +2570,8 @@ def iter_files_with_path_skim(
             dirname = id_to_path[pid] = get_path(id_to_dirnode[pid]) + "/"
         return dirname + name
     def update_path(attr: dict, /) -> dict:
+        attr["top_id"] = top_id
+        attr["top_ancestors"] = top_ancestors
         try:
             if with_ancestors:
                 attr["ancestors"] = get_ancestors(attr["id"], attr)
@@ -2585,12 +2596,28 @@ def iter_files_with_path_skim(
         def set_path_already(*_):
             nonlocal _path_already
             _path_already = True
+        top_id = cid
+        if not cid:
+            top_ancestors = [{"id": 0, "parent_id": 0, "name": ""}]
+        else:
+            top_ancestors = []
+            if id_to_dirnode:
+                add_ancestor = top_ancestors.append
+                tid = top_id
+                while tid and tid in id_to_dirnode:
+                    name, pid = id_to_dirnode[tid]
+                    add_ancestor({"id": tid, "parent_id": pid, "name": name})
+                    tid = pid
+                if not tid:
+                    add_ancestor({"id": 0, "parent_id": 0, "name": ""})
+                top_ancestors.reverse()
         @as_gen_step
         def fetch_dirs(id: int | str, /):
+            nonlocal top_ancestors
             if id:
                 if cid:
                     do_next: Callable = anext if async_ else next
-                    yield do_next(_iter_fs_files(
+                    attr = yield do_next(_iter_fs_files(
                         client, 
                         to_id(id), 
                         page_size=1, 
@@ -2598,9 +2625,10 @@ def iter_files_with_path_skim(
                         async_=async_, 
                         **request_kwargs, 
                     ))
+                    top_ancestors = attr["top_ancestors"]
                 yield through(iter_download_nodes(
                     client, 
-                    to_pickcode(id, stable_point), 
+                    client.to_pickcode(id), 
                     files=False, 
                     id_to_dirnode=id_to_dirnode, 
                     max_workers=max_workers, 
@@ -2872,7 +2900,6 @@ def iter_nodes_by_pickcode(
     """
     if isinstance(client, str):
         client = P115Client(client, check_for_relogin=True)
-    stable_point = client.pickcode_stable_point
     if id_to_dirnode is None:
         id_to_dirnode = ID_TO_DIRNODE_CACHE[client.user_id]
     methods: list[Callable] = []
@@ -2910,7 +2937,7 @@ def iter_nodes_by_pickcode(
         project, 
         conmap(
             get_response, 
-            (to_pickcode(pc, stable_point) for pc in pickcodes), 
+            map(client.to_pickcode, pickcodes), 
             max_workers=max_workers, 
             kwargs=request_kwargs, 
             async_=async_, 
@@ -3096,7 +3123,7 @@ def iter_nodes_using_info(
             return None
         check_response(resp)
         if id_to_dirnode is not ...:
-            _update_resp_2_id_to_dirnode(resp, id_to_dirnode)
+            _update_resp_ancestors(resp, id_to_dirnode)
         return resp
     return do_filter(None, do_map(
         project, 
@@ -3501,7 +3528,7 @@ def iter_files_shortcut(
     async_: Literal[False, True] = False, 
     **request_kwargs, 
 ) -> Iterator[dict] | AsyncIterator[dict]:
-    """遍历目录树，获取文件信息（整合了多个函数的入口）
+    """遍历目录树，获取（仅文件而非目录）文件信息（整合了多个函数的入口）
 
     .. node::
         `is_skim` 和 `with_path` 的不同取值组合，会决定采用不同的函数:
@@ -3521,7 +3548,7 @@ def iter_files_shortcut(
     :param async_: 是否异步
     :param request_kwargs: 其它请求参数
 
-    :return: 迭代器，返回 key 和 重复文件信息 的元组
+    :return: 迭代器，产生文件信息
     """
     if with_path:
         request_kwargs.setdefault("with_ancestors", True)
@@ -4214,6 +4241,7 @@ def share_search_iter(
 
 '''
 # TODO: 需要优化，大优化，优化不好，就删了
+# TODO: 可以在拉取的同时，检测其它待拉取目录大小，但需要设定冷却时间（例如一秒最多 10 次查询）
 @overload
 def traverse_files(
     client: str | P115Client, 

{p115client-0.0.5.14 → p115client-0.0.5.14.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "p115client"
-version = "0.0.5.14"
+version = "0.0.5.14.2"
 description = "Python 115 webdisk client."
 authors = ["ChenyangGao <wosiwujm@gmail.com>"]
 license = "MIT"
@@ -37,7 +37,7 @@ iter_collect = ">=0.0.5.1"
 multidict = "*"
 orjson = "*"
 p115cipher = ">=0.0.3"
-p115pickcode = ">=0.0.3"
+p115pickcode = ">=0.0.4"
 posixpatht = ">=0.0.3"
 python-argtools = ">=0.0.1"
 python-asynctools = ">=0.1.3"