larksync 0.1.0__py3-none-any.whl

larksync/__init__.py

@@ -0,0 +1,6 @@
+"""larksync：飞书电子表格 / 多维表格的拉取与按主键更新。"""
+from .auth import configure
+from .http import LarkError
+from .table import Table
+
+__all__ = ["Table", "LarkError", "configure"]

larksync/auth.py

@@ -0,0 +1,179 @@
+"""本机飞书应用配置与登录。
+
+每人用自己的飞书应用（表格权限因人而异），configure() 一次即可。
+user 身份（默认）首次登录打开浏览器，之后缓存 token、自动续期；tenant 身份无需登录。
+"""
+import json
+import os
+import sys
+import threading
+import time
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import platformdirs
+
+from .http import BASE, LarkError, call
+
+CONFIG_DIR = Path(platformdirs.user_config_dir("larksync", appauthor=False))
+CONFIG_FILE = CONFIG_DIR / "config.json"
+TOKEN_FILE = CONFIG_DIR / "token.json"
+
+SCOPES = "wiki:wiki:readonly sheets:spreadsheet bitable:app"
+_EXPIRY_MARGIN_S = 300   # 提前 5 分钟判过期，免得请求发出的瞬间失效
+_LOGIN_TIMEOUT_S = 180
+
+
+def configure(app_id, app_secret, port=8888):
+    """保存本机的飞书应用。port 要和应用后台配置的重定向地址 http://localhost:<port>/callback 一致。"""
+    write_json(CONFIG_FILE, {"app_id": app_id.strip(), "app_secret": app_secret.strip(),
+                              "port": int(port)})
+
+
+def load_config():
+    cfg = read_json(CONFIG_FILE)
+    app_id = os.environ.get("LARKSYNC_APP_ID") or cfg.get("app_id")
+    app_secret = os.environ.get("LARKSYNC_APP_SECRET") or cfg.get("app_secret")
+    if not app_id or not app_secret:
+        raise LarkError("还没配置飞书应用：先运行 larksync.configure(app_id, app_secret)，"
+                        "或设置环境变量 LARKSYNC_APP_ID / LARKSYNC_APP_SECRET")
+    return app_id, app_secret, int(cfg.get("port") or 8888)
+
+
+class Auth:
+    def __init__(self, method="user"):
+        if method not in ("user", "tenant"):
+            raise LarkError(f'auth 只能是 "user" 或 "tenant"，收到 {method!r}')
+        self.method = method
+        self.app_id, self.app_secret, self.port = load_config()
+
+    def token(self):
+        c = self._cached()
+        if c and c["expires_at"] > time.time():
+            return c["access_token"]
+        if self.method == "tenant":
+            body = call("POST", "/auth/v3/tenant_access_token/internal",
+                        json={"app_id": self.app_id, "app_secret": self.app_secret})
+            return self._save({"access_token": body["tenant_access_token"],
+                               "expires_in": body.get("expire")})
+        if c and (t := self._refresh(c.get("refresh_token"))):
+            return t
+        return self._login()
+
+    def account(self):
+        """已登录的用户名（只看本地缓存，不联网）；没登录返回 None。"""
+        c = self._cached()
+        if not c or (c["expires_at"] <= time.time() and not c.get("refresh_token")):
+            return None
+        return c.get("name") or "飞书用户"
+
+    def logout(self):
+        d = read_json(TOKEN_FILE)
+        if d.pop(self.method, None) is not None:
+            write_json(TOKEN_FILE, d)
+
+    # -- 缓存：按 app_id 隔离，换应用自动作废 --
+
+    def _cached(self):
+        d = read_json(TOKEN_FILE)
+        block = d.get(self.method) if d.get("app_id") == self.app_id else None
+        if isinstance(block, dict) and block.get("access_token"):
+            return block
+        return None
+
+    def _save(self, data):
+        token = data.get("access_token")
+        if not token:
+            raise LarkError(f"飞书没有返回 access_token：{data}")
+        d = read_json(TOKEN_FILE)
+        if d.get("app_id") != self.app_id:
+            d = {"app_id": self.app_id}
+        d[self.method] = {
+            "access_token": token,
+            "refresh_token": data.get("refresh_token", ""),
+            "expires_at": time.time() + float(data.get("expires_in") or 0) - _EXPIRY_MARGIN_S,
+            "name": data.get("name") or (d.get(self.method) or {}).get("name", ""),
+        }
+        try:
+            write_json(TOKEN_FILE, d)
+        except OSError:
+            pass   # 缓存写不下去不该让整个流程失败
+        return token
+
+    # -- user 身份：续期 -> 浏览器登录 --
+
+    def _app_token(self):
+        body = call("POST", "/auth/v3/app_access_token/internal",
+                    json={"app_id": self.app_id, "app_secret": self.app_secret})
+        return body["app_access_token"]
+
+    def _refresh(self, refresh_token):
+        if not refresh_token:
+            return None
+        try:
+            body = call("POST", "/authen/v1/refresh_access_token", token=self._app_token(),
+                        json={"grant_type": "refresh_token", "refresh_token": refresh_token})
+        except LarkError:
+            # refresh_token 每次续期都会轮换：可能是别的进程刚续过，再看一眼缓存
+            c = self._cached()
+            if c and c["expires_at"] > time.time():
+                return c["access_token"]
+            return None
+        return self._save(body.get("data") or {})
+
+    def _login(self):
+        got = {}
+        done = threading.Event()
+
+        class Callback(BaseHTTPRequestHandler):
+            def do_GET(self):
+                got["code"] = (parse_qs(urlparse(self.path).query).get("code") or [None])[0]
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write("<h3>飞书授权完成，可以关闭这个页面了。</h3>".encode())
+                done.set()
+
+            def log_message(self, *a):
+                pass
+
+        try:
+            server = HTTPServer(("localhost", self.port), Callback)
+        except OSError as e:
+            raise LarkError(f"本机端口 {self.port} 被占用：换个端口重新 configure，"
+                            f"并同步修改应用后台的重定向地址") from e
+        threading.Thread(target=server.serve_forever, daemon=True).start()
+        url = f"{BASE}/authen/v1/index?" + urlencode({
+            "app_id": self.app_id, "scope": SCOPES,
+            "redirect_uri": f"http://localhost:{self.port}/callback"})
+        print(f"请在浏览器中登录飞书并授权（没有自动打开就手动访问）：\n  {url}",
+              file=sys.stderr, flush=True)
+        webbrowser.open(url)
+        try:
+            if not done.wait(_LOGIN_TIMEOUT_S) or not got.get("code"):
+                raise LarkError(f"{_LOGIN_TIMEOUT_S} 秒内没有完成飞书授权。服务器上请改用 "
+                                f'auth="tenant"，或拷贝本机的 {TOKEN_FILE.name}')
+        finally:
+            server.shutdown()
+            server.server_close()
+        body = call("POST", "/authen/v1/access_token", token=self._app_token(),
+                    json={"grant_type": "authorization_code", "code": got["code"]})
+        return self._save(body.get("data") or {})
+
+
+def read_json(path):
+    try:
+        d = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return d if isinstance(d, dict) else {}
+
+
+def write_json(path, data):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, path)   # 原子替换，并发写入不会留下半个文件

