sdpy-kit 0.5.0__tar.gz → 0.5.1__tar.gz

{sdpy_kit-0.5.0 → sdpy_kit-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.5.0
+Version: 0.5.1
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -881,6 +881,9 @@ md = AnyDocKit.convert_to_md("scan.pdf", ocr="hosted")  # 需 FIRECRAWL_API_KEY
 
 `AnyDocResult(success, markdown, file_path, source_format, error)`
 
+> 异常：沿用上游 `anydoc.ConvertError` 体系（`MalformedError` / `NeedsOcrError` 等子类可直接捕获），
+> `AnyDocError` 是该基类的别名；安全版 `convert()` 会把它们封装为 `AnyDocResult.error`。
+
 ---
 
 ## kit.docs.docx_kit —— Word 模板动态填充
@@ -1046,8 +1049,8 @@ if result.success:
 | `convert(src_path, output_dir=None, *, ...) -> RcDocParserResult` | 安全版：失败封装为结果对象 |
 
 > 产物：`<out>/images/img-NNN-<sha1 前 10>.<ext>`（按出现顺序、内容哈希命名）；无图不建空目录。
-> 前提：中文标题依赖 `w:outlineLvl` 或「标题 N」样式（都没有时退化为正文）；合并单元格的复杂表格
-> 会退化为 GFM 表格；页眉页脚/脚注不提取。纯本地，无需模型或 GPU。
+> 前提：中文标题依赖 `w:outlineLvl` 或「标题 N」样式（都没有时退化为正文）；合并单元格表格会重建为
+> 等宽 GFM（覆盖位留空，不输出 HTML `<table>`）；页眉页脚/脚注不提取。纯本地，无需模型或 GPU。
 
 ## kit.crawl.wx_article_kit —— 微信公众号文章抓取存储
 

{sdpy_kit-0.5.0 → sdpy_kit-0.5.1}/README.md

@@ -805,6 +805,9 @@ md = AnyDocKit.convert_to_md("scan.pdf", ocr="hosted")  # 需 FIRECRAWL_API_KEY
 
 `AnyDocResult(success, markdown, file_path, source_format, error)`
 
+> 异常：沿用上游 `anydoc.ConvertError` 体系（`MalformedError` / `NeedsOcrError` 等子类可直接捕获），
+> `AnyDocError` 是该基类的别名；安全版 `convert()` 会把它们封装为 `AnyDocResult.error`。
+
 ---
 
 ## kit.docs.docx_kit —— Word 模板动态填充
@@ -970,8 +973,8 @@ if result.success:
 | `convert(src_path, output_dir=None, *, ...) -> RcDocParserResult` | 安全版：失败封装为结果对象 |
 
 > 产物：`<out>/images/img-NNN-<sha1 前 10>.<ext>`（按出现顺序、内容哈希命名）；无图不建空目录。
-> 前提：中文标题依赖 `w:outlineLvl` 或「标题 N」样式（都没有时退化为正文）；合并单元格的复杂表格
-> 会退化为 GFM 表格；页眉页脚/脚注不提取。纯本地，无需模型或 GPU。
+> 前提：中文标题依赖 `w:outlineLvl` 或「标题 N」样式（都没有时退化为正文）；合并单元格表格会重建为
+> 等宽 GFM（覆盖位留空，不输出 HTML `<table>`）；页眉页脚/脚注不提取。纯本地，无需模型或 GPU。
 
 ## kit.crawl.wx_article_kit —— 微信公众号文章抓取存储
 

{sdpy_kit-0.5.0 → sdpy_kit-0.5.1}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.5.0 → sdpy_kit-0.5.1}/kit/docs/anydoc_kit.py

@@ -39,6 +39,10 @@ Author: Clark Chang
 依赖：
 - `firecrawl-anydoc`（extra `anydoc`，导入名 `anydoc`）+ `pikepdf`；
   未安装时导入报错并提示安装命令。
