clip2table 0.1.0__py3-none-any.whl

clip2table/__init__.py

@@ -0,0 +1,11 @@
+"""clip2table - turn any screen you can select into a table.
+
+Copy with a real browser or a real program, read the clipboard, cut the text
+into records, write a table. Nothing is guessed: a value that is not in the
+source stays empty.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

clip2table/__main__.py

@@ -0,0 +1,11 @@
+"""`python -m clip2table` - the path that works before install.
+
+The console script is the normal way in, but a cloned repo has no console
+script yet, and `python -m clip2table` failing with "No module named
+clip2table.__main__" is a bad first minute.
+"""
+from __future__ import annotations
+
+from .cli import main
+
+raise SystemExit(main())

clip2table/capabilities.py

@@ -0,0 +1,86 @@
+"""One capability table, consulted by validation, dispatch and help text.
+
+The rule this module exists to enforce: **a card may not declare something the
+program cannot execute.** Before this table, `kind = "dom"` and `kind = "json"`
+passed validation, ran, and returned None -- so "the page has no such element",
+"the regex found nothing" and "this build cannot do that at all" all arrived at
+the user as the same empty cell. An empty cell that means three different things
+is not a missing value, it is a missing explanation.
+
+Keeping the table in one place means the three consumers cannot drift: the schema
+rejects with the same reason the dispatcher would give, and `cards show` prints
+the same reason a help screen would.
+"""
+from __future__ import annotations
+
+from typing import NamedTuple
+
+from .errors import InputError
+
+
+class Capability(NamedTuple):
+    kind: str
+    channels: tuple[str, ...]   # channels that can actually fill this kind
+    note: str                   # what to use instead, or how it behaves
+    implemented: bool = True
+
+
+# Kinds that appear in KINDS but are not wired to any producer. They stay in the
+# vocabulary so old cards fail loudly rather than silently producing empties;
+# when a producer lands, flip `implemented` and add the channels.
+CAPABILITIES: dict[str, Capability] = {
+    "cell": Capability("cell", ("http", "browser", "desktop"),
+                       "表格的一列（HTML 表格或 TSV），列边界是事实"),
+    "line": Capability("line", ("http", "browser", "desktop"),
+                       "记录的第 n 行，负数从末尾数"),
+    "search": Capability("search", ("http", "browser", "desktop"),
+                         "匹配正则的那一行，再取捕获组"),
+    "span": Capability("span", ("http", "browser", "desktop"),
+                       "两个标记之间的文本，可跨行"),
+    "const": Capability("const", ("http", "browser", "desktop"),
+                        "固定值，只用于标注来源，从不拿来填数据"),
+    "dom": Capability(
+        "dom", (), "还没实现。现在是空值，但空值和「页面上没有这个元素」"
+                   "看起来一模一样。改用 line/search/span/cell —— 复制的文本里"
+                   "一样有这些字段", implemented=False),
+    "json": Capability(
+        "json", (), "还没实现。现在是空值。若目标是 JSON 接口，先把它存成文件，"
+                    "用 run --text-file 走文本路径", implemented=False),
+}
+
+CHANNEL_CAPS: dict[str, tuple[str, ...]] = {
+    "http": ("cell", "line", "search", "span", "const"),
+    "browser": ("cell", "line", "search", "span", "const"),
+    "desktop": ("cell", "line", "search", "span", "const"),
+}
+
+
+def check_kind(kind: str, channel: str | None, where: str) -> None:
+    """Refuse a field the runtime could not fill. Raises with a way forward."""
+    cap = CAPABILITIES.get(kind)
+    if cap is None:
+        raise InputError(f"{where}: kind={kind!r} 不在可用原语里")
+    if not cap.implemented:
+        raise InputError(
+            f"{where}: kind={kind!r} 还没实现，声明它只会得到空值",
+            hint=cap.note)
+    if channel and kind not in CHANNEL_CAPS.get(channel, CHANNEL_CAPS["http"]):
+        usable = "、".join(CHANNEL_CAPS.get(channel, ()))
+        raise InputError(
+            f"{where}: kind={kind!r} 在 {channel} 通道上不可用",
+            hint=f"{channel} 通道能用的原语是 {usable}；{cap.note}")
+
+
+def unsupported_kinds() -> list[str]:
+    """Kinds declared by the vocabulary but not wired up yet."""
+    return [k for k, c in CAPABILITIES.items() if not c.implemented]
+
+
+def describe() -> list[str]:
+    """Human/agent-facing capability list, shared by doctor and cards show."""
+    out = []
+    for kind, cap in CAPABILITIES.items():
+        where = "、".join(cap.channels) if cap.channels else "（无）"
+        state = "" if cap.implemented else "  ← 未实现，卡的校验会直接拒绝"
+        out.append(f"{kind:7s} {where:26s} {cap.note}{state}")
+    return out

clip2table/cards/__init__.py

@@ -0,0 +1 @@
+"""Card loading and validation."""

clip2table/cards/builtin/admin-order-list.toml

@@ -0,0 +1,55 @@
+schema  = 1
+name    = "admin-order-list"
+channel = "browser"
+
+# 后台列表页：表格是事实，列边界就是字段边界。电商/招聘/财务后台结构一致。
+#
+# 为什么 mode = "lines"：后台表格复制出来时，行已经是分开的（HTML 的 <tr>
+# 变成一行 tab 分隔文本，Excel 区域粘贴也是每行一条）。再按锚点分组不是规则，
+# 是 bug——`single` 曾把 11 行表格粘成 1 条记录，第一条字段是表头文字，
+# 还报了两个字段 100% 填充。
+
+samples = "samples/admin-order-list"
+
+[fetch]
+url   = "https://example.com/admin/orders"
+ready = "load"
+scroll = { until = "stable", max = 40, pause_ms = 600 }
+
+[segment]
+mode  = "lines"
+# 后台表格复制出来时第一行通常是列名（「订单号 / 下单时间 / 金额 …」）。
+# 不跳过它就会多出一条「order_no=订单号、amount=空」的记录，amount 的
+# 填充率也因此被拉低——一份干净的表看起来像规则失效。
+skip_header = true
+
+[fields.order_no]
+kind = "cell"
+col  = 0
+
+[fields.created]
+kind = "cell"
+col  = 1
+
+[fields.amount]
+kind = "cell"
+col  = 2
+type = "float"
+
+[fields.status]
+kind = "cell"
+col  = 3
+
+[fields.note]
+kind = "cell"
+col  = 4
+
+[dedupe]
+key          = ["order_no"]
+on_collision = "report_only"
+
+[paging]
+style     = "click"
+next      = "a.next"
+max_pages = 50
+pause_ms  = 1200

clip2table/cards/builtin/generic-item-block.toml

@@ -0,0 +1,57 @@
+schema  = 1
+name    = "generic-item-block"
+channel = "desktop"
+
+# 通用「条目块」：一条短标题行，紧跟一行日期，然后是正文/规格。
+# 电商列表、政务名录、文献列表、房源条目都是这个形状，改的只是字段名。
+#
+# 它要求的形状很具体：日期必须是记录里的**第二行**。
+# 招聘列表那种「标题/公司/地点/薪资/日期」日期在末尾的版式**不适用**本卡——
+# 硬套会把薪资行当成标题。那种版式直接用 `clip2table infer`，S1 会正确切出
+# 五列（已用 fixtures/sample-hr.txt 验证）。用错卡不是数据问题，是选错工具；
+# 报告里的「未识别 N 行」就是它给你的信号。
+
+samples = "samples/generic-item-block"
+
+[segment]
+mode        = "anchor"
+anchor      = '^(?!\s).{1,40}$'
+# The date line must be a BARE date (optionally with a time) and nothing else.
+# A loose date prefix ('^\d{4}-\d{1,2}') also matches a body line that merely
+# begins with a date - "2026-03-12 补记：扶手略窄" - and then that body line
+# becomes a record start, splitting one record into two.
+anchor_next = '^\d{4}\s*[-/.年]\s*\d{1,2}\s*(?:[-/.月]\s*\d{1,2}\s*[日号]?)?(?:\s+\d{1,2}:\d{2}(?::\d{2})?)?\s*$'
+min_lines   = 2
+
+[fields.title]
+kind  = "line"
+index = 0
+
+[fields.date]
+kind    = "search"
+pattern = '(?P<v>\d{4}[-/.]\d{1,2}[-/.]\d{1,2}|\d{4}年\d{1,2}月\d{1,2}日)'
+scope   = "head"
+window  = 2
+type    = "date"
+
+[fields.body]
+kind  = "span"
+from  = "after:date"
+# The `?` makes the stop marker optional: cut before 规格 when the record has
+# one, run to the end of the record when it does not. Strict (no `?`) is the
+# default because a vanished marker usually means the page changed under the
+# card -- and a strict bound that cannot be found returns empty, not the whole
+# record. This card serves both shapes, so it has to declare that explicitly.
+to    = "before?:^规格[:：]"
+type  = "text"
+
+[fields.spec]
+kind    = "search"
+pattern = '^规格[:：]\s*(?P<v>.+)$'
+
+[dedupe]
+key          = ["title", "date", "body"]
+on_collision = "report_only"
+
+[paging]
+style = "none"

clip2table/cards/builtin/job-list.toml

@@ -0,0 +1,54 @@
+schema  = 1
+name    = "job-list"
+channel = "desktop"
+
+# 招聘列表：一条五段——职位 / 公司 / 地点经验 / 薪资 / 发布日期，日期在**最后**。
+#
+# 这张卡的日期锚点是反向的：记录以「日期行」结束，下一条从日期行的下一行开始。
+# 用 notice-list 那种「第二行是日期」的卡去套它，会把薪资行当成标题——所以
+# 这里给的是分开的一张卡，而不是把两张卡揉成一个万能正则。
+#
+# 采集方式：浏览器里 F12 → Elements 之外最省事的形态是「全选复制」，
+# 或者用 desktop 通道对一个只显示招聘列表的窗口按 Ctrl+A。
+
+samples = "samples/job-list"
+
+[harvest]
+select_all = true
+timeout_ms = 5000
+
+[segment]
+# 空行分段。为什么不用 anchor：锚点机制只能把「命中行」当作记录的**起点**，
+# 而这张卡的日期在末尾——写成 anchor 会让每一行都成为起点，然后 min_lines
+# 把单行记录全部滤掉，结果是 0 行、全部未识别（试过，就是这样）。
+# 招聘站复制出来的块之间通常有空行，所以用 blank；没有空行就先用 infer。
+mode        = "blank"
+
+[fields.title]
+kind  = "line"
+index = 0
+
+[fields.company]
+kind  = "line"
+index = 1
+
+[fields.location]
+kind  = "line"
+index = 2
+
+[fields.salary]
+kind  = "line"
+index = 3
+
+[fields.date]
+kind    = "line"
+index   = -1
+type    = "date"
+pattern = '(?P<v>\d{4}[-/.]\d{1,2}[-/.]\d{1,2})'
+
+[dedupe]
+key          = ["title", "company"]
+on_collision = "report_only"
+
+[paging]
+style = "none"

clip2table/cards/builtin/notice-list.toml

@@ -0,0 +1,51 @@
+schema  = 1
+name    = "notice-list"
+channel = "browser"
+
+# 列表页：一屏多条，每条是「标题 / 日期 / 正文」三行一段，还带一个可选的规格行。
+#
+# 这是最通用的列表形状：采购公告、招标信息、政策文件、活动报名、文章列表
+# 都是它。字段名按你的业务改，规则不用动。
+#
+# 分页交给 [paging]：点「下一页」链接，连续 2 页没有新增就自动停。
+
+samples = "samples/notice-list"
+
+[harvest]
+select_all  = true
+timeout_ms  = 5000
+
+[segment]
+mode        = "anchor"
+anchor      = '^(?!\s).{1,60}$'
+# 第二行必须是**裸日期**，不能是「以日期开头的正文」——否则正文里提到
+# 2026-03-12 的那一行会被当成新记录的开头，一条记录被切成两条。
+anchor_next = '^\d{4}\s*[-/.年]\s*\d{1,2}\s*(?:[-/.月]\s*\d{1,2}\s*[日号]?)?\s*$'
+min_lines   = 3
+
+[fields.title]
+kind  = "line"
+index = 0
+
+[fields.date]
+kind    = "line"
+index   = 1
+type    = "date"
+
+[fields.body]
+kind  = "line"
+index = 2
+
+[fields.spec]
+kind    = "search"
+pattern = '^规格[:：]\s*(?P<v>.+)$'
+
+[dedupe]
+key          = ["title"]
+on_collision = "report_only"
+
+[paging]
+style     = "click"
+next      = "a.next"
+max_pages = 5
+pause_ms  = 1200

clip2table/cards/builtin/numbered-list.toml

@@ -0,0 +1,47 @@
+schema  = 1
+name    = "numbered-list"
+channel = "desktop"
+
+# 编号清单：一行一条，「1. 事项名 —— 进度/时间」。
+#
+# 这是台账、任务清单、问题列表、验收项清单最常见的形状——每条只占一行，
+# 和上面那些「多行一段」的卡完全不同。这里靠行首编号切分，不靠空行也不靠
+# 日期，因为这类清单通常把编号当唯一的分界信号。
+
+samples = "samples/numbered-list"
+
+[target]
+# 从任何窗口里复制都行：改成你那个窗口标题里的一段文字。
+# 比如 "工作台账 - Notepad"、"任务列表 - Excel"。
+title   = "工作台账"
+restore = true
+
+[harvest]
+select_all = true
+timeout_ms = 5000
+
+[segment]
+mode   = "anchor"
+# 行首 1. / 2. / 1、/ (1) 都算一条新记录。行内的「——」不当分界：
+# 它就是这条记录里的一个分隔符，切成两条反而会把一条记录拆散。
+anchor = '^\s*(?:\d{1,3}[.、)）]|[（(]\d{1,3}[)）])'
+min_lines = 1
+
+[fields.no]
+kind    = "search"
+pattern = '^\s*(?P<v>\d{1,3})'
+
+[fields.item]
+kind    = "search"
+pattern = '^\s*\d{1,3}[.、)）]\s*(?P<v>.+?)\s*(?:——|--|—)\s*'
+
+[fields.progress]
+kind    = "search"
+pattern = '(?:——|--|—)\s*(?P<v>.+)$'
+
+[dedupe]
+key          = ["no"]
+on_collision = "report_only"
+
+[paging]
+style = "none"

clip2table/cards/builtin/samples/admin-order-list/orders.tsv.expect.tsv

@@ -0,0 +1,6 @@
+order_no	created	amount	status	note
+SO-2026-0001	2026-03-01 09:12	129.0	已付款	加急
+SO-2026-0002	2026-03-01 10:04	368.5	已发货	无
+SO-2026-0003	2026-03-02 14:33	42.0	待付款	无
+SO-2026-0004	2026-03-02 16:20	1280.0	已完成	开发票
+SO-2026-0005	2026-03-03 08:55	76.8	已退款	客户取消

clip2table/cards/builtin/samples/admin-order-list/orders.tsv.txt

@@ -0,0 +1,6 @@
+订单号	下单时间	金额	状态	备注
+SO-2026-0001	2026-03-01 09:12	129.00	已付款	加急
+SO-2026-0002	2026-03-01 10:04	368.50	已发货	无
+SO-2026-0003	2026-03-02 14:33	42.00	待付款	无
+SO-2026-0004	2026-03-02 16:20	1,280.00	已完成	开发票
+SO-2026-0005	2026-03-03 08:55	76.80	已退款	客户取消

clip2table/cards/builtin/samples/generic-item-block/gov-list.expect.tsv

@@ -0,0 +1,4 @@
+title	date	body	spec
+临江区市场监督管理局后勤服务中心	2026-01-15	统一社会信用代码 91330100MA2XXXX1X\n法定代表人：周某\n登记状态：存续\n注册资本：500 万元	
+滨河区行政审批服务中心	2026-01-09	统一社会信用代码 91330100MA2XXXX2X\n法定代表人：李某\n登记状态：注销\n注册资本：120 万元	
+新桥镇农业农村办公室	2025-12-28	统一社会信用代码 91330100MA2XXXX3X\n法定代表人：吴某\n登记状态：存续\n注册资本：80 万元	

clip2table/cards/builtin/samples/generic-item-block/gov-list.txt

@@ -0,0 +1,20 @@
+临江区市场监督管理局后勤服务中心
+2026-01-15
+统一社会信用代码 91330100MA2XXXX1X
+法定代表人：周某
+登记状态：存续
+注册资本：500 万元
+
+滨河区行政审批服务中心
+2026-01-09
+统一社会信用代码 91330100MA2XXXX2X
+法定代表人：李某
+登记状态：注销
+注册资本：120 万元
+
+新桥镇农业农村办公室
+2025-12-28
+统一社会信用代码 91330100MA2XXXX3X
+法定代表人：吴某
+登记状态：存续
+注册资本：80 万元

clip2table/cards/builtin/samples/job-list/hr-roles.expect.tsv

@@ -0,0 +1,5 @@
+title	company	location	salary	date
+后端开发工程师（Python）	星野科技	杭州 · 3-5 年	25-40K · 14薪	2026-03-09
+数据分析师	青禾数据	上海 · 1-3 年	18-25K · 13薪	2026-03-08
+产品经理（B端）	同衡软件	深圳 · 5-10 年	30-50K · 15薪	2026-03-06
+测试开发工程师	临江智能	成都 · 3-5 年	20-30K · 13薪	2026-03-05

clip2table/cards/builtin/samples/job-list/hr-roles.txt

@@ -0,0 +1,23 @@
+后端开发工程师（Python）
+星野科技
+杭州 · 3-5 年
+25-40K · 14薪
+2026-03-09
+
+数据分析师
+青禾数据
+上海 · 1-3 年
+18-25K · 13薪
+2026-03-08
+
+产品经理（B端）
+同衡软件
+深圳 · 5-10 年
+30-50K · 15薪
+2026-03-06
+
+测试开发工程师
+临江智能
+成都 · 3-5 年
+20-30K · 13薪
+2026-03-05

clip2table/cards/builtin/samples/notice-list/list-page.expect.tsv

@@ -0,0 +1,4 @@
+title	date	body	spec
+星海无线耳机 Pro	2026-03-14	包装完好，降噪比上一代强不少，通勤地铁里基本听不到报站	黑色 / 降噪版
+轻羽人体工学椅	2026-03-11	腰托支撑到位，坐了三天没腰疼，就是扶手略窄	灰 / 带脚托
+山雾便携咖啡机	2026-03-08	出液稳定，清洗麻烦，旅行箱里占地方	银 / 单杯

clip2table/cards/builtin/samples/notice-list/list-page.txt

@@ -0,0 +1,17 @@
+星海无线耳机 Pro
+2026-03-14
+包装完好，降噪比上一代强不少，通勤地铁里基本听不到报站
+规格：黑色 / 降噪版
+有用(128)
+
+轻羽人体工学椅
+2026-03-11
+腰托支撑到位，坐了三天没腰疼，就是扶手略窄
+规格：灰 / 带脚托
+有用(56)
+
+山雾便携咖啡机
+2026-03-08
+出液稳定，清洗麻烦，旅行箱里占地方
+规格：银 / 单杯
+有用(37)

clip2table/cards/builtin/samples/numbered-list/project-list.expect.tsv

@@ -0,0 +1,5 @@
+no	item	progress
+1	射频识别门禁改造	2026-02 完成招标
+2	机房动环监控扩容	2026-03 进场施工
+3	无线覆盖二期	预算待批
+4	视频会议终端替换	已验收

clip2table/cards/builtin/samples/numbered-list/project-list.txt

@@ -0,0 +1,4 @@
+1. 射频识别门禁改造 —— 2026-02 完成招标
+2. 机房动环监控扩容 —— 2026-03 进场施工
+3. 无线覆盖二期 —— 预算待批
+4. 视频会议终端替换 —— 已验收

clip2table/cards/loader.py

@@ -0,0 +1,50 @@
+"""Card loader: TOML in, Card out. No magic lookup order beyond the obvious."""
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from ..errors import InputError
+from .schema import Card, parse_card
+
+
+def load_card(path: str | Path) -> Card:
+    p = Path(path)
+    if not p.exists():
+        raise InputError(f"找不到卡：{p}", hint="用 `clip2table cards list` 看内置卡")
+    if p.suffix.lower() != ".toml":
+        raise InputError(f"卡必须是 .toml 文件：{p}")
+    try:
+        raw = p.read_bytes()
+    except OSError as e:
+        raise InputError(f"读不了卡 {p}：{e}") from None
+    try:
+        data = tomllib.loads(raw.decode("utf-8"))
+    except UnicodeDecodeError:
+        raise InputError(f"卡不是 UTF-8：{p}") from None
+    except tomllib.TOMLDecodeError as e:
+        raise InputError(f"卡不是合法 TOML：{p}\n  {e}") from None
+    return parse_card(data, str(p))
+
+
+def builtin_dir() -> Path:
+    return Path(__file__).with_name("builtin")
+
+
+def list_builtin() -> list[Path]:
+    d = builtin_dir()
+    if not d.is_dir():
+        return []
+    return sorted(d.glob("*.toml"))
+
+
+def resolve_card(name_or_path: str) -> Card:
+    """A path, or a builtin card name without the .toml suffix."""
+    p = Path(name_or_path)
+    if p.exists():
+        return load_card(p)
+    candidate = builtin_dir() / f"{name_or_path}.toml"
+    if candidate.exists():
+        return load_card(candidate)
+    raise InputError(f"找不到卡 {name_or_path!r}",
+                     hint="给一个 .toml 路径，或用 `clip2table cards list` 里的名字")