larksync/bitable.py

@@ -0,0 +1,186 @@
+"""多维表格后端：字段即列，record_id 即行。"""
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+
+from .http import LarkError, call
+from .sheets import cell_str
+
+_BATCH = 500
+_OR_MAX = 50          # 一次查询里 OR 的条件数
+_LOOKUP_MAX = 2000    # 主键值再多就不如直接读全表
+_WORKERS = 5
+_FILTERABLE = {1, 13}  # 能按「等于」精确查询的主键类型：文本、电话
+_WRITABLE = {1, 2, 3, 4, 5, 7, 13}   # 文本 数字 单选 多选 日期 复选框 电话
+_DATES = {5, 1001, 1002}             # 日期 创建时间 修改时间
+_DATE_FORMATS = ("%Y-%m-%d", "%Y/%m/%d", "%Y-%m-%d %H:%M", "%Y/%m/%d %H:%M",
+                 "%Y-%m-%d %H:%M:%S", "%Y/%m/%d %H:%M:%S")
+_TRUE = {"true", "1", "是", "yes", "y", "✓"}
+_FALSE = {"false", "0", "否", "no", "n"}
+
+
+class Bitable:
+    def __init__(self, auth, app_token, table_id=None):
+        self.auth = auth
+        tables = call("GET", f"/bitable/v1/apps/{app_token}/tables", token=auth.token(),
+                      params={"page_size": 100})["data"].get("items") or []
+        self._tabs = [(t["table_id"], t.get("name", "")) for t in tables]
+        if not self._tabs:
+            raise LarkError("这个多维表格里没有数据表")
+        table_id = table_id or self._tabs[0][0]
+        if table_id not in dict(self._tabs):
+            ids = [f"{i}（{n}）" for i, n in self._tabs]
+            raise LarkError(f"没有 table={table_id} 的数据表，现有：{', '.join(ids)}")
+        self.target = f"bitable:{app_token}:{table_id}"
+        app = call("GET", f"/bitable/v1/apps/{app_token}", token=auth.token())["data"].get("app") or {}
+        self.doc_title = app.get("name", "")
+        self._base = f"/bitable/v1/apps/{app_token}/tables/{table_id}"
+        self._fields = {}   # 字段名 → 类型，每次读取都刷新
+
+    def tabs(self):
+        return list(self._tabs)
+
+    def columns(self):
+        self._fields = {f["field_name"]: f["type"] for f in self._pages("GET", "/fields", 100)}
+        return list(self._fields)
+
+    def read(self):
+        """返回 (列名, 记录, record_id)；全空的记录跳过。"""
+        header = self.columns()
+        rows, refs = [], []
+        for it in self._pages("POST", "/records/search", 500, json={}):
+            row = self._row(it["fields"])
+            if any(row.values()):
+                rows.append(row)
+                refs.append(it["record_id"])
+        return header, rows, refs
+
+    def lookup(self, key, values):
+        """主键第一列取值在 values 里的记录。返回 (记录, record_id, 表的总记录数)。
+
+        按条件查询，每次 OR 50 个值、并发 5 个请求；主键不是文本类或值太多时退回读全表。
+        """
+        self.columns()
+        values = sorted(v for v in values if v)
+        if self._fields.get(key[0]) not in _FILTERABLE or len(values) > _LOOKUP_MAX:
+            _, rows, refs = self.read()
+            return rows, refs, len(rows)
+
+        def search(chunk):
+            flt = {"conjunction": "or", "conditions": [
+                {"field_name": key[0], "operator": "is", "value": [v]} for v in chunk]}
+            return [(it["record_id"], self._row(it["fields"]))
+                    for it in self._pages("POST", "/records/search", 500, json={"filter": flt})]
+
+        chunks = [values[i:i + _OR_MAX] for i in range(0, len(values), _OR_MAX)]
+        with ThreadPoolExecutor(_WORKERS) as pool:
+            total = pool.submit(self._total)
+            found = [hit for part in pool.map(search, chunks) for hit in part]
+        return [r for _, r in found], [ref for ref, _ in found], total.result()
+
+    def _total(self):
+        return call("POST", self._base + "/records/search", token=self.auth.token(),
+                    params={"page_size": 1}, json={})["data"].get("total", 0)
+
+    def fetch(self, refs):
+        """只读指定的记录：{record_id: 记录}，已删除的不在结果里。"""
+        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 writable(self, name):
+        return self._fields.get(name) in _WRITABLE
+
+    def canon(self, name, s):
+        """本地文本按字段类型规整成读回来的样子（如 1.50 → 1.5），值不合法就报错。"""
+        if not s or not self.writable(name):
+            return s
+        return self._text(name, self._value(name, s))
+
+    def update(self, cells):
+        fields = {}
+        for ref, col, val in cells:
+            fields.setdefault(ref, {})[col] = self._value(col, val)
+        recs = [{"record_id": r, "fields": f} for r, f in fields.items()]
+        for i in range(0, len(recs), _BATCH):
+            self._post("/records/batch_update", {"records": recs[i:i + _BATCH]})
+
+    def create(self, rows):
+        """分批新增，每批写完 yield 这批的 record_id。"""
+        for i in range(0, len(rows), _BATCH):
+            recs = [{"fields": {c: self._value(c, v) for c, v in r.items() if v}}
+                    for r in rows[i:i + _BATCH]]
+            data = self._post("/records/batch_create", {"records": recs})
+            yield [r["record_id"] for r in data["records"]]
+
+    def delete(self, refs):
+        for i in range(0, len(refs), _BATCH):
+            self._post("/records/batch_delete", {"records": refs[i:i + _BATCH]})
+
+    def add_fields(self, names):
+        for n in names:
+            self._post("/fields", {"field_name": n, "type": 1})
+            self._fields[n] = 1
+
+    # -- 值转换 --
+
+    def _row(self, fields):
+        return {h: self._text(h, fields.get(h)) for h in self._fields}
+
+    def _text(self, name, v):
+        if self._fields.get(name) in _DATES and isinstance(v, (int, float)):
+            dt = datetime.fromtimestamp(v / 1000)
+            return dt.strftime("%Y-%m-%d" if dt.time() == datetime.min.time() else "%Y-%m-%d %H:%M")
+        return cell_str(v)
+
+    def _value(self, name, s):
+        """文本 → 飞书字段值；空串表示清空。"""
+        if not s:
+            return None
+        t = self._fields[name]
+        if t == 2:
+            s = s.replace(",", "")
+            try:
+                return int(s)
+            except ValueError:
+                pass
+            try:
+                n = float(s)
+            except ValueError:
+                raise LarkError(f"{s!r} 不是数字") from None
+            return int(n) if n.is_integer() else n
+        if t == 4:
+            return [x.strip() for x in s.split(",") if x.strip()]
+        if t == 5:
+            for fmt in _DATE_FORMATS:
+                try:
+                    return int(datetime.strptime(s, fmt).timestamp() * 1000)
+                except ValueError:
+                    pass
+            raise LarkError(f"{s!r} 不是日期（支持 2026-01-02、2026/01/02、可带 HH:MM[:SS]）")
+        if t == 7:
+            if s.lower() in _TRUE:
+                return True
+            if s.lower() in _FALSE:
+                return False
+            raise LarkError(f"{s!r} 不是勾选值（支持 true/false、是/否、1/0）")
+        return s
+
+    # -- HTTP --
+
+    def _pages(self, method, path, size, json=None):
+        page = None
+        while True:
+            params = {"page_size": size, **({"page_token": page} if page else {})}
+            data = call(method, self._base + path, token=self.auth.token(),
+                        params=params, json=json)["data"]
+            yield from data.get("items") or []
+            if not data.get("has_more"):
+                return
+            page = data["page_token"]
+
+    def _post(self, path, payload):
+        return call("POST", self._base + path, token=self.auth.token(), json=payload)["data"]

