docvortex 0.2.1__py3-none-any.whl

docvortex/api.py

@@ -0,0 +1,180 @@
+"""独立文档引擎的分阶段 API 与完整转换入口。"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from io import BytesIO
+import json
+from pathlib import Path
+import time
+from typing import TYPE_CHECKING
+
+from .assets import AssetStore
+from .document.source import HtmlSourceContext, prepare_source
+from .result import AnalysisResult, Diagnostic, DocumentResult, ExportResult, RenderArtifact
+from .schema import DocumentMetadata, FileSuffix, MiddleJson, ModelJson, PageInfo, Producer
+from .version import __version__
+from .render.contracts import DocxRenderOptions, EpubRenderOptions, PdfRenderOptions, RenderFormat, RenderOptions
+
+if TYPE_CHECKING:
+    from .analyzers.native.contracts import NativeBinaryAnalyzer
+    from .document.pdf.document import PDFDocument
+
+
+def analyze(
+    source: str | Path | bytes | PDFDocument,
+    *,
+    file_suffix: FileSuffix | None = None,
+    page_range: str = "",
+    source_context: HtmlSourceContext | None = None,
+) -> AnalysisResult:
+    """执行原生分析，显式调用者选择不会被隐式分类或 OCR 改写。"""
+    from .analyzers.native import models
+
+    started = time.perf_counter()
+    prepared = prepare_source(source, file_suffix=file_suffix, page_range=page_range, source_context=source_context)
+    try:
+        if prepared.file_suffix == "pdf":
+            from .document.pdf.visuals import attach_visual_block_images_from_pdf
+
+            assert prepared.document is not None
+            pages = models.PdfModel().predict(prepared.document)
+            attach_visual_block_images_from_pdf(prepared.document, pages)
+        elif prepared.file_suffix == "html":
+            pages = models.HtmlModel().predict(BytesIO(prepared.data), source_context=prepared.source_context)
+        else:
+            model_types: dict[FileSuffix, type[NativeBinaryAnalyzer]] = {
+                "csv": models.CsvModel,
+                "epub": models.EpubModel,
+                "ofd": models.OfdModel,
+                "doc": models.DocModel,
+                "docx": models.DocxModel,
+                "ppt": models.PptModel,
+                "pptx": models.PptxModel,
+                "xls": models.XlsModel,
+                "xlsx": models.XlsxModel,
+                "rtf": models.RtfModel,
+                "odt": models.OdtModel,
+                "ods": models.OdsModel,
+                "odp": models.OdpModel,
+            }
+            pages = model_types[prepared.file_suffix]().predict(BytesIO(prepared.data))
+        model = ModelJson(
+            pages=pages,
+            page_index_map=prepared.page_index_map or [],
+            metadata=DocumentMetadata(
+                file_suffix=prepared.file_suffix, producer=Producer(name="docvortex", version=__version__)
+            ),
+        )
+        diagnostics = tuple(
+            Diagnostic("broken_page", "The selected PDF page could not be loaded", index)
+            for index in prepared.broken_page_indices
+        )
+        return AnalysisResult(model, diagnostics=diagnostics, elapsed_seconds=time.perf_counter() - started)
+    finally:
+        if prepared.owns_document and prepared.document is not None:
+            prepared.document.close()
+
+
+def postprocess(
+    analysis: AnalysisResult | ModelJson, *, assets: AssetStore | None = None, keep_model_json: bool = False
+) -> DocumentResult:
+    """执行确定性后处理并物化结果素材，智能增强由上层显式调用。"""
+    from .postprocess.document import model_json_to_middle_json
+    from .export.files import materialize_middle
+
+    if isinstance(analysis, AnalysisResult):
+        model, diagnostics = analysis.model_json, analysis.diagnostics
+        if assets is None:
+            assets = analysis.assets
+    else:
+        model, diagnostics = analysis, ()
+    middle = model_json_to_middle_json(model)
+    if model.page_index_map:
+        pages = {page.page_idx: page for page in middle.pages}
+        for diagnostic in diagnostics:
+            if diagnostic.code == "broken_page" and diagnostic.page_index is not None:
+                pages.setdefault(diagnostic.page_index, PageInfo(page_idx=diagnostic.page_index))
+        middle.pages = [pages[index] for index in sorted(pages)]
+    middle, result_assets = materialize_middle(middle, assets)
+    return DocumentResult(middle, result_assets, model if keep_model_json else None, diagnostics)
+
+
+def parse(
+    source: str | Path | bytes | PDFDocument,
+    *,
+    file_suffix: FileSuffix | None = None,
+    page_range: str = "",
+    source_context: HtmlSourceContext | None = None,
+    keep_model_json: bool = False,
+) -> DocumentResult:
+    """完成输入、分析及后处理，返回可脱离原文件使用的结果。"""
+    return postprocess(
+        analyze(source, file_suffix=file_suffix, page_range=page_range, source_context=source_context),
+        keep_model_json=keep_model_json,
+    )
+
+
+def render(
+    middle_json: MiddleJson,
+    output_format: RenderFormat | str,
+    *,
+    assets: AssetStore | None = None,
+    options: RenderOptions | None = None,
+) -> RenderArtifact:
+    """把同一语义文档编码为目标文件，返回值不产生文件系统副作用。"""
+    from .render.api import render as render_value
+    from .render._internal.common.context import owned_render_document
+    from .export.files import materialize_middle
+
+    target = RenderFormat(output_format)
+    middle, resolved_assets = materialize_middle(middle_json, assets)
+    resolver_options = {
+        RenderFormat.DOCX: DocxRenderOptions,
+        RenderFormat.EPUB: EpubRenderOptions,
+        RenderFormat.PDF: PdfRenderOptions,
+    }
+    if target in resolver_options:
+        if options is None:
+            options = resolver_options[target](asset_resolver=resolved_assets.__getitem__)
+        elif isinstance(options, resolver_options[target]) and options.asset_resolver is None:
+            options = replace(options, asset_resolver=resolved_assets.__getitem__)
+    with owned_render_document(middle):
+        value = render_value(middle, target, options=options)
+    if isinstance(value, bytes):
+        content = value
+    elif isinstance(value, str):
+        content = value.encode("utf-8")
+    else:
+        content = json.dumps(value, ensure_ascii=False, indent=2).encode("utf-8")
+    mime_types = {
+        RenderFormat.MARKDOWN: "text/markdown",
+        RenderFormat.HTML: "text/html",
+        RenderFormat.LATEX: "application/x-tex",
+        RenderFormat.DOCX: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        RenderFormat.EPUB: "application/epub+zip",
+        RenderFormat.PDF: "application/pdf",
+    }
+    packaged = target in resolver_options
+    return RenderArtifact(
+        content, target, mime_types.get(target, "application/json"), AssetStore() if packaged else resolved_assets
+    )
+
+
+def convert(
+    source: str | Path | bytes | PDFDocument,
+    output_path: str | Path,
+    *,
+    output_format: RenderFormat | str = RenderFormat.MARKDOWN,
+    file_suffix: FileSuffix | None = None,
+    page_range: str = "",
+    source_context: HtmlSourceContext | None = None,
+    options: RenderOptions | None = None,
+    overwrite: bool = False,
+) -> ExportResult:
+    """使用完整原生流程进行一次转换，并返回实际写出的文件路径。"""
+    result = parse(source, file_suffix=file_suffix, page_range=page_range, source_context=source_context)
+    return result.export(output_path, output_format=output_format, options=options, overwrite=overwrite)
+
+
+__all__ = ["analyze", "postprocess", "parse", "render", "convert"]

docvortex/assets/__init__.py

@@ -0,0 +1,5 @@
+"""文档素材的显式字节所有权与读取接口。"""
+
+from .store import AssetStore
+
+__all__ = ["AssetStore"]

docvortex/assets/store.py

@@ -0,0 +1,51 @@
+"""结果拥有的素材字节集合，所有路径均相对于输出目录。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from hashlib import sha256
+
+from ..foundation.image_payload import validate_image_sidecar_path
+
+
+class AssetStore(Mapping[str, bytes]):
+    """以稳定相对路径读取素材，并共享相同内容的字节对象。"""
+
+    def __init__(self, files: Mapping[str, bytes] | None = None) -> None:
+        """复制素材索引，调用者后续修改字典不会污染结果。"""
+        self._files: dict[str, bytes] = {}
+        self._content: dict[str, bytes] = {}
+        for path, payload in (files or {}).items():
+            self.add(path, payload)
+
+    def add(self, path: str, payload: bytes) -> None:
+        """校验相对路径并拒绝同名不同内容，避免覆盖现有素材。"""
+        path = validate_image_sidecar_path(path)
+        if not isinstance(payload, bytes):
+            raise TypeError("Asset payload must be bytes")
+        if path in self._files and self._files[path] != payload:
+            raise ValueError(f"Conflicting asset payload: {path}")
+        payload = self._content.setdefault(sha256(payload).hexdigest(), payload)
+        self._files[path] = payload
+
+    def __getitem__(self, path: str) -> bytes:
+        """按经过验证的相对路径解析素材，不读取宿主文件或网络。"""
+        return self._files[validate_image_sidecar_path(path)]
+
+    def __iter__(self) -> Iterator[str]:
+        """以登记顺序遍历素材路径。"""
+        return iter(self._files)
+
+    def __len__(self) -> int:
+        """返回素材引用数量。"""
+        return len(self._files)
+
+    def copy(self) -> AssetStore:
+        """建立独立索引并复用不可变字节。"""
+        copied = AssetStore()
+        copied._files = self._files.copy()
+        copied._content = self._content.copy()
+        return copied
+
+
+__all__ = ["AssetStore"]

