docvortex 0.2.1__py3-none-any.whl

docvortex/content/table/structure.py

@@ -0,0 +1,221 @@
+"""跨页表格的表头、宽度和边界行结构判定。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from bs4 import Tag
+
+from ...schema import BlockType
+
+from .blocks import _bbox_for_calculation, _is_continuation_caption, _is_post_table_non_continuation_caption, _table_children
+from .html import _colspan, _rowspan, calculate_row_rendered_segments
+from .models import MAX_HEADER_ROWS, TableMergeState
+
+
+def detect_table_headers(
+    state1: TableMergeState, state2: TableMergeState, max_header_rows: int = MAX_HEADER_ROWS
+) -> tuple[int, bool, list[list[str]]]:
+    """检测并比较两个表格的表头，仅扫描前几行."""
+    front_rows1 = state1.front_header_info[:max_header_rows]
+    front_rows2 = state2.front_header_info[:max_header_rows]
+
+    min_rows = min(len(front_rows1), len(front_rows2), max_header_rows)
+    header_rows = 0
+    headers_match = True
+    header_texts = []
+
+    for row_idx in range(min_rows):
+        row1 = front_rows1[row_idx]
+        row2 = front_rows2[row_idx]
+        structure_match = (
+            row1.cell_count == row2.cell_count
+            and row1.effective_cols == row2.effective_cols
+            and row1.colspans == row2.colspans
+            and row1.rowspans == row2.rowspans
+            and row1.normalized_texts == row2.normalized_texts
+        )
+
+        if structure_match:
+            header_rows += 1
+            header_texts.append(list(row1.display_texts))
+        else:
+            headers_match = header_rows > 0
+            break
+
+    if header_rows == 0:
+        header_rows, headers_match, header_texts = _detect_table_headers_visual(state1, state2, max_header_rows=max_header_rows)
+
+    return header_rows, headers_match, header_texts
+
+
+def _detect_table_headers_visual(
+    state1: TableMergeState,
+    state2: TableMergeState,
+    max_header_rows: int = MAX_HEADER_ROWS,
+) -> tuple[int, bool, list[list[str]]]:
+    """基于视觉一致性检测表头（只比较文本内容，忽略colspan/rowspan差异）."""
+    front_rows1 = state1.front_header_info[:max_header_rows]
+    front_rows2 = state2.front_header_info[:max_header_rows]
+
+    min_rows = min(len(front_rows1), len(front_rows2), max_header_rows)
+    header_rows = 0
+    headers_match = True
+    header_texts = []
+
+    for row_idx in range(min_rows):
+        row1 = front_rows1[row_idx]
+        row2 = front_rows2[row_idx]
+        # OCR 识别表头时可能丢失 colspan/rowspan，这里用渲染段数约束视觉一致性。
+        rendered_segments1 = calculate_row_rendered_segments(state1.rows, row_idx)
+        rendered_segments2 = calculate_row_rendered_segments(state2.rows, row_idx)
+        if row1.normalized_texts == row2.normalized_texts and rendered_segments1 == rendered_segments2:
+            header_rows += 1
+            header_texts.append(list(row1.display_texts))
+        else:
+            headers_match = header_rows > 0
+            break
+
+    if header_rows == 0:
+        headers_match = False
+
+    return header_rows, headers_match, header_texts
+
+
+def _expand_header_count_by_rowspan(rows: list[Tag], header_count: int) -> int:
+    """按表头 rowspan 覆盖范围扩展跳过行数。
+
+    跨页续表的第一行表头可能包含 rowspan。如果只跳过已匹配的首行，
+    被该 rowspan 覆盖的后续表头行会失去占位来源，合并后形成半截表头。
+    因此跳过重复表头时，需要覆盖所有由已跳过表头行跨行占据的行。
+    """
+    if header_count <= 0 or not rows:
+        return header_count
+
+    expanded_header_count = min(header_count, len(rows))
+    row_idx = 0
+    while row_idx < expanded_header_count:
+        row = rows[row_idx]
+        for cell in row.find_all(["td", "th"]):
+            rowspan = _rowspan(cell)
+            if rowspan > 1:
+                expanded_header_count = max(expanded_header_count, row_idx + rowspan)
+                expanded_header_count = min(expanded_header_count, len(rows))
+        row_idx += 1
+
+    return expanded_header_count
+
+
+def can_merge_by_structure(
+    current_state: TableMergeState,
+    previous_state: TableMergeState,
+    current_bbox: Any = None,
+    previous_bbox: Any = None,
+) -> bool:
+    """仅基于表格结构判断是否可合并（不检查 caption/footnote）。
+
+    供外部工具调用，忽略 caption 和 footnote 检查。
+    """
+    if (
+        current_bbox is not None
+        and previous_bbox is not None
+        and not _table_widths_are_compatible(
+            current_bbox,
+            previous_bbox,
+        )
+    ):
+        return False
+
+    if (
+        previous_state.total_cols <= 0
+        or current_state.total_cols <= 0
+        or previous_state.last_data_row_metrics is None
+        or current_state.last_data_row_metrics is None
+    ):
+        return False
+
+    if previous_state.total_cols == current_state.total_cols:
+        return True
+
+    return check_rows_match(previous_state, current_state)
+
+
+def _table_widths_are_compatible(current_bbox: Any, previous_bbox: Any) -> bool:
+    """使用千分位 bbox 判断两张表的宽度相对差是否小于百分之十。"""
+    current_calc_bbox = _bbox_for_calculation(current_bbox)
+    previous_calc_bbox = _bbox_for_calculation(previous_bbox)
+    if current_calc_bbox is None or previous_calc_bbox is None:
+        return False
+
+    current_width = current_calc_bbox[2] - current_calc_bbox[0]
+    previous_width = previous_calc_bbox[2] - previous_calc_bbox[0]
+    min_width = min(current_width, previous_width)
+    return min_width > 0 and abs(current_width - previous_width) / min_width < 0.1
+
+
+def can_merge_tables(current_state: TableMergeState, previous_state: TableMergeState) -> bool:
+    """根据 dict 表格的辅助文本、宽度和 HTML 结构判断是否可合并。"""
+    current_table_block = current_state.owner_block
+    previous_table_block = previous_state.owner_block
+
+    if not isinstance(previous_table_block, dict) or not isinstance(current_table_block, dict):
+        return False
+
+    previous_children = _table_children(previous_table_block)
+    current_children = _table_children(current_table_block)
+    footnote_count = sum(1 for block in previous_children if block.get("type") == BlockType.TABLE_FOOTNOTE)
+    caption_blocks = [block for block in current_children if block.get("type") == BlockType.TABLE_CAPTION]
+    merge_caption_blocks = [
+        block for block in caption_blocks if not _is_post_table_non_continuation_caption(current_table_block, block)
+    ]
+    if merge_caption_blocks:
+        has_continuation_marker = any(_is_continuation_caption(block) for block in merge_caption_blocks)
+
+        if not has_continuation_marker:
+            return False
+
+        if footnote_count > 1:
+            return False
+    elif footnote_count > 0:
+        return False
+
+    if not _table_widths_are_compatible(current_table_block.get("bbox"), previous_table_block.get("bbox")):
+        return False
+
+    return can_merge_by_structure(current_state, previous_state)
+
+
+def check_rows_match(previous_state: TableMergeState, current_state: TableMergeState) -> bool:
+    """检查表格边界行是否匹配."""
+    last_row_metrics = previous_state.last_data_row_metrics
+    if last_row_metrics is None:
+        return False
+
+    header_count, _, _ = detect_table_headers(previous_state, current_state)
+    header_count = _expand_header_count_by_rowspan(current_state.rows, header_count)
+    first_data_row_metrics = current_state.front_first_data_row_metrics.get(header_count)
+    if first_data_row_metrics is None:
+        return False
+
+    previous_rendered_segments = calculate_row_rendered_segments(previous_state.rows, last_row_metrics.row_idx)
+    current_rendered_segments = calculate_row_rendered_segments(current_state.rows, first_data_row_metrics.row_idx)
+
+    return (
+        last_row_metrics.effective_cols == first_data_row_metrics.effective_cols
+        or last_row_metrics.actual_cols == first_data_row_metrics.actual_cols
+        or previous_rendered_segments == current_rendered_segments
+    )
+
+
+def check_row_columns_match(row1: Tag, row2: Tag) -> bool:
+    """判断两行显式单元格数量与 colspan 结构是否一致。"""
+    cells1 = row1.find_all(["td", "th"])
+    cells2 = row2.find_all(["td", "th"])
+    if len(cells1) != len(cells2):
+        return False
+    for cell1, cell2 in zip(cells1, cells2):
+        colspan1 = _colspan(cell1)
+        colspan2 = _colspan(cell2)
+        if colspan1 != colspan2:
+            return False
+    return True

docvortex/content/tree.py

@@ -0,0 +1,5 @@
+"""严格文档树的公共遍历能力。"""
+
+from ..schema import _iter_child_blocks as iter_child_blocks
+
+__all__ = ["iter_child_blocks"]

docvortex/document/__init__.py

@@ -0,0 +1,3 @@
+"""DocVortex 模块边界。"""
+
+__all__ = []

docvortex/document/contracts.py

@@ -0,0 +1,22 @@
+"""HTML Flash 解析使用的来源上下文契约。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from docvortex.foundation.type_identity import preserve_type_module
+
+
+@dataclass(frozen=True, slots=True)
+class HtmlSourceContext:
+    """保存相对链接解析及 HTML 解码所需的来源上下文。"""
+
+    source_uri: str | None = None
+    local_resource_root: Path | None = None
+    transport_encoding: str | None = None
+
+
+__all__ = ["HtmlSourceContext"]
+
+# 保持既有公开类型的 pickle 路径，所有旧、新入口指向同一个类。
+preserve_type_module(HtmlSourceContext, "docvortex.analyzers.native.html.contracts")