larksync/diff.py

@@ -0,0 +1,154 @@
+"""差异计算：按主键匹配本地行和在线行（两种表共用）。"""
+import csv
+import io
+import os
+from datetime import date, datetime, time
+from dataclasses import dataclass, field
+
+from .http import LarkError
+
+
+@dataclass(frozen=True)
+class Change:
+    key: tuple
+    column: str
+    old: str
+    new: str
+    ref: object = field(default=None, repr=False)   # 在线行的 ref，写入时定位用
+
+
+class Plan:
+    """diff 的结果。apply 只写 changed 和 added，写之前可以随意删减。
+
+    默认只填空：在线已有不同值的格子放进 conflicts，不写；人工确认后
+    移入 changed 才会写（全部覆盖：plan.changed += plan.conflicts）。
+    """
+
+    def __init__(self, table, key, changed, conflicts, added, unmatched):
+        self._table = table
+        self.key = key
+        self.changed = changed      # list[Change]：在线为空、本地有值
+        self.conflicts = conflicts  # list[Change]：在线已有不同的值（警告）
+        self.added = added          # list[dict]：本地有、在线没有的行
+        self.unmatched = unmatched  # int：在线有、本地没有的行数（只提示，不删）
+
+    def __repr__(self):
+        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 load(source):
+    """CSV / xlsx 的路径或字节、或 list[dict] → (列名, 行)；值统一成去掉首尾空白的字符串。
+
+    xlsx 读第一个（打开时显示的）工作表，第 1 行是表头。
+    """
+    if isinstance(source, (str, os.PathLike)):
+        with open(source, "rb") as f:
+            source = f.read()
+    if isinstance(source, bytes) and source[:4] == b"PK\x03\x04":   # xlsx 本质是 zip
+        raw, rows = _xlsx(source)
+    elif isinstance(source, bytes):
+        reader = csv.DictReader(io.StringIO(decode(source), newline=""))
+        raw = reader.fieldnames or []
+        rows = list(reader)
+    else:
+        rows = list(source)
+        raw = list(dict.fromkeys(k for r in rows for k in r))
+    header = [str(h).strip() for h in raw if h is not None and str(h).strip()]
+    dupes = sorted({h for h in header if header.count(h) > 1})
+    if dupes:
+        raise LarkError(f"本地数据的列名重复：{'、'.join(dupes)}")
+    rows = [{str(k).strip(): "" if v is None else str(v).strip()
+             for k, v in r.items() if k is not None and str(k).strip()} for r in rows]
+    return header, rows
+
+
+def _xlsx(data):
+    from openpyxl import load_workbook   # 只有读 xlsx 时才需要
+
+    ws = load_workbook(io.BytesIO(data), read_only=True, data_only=True).active
+    grid = [[_xlsx_cell(v) for v in row] for row in ws.iter_rows(values_only=True)]
+    if not grid:
+        return [], []
+    header = grid[0]
+    return header, [dict(zip(header, r)) for r in grid[1:] if any(r)]
+
+
+def _xlsx_cell(v):
+    """按单元格显示的样子转文本：整数不带 .0，日期不带 00:00:00。"""
+    if v is None:
+        return ""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, float) and v.is_integer():
+        return str(int(v))
+    if isinstance(v, datetime):
+        return v.strftime("%Y-%m-%d" if v.time() == time() else "%Y-%m-%d %H:%M:%S")
+    if isinstance(v, date):
+        return v.isoformat()
+    return str(v)
+
+
+def decode(data):
+    """UTF-8（含 BOM）优先，不行再按 GBK：Excel 中文版另存的 CSV 默认是 GBK。"""
+    try:
+        return data.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        try:
+            return data.decode("gb18030")
+        except UnicodeDecodeError:
+            raise LarkError("CSV 编码认不出来：请另存为 UTF-8 编码的 CSV") from None
+
+
+def compute(online_rows, online_refs, local_rows, key, columns):
+    """返回 (补空, 不一致, 新增的本地行, 匹配上的行数)。本地为空的格子不参与（不会清空在线值）。"""
+    online = keyed(online_rows, key, online_refs)
+    local = keyed(local_rows, key, local=True)
+    changed, conflicts = [], []
+    for k, (_, r) in local.items():
+        if k not in online:
+            continue
+        ref, o = online[k]
+        for c in columns:
+            new, old = r.get(c, ""), o.get(c, "")
+            if new and new != old:
+                (conflicts if old else changed).append(Change(k, c, old, new, ref))
+    added = [r for k, (_, r) in local.items() if k not in online]
+    return changed, conflicts, added, sum(1 for k in local if k in online)
+
+
+def keyed(rows, key, refs=None, local=False):
+    """按主键建索引 {key: (ref, row)}。主键为空：在线行跳过，本地行报错；主键重复报错。"""
+    idx, dupes, empty = {}, [], []
+    for i, r in enumerate(rows):
+        k = tuple(r.get(c, "") for c in key)
+        if not any(k):
+            empty.append(i + 1)
+            continue
+        if k in idx:
+            dupes.append(k)
+            continue
+        idx[k] = (refs[i] if refs else i, r)
+    where = "本地数据" if local else "在线表"
+    if local and empty:
+        raise LarkError(f"{where}第 {brief(map(str, empty), sep='、')} 条的主键为空")
+    if dupes:
+        uniq = list(dict.fromkeys(dupes))
+        raise LarkError(f"{where}按「{' + '.join(key)}」匹配时有 {len(uniq)} 个值重复，例如："
+                        f"{'、'.join(show_key(k) for k in uniq[:5])}。主键要能唯一确定一行，"
+                        f"可以再多勾选一个字段组成联合主键")
+    return idx
+
+
+def show_key(k):
+    return "/".join(k)
+
+
+def brief(lines, n=20, sep="\n"):
+    lines = list(lines)
+    more = f"{sep}…共 {len(lines)} 处" if len(lines) > n else ""
+    return sep.join(lines[:n]) + more