+
+异常：
+- 沿用上游 `anydoc.ConvertError` 体系（不包装，保留 `MalformedError` /
+  `NeedsOcrError` 等子类可捕获性）；`AnyDocError` 是该基类的别名。
 """
 
 import io
@@ -58,6 +62,9 @@ from kit.config.log_config import get_default_logger
 
 logger = get_default_logger(__name__)
 
+# 异常别名：沿用 anydoc 的异常体系，不包装（保留上游子类可捕获性）
+AnyDocError = anydoc.ConvertError
+
 # kit 维护的扩展名白名单（用于本地快速校验与错误提示）。
 # 注意：这是 anydoc 实际支持面的子集——anydoc 另支持 docm / pptm / ppsx / ppsm /
 # xlsm / xlsb / pps / pot / odt / ods / odp / rtf / epub 等。

{sdpy_kit-0.5.0 → sdpy_kit-0.5.1}/kit/docs/rc_docparser_kit.py

@@ -35,14 +35,17 @@ Author: Clark Chang
   图片引用统一改写为 `images/<文件名>`（库在 Windows 上输出反斜杠相对路径）。
 - 图片：库按出现顺序产出 `img-NNN-<sha1 前 10>.<ext>`，本模块复制到 `images/`；
   `extract_images=False` 时不落图片并删除 md 中的图片引用行。
+- 表格：用 python-docx 把每张表重建为**等宽 GFM 网格**，合并单元格的覆盖位留空
+  （库原生产物会把同一单元格文本复制到每个覆盖列/行）；表格数量不匹配时保留原产物。
 - 临时副本与解析工作目录均创建在产物目录内的临时目录，结束后清理，不修改源文件。
 
 前提条件：
 - 纯本地解析：不需要 GPU、模型权重、OCR、GTK 等系统库。
 - 中文标题依赖 `w:outlineLvl` 或「标题 N」样式；两者都没有（仅靠字号/加粗）时
   无法还原层级。
-- 已知限制：页眉页脚与脚注不提取；合并单元格的复杂表格退化为 GFM 表格
-  （跨行跨列丢失）；未带 `w:numPr` 的列表样式（如 List Bullet）按普通段落输出。
+- 已知限制：页眉页脚与脚注不提取；合并单元格按「覆盖位留空」展平（span 语义不再标出），
+  单元格内嵌图片/公式只保留文字；未带 `w:numPr` 的列表样式（如 List Bullet）
+  按普通段落输出。
 
 依赖：
 - `rc-docparser>=0.2.2`（`pip install sdpy-kit[docx-parse]`）；
@@ -64,6 +67,7 @@ try:
     from docx import Document
     from docx.enum.style import WD_STYLE_TYPE
     from docx.oxml.ns import qn
+    from docx.text.paragraph import Paragraph
 except ImportError as e:
     raise ImportError(
         "rc_docparser_kit 需要可选依赖，请安装：pip install sdpy-kit[docx-parse]"
@@ -89,6 +93,9 @@ _CAPTION_LIKE_RE = re.compile(
 # 标题文本长度上限（超过视为误设大纲级别的正文/图注）
 _MAX_HEADING_CHARS = 60
 
+# GFM 表格行（用于定位库输出中的表格块）
+_TABLE_LINE_PREFIX = "|"
+
 
 class RcDocParserError(Exception):
     """docx 解析异常（依赖调用失败 / 产物缺失 / 落盘失败）"""
@@ -257,6 +264,105 @@ class RcDocParserKit:
         ]
         return "\n".join(kept)
 
+    # ------------------------------------------------------------------
+    # 表格重建（合并单元格 → 等宽 GFM）
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _tc_text(tc) -> str:
+        """从 `w:tc` 取文本：段落用空格连接，转义竖线（GFM 单元格不能换行）"""
+        parts = [Paragraph(p, None).text.strip() for p in tc.findall(qn("w:p"))]
+        text = " ".join(part for part in parts if part)
+        return text.replace("|", "\\|")
+
+    @classmethod
+    def _table_grid(cls, table) -> list[list[str]]:
+        """把 docx 表格重建为等宽矩形网格（合并格的覆盖位留空）
+
+        直接读 OOXML：每个 `w:tr` 的 `w:tc` 列表是「逻辑单元格」（不含网格展开），
+        `w:gridSpan` 给出横向跨度，`w:vMerge`（无 val 或 `continue`）表示纵向续接。
+        横向与纵向的覆盖位一律留空，避免同一单元格文本被复制到每一列/每一行。
+        """
+        rows: list[list[str]] = []
+        for tr in table._tbl.tr_lst:
+            cells: list[str] = []
+            for tc in tr.tc_lst:
+                tc_pr = tc.tcPr
+                span = 1
+                if tc_pr is not None and tc_pr.gridSpan is not None:
+                    span = max(1, int(tc_pr.gridSpan.val))
+                continued = False
+                if tc_pr is not None and tc_pr.vMerge is not None:
+                    continued = tc_pr.vMerge.val in (None, "continue")
+                cells.append("" if continued else cls._tc_text(tc))
+                cells.extend([""] * (span - 1))
+            rows.append(cells)
+
+        width = max((len(row) for row in rows), default=0)
+        return [row + [""] * (width - len(row)) for row in rows]
+
+    @staticmethod
+    def _render_gfm_table(rows: list[list[str]]) -> list[str]:
+        """把矩形网格渲染为 GFM 表格行（首行作表头）"""
+        if not rows:
+            return []
+        width = max(len(row) for row in rows)
+        lines = [
+            "| " + " | ".join(rows[0]) + " |",
+            "| " + " | ".join(["---"] * width) + " |",
+        ]
+        for row in rows[1:]:
+            lines.append("| " + " | ".join(row) + " |")
+        return lines
+
+    @classmethod
+    def _rebuild_tables(cls, markdown: str, src: Path) -> str:
+        """用 python-docx 重建的等宽 GFM 表格替换库输出的表格块
+
+        库按 `row.cells` 取文本，合并单元格会重复出现在每个覆盖格位；这里按顺序
+        一一替换。表格数量不一致、或读取 docx 失败时**保留原产物**并 warning，
+        不影响整体转换。
+        """
+        try:
+            doc = Document(str(src))
+        except Exception as e:  # noqa: BLE001 - 表格重建失败不应影响正文
+            logger.warning(f"读取 docx 表格失败，保留库输出: {e}")
+            return markdown
+        if not doc.tables:
+            return markdown
+
+        lines = markdown.splitlines()
+        blocks: list[tuple[int, int]] = []
+        index = 0
+        while index < len(lines):
+            if lines[index].lstrip().startswith(_TABLE_LINE_PREFIX):
+                start = index
+                while index < len(lines) and lines[index].lstrip().startswith(
+                    _TABLE_LINE_PREFIX
+                ):
+                    index += 1
+                blocks.append((start, index))
+            else:
+                index += 1
+
+        if len(blocks) != len(doc.tables):
+            logger.warning(
+                f"表格数量不匹配（md {len(blocks)} / docx {len(doc.tables)}），"
+                f"保留原始表格"
+            )
+            return markdown
+
+        rebuilt: list[str] = []
+        cursor = 0
+        for (start, end), table in zip(blocks, doc.tables):
+            rebuilt.extend(lines[cursor:start])
+            rebuilt.extend(cls._render_gfm_table(cls._table_grid(table)))
+            cursor = end
+        rebuilt.extend(lines[cursor:])
+
+        suffix = "\n" if markdown.endswith("\n") else ""
+        return "\n".join(rebuilt) + suffix
+
     @staticmethod
     def _outline_level(paragraph) -> int | None:
         """读取段落的 `w:outlineLvl`（0 基）并转为 Heading 级别，无则 None"""
@@ -374,6 +480,7 @@ class RcDocParserKit:
                 mapping=mapping,
                 extract_images=extract_images,
             )
+            markdown = cls._rebuild_tables(markdown, src)
             md_path = out_dir / f"{src.stem}.md"
             md_path.write_text(markdown, encoding="utf-8")
         finally:
@@ -445,6 +552,7 @@ class RcDocParserKit:
         markdown = cls._render(
             raw_md, images, src.stem, mapping=mapping, extract_images=True
         )
+        markdown = cls._rebuild_tables(markdown, src)
         logger.info(f"docx 解析成功: {src.name}（{len(markdown)} 字符）")
         return markdown