docvortex/cli.py

@@ -0,0 +1,54 @@
+"""独立转换命令行，业务行为全部委托公开 API。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from .version import __version__
+
+
+@click.group(help="DocVortex: native multi-format document parsing and conversion.")
+@click.version_option(__version__)
+def main() -> None:
+    """提供独立文档引擎的命令行入口。"""
+
+
+@main.command("convert")
+@click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--output", "-o", required=True, type=click.Path(path_type=Path))
+@click.option(
+    "--format",
+    "output_format",
+    default="markdown",
+    show_default=True,
+    type=click.Choice(["markdown", "html", "latex", "docx", "epub", "pdf", "structured_content"]),
+)
+@click.option("--pages", "page_range", default="", help="PDF page selection: 1-5, r1, all.")
+@click.option("--overwrite", is_flag=True)
+def convert_command(source: Path, output: Path, output_format: str, page_range: str, overwrite: bool) -> None:
+    """转换原生文档并写出目标文件及所需素材。"""
+    from .api import convert
+
+    try:
+        result = convert(source, output, output_format=output_format, page_range=page_range, overwrite=overwrite)
+    except (ValueError, OSError) as error:
+        raise click.ClickException(str(error)) from error
+    click.echo(str(result.path))
+
+
+@main.command("classify")
+@click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+def classify_command(source: Path) -> None:
+    """显式判断 PDF 应使用文本解析还是 OCR，不启动任何推理。"""
+    from .document.pdf import PDFDocument
+
+    with PDFDocument(source.read_bytes()) as document:
+        click.echo(document.classify())
+
+
+__all__ = ["main"]
+
+if __name__ == "__main__":
+    main()

docvortex/codecs/__init__.py

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

docvortex/codecs/html/__init__.py

@@ -0,0 +1,22 @@
+"""DocVortex HTML v1 canonical wire 的轻量内部入口。"""
+
+from __future__ import annotations
+
+from lxml import etree  # type: ignore[reportMissingImports]
+
+from .resources import WireResourceContext
+from .contracts import DOCVORTEX_HTML_VERSION, WireDecodeResult
+
+
+def decode_docvortex_html_wire(body: etree._Element, resources: WireResourceContext) -> WireDecodeResult:
+    """只对 canonical v1 wire 精确解码，其余输入返回通用投影信号。"""
+    from .materializer import materialize_docvortex_html_wire
+    from .parser import parse_docvortex_html_wire
+
+    plan, fallback_reason = parse_docvortex_html_wire(body)
+    if plan is None:
+        return WireDecodeResult(None, fallback_reason)
+    return WireDecodeResult(materialize_docvortex_html_wire(plan, resources))
+
+
+__all__ = ["DOCVORTEX_HTML_VERSION", "WireDecodeResult", "decode_docvortex_html_wire"]

docvortex/codecs/html/contracts.py

@@ -0,0 +1,236 @@
+"""DocVortex HTML v1 canonical wire 的内部类型契约。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, TypeAlias, Union
+
+from lxml import etree  # type: ignore[reportMissingImports]
+
+from ...schema import BlockType
+
+
+DOCVORTEX_HTML_VERSION = "1"
+WIRE_BLOCK_CLASS = "docvortex-block"
+WIRE_DOCUMENT_CLASS = "docvortex-document"
+WIRE_INDEX_CLASS = "docvortex-index"
+WIRE_LIST_CONTENT_CLASS = "docvortex-list-content"
+WIRE_LIST_MARKER_CLASS = "docvortex-list-marker"
+WIRE_PAGE_BREAK_CLASS = "docvortex-page-break"
+WIRE_PAGE_CLASS = "docvortex-page"
+WIRE_VISUAL_BODY_CLASS = "docvortex-visual-body"
+WireRenderMode: TypeAlias = Literal["default", "full"]
+WireFallbackReason: TypeAlias = Literal["unsupported_version", "non_canonical_wire"]
+
+
+@dataclass(frozen=True, slots=True)
+class TextWireSpec:
+    """保存一个文本类顶层 block 的 canonical 节点与元数据。"""
+
+    wrapper: etree._Element
+    content_root: etree._Element
+    block_type: BlockType
+    page_idx: int
+    block_index: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class EquationWireSpec:
+    """保存一个行间公式或公式图片 carrier。"""
+
+    wrapper: etree._Element
+    content_root: etree._Element
+    page_idx: int
+    block_index: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationWireSpec:
+    """保存 visual caption/footnote 的 canonical 行内容器。"""
+
+    element: etree._Element
+    block_type: BlockType
+
+
+@dataclass(frozen=True, slots=True)
+class RichVisualBodyWireSpec:
+    """保存普通 image/chart body 的主图片与规范化富内容片段。"""
+
+    element: etree._Element
+    parent_type: BlockType
+    sub_type: str
+    primary_image: etree._Element | None
+    content_fragment: etree._Element | None
+
+
+@dataclass(frozen=True, slots=True)
+class FlowchartBodyWireSpec:
+    """保存 flowchart 源码与可选 raster fallback。"""
+
+    element: etree._Element
+    source_element: etree._Element
+    fallback_image: etree._Element | None
+
+
+@dataclass(frozen=True, slots=True)
+class TableBodyWireSpec:
+    """保存 table body 的唯一 canonical 载荷。"""
+
+    element: etree._Element
+    kind: Literal["empty", "html", "text", "image"]
+    payload_element: etree._Element | None
+
+
+@dataclass(frozen=True, slots=True)
+class CodeBodyWireSpec:
+    """保存 code/algorithm body 的唯一 canonical 内容载体。"""
+
+    element: etree._Element
+    kind: Literal["code", "algorithm"]
+    content_element: etree._Element
+
+
+VisualBodyWireSpec: TypeAlias = Union[
+    RichVisualBodyWireSpec,
+    FlowchartBodyWireSpec,
+    TableBodyWireSpec,
+    CodeBodyWireSpec,
+]
+VisualChildWireSpec: TypeAlias = Union[VisualBodyWireSpec, AnnotationWireSpec]
+
+
+@dataclass(frozen=True, slots=True)
+class VisualWireSpec:
+    """保存 visual 顶层 block 与已按 DOM 顺序解析的子节点。"""
+
+    wrapper: etree._Element
+    content_root: etree._Element
+    block_type: BlockType
+    page_idx: int
+    block_index: int | None
+    sub_type: str
+    guess_lang: str
+    children: tuple[VisualChildWireSpec, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ListLeafWireSpec:
+    """保存一个列表叶子的内容 carrier、marker 与公开类型。"""
+
+    block_type: BlockType
+    block_index: int | None
+    content_element: etree._Element | None
+    marker: str
+
+
+@dataclass(frozen=True, slots=True)
+class ListWireSpec:
+    """保存一个 canonical 列表及其递归子项。"""
+
+    element: etree._Element
+    block_index: int | None
+    ordered: bool
+    start: int
+    sub_type: str
+    classes: frozenset[str]
+    children: tuple[Union[ListLeafWireSpec, "ListWireSpec"], ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ListBlockWireSpec:
+    """保存顶层 ListBlock wrapper 与列表树。"""
+
+    wrapper: etree._Element
+    page_idx: int
+    block_index: int | None
+    root: ListWireSpec
+
+
+@dataclass(frozen=True, slots=True)
+class IndexLeafWireSpec:
+    """保存一个目录叶子的 canonical 内容 carrier 与元数据。"""
+
+    block_type: BlockType
+    block_index: int | None
+    content_element: etree._Element | None
+    anchor: str
+    level: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class IndexWireSpec:
+    """保存一个 canonical 目录列表及其递归子项。"""
+
+    element: etree._Element
+    block_index: int | None
+    children: tuple[Union[IndexLeafWireSpec, "IndexWireSpec"], ...]
+
+
+@dataclass(frozen=True, slots=True)
+class IndexBlockWireSpec:
+    """保存顶层 IndexBlock wrapper 与目录树。"""
+
+    wrapper: etree._Element
+    page_idx: int
+    block_index: int | None
+    root: IndexWireSpec
+
+
+PageWireSpec: TypeAlias = Union[
+    TextWireSpec,
+    EquationWireSpec,
+    VisualWireSpec,
+    ListBlockWireSpec,
+    IndexBlockWireSpec,
+]
+
+
+@dataclass(frozen=True, slots=True)
+class DocVortexHtmlWirePlan:
+    """保存一次无资源副作用的完整 canonical wire 解析结果。"""
+
+    root: etree._Element
+    render_mode: WireRenderMode
+    blocks: tuple[PageWireSpec, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class WireDecodeResult:
+    """区分未命中 wire、精确解码成功与需要通用回退。"""
+
+    blocks: list[dict[str, object]] | None
+    fallback_reason: WireFallbackReason | None = None
+
+
+__all__ = [
+    "AnnotationWireSpec",
+    "CodeBodyWireSpec",
+    "EquationWireSpec",
+    "FlowchartBodyWireSpec",
+    "IndexBlockWireSpec",
+    "IndexLeafWireSpec",
+    "IndexWireSpec",
+    "ListBlockWireSpec",
+    "ListLeafWireSpec",
+    "ListWireSpec",
+    "DOCVORTEX_HTML_VERSION",
+    "DocVortexHtmlWirePlan",
+    "PageWireSpec",
+    "RichVisualBodyWireSpec",
+    "TableBodyWireSpec",
+    "TextWireSpec",
+    "VisualBodyWireSpec",
+    "VisualChildWireSpec",
+    "VisualWireSpec",
+    "WireDecodeResult",
+    "WireFallbackReason",
+    "WireRenderMode",
+    "WIRE_BLOCK_CLASS",
+    "WIRE_DOCUMENT_CLASS",
+    "WIRE_INDEX_CLASS",
+    "WIRE_LIST_CONTENT_CLASS",
+    "WIRE_LIST_MARKER_CLASS",
+    "WIRE_PAGE_BREAK_CLASS",
+    "WIRE_PAGE_CLASS",
+    "WIRE_VISUAL_BODY_CLASS",
+]