larksync/history.py

@@ -0,0 +1,41 @@
+"""写入记录：每次写飞书之前先落盘，撤销时据此还原。"""
+import secrets
+import time
+from dataclasses import asdict
+
+from .auth import CONFIG_DIR, read_json, write_json
+from .http import LarkError
+
+DIR = CONFIG_DIR / "history"
+
+
+def new(url, target, key, changed, added):
+    rec = {
+        "id": time.strftime("%Y%m%d-%H%M%S-") + secrets.token_hex(2),
+        "time": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "url": url,
+        "target": target,
+        "key": list(key),
+        "status": "pending",        # pending → done → undone；中途失败会停在 pending
+        "changed": [asdict(c) for c in changed],
+        "added": added,
+        "created": [],              # 新增行的 ref，和 added 一一对应，每批写完就更新
+    }
+    save(rec)
+    return rec
+
+
+def save(rec):
+    write_json(DIR / f"{rec['id']}.json", rec)
+
+
+def load(record_id):
+    rec = read_json(DIR / f"{record_id}.json")
+    if not rec:
+        raise LarkError(f"找不到写入记录 {record_id}")
+    return rec
+
+
+def records():
+    """所有写入记录，新的在前。"""
+    return [read_json(p) for p in sorted(DIR.glob("*.json"), reverse=True)]

larksync/http.py

@@ -0,0 +1,55 @@
+"""飞书开放平台 HTTP：网络错误和限流自动退避重试，错误码统一转成 LarkError。"""
+import os
+import time
+
+import httpx
+
+BASE = "https://open.feishu.cn/open-apis"
+_TRIES = 5
+_RATE_LIMITED = {99991400, 1254290, 1254291}   # 频控、多维表格写冲突
+
+
+class LarkError(Exception):
+    def __init__(self, msg, code=None):
+        super().__init__(msg)
+        self.code = code
+
+
+_client = None
+_client_pid = None
+
+
+def _http():
+    # fork 出来的子进程不能复用父进程的连接池
+    global _client, _client_pid
+    if _client is None or _client_pid != os.getpid():
+        _client = httpx.Client(base_url=BASE, timeout=30)
+        _client_pid = os.getpid()
+    return _client
+
+
+def call(method, path, *, token=None, params=None, json=None):
+    """返回飞书响应的完整 body（code == 0）。"""
+    headers = {"Authorization": f"Bearer {token}"} if token else {}
+    for attempt in range(_TRIES):
+        last = attempt == _TRIES - 1
+        try:
+            resp = _http().request(method, path, headers=headers, params=params, json=json)
+        except httpx.TransportError as e:
+            if last:
+                raise LarkError(f"网络错误：{e}") from e
+            time.sleep(2 ** attempt)
+            continue
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {}
+        code = body.get("code")
+        retryable = resp.status_code == 429 or resp.status_code >= 500 or code in _RATE_LIMITED
+        if retryable and not last:
+            time.sleep(2 ** attempt)
+            continue
+        if code not in (0, None) or resp.is_error:
+            shown = code if code is not None else f"HTTP {resp.status_code}"
+            raise LarkError(f"飞书接口返回错误 {shown}：{body.get('msg') or resp.text[:300]}", code)
+        return body

larksync/sheets.py

