tableprobe 0.1.0__tar.gz

tableprobe-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+__pycache__/
+*.pyc

tableprobe-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: tableprobe
+Version: 0.1.0
+Summary: 上课演示用的表探查库：打开 CSV、Parquet、SQLite、xlsx 和 MySQL，回答行数、列数和列角色。
+Project-URL: Homepage, https://github.com/WangLaoShi/wanglaoshi-sql
+Project-URL: Source, https://github.com/WangLaoShi/wanglaoshi-sql
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=1.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mysql
+Description-Content-Type: text/markdown
+
+# tableprobe
+
+上课时用的表探查库。把 CSV、Parquet、SQLite、xlsx 和 MySQL 里的一张表收成同一个对象，然后回答三件事：有多少行、有多少列、每一列是维度、度量、时间还是标识。
+
+```python
+from tableprobe import open_table
+
+orders = open_table("examples/orders.csv")
+print(orders.row_count())
+print(orders.column_count())
+for column in orders.profile():
+    print(column)
+```
+
+仓库里的 `python examples/demo.py` 就是这段调用。范围和取舍写在 [docs/spec.md](docs/spec.md)。
+
+## 安装
+
+发布到 PyPI 之后：
+
+```bash
+pip install tableprobe
+```
+
+在本仓库里试用：
+
+```bash
+pip install -e .
+```
+
+CSV、Parquet 和 SQLite 装完就能打开。xlsx 和 MySQL 第一次使用时，DuckDB 会下载对应扩展，电脑需要能联网。`pip install tableprobe[mysql]` 是预留的安装标记，目前没有额外的 Python 包。
+
+CSV 请存成 UTF-8。
+
+## 打开一张表
+
+```python
+from tableprobe import open_table
+
+open_table("sales.csv")
+open_table("sales.parquet")
+open_table("sqlite:///app.db", table="users")
+open_table("book.xlsx", sheet="Q1")          # 不写 sheet 就用第一张工作表
+open_table("mysql://user:pass@host:3306/shop", table="orders")
+```
+
+SQLite 和 MySQL 必须传入 `table`。一个 `Table` 持有一条连接，用完可以 `close()`，也可以写在 `with` 里。
+
+## 行数、列数和画像
+
+`row_count()` 永远是精确的 `COUNT(*)`。`column_count()` 是列数。
+
+`profile()` 的每一列有名字、类型、抽样空值率、抽样基数、抽样行数、角色和一句理由。空值率和基数最多只看 10000 行；小文件会看完全部行，结果里仍写着抽样行数，所以它不是另一套全表精确统计。MySQL 系统表里的估计行数不会拿来冒充 `row_count()`。
+
+有列但一行都没有的表，`profile()` 返回空列表。某一列全是空值时，基数是 0，空值率是 1。
+
+## 维度和度量
+
+角色由库自动判断，错了可以接受。理由用来讲「为什么判成这样」。
+
+| 角色 | 怎么看出来 |
+| --- | --- |
+| 标识 | 列名是 `id`、以 `_id` 结尾、含 `uuid` 或 `guid`，或者这一列是 SQLite 主键 |
+| 时间 | 日期或时间类型 |
+| 维度 | 文本、布尔、低基数的数字，以及列名像年份、邮编、编码、评分、等级 |
+| 度量 | 其余适合求和或平均的数字 |
+| 未知 | 对不上上面几条，理由里会写出类型 |
+
+`dimensions()`、`measures()`、`times()` 和 `identifiers()` 按角色返回列名。课堂上要改一列：
+
+```python
+orders.set_role("金额", "维度")
+orders.dimensions()
+```
+
+这一改只存在于当前这个对象，理由变成「课堂上手工指定。」
+
+## 第一版不读什么
+
+旧版 `.xls`、带合并单元格的工作表、第一行有空列名的表，都会直接用中文报错。不做查询、写回和画图。
+
+报错里的 MySQL 密码会打成 `***`。

tableprobe-0.1.0/README.md

