larksync 0.1.0__tar.gz → 0.1.2__tar.gz

{larksync-0.1.0 → larksync-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: larksync
-Version: 0.1.0
+Version: 0.1.2
 Summary: 飞书电子表格 / 多维表格的拉取与按主键更新（Feishu / Lark sheets & bitable sync）
 Project-URL: Homepage, https://github.com/libcyz/larksync
 Project-URL: Documentation, https://github.com/libcyz/larksync/blob/main/docs/python.md
@@ -29,9 +29,9 @@ Description-Content-Type: text/markdown
 
 # larksync
 
-这是一个用来同步飞书表格的项目，大多数项目的非技术人员在使用飞书在线表格进行管理的时候经常会出现大量数据需要人工核对，可能又需要去重，于是添加新的表变的非常麻烦，而整理好的csv中如果出现重复的数据，直接复制的话就gameover，当然会有用豆包更新表格的声音，如果你用豆包更新表格，那我不要和你说话。
+这是一个用来同步飞书表格的项目，大多数项目的非技术人员在使用飞书在线表格进行管理的时候经常会出现大量数据需要人工核对，可能又需要去重，于是添加新的表变的非常麻烦，而整理好的csv中如果出现重复的数据，直接复制的话就gameover，当然会有用豆包更新表格的声音，如果你使用豆包更新表格，那我不要和你说话。
 
-对于技术人员来讲，在pipeline搭建好之后发现跑脚本前需要拉取在线表格更新后的信息，需要折返到对应表格，下载，另存为csv，大概率还会出现XXXX表(1),XXXX表(2),然后就需要在修改脚本路径和重命名表格这两个愚蠢选项中选择一项，诸如此类，larksync应运而生。
+对于技术人员来讲，在pipeline搭建好之后发现跑脚本前需要拉取在线表格更新后的信息，需要折返到对应表格，下载，另存为csv，大概率还会出现XXXX表(1),XXXX表(2),然后就需要在修改脚本路径和重命名表格这两个愚蠢选项中选择一项，诸如此类，larksync是为了方便复用诞生的。
 
 ## 更新规则
 
@@ -42,31 +42,67 @@ GUI 和 Python 代码使用同一套规则。
 - 新增的行由调用方决定是否写入。GUI 默认不勾选新增的行。
 - 本地文件中为空的格子不参与比较。larksync 不清空在线表的值。
 - larksync 不删除在线表的行。撤销时，只删除本次写入新增的行。
-- 写入前，larksync 重新读取涉及的行。预览后有人修改过这些格子时，写入整体中止。
+- 写入前，larksync 重新读取需要的行。预览后有人修改过这些格子时，写入就终止。
 
 ## 前提
 
-1. 创建一个飞书自建应用。
-2. 为应用开通以下权限：
+1. 创建一个飞书自建应用（企业自建应用）:https://open.feishu.cn/?lang=zh-CN
+2.“权限管理”中为应用开通以下权限：
 ```json
 {
   "scopes": {
     "tenant": [
+      "aily:knowledge:read",
+      "base:record:retrieve",
       "bitable:app",
+      "bitable:app:readonly",
+      "docs:document.media:download",
+      "drive:drive.metadata:readonly",
+      "drive:drive:version",
+      "drive:drive:version:readonly",
+      "im:message",
+      "im:message.group_at_msg.include_bot:readonly",
+      "im:message.group_at_msg:readonly",
+      "im:message.p2p_msg:readonly",
+      "im:message.pins:read",
+      "im:message.reactions:read",
+      "im:message:readonly",
+      "im:message:recall",
+      "im:message:send_as_bot",
+      "im:message:update",
+      "im:resource",
       "sheets:spreadsheet",
+      "sheets:spreadsheet.meta:read",
+      "sheets:spreadsheet.meta:write_only",
+      "sheets:spreadsheet:create",
+      "sheets:spreadsheet:read",
+      "sheets:spreadsheet:readonly",
+      "sheets:spreadsheet:write_only",
+      "wiki:wiki",
       "wiki:wiki:readonly"
     ],
     "user": [
+      "aily:knowledge:read",
+      "base:record:retrieve",
       "bitable:app",
+      "bitable:app:readonly",
       "sheets:spreadsheet",
+      "sheets:spreadsheet.meta:read",
+      "sheets:spreadsheet.meta:write_only",
+      "sheets:spreadsheet:create",
+      "sheets:spreadsheet:read",
+      "sheets:spreadsheet:readonly",
+      "sheets:spreadsheet:write_only",
+      "wiki:wiki",
       "wiki:wiki:readonly"
     ]
   }
 }
 ```
-3. 在应用的重定向 URL 中添加 `http://localhost:8888/callback`。
-4. 发布应用版本。
-
+![权限导入](img/权限导入.png)
+3. 在应用的“安全设置”重定向 URL 中添加 `http://localhost:8888/callback`。
+4. 创建并发布应用版本。
+![重定向url](img/重定向URL.png)
 说明：权限修改并发布后，生效可以有几分钟的延迟;每个人必须使用自己的飞书应用,不同的人对在线表的权限不同。
 
 ## GUI 使用
@@ -109,4 +145,7 @@ GUI 和 Python 代码使用同一套规则。
 - 单击「移除」：删除本机的表格配置。飞书上的在线表和写入记录不变。
 - 单击右上角的用户名：修改 App ID 或 App Secret，或退出登录。
 
+### 注意
+	如果你的windows开着防火墙，windows可能会把这个组件标记成不安全，选择“属性”--“解除锁定” 再重新解压即可。
+	
 开发者调用详见 [docs/python.md](https://github.com/libcyz/larksync/blob/main/docs/python.md)。

{larksync-0.1.0 → larksync-0.1.2}/README.md

@@ -1,8 +1,8 @@
 # larksync
 
-这是一个用来同步飞书表格的项目，大多数项目的非技术人员在使用飞书在线表格进行管理的时候经常会出现大量数据需要人工核对，可能又需要去重，于是添加新的表变的非常麻烦，而整理好的csv中如果出现重复的数据，直接复制的话就gameover，当然会有用豆包更新表格的声音，如果你用豆包更新表格，那我不要和你说话。
+这是一个用来同步飞书表格的项目，大多数项目的非技术人员在使用飞书在线表格进行管理的时候经常会出现大量数据需要人工核对，可能又需要去重，于是添加新的表变的非常麻烦，而整理好的csv中如果出现重复的数据，直接复制的话就gameover，当然会有用豆包更新表格的声音，如果你使用豆包更新表格，那我不要和你说话。
 
-对于技术人员来讲，在pipeline搭建好之后发现跑脚本前需要拉取在线表格更新后的信息，需要折返到对应表格，下载，另存为csv，大概率还会出现XXXX表(1),XXXX表(2),然后就需要在修改脚本路径和重命名表格这两个愚蠢选项中选择一项，诸如此类，larksync应运而生。
+对于技术人员来讲，在pipeline搭建好之后发现跑脚本前需要拉取在线表格更新后的信息，需要折返到对应表格，下载，另存为csv，大概率还会出现XXXX表(1),XXXX表(2),然后就需要在修改脚本路径和重命名表格这两个愚蠢选项中选择一项，诸如此类，larksync是为了方便复用诞生的。
 
 ## 更新规则
 
@@ -13,31 +13,67 @@ GUI 和 Python 代码使用同一套规则。
 - 新增的行由调用方决定是否写入。GUI 默认不勾选新增的行。
 - 本地文件中为空的格子不参与比较。larksync 不清空在线表的值。
 - larksync 不删除在线表的行。撤销时，只删除本次写入新增的行。
-- 写入前，larksync 重新读取涉及的行。预览后有人修改过这些格子时，写入整体中止。
+- 写入前，larksync 重新读取需要的行。预览后有人修改过这些格子时，写入就终止。
 
 ## 前提
 
-1. 创建一个飞书自建应用。
-2. 为应用开通以下权限：
+1. 创建一个飞书自建应用（企业自建应用）:https://open.feishu.cn/?lang=zh-CN
+2.“权限管理”中为应用开通以下权限：
 ```json
 {
   "scopes": {
     "tenant": [
+      "aily:knowledge:read",
+      "base:record:retrieve",
       "bitable:app",
+      "bitable:app:readonly",
+      "docs:document.media:download",
+      "drive:drive.metadata:readonly",
+      "drive:drive:version",
+      "drive:drive:version:readonly",
+      "im:message",
+      "im:message.group_at_msg.include_bot:readonly",
+      "im:message.group_at_msg:readonly",
+      "im:message.p2p_msg:readonly",
+      "im:message.pins:read",
+      "im:message.reactions:read",
+      "im:message:readonly",
+      "im:message:recall",
+      "im:message:send_as_bot",
+      "im:message:update",
+      "im:resource",
       "sheets:spreadsheet",
+      "sheets:spreadsheet.meta:read",
+      "sheets:spreadsheet.meta:write_only",
+      "sheets:spreadsheet:create",
+      "sheets:spreadsheet:read",
+      "sheets:spreadsheet:readonly",
+      "sheets:spreadsheet:write_only",
+      "wiki:wiki",
       "wiki:wiki:readonly"
     ],
     "user": [
+      "aily:knowledge:read",
+      "base:record:retrieve",
       "bitable:app",
+      "bitable:app:readonly",
       "sheets:spreadsheet",
+      "sheets:spreadsheet.meta:read",
+      "sheets:spreadsheet.meta:write_only",
+      "sheets:spreadsheet:create",
+      "sheets:spreadsheet:read",
+      "sheets:spreadsheet:readonly",
+      "sheets:spreadsheet:write_only",
+      "wiki:wiki",
       "wiki:wiki:readonly"
     ]
   }
 }
 ```
-3. 在应用的重定向 URL 中添加 `http://localhost:8888/callback`。
-4. 发布应用版本。
-
+![权限导入](img/权限导入.png)
+3. 在应用的“安全设置”重定向 URL 中添加 `http://localhost:8888/callback`。
+4. 创建并发布应用版本。
+![重定向url](img/重定向URL.png)
 说明：权限修改并发布后，生效可以有几分钟的延迟;每个人必须使用自己的飞书应用,不同的人对在线表的权限不同。
 
 ## GUI 使用
@@ -80,4 +116,7 @@ GUI 和 Python 代码使用同一套规则。
 - 单击「移除」：删除本机的表格配置。飞书上的在线表和写入记录不变。
 - 单击右上角的用户名：修改 App ID 或 App Secret，或退出登录。
 
+### 注意
+	如果你的windows开着防火墙，windows可能会把这个组件标记成不安全，选择“属性”--“解除锁定” 再重新解压即可。
+	
 开发者调用详见 [docs/python.md](https://github.com/libcyz/larksync/blob/main/docs/python.md)。

{larksync-0.1.0 → larksync-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "larksync"
-version = "0.1.0"
+version = "0.1.2"
 description = "飞书电子表格 / 多维表格的拉取与按主键更新（Feishu / Lark sheets & bitable sync）"
 readme = "README.md"
 license = "MIT"

{larksync-0.1.0 → larksync-0.1.2}/src/larksync/bitable.py

@@ -82,14 +82,16 @@ class Bitable:
                     params={"page_size": 1}, json={})["data"].get("total", 0)
 
     def fetch(self, refs):
-        """只读指定的记录：{record_id: 记录}，已删除的不在结果里。"""
+        """只读指定的记录：{record_id: 记录}，已删除的不在结果里。每批 100 条、并发 5 个。"""
         self.columns()
-        out = {}
-        for i in range(0, len(refs), 100):
-            data = self._post("/records/batch_get", {"record_ids": refs[i:i + 100]})
-            for it in data.get("records") or []:
-                out[it["record_id"]] = self._row(it.get("fields") or {})
-        return out
+
+        def get(chunk):
+            return self._post("/records/batch_get", {"record_ids": chunk}).get("records") or []
+
+        chunks = [refs[i:i + 100] for i in range(0, len(refs), 100)]
+        with ThreadPoolExecutor(_WORKERS) as pool:
+            return {it["record_id"]: self._row(it.get("fields") or {})
+                    for part in pool.map(get, chunks) for it in part}
 
     def writable(self, name):
         return self._fields.get(name) in _WRITABLE

{larksync-0.1.0 → larksync-0.1.2}/src/larksync/diff.py

@@ -36,9 +36,12 @@ class Plan:
         return (f"补空 {len(self.changed)} 格 / 新增 {len(self.added)} 行 / "
                 f"不一致 {len(self.conflicts)} 格（未写入）/ 未匹配 {self.unmatched} 行")
 
-    def apply(self):
-        """写入飞书，返回写入记录 id（用于 Table.undo）。"""
-        return self._table._apply(self)
+    def apply(self, progress=None):
+        """写入飞书，返回写入记录 id（用于 Table.undo）。
+
+        progress(阶段, 已完成, 总数)：可选的进度回调，阶段是「检查」或「写入」。
+        """
+        return self._table._apply(self, progress)
 
 
 def load(source):

{larksync-0.1.0 → larksync-0.1.2}/src/larksync/table.py

@@ -11,6 +11,7 @@ from .http import LarkError, call
 from .sheets import Sheets
 
 _DENIED = {91403, 131006, 1254302}
+_PROGRESS_STEP = 1000   # 每写这么多格回调一次进度
 _MISSING_SCOPE = {99991672, 99991679}
 
 
@@ -104,14 +105,18 @@ class Table:
             self._write(rec, [], added)
         return rec["id"]
 
-    def undo(self, record_id):
-        """撤销一次写入：还原改过的格子、删掉新增的行。之后又被别人改过的话整体中止。"""
+    def undo(self, record_id, progress=None):
+        """撤销一次写入：还原改过的格子、删掉新增的行。之后又被别人改过的话整体中止。
+
+        progress(阶段, 已完成, 总数)：可选的进度回调，阶段是「检查」或「撤销」。
+        """
         rec = history.load(record_id)
         if rec["target"] != self._backend.target:
             raise LarkError(f"写入记录 {record_id} 不属于这张表（它属于 {rec['url']}）")
         if rec["status"] == "undone":
             raise LarkError(f"写入记录 {record_id} 已经撤销过了")
         with self._explained():
+            _report(progress, "检查", 0, len(rec["changed"]) + len(rec["created"]))
             current = self._backend.fetch([ch["ref"] for ch in rec["changed"]] + rec["created"])
             conflicts, cells, drop = [], [], []
             for ch in rec["changed"]:
@@ -131,13 +136,18 @@ class Table:
                     drop.append(ref)
             if conflicts:
                 raise LarkError("撤销会覆盖别人之后的修改，已中止：\n" + brief(conflicts))
-            self._backend.update(cells)
+            total = len(cells) + len(drop)
+            for i in range(0, len(cells), _PROGRESS_STEP):
+                self._backend.update(cells[i:i + _PROGRESS_STEP])
+                _report(progress, "撤销", min(i + _PROGRESS_STEP, len(cells)), total)
             self._backend.delete(drop)
+            _report(progress, "撤销", total, total)
         rec["status"] = "undone"
         history.save(rec)
 
-    def _apply(self, plan):
+    def _apply(self, plan, progress=None):
         with self._explained():
+            _report(progress, "检查", 0, len(plan.changed) + len(plan.added))
             current = self._backend.fetch([ch.ref for ch in plan.changed])   # 只读涉及的行
             taken = {}
             if plan.added:   # 确认新增的主键没被别人抢先加上
@@ -158,14 +168,20 @@ class Table:
                 raise LarkError("在线表在 diff 之后被改过，已中止写入，请重新 diff：\n"
                                 + brief(conflicts))
             rec = history.new(self.url, self._backend.target, plan.key, plan.changed, plan.added)
-            self._write(rec, cells, plan.added)
+            self._write(rec, cells, plan.added, progress)
         return rec["id"]
 
-    def _write(self, rec, cells, added):
-        self._backend.update(cells)
+    def _write(self, rec, cells, added, progress=None):
+        total = len(cells) + len(added)
+        for i in range(0, len(cells), _PROGRESS_STEP):
+            self._backend.update(cells[i:i + _PROGRESS_STEP])
+            _report(progress, "写入", min(i + _PROGRESS_STEP, len(cells)), total)
         for refs in self._backend.create(added):
+            if not refs:
+                continue
             rec["created"] += refs
             history.save(rec)   # 每批落盘，中途失败也能撤销已写入的部分
+            _report(progress, "写入", len(cells) + len(rec["created"]), total)
         rec["status"] = "done"
         history.save(rec)
 
@@ -199,6 +215,11 @@ class Table:
             raise
 
 
+def _report(progress, stage, done, total):
+    if progress:
+        progress(stage, done, total)
+
+
 def _cell(row, key_cols, key, column):
     """行还在、主键没变时返回该格的值，否则 None（行被删或电子表格行位置变了）。"""
     if row is None or tuple(row.get(c, "") for c in key_cols) != tuple(key):

{larksync-0.1.0 → larksync-0.1.2}/tests/test_flow.py

@@ -153,3 +153,14 @@ def test_diff_validation():
         t.diff([{"ID": "1", "状态": "b"}, {"ID": "1", "状态": "c"}], key="ID")
     with pytest.raises(LarkError, match="主键为空"):
         t.diff([{"ID": "", "状态": "b"}], key="ID")
+
+
+def test_progress_callback():
+    t = table(["ID", "状态"], [{"ID": str(i), "状态": ""} for i in range(2500)])
+    plan = t.diff([{"ID": str(i), "状态": "x"} for i in range(2500)], key="ID")
+    seen = []
+    rid = plan.apply(progress=lambda stage, done, total: seen.append((stage, done, total)))
+    assert seen == [("检查", 0, 2500), ("写入", 1000, 2500), ("写入", 2000, 2500), ("写入", 2500, 2500)]
+    seen.clear()
+    t.undo(rid, progress=lambda *a: seen.append(a))
+    assert seen[0] == ("检查", 0, 2500) and seen[-1] == ("撤销", 2500, 2500)