@@ -0,0 +1,230 @@
+"""电子表格后端：第 1 行是表头，下面每行一条记录，行号即 ref。"""
+from .http import LarkError, call
+
+_ROWS_PER_READ = 2000
+_CELLS_PER_WRITE = 5000
+_DIM_MAX = 5000   # 一次最多增删的行 / 列数
+
+
+class Sheets:
+    def __init__(self, auth, token, sheet_id=None):
+        self.auth, self.token = auth, token
+        self._api = f"/sheets/v2/spreadsheets/{token}"
+        tabs = self._meta()
+        tab = next((t for t in tabs if t.get("sheetId") == sheet_id), None) if sheet_id \
+            else (tabs[0] if tabs else None)
+        if tab is None:
+            ids = [f"{t.get('sheetId')}（{t.get('title')}）" for t in tabs]
+            raise LarkError(f"没有 sheet={sheet_id} 的工作表，现有：{', '.join(ids)}")
+        self.sheet_id = tab["sheetId"]
+        self.title = tab.get("title", "")
+        self.target = f"sheet:{token}:{self.sheet_id}"
+        self._size(tab)
+        self._col = {}    # 列名 → 列下标，每次读取都刷新
+        self._last = 1    # 最后一个非空数据行的行号
+
+    def tabs(self):
+        return list(self._tabs)
+
+    def columns(self):
+        self._refresh()
+        header = self._grid(1, 1)
+        return self._index(header[0] if header else [])
+
+    def read(self):
+        """返回 (列名, 记录, 行号)。"""
+        self._refresh()
+        grid = []
+        for start in range(1, self._rows + 1, _ROWS_PER_READ):
+            grid += self._grid(start, min(start + _ROWS_PER_READ - 1, self._rows))
+        header, rows, refs = records(grid)
+        self._index(grid[0] if grid else [])
+        self._last = max(refs, default=1)
+        return header, rows, refs
+
+    def lookup(self, key, values):
+        """主键第一列取值在 values 里的行。电子表格读全表很快，直接读全表。返回 (记录, 行号, 总行数)。"""
+        _, rows, refs = self.read()
+        return rows, refs, len(rows)
+
+    def fetch(self, refs):
+        """{行号: 记录}。电子表格读全表也很快，直接读全表再挑。"""
+        _, rows, all_refs = self.read()
+        current = dict(zip(all_refs, rows))
+        return {r: current[r] for r in refs if r in current}
+
+    def writable(self, name):
+        return True
+
+    def canon(self, name, s):
+        return s
+
+    def update(self, cells):
+        """按列把相邻行合并成一个区域写入。"""
+        by_col = {}
+        for row, col, val in cells:
+            by_col.setdefault(self._col[col], []).append((row, val))
+        ranges = []
+        for ci, items in by_col.items():
+            items.sort()
+            run = [items[0]]
+            for it in items[1:]:
+                if it[0] != run[-1][0] + 1:
+                    ranges.append(self._range(ci, ci, run[0][0], [[v] for _, v in run]))
+                    run = []
+                run.append(it)
+            ranges.append(self._range(ci, ci, run[0][0], [[v] for _, v in run]))
+        self._write(ranges)
+
+    def create(self, rows):
+        """追加到最后一个数据行之后，不够就先加行；每批写完 yield 这批的行号。"""
+        if not rows:
+            return
+        width = max(self._col.values()) + 1
+        names = {i: c for c, i in self._col.items()}
+        start = self._last + 1
+        self._grow("ROWS", start + len(rows) - 1 - self._rows)
+        step = max(1, _CELLS_PER_WRITE // width)
+        for i in range(0, len(rows), step):
+            chunk = rows[i:i + step]
+            values = [[r.get(names.get(j), "") for j in range(width)] for r in chunk]
+            self._write([self._range(0, width - 1, start + i, values)])
+            yield list(range(start + i, start + i + len(chunk)))
+        self._last = start + len(rows) - 1
+
+    def delete(self, refs):
+        """从下往上删，避免删掉上面的行后下面的行号变化。"""
+        for hi, lo in _runs(sorted(refs, reverse=True)):
+            call("DELETE", f"{self._api}/dimension_range", token=self.auth.token(),
+                 json={"dimension": {"sheetId": self.sheet_id, "majorDimension": "ROWS",
+                                     "startIndex": lo, "endIndex": hi}})
+
+    def add_fields(self, names):
+        """在表头最后一列之后追加列名。"""
+        if not names:
+            return
+        start = max(self._col.values(), default=-1) + 1
+        self._grow("COLUMNS", start + len(names) - self._cols)
+        self._write([self._range(start, start + len(names) - 1, 1, [list(names)])])
+        self._col.update({n: start + i for i, n in enumerate(names)})
+
+    # -- 内部 --
+
+    def _meta(self):
+        data = call("GET", f"{self._api}/metainfo", token=self.auth.token())["data"]
+        self.doc_title = (data.get("properties") or {}).get("title", "")
+        tabs = data.get("sheets") or []
+        self._tabs = [(t.get("sheetId"), t.get("title", "")) for t in tabs]
+        return tabs
+
+    def _refresh(self):
+        """行列数可能被别人改过，读之前先刷新。"""
+        tab = next((t for t in self._meta() if t.get("sheetId") == self.sheet_id), None)
+        if tab is None:
+            raise LarkError(f"工作表 {self.title}（{self.sheet_id}）已被删除")
+        self._size(tab)
+
+    def _size(self, tab):
+        self._rows = int(tab.get("rowCount") or 0)
+        self._cols = int(tab.get("columnCount") or 0)
+
+    def _index(self, header):
+        names = [h for h in header if h]
+        records([header])   # 顺便检查重复列名
+        self._col = {h: i for i, h in enumerate(header) if h}
+        return names
+
+    def _grid(self, start, end):
+        if self._cols == 0:
+            return []
+        body = call("GET", f"{self._api}/values/"
+                           f"{self.sheet_id}!A{start}:{column_letter(self._cols - 1)}{end}",
+                    token=self.auth.token(), params={"valueRenderOption": "FormattedValue"})
+        return [[cell_str(c) for c in row] for row in body["data"]["valueRange"].get("values") or []]
+
+    def _range(self, c1, c2, row, values):
+        rng = f"{self.sheet_id}!{column_letter(c1)}{row}:{column_letter(c2)}{row + len(values) - 1}"
+        return {"range": rng, "values": values}
+
+    def _write(self, ranges):
+        batch, cells = [], 0
+        for r in ranges + [None]:
+            n = sum(len(v) for v in r["values"]) if r else 0
+            if batch and (r is None or cells + n > _CELLS_PER_WRITE):
+                call("POST", f"{self._api}/values_batch_update", token=self.auth.token(),
+                     json={"valueRanges": batch})
+                batch, cells = [], 0
+            if r:
+                batch.append(r)
+                cells += n
+
+    def _grow(self, dim, n):
+        """末尾补 n 行 / 列（n <= 0 时什么都不做）。"""
+        while n > 0:
+            k = min(n, _DIM_MAX)
+            call("POST", f"{self._api}/dimension_range", token=self.auth.token(),
+                 json={"dimension": {"sheetId": self.sheet_id, "majorDimension": dim, "length": k}})
+            if dim == "ROWS":
+                self._rows += k
+            else:
+                self._cols += k
+            n -= k
+
+
+def _runs(desc):
+    """降序行号 → 连续段 [(hi, lo)]。"""
+    out = []
+    for r in desc:
+        if out and out[-1][1] == r + 1:
+            out[-1] = (out[-1][0], r)
+        else:
+            out.append((r, r))
+    return out
+
+
+def records(grid):
+    """表头为空的列跳过，整行为空的行跳过；列名重复直接报错。返回 (列名, 记录, 行号)。"""
+    if not grid:
+        return [], [], []
+    header = grid[0]
+    cols = [i for i, h in enumerate(header) if h]
+    dupes = sorted({header[i] for i in cols if header.count(header[i]) > 1})
+    if dupes:
+        raise LarkError(f"表头有重复的列名：{', '.join(dupes)}")
+    rows, refs = [], []
+    for n, r in enumerate(grid[1:], start=2):
+        r = r + [""] * (len(header) - len(r))
+        if any(r[i] for i in cols):
+            rows.append({header[i]: r[i] for i in cols})
+            refs.append(n)
+    return [header[i] for i in cols], rows, refs
+
+
+def cell_str(v):
+    """飞书单元格 / 字段值 → 文本（两种表共用）。"""
+    if v is None:
+        return ""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, list):
+        if v and all(isinstance(x, dict) and "text" in x for x in v):   # 富文本分段
+            return "".join(str(x["text"]) for x in v).strip()
+        return ",".join(s for s in map(cell_str, v) if s)              # 多选、人员等
+    if isinstance(v, dict):   # 链接、人员、附件、公式等
+        for k in ("text", "name", "link", "full_address"):
+            if v.get(k):
+                return str(v[k]).strip()
+        return cell_str(v.get("value"))
+    if isinstance(v, float) and v.is_integer():
+        return str(int(v))
+    return str(v).strip()
+
+
+def column_letter(index):
+    """0 -> A, 25 -> Z, 26 -> AA"""
+    out = ""
+    while True:
+        out = chr(ord("A") + index % 26) + out
+        index = index // 26 - 1
+        if index < 0:
+            return out