@@ -0,0 +1,82 @@
+# tableprobe
+
+上课时用的表探查库。把 CSV、Parquet、SQLite、xlsx 和 MySQL 里的一张表收成同一个对象，然后回答三件事：有多少行、有多少列、每一列是维度、度量、时间还是标识。
+
+```python
+from tableprobe import open_table
+
+orders = open_table("examples/orders.csv")
+print(orders.row_count())
+print(orders.column_count())
+for column in orders.profile():
+    print(column)
+```
+
+仓库里的 `python examples/demo.py` 就是这段调用。范围和取舍写在 [docs/spec.md](docs/spec.md)。
+
+## 安装
+
+发布到 PyPI 之后：
+
+```bash
+pip install tableprobe
+```
+
+在本仓库里试用：
+
+```bash
+pip install -e .
+```
+
+CSV、Parquet 和 SQLite 装完就能打开。xlsx 和 MySQL 第一次使用时，DuckDB 会下载对应扩展，电脑需要能联网。`pip install tableprobe[mysql]` 是预留的安装标记，目前没有额外的 Python 包。
+
+CSV 请存成 UTF-8。
+
+## 打开一张表
+
+```python
+from tableprobe import open_table
+
+open_table("sales.csv")
+open_table("sales.parquet")
+open_table("sqlite:///app.db", table="users")
+open_table("book.xlsx", sheet="Q1")          # 不写 sheet 就用第一张工作表
+open_table("mysql://user:pass@host:3306/shop", table="orders")
+```
+
+SQLite 和 MySQL 必须传入 `table`。一个 `Table` 持有一条连接，用完可以 `close()`，也可以写在 `with` 里。
+
+## 行数、列数和画像
+
+`row_count()` 永远是精确的 `COUNT(*)`。`column_count()` 是列数。
+
+`profile()` 的每一列有名字、类型、抽样空值率、抽样基数、抽样行数、角色和一句理由。空值率和基数最多只看 10000 行；小文件会看完全部行，结果里仍写着抽样行数，所以它不是另一套全表精确统计。MySQL 系统表里的估计行数不会拿来冒充 `row_count()`。
+
+有列但一行都没有的表，`profile()` 返回空列表。某一列全是空值时，基数是 0，空值率是 1。
+
+## 维度和度量
+
+角色由库自动判断，错了可以接受。理由用来讲「为什么判成这样」。
+
+| 角色 | 怎么看出来 |
+| --- | --- |
+| 标识 | 列名是 `id`、以 `_id` 结尾、含 `uuid` 或 `guid`，或者这一列是 SQLite 主键 |
+| 时间 | 日期或时间类型 |
+| 维度 | 文本、布尔、低基数的数字，以及列名像年份、邮编、编码、评分、等级 |
+| 度量 | 其余适合求和或平均的数字 |
+| 未知 | 对不上上面几条，理由里会写出类型 |
+
+`dimensions()`、`measures()`、`times()` 和 `identifiers()` 按角色返回列名。课堂上要改一列：
+
+```python
+orders.set_role("金额", "维度")
+orders.dimensions()
+```
+
+这一改只存在于当前这个对象，理由变成「课堂上手工指定。」
+
+## 第一版不读什么
+
+旧版 `.xls`、带合并单元格的工作表、第一行有空列名的表，都会直接用中文报错。不做查询、写回和画图。
+
+报错里的 MySQL 密码会打成 `***`。

tableprobe-0.1.0/aq.md

@@ -0,0 +1,7 @@
+## 我们做的 pypi 是不是可以引用别人的项目
+
+当然能，而且应该
+
+> 不用重复发明轮子，别人做了，我们可以直接借鉴。别人做了，我们就不要再做一遍。
+
+## 

tableprobe-0.1.0/docs/spec.md