docvortex/document/detection.py

@@ -0,0 +1,389 @@
+"""根据文件内容和容器结构识别 DocVortex 支持的输入后缀。"""
+
+from __future__ import annotations
+
+from io import BytesIO
+from functools import lru_cache
+from pathlib import Path
+from xml.etree import ElementTree
+from zipfile import BadZipFile, ZipFile
+
+from loguru import logger
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from magika import Magika
+
+from .filetypes import CSV_EXTENSIONS, HTML_EXTENSIONS, IMAGE_EXTENSIONS, rtf_header_offset
+
+PDF_SIG_BYTES = b"%PDF"
+OLE2_SIG_BYTES = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+OOXML_ROOT_RELS = "_rels/.rels"
+OOXML_CONTENT_TYPES = "[Content_Types].xml"
+OOXML_PACKAGE_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+OOXML_CONTENT_TYPES_NS = "http://schemas.openxmlformats.org/package/2006/content-types"
+OOXML_OFFICE_DOCUMENT_REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument"
+OOXML_MAIN_CONTENT_TYPES = {
+    ("application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"): "docx",
+    ("application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml"): "pptx",
+    ("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"): "xlsx",
+}
+ODF_MIMETYPE_SUFFIXES = {
+    "application/vnd.oasis.opendocument.text": "odt",
+    "application/vnd.oasis.opendocument.spreadsheet": "ods",
+    "application/vnd.oasis.opendocument.presentation": "odp",
+}
+ODF_MANIFEST_PATH = "META-INF/manifest.xml"
+ODF_MANIFEST_NS = "urn:oasis:names:tc:opendocument:xmlns:manifest:1.0"
+# OLE2 compound file 内部 stream 名 → 旧 Office 格式后缀
+# doc: WordDocument stream；xls: Workbook 或 Book stream；ppt: PowerPoint Document stream
+OLE2_STREAM_SUFFIX_MAP: dict[str, str] = {
+    "WordDocument": "doc",
+    "Workbook": "xls",
+    "Book": "xls",
+    "PowerPoint Document": "ppt",
+}
+_STRONG_CONTENT_SUFFIXES = frozenset(
+    {
+        "pdf",
+        "doc",
+        "docx",
+        "ppt",
+        "pptx",
+        "xls",
+        "xlsx",
+        "rtf",
+        "epub",
+        "ofd",
+        "odt",
+        "ods",
+        "odp",
+        *IMAGE_EXTENSIONS,
+    }
+)
+
+
+@lru_cache(maxsize=1)
+def _magika() -> Magika:
+    """惰性创建文件类型识别器，避免导入 parser 时加载模型。"""
+    from magika import Magika
+
+    return Magika()
+
+
+def _strip_package_part_name(part_name: str | None) -> str:
+    """规范化 OPC part 路径，方便匹配 Content_Types 中的 PartName。"""
+    if not part_name:
+        return ""
+    return part_name.replace("\\", "/").lstrip("/")
+
+
+def _ooxml_relationship_targets(root: ElementTree.Element) -> list[str]:
+    """从根关系文件中提取 Office 主文档关系目标。"""
+    targets = []
+    for relationship in root:
+        if relationship.tag not in {
+            f"{{{OOXML_PACKAGE_REL_NS}}}Relationship",
+            "Relationship",
+        }:
+            continue
+        if relationship.get("TargetMode") == "External":
+            continue
+        if relationship.get("Type") != OOXML_OFFICE_DOCUMENT_REL:
+            continue
+        target = _strip_package_part_name(relationship.get("Target"))
+        if target:
+            targets.append(target)
+    return targets
+
+
+def _ooxml_content_type_overrides(root: ElementTree.Element) -> dict[str, str]:
+    """读取 Content_Types 中每个显式 part 的 ContentType 映射。"""
+    overrides = {}
+    for override in root:
+        if override.tag not in {
+            f"{{{OOXML_CONTENT_TYPES_NS}}}Override",
+            "Override",
+        }:
+            continue
+        part_name = _strip_package_part_name(override.get("PartName"))
+        content_type = override.get("ContentType")
+        if part_name and content_type:
+            overrides[part_name] = content_type
+    return overrides
+
+
+def _guess_ooxml_suffix_from_zip(package: ZipFile) -> str | None:
+    """根据 OOXML 包内标准主文档关系和主内容类型判断 Office 子类型。"""
+    rels_root = ElementTree.fromstring(package.read(OOXML_ROOT_RELS))
+    content_types_root = ElementTree.fromstring(package.read(OOXML_CONTENT_TYPES))
+
+    overrides = _ooxml_content_type_overrides(content_types_root)
+    for target in _ooxml_relationship_targets(rels_root):
+        suffix = OOXML_MAIN_CONTENT_TYPES.get(overrides.get(target, ""))
+        if suffix:
+            return suffix
+    return None
+
+
+def _guess_ooxml_suffix_by_bytes(file_bytes: bytes) -> str | None:
+    """优先用 OOXML 包结构识别 docx/pptx/xlsx，避免 Magika 被内嵌对象误导。"""
+    try:
+        with ZipFile(BytesIO(file_bytes)) as package:
+            return _guess_ooxml_suffix_from_zip(package)
+    except (
+        BadZipFile,
+        KeyError,
+        ElementTree.ParseError,
+        RuntimeError,
+        OSError,
+        ValueError,
+    ):
+        return None
+
+
+def _guess_ooxml_suffix_by_path(file_path: Path) -> str | None:
+    """从文件路径读取 OOXML 包结构；失败时交给 Magika 原有逻辑兜底。"""
+    try:
+        with ZipFile(file_path) as package:
+            return _guess_ooxml_suffix_from_zip(package)
+    except (
+        BadZipFile,
+        KeyError,
+        ElementTree.ParseError,
+        RuntimeError,
+        OSError,
+        ValueError,
+    ):
+        return None
+
+
+def _guess_odf_suffix_from_zip(package: ZipFile) -> str | None:
+    """按 ODF mimetype、manifest 根条目依次识别 odt/ods/odp。"""
+    try:
+        mimetype_info = package.getinfo("mimetype")
+        if mimetype_info.file_size <= 256:
+            mimetype = package.read(mimetype_info).decode("ascii", errors="strict").strip()
+            if suffix := ODF_MIMETYPE_SUFFIXES.get(mimetype):
+                return suffix
+    except (KeyError, UnicodeDecodeError, RuntimeError, OSError, ValueError):
+        pass
+    try:
+        manifest_info = package.getinfo(ODF_MANIFEST_PATH)
+        if manifest_info.file_size > 1024 * 1024:
+            return None
+        root = ElementTree.fromstring(package.read(manifest_info))
+    except (KeyError, ElementTree.ParseError, RuntimeError, OSError, ValueError):
+        return None
+    for entry in root.iter(f"{{{ODF_MANIFEST_NS}}}file-entry"):
+        if entry.get(f"{{{ODF_MANIFEST_NS}}}full-path") != "/":
+            continue
+        media_type = entry.get(f"{{{ODF_MANIFEST_NS}}}media-type", "").strip()
+        return ODF_MIMETYPE_SUFFIXES.get(media_type)
+    return None
+
+
+def _guess_odf_suffix_by_bytes(file_bytes: bytes) -> str | None:
+    """从内存 ZIP 包识别 ODF，失败时不影响后续 OLE/Magika/CSV 路由。"""
+    try:
+        with ZipFile(BytesIO(file_bytes)) as package:
+            return _guess_odf_suffix_from_zip(package)
+    except (BadZipFile, RuntimeError, OSError, ValueError):
+        return None
+
+
+def _guess_odf_suffix_by_path(file_path: Path) -> str | None:
+    """从路径 ZIP 包识别 ODF，保持现有 OOXML 检测优先级。"""
+    try:
+        with ZipFile(file_path) as package:
+            return _guess_odf_suffix_from_zip(package)
+    except (BadZipFile, RuntimeError, OSError, ValueError):
+        return None
+
+
+def _guess_epub_suffix_by_bytes(file_bytes: bytes) -> str | None:
+    """从内存 ZIP 包验证 EPUB 强内容身份。"""
+    from ..analyzers.native.epub import detect_epub
+
+    return "epub" if detect_epub(file_bytes) else None
+
+
+def _guess_epub_suffix_by_path(file_path: Path) -> str | None:
+    """从路径 ZIP 包验证 EPUB 强内容身份。"""
+    from ..analyzers.native.epub import detect_epub_path
+
+    return "epub" if detect_epub_path(file_path) else None
+
+
+def _guess_ofd_suffix_by_bytes(file_bytes: bytes) -> str | None:
+    """从内存 ZIP 包验证 OFD 强内容身份。"""
+    from ..analyzers.native.ofd import detect_ofd
+
+    return "ofd" if detect_ofd(file_bytes) else None
+
+
+def _guess_ofd_suffix_by_path(file_path: Path) -> str | None:
+    """从路径 ZIP 包验证 OFD 强内容身份。"""
+    from ..analyzers.native.ofd import detect_ofd_path
+
+    return "ofd" if detect_ofd_path(file_path) else None
+
+
+def _guess_ole2_suffix_by_bytes(file_bytes: bytes) -> str | None:
+    """用 OLE2 magic + olefile 内部 stream 区分 doc/xls/ppt。
+
+    olefile 是纯 Python 库且已是核心依赖（mineru.model.flash.office.legacy 使用）。
+    在 OOXML 识别失败后、Magika 兜底前插入此层，避免 Magika 对 OLE2 返回 unknown。
+    """
+    if len(file_bytes) < 8 or file_bytes[:8] != OLE2_SIG_BYTES:
+        return None
+    try:
+        import olefile  # type: ignore[import-untyped]
+
+        with olefile.OleFileIO(BytesIO(file_bytes)) as ole:
+            for stream_name in ole.listdir(streams=True):
+                name = "/".join(stream_name)
+                suffix = OLE2_STREAM_SUFFIX_MAP.get(name)
+                if suffix:
+                    return suffix
+    except Exception:
+        return None
+    return None
+
+
+def _guess_ole2_suffix_by_path(file_path: Path) -> str | None:
+    """从文件路径读取 OLE2 容器并识别旧 Office 格式。"""
+    try:
+        with open(file_path, "rb") as f:
+            return _guess_ole2_suffix_by_bytes(f.read())
+    except OSError:
+        return None
+
+
+def _has_pdf_signature_by_path(file_path: Path) -> bool:
+    """读取文件头判断路径指向的内容是否具有 PDF 强签名。"""
+    try:
+        with open(file_path, "rb") as file:
+            return file.read(len(PDF_SIG_BYTES)) == PDF_SIG_BYTES
+    except OSError:
+        return False
+
+
+def _has_rtf_signature_by_path(file_path: Path) -> bool:
+    """读取有限文件头并按共享规则识别 RTF 根组。"""
+    try:
+        with open(file_path, "rb") as file:
+            return rtf_header_offset(file.read(128)) is not None
+    except OSError:
+        return False
+
+
+def _resolve_signatureless_csv_suffix(detected_suffix: str, file_path: str | Path | None) -> str:
+    """以 .csv/.tsv 扩展名兜底无签名分隔文本，并保留强内容类型的优先级。"""
+    extension = Path(file_path).suffix.lower().lstrip(".") if file_path else ""
+    if extension in CSV_EXTENSIONS:
+        if detected_suffix in _STRONG_CONTENT_SUFFIXES:
+            return detected_suffix
+        return "csv"
+    if detected_suffix == "csv":
+        if extension in ODF_MIMETYPE_SUFFIXES.values():
+            return "txt"
+        return extension or "txt"
+    return detected_suffix
+
+
+def _resolve_signatureless_html_suffix(detected_suffix: str, file_path: str | Path | None) -> str:
+    """用 HTML_EXTENSIONS 兜底短文本，并把 Magika 的 HTML 结果统一规范为 html。"""
+    extension = Path(file_path).suffix.lower().lstrip(".") if file_path else ""
+    if extension in HTML_EXTENSIONS and detected_suffix not in _STRONG_CONTENT_SUFFIXES:
+        return "html"
+    return "html" if detected_suffix == "html" else detected_suffix
+
+
+def _reject_unverified_package_suffix(detected_suffix: str) -> str:
+    """拒绝未通过包身份验证、仅由启发式工具猜出的 ODF/EPUB/OFD 类型。"""
+    package_suffixes = {*ODF_MIMETYPE_SUFFIXES.values(), "epub", "ofd"}
+    return "unknown" if detected_suffix in package_suffixes else detected_suffix
+
+
+def guess_suffix_by_bytes(file_bytes: bytes, file_path: str | None = None) -> str:
+    if file_bytes[: len(PDF_SIG_BYTES)] == PDF_SIG_BYTES:
+        return "pdf"
+    if rtf_header_offset(file_bytes[:128]) is not None:
+        return "rtf"
+
+    ofd_suffix = _guess_ofd_suffix_by_bytes(file_bytes)
+    if ofd_suffix:
+        return ofd_suffix
+
+    epub_suffix = _guess_epub_suffix_by_bytes(file_bytes)
+    if epub_suffix:
+        return epub_suffix
+
+    ooxml_suffix = _guess_ooxml_suffix_by_bytes(file_bytes)
+    if ooxml_suffix:
+        return ooxml_suffix
+
+    odf_suffix = _guess_odf_suffix_by_bytes(file_bytes)
+    if odf_suffix:
+        return odf_suffix
+
+    ole2_suffix = _guess_ole2_suffix_by_bytes(file_bytes)
+    if ole2_suffix:
+        return ole2_suffix
+
+    suffix = _magika().identify_bytes(file_bytes).prediction.output.label
+    if (
+        file_path
+        and suffix in ["ai", "html"]
+        and Path(file_path).suffix.lower() in [".pdf"]
+        and file_bytes[:4] == PDF_SIG_BYTES
+    ):
+        suffix = "pdf"
+    suffix = _resolve_signatureless_csv_suffix(_reject_unverified_package_suffix(suffix), file_path)
+    return _resolve_signatureless_html_suffix(suffix, file_path)
+
+
+def guess_suffix_by_path(file_path: str | Path) -> str:
+    if not isinstance(file_path, Path):
+        file_path = Path(file_path)
+
+    if _has_rtf_signature_by_path(file_path):
+        return "rtf"
+
+    ofd_suffix = _guess_ofd_suffix_by_path(file_path)
+    if ofd_suffix:
+        return ofd_suffix
+
+    epub_suffix = _guess_epub_suffix_by_path(file_path)
+    if epub_suffix:
+        return epub_suffix
+
+    ooxml_suffix = _guess_ooxml_suffix_by_path(file_path)
+    if ooxml_suffix:
+        return ooxml_suffix
+
+    odf_suffix = _guess_odf_suffix_by_path(file_path)
+    if odf_suffix:
+        return odf_suffix
+
+    ole2_suffix = _guess_ole2_suffix_by_path(file_path)
+    if ole2_suffix:
+        return ole2_suffix
+
+    if _has_pdf_signature_by_path(file_path):
+        return "pdf"
+
+    suffix = _magika().identify_path(file_path).prediction.output.label
+    if suffix in ["ai", "html"] and file_path.suffix.lower() in [".pdf"]:
+        try:
+            with open(file_path, "rb") as f:
+                if f.read(4) == PDF_SIG_BYTES:
+                    suffix = "pdf"
+        except Exception as e:
+            logger.warning(f"Failed to read file {file_path} for PDF signature check: {e}")
+    suffix = _resolve_signatureless_csv_suffix(_reject_unverified_package_suffix(suffix), file_path)
+    return _resolve_signatureless_html_suffix(suffix, file_path)
+
+
+__all__ = ["guess_suffix_by_bytes", "guess_suffix_by_path"]