larksync/table.py

@@ -0,0 +1,223 @@
+"""Table：用链接打开一张飞书表，拉取 / 按主键更新 / 撤销。"""
+import csv
+from contextlib import contextmanager
+from urllib.parse import parse_qs, urlparse
+
+from . import history
+from .auth import SCOPES, Auth
+from .bitable import Bitable
+from .diff import Plan, brief, compute, keyed, load, show_key
+from .http import LarkError, call
+from .sheets import Sheets
+
+_DENIED = {91403, 131006, 1254302}
+_MISSING_SCOPE = {99991672, 99991679}
+
+
+class Table:
+    def __init__(self, url, auth="user", tab=None):
+        """tab：工作表 / 数据表 id，不传就用链接里的 ?sheet= / ?table=，再没有就用第一个。"""
+        self.url = url
+        self._auth = Auth(auth)
+        kind, token, sub = parse_url(url)
+        sub = tab or sub
+        title = None
+        with self._explained():
+            if kind == "wiki":
+                node = call("GET", "/wiki/v2/spaces/get_node", token=self._auth.token(),
+                            params={"token": token, "obj_type": "wiki"})["data"]["node"]
+                kind, token, title = node["obj_type"], node["obj_token"], node.get("title")
+            if kind == "sheet":
+                self._backend = Sheets(self._auth, token, sub)
+            elif kind == "bitable":
+                self._backend = Bitable(self._auth, token, sub)
+            else:
+                raise LarkError(f"不支持的文档类型 {kind!r}，只支持电子表格和多维表格")
+        self.title = title or self._backend.doc_title   # 文档标题（知识库链接用节点标题）
+        self.tab = self._backend.target.split(":")[2]  # 当前工作表 / 数据表 id
+
+    def tabs(self):
+        """同一文档里的所有工作表 / 数据表：[(id, 标题)]。"""
+        return self._backend.tabs()
+
+    def columns(self):
+        """表头（只读表头，不读数据）。"""
+        with self._explained():
+            return self._backend.columns()
+
+    def pull(self, path=None):
+        """拉取整张表，返回 list[dict]；传 path 时同时写成 CSV（utf-8-sig，Excel 可直接打开）。"""
+        with self._explained():
+            header, rows, _ = self._backend.read()
+        if path is not None:
+            with open(path, "w", encoding="utf-8-sig", newline="") as f:
+                w = csv.DictWriter(f, fieldnames=header)
+                w.writeheader()
+                w.writerows(rows)
+        return rows
+
+    def diff(self, source, key, columns=None):
+        """按主键比较本地数据（CSV 路径或 list[dict]）和在线表，见 Plan。
+
+        columns 为空时比较本地所有非主键列；新增行写入本地和在线共有的所有可写列。
+        """
+        local_header, local_rows = load(source)
+        with self._explained():
+            header = self._backend.columns()
+        key = [key] if isinstance(key, str) else list(key)
+        cols = list(columns) if columns is not None else [c for c in local_header if c not in key]
+        for c in key + cols:
+            if c not in local_header:
+                raise LarkError(f"本地数据里没有列「{c}」")
+            if c not in header:
+                tip = "；只更新部分列请传 columns=[...]" if columns is None else ""
+                raise LarkError(f"在线表里没有列「{c}」{tip}")
+        readonly = [c for c in cols if not self._backend.writable(c)]
+        if readonly:
+            raise LarkError(f"这些列在线表里是只读的，不能更新：{'、'.join(readonly)}")
+
+        common = [c for c in local_header if c in header]
+        local_rows = self._canon(local_rows, common)
+        wanted = {k[0] for k in keyed(local_rows, key, local=True)}
+        with self._explained():   # 只读主键和本地相同的行，表再大也快
+            rows, refs, total = self._backend.lookup(key, wanted)
+        changed, conflicts, added, matched = compute(rows, refs, local_rows, key, cols)
+        if added and not all(self._backend.writable(c) for c in key):
+            raise LarkError("主键列在线表里是只读的，不能新增行")
+        writable = [c for c in common if self._backend.writable(c)]
+        added = [{c: r[c] for c in writable} for r in added]
+        return Plan(self, key, changed, conflicts, added, total - matched)
+
+    def init(self, source):
+        """用首个 CSV 初始化空表：补齐在线表缺少的列，再写入全部行。返回写入记录 id。"""
+        local_header, local_rows = load(source)
+        with self._explained():
+            header, rows, _ = self._backend.read()
+            if rows:
+                raise LarkError("表里已经有数据，init 只能用于空表；更新请用 diff")
+            self._backend.add_fields([c for c in local_header if c not in header])
+            readonly = [c for c in local_header if not self._backend.writable(c)]
+            if readonly:
+                raise LarkError(f"这些列在线表里是只读的，不能写入：{'、'.join(readonly)}")
+            added = self._canon(local_rows, local_header)
+            rec = history.new(self.url, self._backend.target, [], [], added)
+            self._write(rec, [], added)
+        return rec["id"]
+
+    def undo(self, record_id):
+        """撤销一次写入：还原改过的格子、删掉新增的行。之后又被别人改过的话整体中止。"""
+        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():
+            current = self._backend.fetch([ch["ref"] for ch in rec["changed"]] + rec["created"])
+            conflicts, cells, drop = [], [], []
+            for ch in rec["changed"]:
+                cur = _cell(current.get(ch["ref"]), rec["key"], tuple(ch["key"]), ch["column"])
+                if cur == ch["new"]:
+                    cells.append((ch["ref"], ch["column"], ch["old"]))
+                elif cur != ch["old"]:   # 等于 old 说明这格当时没写成，跳过
+                    conflicts.append(_conflict(ch["key"], ch["column"], ch["new"], cur))
+            for ref, row in zip(rec["created"], rec["added"]):
+                cur = current.get(ref)
+                if cur is None:
+                    continue   # 已经被删了
+                if any(cur.get(c, "") != v for c, v in row.items()):
+                    who = show_key([row.get(c, "") for c in rec["key"]]) if rec["key"] else ref
+                    conflicts.append(f"新增的行 {who} 之后被改过")
+                else:
+                    drop.append(ref)
+            if conflicts:
+                raise LarkError("撤销会覆盖别人之后的修改，已中止：\n" + brief(conflicts))
+            self._backend.update(cells)
+            self._backend.delete(drop)
+        rec["status"] = "undone"
+        history.save(rec)
+
+    def _apply(self, plan):
+        with self._explained():
+            current = self._backend.fetch([ch.ref for ch in plan.changed])   # 只读涉及的行
+            taken = {}
+            if plan.added:   # 确认新增的主键没被别人抢先加上
+                rows, refs, _ = self._backend.lookup(plan.key, {r[plan.key[0]] for r in plan.added})
+                taken = keyed(rows, plan.key, refs)
+            conflicts, cells = [], []
+            for ch in plan.changed:
+                cur = _cell(current.get(ch.ref), plan.key, ch.key, ch.column)
+                if cur != ch.old:
+                    conflicts.append(_conflict(ch.key, ch.column, ch.old, cur))
+                else:
+                    cells.append((ch.ref, ch.column, ch.new))
+            for r in plan.added:
+                k = tuple(r[c] for c in plan.key)
+                if k in taken:
+                    conflicts.append(f"{show_key(k)}：已经被别人新增")
+            if conflicts:
+                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)
+        return rec["id"]
+
+    def _write(self, rec, cells, added):
+        self._backend.update(cells)
+        for refs in self._backend.create(added):
+            rec["created"] += refs
+            history.save(rec)   # 每批落盘，中途失败也能撤销已写入的部分
+        rec["status"] = "done"
+        history.save(rec)
+
+    def _canon(self, rows, cols):
+        errors, out = [], []
+        for i, r in enumerate(rows, 1):
+            r = dict(r)
+            for c in cols:
+                try:
+                    r[c] = self._backend.canon(c, r.get(c, ""))
+                except LarkError as e:
+                    errors.append(f"第 {i} 条「{c}」：{e}")
+            out.append(r)
+        if errors:
+            raise LarkError("本地数据里有写不进在线表的值：\n" + brief(errors))
+        return out
+
+    @contextmanager
+    def _explained(self):
+        """把权限类错误码翻译成能照着做的提示。"""
+        try:
+            yield
+        except LarkError as e:
+            if e.code in _DENIED:
+                hint = ("把你的应用加为这张表的协作者，或改用 auth=\"user\""
+                        if self._auth.method == "tenant" else "确认你的飞书账号能编辑这张表")
+                raise LarkError(f"没有权限访问 {self.url}：{hint}", e.code) from e
+            if e.code in _MISSING_SCOPE:
+                raise LarkError(f"应用缺少权限：请在飞书开发者后台开通 {SCOPES} 并发布，"
+                                f"然后重新登录", e.code) from e
+            raise
+
+
+def _cell(row, key_cols, key, column):
+    """行还在、主键没变时返回该格的值，否则 None（行被删或电子表格行位置变了）。"""
+    if row is None or tuple(row.get(c, "") for c in key_cols) != tuple(key):
+        return None
+    return row.get(column, "")
+
+
+def _conflict(key, column, expected, current):
+    now = "（行已被删除）" if current is None else repr(current)
+    return f"{show_key(key)}「{column}」：应为 {expected!r}，现在是 {now}"
+
+
+def parse_url(url):
+    """返回 (类型, token, sheet/table id)；类型为 wiki / sheet / bitable。"""
+    u = urlparse(url.strip())
+    parts = [p for p in u.path.split("/") if p]
+    q = parse_qs(u.query)
+    sub = (q.get("sheet") or q.get("table") or [None])[0]
+    kinds = {"wiki": "wiki", "sheets": "sheet", "base": "bitable"}
+    if len(parts) >= 2 and parts[-2] in kinds:
+        return kinds[parts[-2]], parts[-1], sub
+    raise LarkError(f"认不出的飞书链接：{url}（支持 /wiki/、/sheets/、/base/ 链接）")