@@ -0,0 +1,103 @@
+# tableprobe 范围说明
+
+仓库名是 `wanglaoshi-sql`。PyPI 包名是 `tableprobe`。这是一个供上课演示的 Python 库：把 CSV、Parquet、xlsx 的一个工作表、SQLite 的一张表、MySQL 的一张表，变成同一个 `Table` 对象，并回答行数、列数，以及每一列是维度、度量、时间，还是标识。
+
+文档和示例用中文。调用要短，能在课堂上当场敲完。
+
+Parquet 与 CSV、SQLite 同为第一版的本地来源，用 DuckDB 自带的 `read_parquet` 读取，不额外安装扩展，也不依赖 pyarrow。
+
+## 这个库做什么
+
+调用方面对的是「一张表」，不是「一个数据库连接」。连接只负责把表打开。
+
+```python
+from tableprobe import open_table
+
+orders = open_table("sales.csv")
+orders = open_table("sales.parquet")
+orders = open_table("sqlite:///app.db", table="users")
+orders = open_table("book.xlsx", sheet="Q1")
+orders = open_table("mysql://user:pass@host:3306/shop", table="orders")
+
+orders.row_count()
+orders.column_count()
+orders.profile()
+orders.dimensions()
+orders.measures()
+orders.times()
+orders.identifiers()
+```
+
+PyPI 上已有 [`wanglaoshi`](https://pypi.org/project/wanglaoshi/)（数据分析入门与竞赛工具包）。本库使用 `tableprobe`，不沿用那个名字。
+
+## 和现成项目的分工
+
+连接和查询已经有成熟实现，本库不重写驱动。
+
+| 已有项目 | 它负责的部分 | 本库不重复的原因 |
+| --- | --- | --- |
+| [DuckDB](https://duckdb.org/) | 读取 CSV、Parquet、xlsx，挂载 SQLite、MySQL，并用同一套 SQL 做 `COUNT(*)`、`DESCRIBE` | 没有「维度 / 度量」这一层，调用方仍要写 SQL |
+| [Ibis](https://github.com/ibis-project/ibis) | 用同一套 Python API 查询 MySQL、SQLite、DuckDB 等二十多个后端 | Excel 不是一等公民；列角色要调用方自己判断 |
+| SQLAlchemy、`records` | 连接关系型数据库并执行 SQL | 不覆盖 CSV、Excel、Parquet |
+| [Frictionless](https://pypi.org/project/frictionless/) | 描述并校验文件和 SQL 表的 schema | 有字段类型，没有分析语义 |
+| [semql-introspect](https://pypi.org/project/semql-introspect/)、[Cantrip](https://pypi.org/project/cantrip/) | 从数仓 schema 推断度量、维度、时间维度 | 面向语义层代码生成，不读 Excel、CSV，也不回答「这张表有多少行」 |
+| [Woodwork](https://woodwork.alteryx.com/) | 给已载入内存的 DataFrame 打 `numeric`、`category` 标签 | 不负责打开数据源 |
+
+执行引擎只用 DuckDB。CSV 用 `read_csv_auto`，Parquet 用 `read_parquet`，xlsx 用 `read_xlsx`，SQLite 和 MySQL 用 `ATTACH`。五类来源最后都落成同一张视图。筛选、分组、聚合交给 Ibis 或 DuckDB。第一版没有 `head`、过滤、分组和画图。
+
+## 第一版范围
+
+五类来源：
+
+- CSV
+- Parquet
+- xlsx 的一个工作表，且是第一行为列名的矩形表。没写 `sheet` 时用第一张工作表
+- SQLite 的一张表。路径可以是 `.db`、`.sqlite`、`.sqlite3`，也可以是 `sqlite:///文件路径`，并且必须传入 `table`
+- MySQL 的一张表。连接串是 `mysql://用户:密码@主机:端口/库名`，并且必须传入 `table`
+
+接口：
+
+- `row_count()`：精确行数，始终是 `COUNT(*)`
+- `column_count()`：来自 `DESCRIBE` 的列数
+- `profile()`：逐列的名字、DuckDB 类型、抽样空值率、抽样基数、抽样行数、角色和理由
+- `dimensions()`、`measures()`、`times()`、`identifiers()`：按角色返回列名
+- `set_role(column, role)`：只改当前对象。角色可以写 `维度`、`度量`、`时间`、`标识`，或对应的英文。理由改为「课堂上手工指定。」
+
+空表（有列但 0 行）的 `profile()` 返回空列表，`column_count()` 仍返回列数。全空列的基数为 0，空值率为 1。
+
+依赖按来源拆开。默认安装覆盖 CSV、Parquet、SQLite 和 xlsx 的读取代码；`pip install tableprobe[mysql]` 目前是预留标记，没有额外的 Python 包。xlsx 和 MySQL 第一次打开时，由 DuckDB 下载 `excel` 或 `mysql` 扩展，电脑需要能联网。
+
+大表禁止为了分类做全表扫描。空值率和基数来自 `USING SAMPLE 10000 ROWS`，小表会覆盖全表，结果里仍写明抽样行数。行数使用精确 `COUNT(*)`。MySQL 大表上精确计数可能很慢；`information_schema` 中的行数是估算，不作为精确行数返回。
+
+报错用中文。连接串和报错文本里的密码会打码。SQLite 能通过 `DESCRIBE` 看到主键时，该列标为标识。
+
+## 第一版不做
+
+- 自研数据库驱动、ORM、SQL 生成器
+- 把整表载入内存再计数
+- 跨表 JOIN、写回、ETL、画图
+- xlsx 的多表头、合并单元格，以及旧版 `.xls`
+- 在文档或介绍中承诺「支持所有数据库」
+
+合并单元格、空列名和 `.xls` 直接给出中文错误。Postgres 可以后加：DuckDB 已经能挂载它，但未验证之前不写入支持列表。
+
+## 列角色
+
+列角色由库自动判断。判断会错，课堂上可以接受；`profile()` 仍给出一句中文理由。老师可以用 `set_role` 当场改一列，再看四个筛选方法的变化。
+
+判断是纯函数，不连接数据库。先命中先停：
+
+1. 列名是 `id`、以 `_id` 结尾，或含 `uuid` / `guid`，标为标识。SQLite 主键同样标为标识。
+2. 日期或时间类型标为时间。
+3. 列名像年份、邮编、编码、评分、等级（以及英文 `year`、`zip`、`code`、`rating`、`score`、`level`、`grade`），即使是数字也标为维度。
+4. 数值列中，不重复值不超过 20，或不重复值占非空值不超过 5% 且非空值至少 20 个，标为维度；其余标为度量。
+5. 布尔和字符串标为维度。
+6. 其余标为未知，并写明类型。
+
+年份、邮编、1–5 分的评分、`user_id` 即使是数字，也不标成度量。
+
+## 已定
+
+- 用途：上课演示。文档用中文，示例保持能当场敲完的长度。
+- 列角色：自动判断。错了可以接受，理由要能讲出来，并可用 `set_role` 当场改正。
+- 发布名：PyPI 包名 `tableprobe`，导入 `from tableprobe import open_table`。仓库名仍是 `wanglaoshi-sql`。

tableprobe-0.1.0/examples/demo.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from tableprobe import open_table
+
+orders = open_table(Path(__file__).with_name("orders.csv"))
+print(orders.row_count())
+print(orders.column_count())
+for column in orders.profile():
+    print(column)

tableprobe-0.1.0/examples/orders.csv

@@ -0,0 +1,31 @@
+金额,地区,下单日期,user_id,年份,评分
+100,华东,2024-01-01,1000,2022,1
+117,华北,2024-01-02,1001,2023,2
+134,华南,2024-01-03,1002,2024,3
+151,西南,2024-01-04,1003,2025,4
+168,华东,2024-01-05,1004,2022,5
+185,华北,2024-01-06,1005,2023,1
+202,华南,2024-01-07,1006,2024,2
+219,西南,2024-01-08,1007,2025,3
+236,华东,2024-01-09,1008,2022,4
+253,华北,2024-01-10,1009,2023,5
+270,华南,2024-01-11,1010,2024,1
+287,西南,2024-01-12,1011,2025,2
+304,华东,2024-01-13,1012,2022,3
+321,华北,2024-01-14,1013,2023,4
+338,华南,2024-01-15,1014,2024,5
+355,西南,2024-01-16,1015,2025,1
+372,华东,2024-01-17,1016,2022,2
+389,华北,2024-01-18,1017,2023,3
+406,华南,2024-01-19,1018,2024,4
+423,西南,2024-01-20,1019,2025,5
+440,华东,2024-01-21,1020,2022,1
+457,华北,2024-01-22,1021,2023,2
+474,华南,2024-01-23,1022,2024,3
+491,西南,2024-01-24,1023,2025,4
+508,华东,2024-01-25,1024,2022,5
+525,华北,2024-01-26,1025,2023,1
+542,华南,2024-01-27,1026,2024,2
+559,西南,2024-01-28,1027,2025,3
+576,华东,2024-01-29,1028,2022,4
+593,华北,2024-01-30,1029,2023,5

tableprobe-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tableprobe"
+version = "0.1.0"
+description = "上课演示用的表探查库：打开 CSV、Parquet、SQLite、xlsx 和 MySQL，回答行数、列数和列角色。"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["duckdb>=1.1.0"]
+
+[project.urls]
+Homepage = "https://github.com/WangLaoShi/wanglaoshi-sql"
+Source = "https://github.com/WangLaoShi/wanglaoshi-sql"
+
+[project.optional-dependencies]
+mysql = []
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tableprobe-0.1.0/src/tableprobe/__init__.py

@@ -0,0 +1,6 @@
+"""把一张表收成同一个对象，回答行数、列数和列角色。"""
+
+from tableprobe.open import open_table
+
+__all__ = ["open_table"]
+__version__ = "0.1.0"

tableprobe-0.1.0/src/tableprobe/errors.py

@@ -0,0 +1,22 @@
+"""中文错误，以及连接信息里的密码打码。"""
+
+from __future__ import annotations
+
+import re
+
+_MYSQL_URL = re.compile(r"(mysql://[^:\s/@]+:)([^@/\s]*)(@)")
+_QUOTED_PASSWORD = re.compile(r"(password\s*=\s*')((?:''|[^'])*)(')", re.IGNORECASE)
+_BARE_PASSWORD = re.compile(r"(password\s*=\s*)(\S+)", re.IGNORECASE)
+
+
+class TableProbeError(Exception):
+    """tableprobe 抛出的错误，说明文字是中文。"""
+
+
+def redact(text: str) -> str:
+    """去掉连接串和报错文本里的密码。"""
+
+    text = _MYSQL_URL.sub(r"\1***\3", text)
+    text = _QUOTED_PASSWORD.sub(r"\1***\3", text)
+    text = _BARE_PASSWORD.sub(r"\1***", text)
+    return text

tableprobe-0.1.0/src/tableprobe/open.py

@@ -0,0 +1,192 @@
+"""打开一种数据源，并把它落成同一张 DuckDB 视图。"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+from tableprobe.errors import TableProbeError, redact
+from tableprobe.sql import quote_ident, sql_literal
+
+
+@dataclass(frozen=True)
+class OpenRequest:
+    kind: str
+    label: str
+    path: str | None = None
+    table: str | None = None
+    sheet: str | None = None
+    mysql_host: str | None = None
+    mysql_port: int | None = None
+    mysql_user: str | None = None
+    mysql_password: str | None = None
+    mysql_database: str | None = None
+
+
+def open_table(
+    source: str | os.PathLike[str],
+    *,
+    table: str | None = None,
+    sheet: str | None = None,
+):
+    """打开 CSV、Parquet、SQLite、xlsx 或 MySQL 里的一张表。"""
+
+    request = parse_source(source, table=table, sheet=sheet)
+    from tableprobe.table import Table
+
+    return Table(request)
+
+
+def parse_source(
+    source: str | os.PathLike[str],
+    *,
+    table: str | None,
+    sheet: str | None,
+) -> OpenRequest:
+    raw = os.fspath(source)
+    if raw.startswith("mysql://"):
+        return _parse_mysql(raw, table=table, sheet=sheet)
+    if raw.startswith("sqlite:"):
+        return _parse_sqlite_uri(raw, table=table, sheet=sheet)
+
+    path = Path(raw).expanduser()
+    suffix = path.suffix.lower()
+    if suffix == ".xls":
+        raise TableProbeError("不支持旧版 .xls，请另存为 .xlsx。")
+    if suffix in {".csv", ".parquet", ".xlsx", ".db", ".sqlite", ".sqlite3"}:
+        if not path.is_file():
+            raise TableProbeError(f"找不到文件：{path}")
+        resolved = str(path.resolve())
+        if suffix == ".csv":
+            _reject_table_and_sheet(table, sheet)
+            return OpenRequest(kind="csv", label=resolved, path=resolved)
+        if suffix == ".parquet":
+            _reject_table_and_sheet(table, sheet)
+            return OpenRequest(kind="parquet", label=resolved, path=resolved)
+        if suffix == ".xlsx":
+            if table:
+                raise TableProbeError("只有 SQLite 和 MySQL 需要传入 table。")
+            return OpenRequest(kind="xlsx", label=resolved, path=resolved, sheet=sheet)
+        _require_table(table, "SQLite")
+        if sheet is not None:
+            raise TableProbeError("只有 xlsx 可以指定 sheet。")
+        return OpenRequest(kind="sqlite", label=resolved, path=resolved, table=table)
+    raise TableProbeError("无法识别这个数据源。支持 CSV、Parquet、SQLite、xlsx 和 MySQL。")
+
+
+def mysql_attach_sql(request: OpenRequest) -> str:
+    parts = [
+        _mysql_token("host", request.mysql_host or ""),
+        f"port={request.mysql_port}",
+        _mysql_token("user", request.mysql_user or ""),
+        _mysql_token("password", request.mysql_password or ""),
+        _mysql_token("database", request.mysql_database or ""),
+        "connect_timeout=5",
+    ]
+    return "ATTACH " + sql_literal(" ".join(parts)) + " AS src (TYPE mysql)"
+
+
+def view_sql(request: OpenRequest, sheet_name: str | None = None) -> list[str]:
+    """返回按顺序执行的 SQL。最后一张视图名固定为 probe_table。"""
+
+    if request.kind == "csv":
+        return [
+            "CREATE VIEW probe_table AS SELECT * FROM read_csv_auto("
+            + sql_literal(request.path or "")
+            + ")"
+        ]
+    if request.kind == "parquet":
+        return [
+            "CREATE VIEW probe_table AS SELECT * FROM read_parquet("
+            + sql_literal(request.path or "")
+            + ")"
+        ]
+    if request.kind == "sqlite":
+        return [
+            "ATTACH "
+            + sql_literal(request.path or "")
+            + " AS src (TYPE sqlite)",
+            "CREATE VIEW probe_table AS SELECT * FROM src." + quote_ident(request.table or ""),
+        ]
+    if request.kind == "xlsx":
+        options = "header = true"
+        if sheet_name:
+            options += ", sheet = " + sql_literal(sheet_name)
+        return [
+            "CREATE VIEW probe_table AS SELECT * FROM read_xlsx("
+            + sql_literal(request.path or "")
+            + ", "
+            + options
+            + ")"
+        ]
+    return [
+        mysql_attach_sql(request),
+        "CREATE VIEW probe_table AS SELECT * FROM src." + quote_ident(request.table or ""),
+    ]
+
+
+def _parse_mysql(raw: str, *, table: str | None, sheet: str | None) -> OpenRequest:
+    if sheet is not None:
+        raise TableProbeError("只有 xlsx 可以指定 sheet。")
+    _require_table(table, "MySQL")
+    parsed = urlparse(raw)
+    database = unquote(parsed.path.lstrip("/"))
+    if (
+        parsed.scheme != "mysql"
+        or not parsed.hostname
+        or not database
+        or "/" in database
+        or parsed.username is None
+    ):
+        raise TableProbeError("MySQL 连接串应为 mysql://用户:密码@主机:端口/库名。")
+    password = unquote(parsed.password) if parsed.password is not None else ""
+    user = unquote(parsed.username)
+    host = parsed.hostname
+    port = parsed.port or 3306
+    label = f"mysql://{user}:***@{host}:{port}/{database}"
+    return OpenRequest(
+        kind="mysql",
+        label=redact(label),
+        table=table,
+        mysql_host=host,
+        mysql_port=port,
+        mysql_user=user,
+        mysql_password=password,
+        mysql_database=database,
+    )
+
+
+def _parse_sqlite_uri(raw: str, *, table: str | None, sheet: str | None) -> OpenRequest:
+    if not raw.startswith("sqlite:///"):
+        raise TableProbeError("SQLite 连接串应为 sqlite:///文件路径。")
+    if sheet is not None:
+        raise TableProbeError("只有 xlsx 可以指定 sheet。")
+    _require_table(table, "SQLite")
+    file_path = Path(raw.removeprefix("sqlite:///")).expanduser()
+    if not file_path.is_file():
+        raise TableProbeError(f"找不到文件：{file_path}")
+    resolved = str(file_path.resolve())
+    return OpenRequest(kind="sqlite", label=resolved, path=resolved, table=table)
+
+
+def _require_table(table: str | None, kind: str) -> None:
+    if not table:
+        raise TableProbeError(f"打开 {kind} 时必须传入 table。")
+
+
+def _reject_table_and_sheet(table: str | None, sheet: str | None) -> None:
+    if table:
+        raise TableProbeError("只有 SQLite 和 MySQL 需要传入 table。")
+    if sheet is not None:
+        raise TableProbeError("只有 xlsx 可以指定 sheet。")
+
+
+def _mysql_token(key: str, value: str) -> str:
+    if any(character.isspace() or character in "'\"=" for character in value):
+        label = {"host": "主机", "user": "用户名", "password": "密码", "database": "库名"}.get(
+            key, key
+        )
+        raise TableProbeError(f"MySQL 的{label}里先不要使用空格、等号或引号。")
+    return f"{key}={value}"

tableprobe-0.1.0/src/tableprobe/profile.py

@@ -0,0 +1,79 @@
+"""抽样统计。不把整表拉进 Python。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from tableprobe.sql import quote_ident
+
+SAMPLE_LIMIT = 10_000
+
+
+@dataclass(frozen=True)
+class ColumnStat:
+    name: str
+    duckdb_type: str
+    null_rate: float
+    distinct_count: int
+    non_null_count: int
+    sample_rows: int
+    is_primary_key: bool
+
+
+@dataclass(frozen=True)
+class ColumnProfile:
+    """一列的画像。role 取维度、度量、时间、标识或未知。"""
+
+    name: str
+    duckdb_type: str
+    null_rate: float
+    distinct_count: int
+    sample_rows: int
+    role: str
+    reason: str
+
+    def __str__(self) -> str:
+        return (
+            f"{self.name}\t{self.duckdb_type}\t"
+            f"空值率 {self.null_rate:.0%}\t"
+            f"基数 {self.distinct_count}\t"
+            f"抽样 {self.sample_rows} 行\t"
+            f"{self.role}\t{self.reason}"
+        )
+
+
+def collect_stats(connection, columns: list[tuple[str, str, bool]]) -> list[ColumnStat]:
+    """对最多 10000 行的抽样计算每列的空值率和基数。"""
+
+    if not columns:
+        return []
+
+    pieces = ["COUNT(*) AS sample_rows"]
+    for index, (name, _, _) in enumerate(columns):
+        ident = quote_ident(name)
+        pieces.append(f"COUNT({ident}) AS non_null_{index}")
+        pieces.append(f"COUNT(DISTINCT {ident}) AS distinct_{index}")
+    sql = (
+        "SELECT "
+        + ", ".join(pieces)
+        + f" FROM (SELECT * FROM probe_table USING SAMPLE {SAMPLE_LIMIT} ROWS)"
+    )
+    row = connection.execute(sql).fetchone()
+    sample_rows = int(row[0])
+    stats: list[ColumnStat] = []
+    for index, (name, duckdb_type, is_primary_key) in enumerate(columns):
+        non_null = int(row[1 + index * 2])
+        distinct = int(row[2 + index * 2])
+        null_rate = 0.0 if sample_rows == 0 else (sample_rows - non_null) / sample_rows
+        stats.append(
+            ColumnStat(
+                name=name,
+                duckdb_type=duckdb_type,
+                null_rate=null_rate,
+                distinct_count=distinct,
+                non_null_count=non_null,
+                sample_rows=sample_rows,
+                is_primary_key=is_primary_key,
+            )
+        )
+    return stats