tableprobe 0.1.0__py3-none-any.whl

tableprobe/__init__.py

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

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/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/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

tableprobe/roles.py

@@ -0,0 +1,156 @@
+"""列角色判断。这个模块不连接数据库。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+# 先命中先停：标识、时间、列名维度、数值基数、布尔或文本、未知。
+_IDENTIFIER_EXACT = {"id"}
+_DIMENSION_TOKENS = {
+    "year",
+    "zip",
+    "postal",
+    "postcode",
+    "zipcode",
+    "code",
+    "rating",
+    "score",
+    "level",
+    "grade",
+    "rank",
+}
+_DIMENSION_ZH = ("年份", "邮编", "编码", "评分", "等级")
+_NUMERIC = {
+    "TINYINT",
+    "SMALLINT",
+    "INTEGER",
+    "INT",
+    "BIGINT",
+    "HUGEINT",
+    "UTINYINT",
+    "USMALLINT",
+    "UINTEGER",
+    "UBIGINT",
+    "UHUGEINT",
+    "FLOAT",
+    "DOUBLE",
+    "REAL",
+    "DECIMAL",
+    "NUMERIC",
+}
+_BOOLEAN = {"BOOLEAN", "BOOL", "LOGICAL"}
+_STRING = {"VARCHAR", "CHAR", "BPCHAR", "TEXT", "STRING"}
+_LOW_DISTINCT = 20
+_LOW_RATIO = 0.05
+_MIN_NON_NULL_FOR_RATIO = 20
+
+
+class Role(StrEnum):
+    DIMENSION = "dimension"
+    MEASURE = "measure"
+    TIME = "time"
+    IDENTIFIER = "identifier"
+    UNKNOWN = "unknown"
+
+
+ROLE_LABELS = {
+    Role.DIMENSION: "维度",
+    Role.MEASURE: "度量",
+    Role.TIME: "时间",
+    Role.IDENTIFIER: "标识",
+    Role.UNKNOWN: "未知",
+}
+
+_ROLE_ALIASES = {
+    "dimension": Role.DIMENSION,
+    "measure": Role.MEASURE,
+    "time": Role.TIME,
+    "identifier": Role.IDENTIFIER,
+    "维度": Role.DIMENSION,
+    "度量": Role.MEASURE,
+    "时间": Role.TIME,
+    "标识": Role.IDENTIFIER,
+}
+
+MANUAL_REASON = "课堂上手工指定。"
+
+
+@dataclass(frozen=True)
+class RoleDecision:
+    role: Role
+    reason: str
+
+
+def parse_role(value: str) -> Role:
+    key = value.strip()
+    role = _ROLE_ALIASES.get(key) or _ROLE_ALIASES.get(key.lower())
+    if role is None:
+        raise ValueError(key)
+    return role
+
+
+def infer_role(
+    name: str,
+    duckdb_type: str,
+    *,
+    distinct_count: int,
+    non_null_count: int,
+    is_primary_key: bool = False,
+) -> RoleDecision:
+    """按固定顺序判断一列的角色。"""
+
+    if _is_identifier_name(name):
+        return RoleDecision(Role.IDENTIFIER, "列名像标识（id、_id、uuid 或 guid）。")
+    if is_primary_key:
+        return RoleDecision(Role.IDENTIFIER, "这一列是主键，当作标识。")
+
+    base = _base_type(duckdb_type)
+    if _is_temporal(base):
+        return RoleDecision(Role.TIME, "这一列是日期或时间。")
+    if _is_dimension_name(name):
+        return RoleDecision(Role.DIMENSION, "列名像年份、邮编、编码、评分或等级，当作维度。")
+    if base in _NUMERIC:
+        if _low_cardinality(distinct_count, non_null_count):
+            return RoleDecision(Role.DIMENSION, "数值列的不重复值很少，当作维度。")
+        return RoleDecision(Role.MEASURE, "数值列可以做求和或平均，当作度量。")
+    if base in _BOOLEAN:
+        return RoleDecision(Role.DIMENSION, "布尔列当作维度。")
+    if base in _STRING:
+        return RoleDecision(Role.DIMENSION, "文本列当作维度。")
+    return RoleDecision(Role.UNKNOWN, f"这个类型无法判断角色：{duckdb_type}。")
+
+
+def _is_identifier_name(name: str) -> bool:
+    lowered = name.lower()
+    return (
+        lowered in _IDENTIFIER_EXACT
+        or lowered.endswith("_id")
+        or "uuid" in lowered
+        or "guid" in lowered
+    )
+
+
+def _is_dimension_name(name: str) -> bool:
+    if any(token in name for token in _DIMENSION_ZH):
+        return True
+    parts = name.lower().replace("-", "_").split("_")
+    return any(part in _DIMENSION_TOKENS for part in parts)
+
+
+def _low_cardinality(distinct_count: int, non_null_count: int) -> bool:
+    if distinct_count <= _LOW_DISTINCT:
+        return True
+    if non_null_count < _MIN_NON_NULL_FOR_RATIO or non_null_count == 0:
+        return False
+    return distinct_count / non_null_count <= _LOW_RATIO
+
+
+def _base_type(duckdb_type: str) -> str:
+    return duckdb_type.upper().split("(", 1)[0].strip()
+
+
+def _is_temporal(base: str) -> bool:
+    if base.startswith("TIMESTAMP") or base.startswith("DATETIME") or base.startswith("DATE"):
+        return True
+    return base == "TIME" or base.startswith("TIME ")

tableprobe/sql.py

@@ -0,0 +1,11 @@
+"""拼 SQL 时用到的转义。"""
+
+from __future__ import annotations
+
+
+def quote_ident(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def sql_literal(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"

tableprobe/table.py

@@ -0,0 +1,170 @@
+"""一张表：精确行数、列数，以及抽样后的列角色。"""
+
+from __future__ import annotations
+
+import duckdb
+
+from tableprobe.errors import TableProbeError, redact
+from tableprobe.open import OpenRequest, view_sql
+from tableprobe.profile import ColumnProfile, collect_stats
+from tableprobe.roles import MANUAL_REASON, ROLE_LABELS, Role, infer_role, parse_role
+from tableprobe.xlsx_check import prepare_sheet
+
+
+class Table:
+    """一个数据源里的一张表。一个对象持有一条 DuckDB 连接。"""
+
+    def __init__(self, request: OpenRequest) -> None:
+        self._request = request
+        self._con = duckdb.connect()
+        self._columns: list[tuple[str, str, bool]] = []
+        self._overrides: dict[str, Role] = {}
+        self._stats = None
+        try:
+            self._load()
+        except Exception:
+            self.close()
+            raise
+
+    def row_count(self) -> int:
+        """精确行数，使用 COUNT(*)。"""
+
+        row = self._execute("SELECT COUNT(*) FROM probe_table").fetchone()
+        return int(row[0])
+
+    def column_count(self) -> int:
+        self._require_open()
+        return len(self._columns)
+
+    def profile(self) -> list[ColumnProfile]:
+        """每列的类型、抽样空值率、抽样基数、抽样行数和角色。空表返回空列表。"""
+
+        self._require_open()
+        if self._stats is None:
+            if self.row_count() == 0:
+                self._stats = []
+            else:
+                try:
+                    self._stats = collect_stats(self._con, self._columns)
+                except TableProbeError:
+                    raise
+                except Exception as exc:
+                    raise TableProbeError("读取数据失败：" + redact(str(exc))) from exc
+        profiles: list[ColumnProfile] = []
+        for stat in self._stats:
+            if stat.name in self._overrides:
+                role = self._overrides[stat.name]
+                reason = MANUAL_REASON
+            else:
+                decision = infer_role(
+                    stat.name,
+                    stat.duckdb_type,
+                    distinct_count=stat.distinct_count,
+                    non_null_count=stat.non_null_count,
+                    is_primary_key=stat.is_primary_key,
+                )
+                role = decision.role
+                reason = decision.reason
+            profiles.append(
+                ColumnProfile(
+                    name=stat.name,
+                    duckdb_type=stat.duckdb_type,
+                    null_rate=stat.null_rate,
+                    distinct_count=stat.distinct_count,
+                    sample_rows=stat.sample_rows,
+                    role=ROLE_LABELS[role],
+                    reason=reason,
+                )
+            )
+        return profiles
+
+    def set_role(self, column: str, role: str) -> None:
+        """只改当前这个表对象上某一列的角色。"""
+
+        self._require_open()
+        if column not in {name for name, _, _ in self._columns}:
+            raise TableProbeError(f"没有这一列：{column}")
+        try:
+            parsed = parse_role(role)
+        except ValueError:
+            raise TableProbeError("角色只能是维度、度量、时间或标识。") from None
+        self._overrides[column] = parsed
+
+    def dimensions(self) -> list[str]:
+        return self._names(Role.DIMENSION)
+
+    def measures(self) -> list[str]:
+        return self._names(Role.MEASURE)
+
+    def times(self) -> list[str]:
+        return self._names(Role.TIME)
+
+    def identifiers(self) -> list[str]:
+        return self._names(Role.IDENTIFIER)
+
+    def close(self) -> None:
+        if self._con is not None:
+            self._con.close()
+            self._con = None
+
+    def __enter__(self) -> Table:
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def __repr__(self) -> str:
+        if self._con is None:
+            return "Table(已关闭)"
+        return f"Table({self._request.label})"
+
+    def _load(self) -> None:
+        sheet_name = None
+        if self._request.kind == "xlsx":
+            sheet_name = prepare_sheet(self._request.path or "", self._request.sheet)
+            self._ensure_extension("excel")
+        elif self._request.kind == "mysql":
+            self._ensure_extension("mysql")
+        for statement in view_sql(self._request, sheet_name):
+            self._execute(statement)
+        described = self._execute("DESCRIBE probe_table").fetchall()
+        columns: list[tuple[str, str, bool]] = []
+        for row in described:
+            name = "" if row[0] is None else str(row[0])
+            if not name.strip():
+                raise TableProbeError("这个表的第一行有空列名，不是矩形表。")
+            columns.append((name, str(row[1]), row[3] == "PRI"))
+        self._columns = columns
+
+    def _ensure_extension(self, name: str) -> None:
+        try:
+            self._con.execute(f"INSTALL {name}")
+            self._con.execute(f"LOAD {name}")
+        except Exception as exc:
+            raise TableProbeError(
+                f"加载 DuckDB 的 {name} 扩展失败。上课时请先确认这台电脑能联网。"
+                + redact(str(exc))
+            ) from exc
+
+    def _names(self, role: Role) -> list[str]:
+        label = ROLE_LABELS[role]
+        return [column.name for column in self.profile() if column.role == label]
+
+    def _execute(self, sql: str):
+        self._require_open()
+        try:
+            return self._con.execute(sql)
+        except TableProbeError:
+            raise
+        except Exception as exc:
+            raise TableProbeError("读取数据失败：" + redact(str(exc))) from exc
+
+    def _require_open(self) -> None:
+        if self._con is None:
+            raise TableProbeError("这个表已经关闭。")

tableprobe/xlsx_check.py

@@ -0,0 +1,140 @@
+"""检查 xlsx 是不是第一行为列名的矩形表。只用标准库。"""
+
+from __future__ import annotations
+
+import zipfile
+from xml.etree import ElementTree
+
+from tableprobe.errors import TableProbeError
+
+
+def prepare_sheet(path: str, sheet: str | None) -> str:
+    """确认工作表能读，并返回实际使用的工作表名。"""
+
+    try:
+        with zipfile.ZipFile(path) as archive:
+            sheet_name, sheet_xml = _read_sheet(archive, sheet)
+            shared = _shared_strings(archive)
+    except TableProbeError:
+        raise
+    except zipfile.BadZipFile as exc:
+        raise TableProbeError("这个文件不是有效的 xlsx。") from exc
+    except KeyError as exc:
+        raise TableProbeError("这个文件不是有效的 xlsx。") from exc
+    except ElementTree.ParseError as exc:
+        raise TableProbeError("这个文件不是有效的 xlsx。") from exc
+
+    root = ElementTree.fromstring(sheet_xml)
+    for element in root.iter():
+        if _local(element.tag) == "mergeCell":
+            raise TableProbeError("这个工作表有合并单元格，第一版只读取矩形表。")
+    _reject_blank_header(root, shared)
+    return sheet_name
+
+
+def _read_sheet(archive: zipfile.ZipFile, sheet: str | None) -> tuple[str, bytes]:
+    workbook = ElementTree.fromstring(archive.read("xl/workbook.xml"))
+    sheets: list[tuple[str, str]] = []
+    for element in workbook.iter():
+        if _local(element.tag) != "sheet":
+            continue
+        name = element.attrib.get("name") or ""
+        rel_id = _attr(element, "id")
+        if rel_id:
+            sheets.append((name, rel_id))
+    if not sheets:
+        raise TableProbeError("这个 xlsx 里没有工作表。")
+
+    if sheet is None:
+        sheet_name, rel_id = sheets[0]
+    else:
+        matches = [item for item in sheets if item[0] == sheet]
+        if not matches:
+            raise TableProbeError(f"这个工作表不存在：{sheet}")
+        sheet_name, rel_id = matches[0]
+
+    rels = ElementTree.fromstring(archive.read("xl/_rels/workbook.xml.rels"))
+    target = None
+    for element in rels.iter():
+        if _local(element.tag) == "Relationship" and element.attrib.get("Id") == rel_id:
+            target = element.attrib.get("Target")
+    if not target:
+        raise TableProbeError("这个文件不是有效的 xlsx。")
+    target = target.replace("\\", "/").lstrip("/")
+    if target.startswith("./"):
+        target = target[2:]
+    if not target.startswith("xl/"):
+        target = "xl/" + target
+    return sheet_name, archive.read(target)
+
+
+def _shared_strings(archive: zipfile.ZipFile) -> list[str]:
+    if "xl/sharedStrings.xml" not in archive.namelist():
+        return []
+    root = ElementTree.fromstring(archive.read("xl/sharedStrings.xml"))
+    values: list[str] = []
+    for item in list(root):
+        if _local(item.tag) != "si":
+            continue
+        texts = [
+            node.text or ""
+            for node in item.iter()
+            if _local(node.tag) == "t"
+        ]
+        values.append("".join(texts))
+    return values
+
+
+def _reject_blank_header(root: ElementTree.Element, shared: list[str]) -> None:
+    first_row = next((element for element in root.iter() if _local(element.tag) == "row"), None)
+    if first_row is None:
+        raise TableProbeError("这个工作表的第一行有空列名，不是矩形表。")
+
+    cells: list[tuple[int, str]] = []
+    for element in list(first_row):
+        if _local(element.tag) != "c":
+            continue
+        cells.append((_column_index(element.attrib.get("r", "")), _cell_text(element, shared)))
+    if not cells:
+        raise TableProbeError("这个工作表的第一行有空列名，不是矩形表。")
+
+    cells.sort(key=lambda item: item[0])
+    indexes = [index for index, _ in cells]
+    if indexes != list(range(1, len(indexes) + 1)):
+        raise TableProbeError("这个工作表的第一行有空列名，不是矩形表。")
+    if any(not text.strip() for _, text in cells):
+        raise TableProbeError("这个工作表的第一行有空列名，不是矩形表。")
+
+
+def _cell_text(cell: ElementTree.Element, shared: list[str]) -> str:
+    kind = cell.attrib.get("t")
+    value = next((node.text or "" for node in cell.iter() if _local(node.tag) == "v"), "")
+    if kind == "s":
+        try:
+            return shared[int(value)]
+        except (ValueError, IndexError):
+            return ""
+    if kind == "inlineStr":
+        return "".join(node.text or "" for node in cell.iter() if _local(node.tag) == "t")
+    return value
+
+
+def _column_index(ref: str) -> int:
+    letters = "".join(character for character in ref if character.isalpha())
+    if not letters:
+        return 0
+    index = 0
+    for character in letters:
+        index = index * 26 + (ord(character.upper()) - 64)
+    return index
+
+
+def _local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def _attr(element: ElementTree.Element, name: str) -> str | None:
+    for key, value in element.attrib.items():
+        if _local(key) == name:
+            return value
+    return None

tableprobe-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+tableprobe/__init__.py,sha256=-ivhMRFGl3tnVCAr7OnjVSJ3a__Nux3qeOt0qLSAiGY,167
+tableprobe/errors.py,sha256=kYjVPypKXjUJimga6A3WioS3X7_z2XbOxXlgZd04dOE,671
+tableprobe/open.py,sha256=MOf4BrYRKnkrJkyoDYb5XaAYf2uhvf4MFWmIxDkZx_A,6829
+tableprobe/profile.py,sha256=tz9baraokXE4wgymJqYaEhRJ1fFInGi5LG5PN7QVi-Y,2254
+tableprobe/roles.py,sha256=mVf5m8BiuUT9t8pbcDFi8qLuhuUe_sW_ceZg12KTJzk,4167
+tableprobe/sql.py,sha256=0ON4e4RnD2fOrMQSZK0SzsWdyjKNTibeqWlwcDPStVQ,242
+tableprobe/table.py,sha256=ZHoCy-QrkAsH6NrFY8IXmKZ038AWgGz1vXqqLLmjpGE,5949
+tableprobe/xlsx_check.py,sha256=1HpgJfffNgTBb9uTLheN6a7XNCeVvlT6c7tHA4mHTfQ,5082
+tableprobe-0.1.0.dist-info/METADATA,sha256=jFNp6konsFihunWqFzot3UbdiIx2LSbGPnM34a22wUc,3470
+tableprobe-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+tableprobe-0.1.0.dist-info/RECORD,,

tableprobe-0.1.0.dist-info/WHEEL

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