larksync-0.1.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: larksync
+Version: 0.1.0
+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
+Project-URL: Issues, https://github.com/libcyz/larksync/issues
+Author-email: libcyz <2840424020@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bitable,csv,feishu,lark,spreadsheet,sync,xlsx
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: platformdirs>=4
+Provides-Extra: gui
+Requires-Dist: pywebview>=6.2.1; extra == 'gui'
+Description-Content-Type: text/markdown
+
+# larksync
+
+这是一个用来同步飞书表格的项目，大多数项目的非技术人员在使用飞书在线表格进行管理的时候经常会出现大量数据需要人工核对，可能又需要去重，于是添加新的表变的非常麻烦，而整理好的csv中如果出现重复的数据，直接复制的话就gameover，当然会有用豆包更新表格的声音，如果你用豆包更新表格，那我不要和你说话。
+
+对于技术人员来讲，在pipeline搭建好之后发现跑脚本前需要拉取在线表格更新后的信息，需要折返到对应表格，下载，另存为csv，大概率还会出现XXXX表(1),XXXX表(2),然后就需要在修改脚本路径和重命名表格这两个愚蠢选项中选择一项，诸如此类，larksync应运而生。
+
+## 更新规则
+
+GUI 和 Python 代码使用同一套规则。
+
+- 补空的格子默认写入。
+- 不一致的格子默认不写入。人工确认后，才可以写入。
+- 新增的行由调用方决定是否写入。GUI 默认不勾选新增的行。
+- 本地文件中为空的格子不参与比较。larksync 不清空在线表的值。
+- larksync 不删除在线表的行。撤销时，只删除本次写入新增的行。
+- 写入前，larksync 重新读取涉及的行。预览后有人修改过这些格子时，写入整体中止。
+
+## 前提
+
+1. 创建一个飞书自建应用。
+2. 为应用开通以下权限：
+```json
+{
+  "scopes": {
+    "tenant": [
+      "bitable:app",
+      "sheets:spreadsheet",
+      "wiki:wiki:readonly"
+    ],
+    "user": [
+      "bitable:app",
+      "sheets:spreadsheet",
+      "wiki:wiki:readonly"
+    ]
+  }
+}
+```
+3. 在应用的重定向 URL 中添加 `http://localhost:8888/callback`。
+4. 发布应用版本。
+
+说明：权限修改并发布后，生效可以有几分钟的延迟;每个人必须使用自己的飞书应用,不同的人对在线表的权限不同。
+
+## GUI 使用
+
+### 首次配置
+
+1. 启动 larksync。结果：弹出「飞书应用与登录」窗口。
+2. 填写「App ID」和「App Secret」。
+3. 单击「保存并登录」。结果：浏览器打开飞书授权页。
+4. 在 180 秒内单击「授权」。结果：窗口右上角显示你的飞书用户名。
+
+登录状态保存在本机。下次启动时，不需要再登录。
+
+## 术语
+
+- **主键**：用来匹配行的字段。本地文件的行和在线表的行，主键值相同时视为同一行。
+- **联合主键**：多个字段一起作为主键。一个字段的值有重复时，使用联合主键。
+- **补空**：在线表的格子为空，本地文件有值。
+- **未匹配**：在线表有这一行，本地文件没有这一行。
+
+### 用本地文件更新在线表
+
+1. 在左侧列表中选择一张在线表。结果：顶部显示表头的前 8 个字段。
+2. 把本地文件拖入虚线框。也可以单击虚线框，选择本地文件。
+3. 在「列对应」中检查每一个 CSV 列对应的字段。同名的列自动对应。
+4. 勾选「主键」。一个字段的值有重复时，勾选多个字段。
+5. 勾选「更新」中要写入的列。表头的「更新」复选框可以全选。
+6. 单击「生成预览」。结果：显示「补空」「不一致」「新增」「未匹配」4 个页签。
+7. 在「不一致」中核对每一个格子。只勾选确认要覆盖的格子。
+8. 在「新增」中勾选确认要增加的行。
+9. 单击「写入飞书」。结果：弹出确认框。
+10. 单击「写入」。结果：显示「已写入飞书」。
+
+列对应和主键保存在表格配置中。下次拖入同样格式的本地文件时，自动恢复。
+
+
+### 其他操作
+
+- 单击「刷新」：重新读取表头。在线表增加字段后，必须刷新。
+- 单击「移除」：删除本机的表格配置。飞书上的在线表和写入记录不变。
+- 单击右上角的用户名：修改 App ID 或 App Secret，或退出登录。
+
+开发者调用详见 [docs/python.md](https://github.com/libcyz/larksync/blob/main/docs/python.md)。

larksync-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+larksync/__init__.py,sha256=tX6IyreofXlcyzPGlqXuW-YlVCKqZ7GsJrNZ4_dMdQE,209
+larksync/auth.py,sha256=_ObpI4oGBZjuzY58P6pjSxyTuzRdGFJxdgLTRgvPK5E,7359
+larksync/bitable.py,sha256=OJR55K1_yLPBH9BVGuVQdOSgiRaCZRkcV8CFbGlzH6U,7913
+larksync/diff.py,sha256=d2hK3lbKyg1gLkEAJU2Y4HgPo5Ha7rh4KOW6pfOhBHs,5950
+larksync/history.py,sha256=5CFhGX2a1qjrU_rY0Y6JQ_CS8FJD1OQRo1OtFCqsbC0,1176
+larksync/http.py,sha256=ASV1e-dKTuKVN7c4DFZ7qS6P392_0q5fuCLOFDVfir4,1840
+larksync/sheets.py,sha256=n4QHo6BEIgrxU-q2fsX-kbwqRU8yigOU2dvy5bxT_zk,9070
+larksync/table.py,sha256=-E5BijD8s6GYPbGH5cbnliPqQBa33onBTiCQSOYwdX0,10902
+larksync-0.1.0.dist-info/METADATA,sha256=FruJ41WMvBqIhXQA548jjPfkr3MK3DygdpdpSAu9Xu0,5239
+larksync-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+larksync-0.1.0.dist-info/licenses/LICENSE,sha256=4p3g86FDNGRkEj9t8VzsWU7MIUKzKe5yXw8Ffqd1KkU,1063
+larksync-0.1.0.dist-info/RECORD,,

larksync-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

larksync-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 libcyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.