docvortex 0.2.1__py3-none-any.whl

docvortex/render/api.py

@@ -0,0 +1,199 @@
+"""严格 MiddleJson 多格式渲染的统一公共入口。"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, overload
+
+from ..schema import MiddleJson
+
+from .contracts import (
+    DocxRenderOptions,
+    EpubRenderOptions,
+    HtmlRenderOptions,
+    LatexRenderOptions,
+    MarkdownRenderOptions,
+    PdfRenderOptions,
+    RenderFormat,
+    RenderOptions,
+    RenderOutput,
+    StructuredContentRenderOptions,
+)
+from .docx import render_docx
+from .epub import render_epub
+from .html import render_html
+from .latex import render_latex
+from .markdown import render_markdown
+from .pdf import render_pdf
+from .structured_content import render_structured_content
+
+
+@overload
+def render(
+    middle_json: MiddleJson,
+    output_format: Literal[RenderFormat.MARKDOWN],
+    *,
+    options: MarkdownRenderOptions | None = None,
+) -> str:
+    """声明 Markdown 目标对应的字符串返回类型。"""
+    ...
+
+
+@overload
+def render(
+    middle_json: MiddleJson,
+    output_format: Literal[RenderFormat.HTML],
+    *,
+    options: HtmlRenderOptions | None = None,
+) -> str:
+    """声明 HTML 目标对应的字符串返回类型。"""
+    ...
+
+
+@overload
+def render(
+    middle_json: MiddleJson,
+    output_format: Literal[RenderFormat.LATEX],
+    *,
+    options: LatexRenderOptions | None = None,
+) -> str:
+    """声明 LaTeX 目标对应的字符串返回类型。"""
+    ...
+
+
+@overload
+def render(
+    middle_json: MiddleJson,
+    output_format: Literal[RenderFormat.DOCX],
+    *,
+    options: DocxRenderOptions | None = None,
+) -> bytes:
+    """声明 DOCX 目标对应的字节返回类型。"""
+    ...
+
+
+@overload
+def render(
+    middle_json: MiddleJson,
+    output_format: Literal[RenderFormat.EPUB],
+    *,
+    options: EpubRenderOptions | None = None,
+) -> bytes:
+    """声明 EPUB 目标对应的字节返回类型。"""
+    ...
+
+
+@overload
+def render(
+    middle_json: MiddleJson,
+    output_format: Literal[RenderFormat.PDF],
+    *,
+    options: PdfRenderOptions | None = None,
+) -> bytes:
+    """声明 PDF 目标对应的字节返回类型。"""
+    ...
+
+
+@overload
+def render(
+    middle_json: MiddleJson,
+    output_format: Literal[RenderFormat.STRUCTURED_CONTENT],
+    *,
+    options: StructuredContentRenderOptions | None = None,
+) -> dict[str, Any]:
+    """声明 Structured Content 目标对应的字典返回类型。"""
+    ...
+
+
+def render(
+    middle_json: MiddleJson,
+    output_format: RenderFormat,
+    *,
+    options: RenderOptions | None = None,
+) -> RenderOutput:
+    """按严格目标格式和对应选项把 MiddleJson 渲染为原生结果。"""
+    if not isinstance(middle_json, MiddleJson):
+        raise TypeError("render expects a MiddleJson instance")
+    if not isinstance(output_format, RenderFormat):
+        raise TypeError("output_format must be a RenderFormat value")
+
+    if output_format is RenderFormat.MARKDOWN:
+        resolved_options = options if options is not None else MarkdownRenderOptions()
+        if not isinstance(resolved_options, MarkdownRenderOptions):
+            raise TypeError("MARKDOWN output requires MarkdownRenderOptions")
+        return render_markdown(
+            middle_json,
+            latex_delimiters=resolved_options.latex_delimiters,
+            mode=resolved_options.mode,
+            asset_base_url=resolved_options.asset_base_url,
+            image_renderer=resolved_options.image_renderer,
+        )
+
+    if output_format is RenderFormat.HTML:
+        resolved_options = options if options is not None else HtmlRenderOptions()
+        if not isinstance(resolved_options, HtmlRenderOptions):
+            raise TypeError("HTML output requires HtmlRenderOptions")
+        return render_html(
+            middle_json,
+            mode=resolved_options.mode,
+            asset_base_url=resolved_options.asset_base_url,
+            standalone=resolved_options.standalone,
+            document_title=resolved_options.document_title,
+        )
+
+    if output_format is RenderFormat.LATEX:
+        resolved_options = options if options is not None else LatexRenderOptions()
+        if not isinstance(resolved_options, LatexRenderOptions):
+            raise TypeError("LATEX output requires LatexRenderOptions")
+        return render_latex(
+            middle_json,
+            asset_base_path=resolved_options.asset_base_path,
+            document_title=resolved_options.document_title,
+        )
+
+    if output_format is RenderFormat.DOCX:
+        resolved_options = options if options is not None else DocxRenderOptions()
+        if not isinstance(resolved_options, DocxRenderOptions):
+            raise TypeError("DOCX output requires DocxRenderOptions")
+        return render_docx(
+            middle_json,
+            asset_resolver=resolved_options.asset_resolver,
+        )
+
+    if output_format is RenderFormat.EPUB:
+        resolved_options = options if options is not None else EpubRenderOptions()
+        if not isinstance(resolved_options, EpubRenderOptions):
+            raise TypeError("EPUB output requires EpubRenderOptions")
+        return render_epub(
+            middle_json,
+            title=resolved_options.title,
+            authors=resolved_options.authors,
+            language=resolved_options.language,
+            identifier=resolved_options.identifier,
+            modified_at=resolved_options.modified_at,
+            asset_resolver=resolved_options.asset_resolver,
+        )
+
+    if output_format is RenderFormat.PDF:
+        resolved_options = options if options is not None else PdfRenderOptions()
+        if not isinstance(resolved_options, PdfRenderOptions):
+            raise TypeError("PDF output requires PdfRenderOptions")
+        return render_pdf(
+            middle_json,
+            asset_resolver=resolved_options.asset_resolver,
+            document_title=resolved_options.document_title,
+        )
+
+    if output_format is RenderFormat.STRUCTURED_CONTENT:
+        resolved_options = options if options is not None else StructuredContentRenderOptions()
+        if not isinstance(resolved_options, StructuredContentRenderOptions):
+            raise TypeError("STRUCTURED_CONTENT output requires StructuredContentRenderOptions")
+        return render_structured_content(
+            middle_json,
+            latex_delimiters=resolved_options.latex_delimiters,
+            asset_base_url=resolved_options.asset_base_url,
+        )
+
+    raise ValueError(f"Unsupported RenderFormat: {output_format}")
+
+
+__all__ = ["render"]

docvortex/render/contracts.py

@@ -0,0 +1,205 @@
+"""MiddleJson 多格式 renderer 共用的公共类型与调用选项。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+import re
+from typing import Any, Callable, TypeAlias
+
+from ..schema import BlockBase
+from ..options import LatexDelimitersConfig
+
+
+class RenderFormat(str, Enum):
+    """统一渲染入口支持的目标格式。"""
+
+    MARKDOWN = "markdown"
+    HTML = "html"
+    LATEX = "latex"
+    DOCX = "docx"
+    EPUB = "epub"
+    STRUCTURED_CONTENT = "structured_content"
+    PDF = "pdf"
+
+
+class RenderMode(str, Enum):
+    """Markdown 与 HTML renderer 共用的默认合并视图与完整分页视图。"""
+
+    DEFAULT = "default"
+    FULL = "full"
+
+
+AssetResolver: TypeAlias = Callable[[str], bytes]
+ImageRenderer: TypeAlias = Callable[[BlockBase], str]
+
+
+def _validate_mode(mode: object) -> None:
+    """校验 Markdown 与 HTML renderer 的公共模式参数。"""
+    if not isinstance(mode, RenderMode):
+        raise TypeError("mode must be a RenderMode value")
+
+
+def _validate_asset_base_url(asset_base_url: object) -> None:
+    """校验用于拼接相对图片路径的资源根地址。"""
+    if not isinstance(asset_base_url, str):
+        raise TypeError("asset_base_url must be a string")
+
+
+@dataclass(frozen=True, slots=True)
+class MarkdownRenderOptions:
+    """Markdown renderer 的统一入口选项。"""
+
+    latex_delimiters: LatexDelimitersConfig | None = None
+
+    mode: RenderMode = RenderMode.DEFAULT
+    asset_base_url: str = ""
+    image_renderer: ImageRenderer | None = None
+
+    def __post_init__(self) -> None:
+        """在构造时拒绝不符合严格公共契约的选项值。"""
+        _validate_mode(self.mode)
+        _validate_asset_base_url(self.asset_base_url)
+        if self.image_renderer is not None and not callable(self.image_renderer):
+            raise TypeError("image_renderer must be callable or None")
+
+
+@dataclass(frozen=True, slots=True)
+class HtmlRenderOptions:
+    """HTML renderer 的统一入口选项。"""
+
+    mode: RenderMode = RenderMode.DEFAULT
+    asset_base_url: str = ""
+    standalone: bool = True
+    document_title: str | None = None
+
+    def __post_init__(self) -> None:
+        """在构造时校验 HTML 文档形态与标题选项。"""
+        _validate_mode(self.mode)
+        _validate_asset_base_url(self.asset_base_url)
+        if not isinstance(self.standalone, bool):
+            raise TypeError("standalone must be a bool")
+        if self.document_title is not None and not isinstance(self.document_title, str):
+            raise TypeError("document_title must be a string or None")
+
+
+@dataclass(frozen=True, slots=True)
+class LatexRenderOptions:
+    """LaTeX renderer 的统一入口选项。"""
+
+    asset_base_path: str = ""
+    document_title: str | None = None
+
+    def __post_init__(self) -> None:
+        """在构造时校验 LaTeX 素材路径前缀与文档标题。"""
+        if not isinstance(self.asset_base_path, str):
+            raise TypeError("asset_base_path must be a string")
+        if self.document_title is not None and not isinstance(self.document_title, str):
+            raise TypeError("document_title must be a string or None")
+
+
+@dataclass(frozen=True, slots=True)
+class DocxRenderOptions:
+    """DOCX renderer 的统一入口选项。"""
+
+    asset_resolver: AssetResolver | None = None
+
+    def __post_init__(self) -> None:
+        """在构造时校验可选素材解析器。"""
+        if self.asset_resolver is not None and not callable(self.asset_resolver):
+            raise TypeError("asset_resolver must be callable or None")
+
+
+_EPUB_LANGUAGE_RE = re.compile(r"(?:[A-Za-z]{2,8}|und)(?:-[A-Za-z0-9]{1,8})*\Z", re.IGNORECASE)
+
+
+@dataclass(frozen=True, slots=True)
+class EpubRenderOptions:
+    """EPUB 3.3 renderer 的统一入口选项。"""
+
+    title: str | None = None
+    authors: tuple[str, ...] = ()
+    language: str = "und"
+    identifier: str | None = None
+    modified_at: datetime | None = None
+    asset_resolver: AssetResolver | None = None
+
+    def __post_init__(self) -> None:
+        """在构造时校验 EPUB 元数据、时间与素材解析器。"""
+        if self.title is not None and (not isinstance(self.title, str) or not self.title.strip()):
+            raise TypeError("title must be a non-empty string or None")
+        if not isinstance(self.authors, tuple) or any(
+            not isinstance(author, str) or not author.strip() for author in self.authors
+        ):
+            raise TypeError("authors must be a tuple of non-empty strings")
+        if not isinstance(self.language, str) or _EPUB_LANGUAGE_RE.fullmatch(self.language.strip()) is None:
+            raise ValueError("language must be a supported BCP 47 language tag")
+        if self.identifier is not None and (not isinstance(self.identifier, str) or not self.identifier.strip()):
+            raise TypeError("identifier must be a non-empty string or None")
+        if self.modified_at is not None:
+            if not isinstance(self.modified_at, datetime):
+                raise TypeError("modified_at must be a datetime or None")
+            if self.modified_at.utcoffset() is None:
+                raise ValueError("modified_at must be timezone-aware")
+            if self.modified_at.year < 1000:
+                raise ValueError("modified_at year must use four digits")
+        if self.asset_resolver is not None and not callable(self.asset_resolver):
+            raise TypeError("asset_resolver must be callable or None")
+
+
+@dataclass(frozen=True, slots=True)
+class PdfRenderOptions:
+    """PDF renderer 的统一入口选项。"""
+
+    asset_resolver: AssetResolver | None = None
+    document_title: str | None = None
+
+    def __post_init__(self) -> None:
+        """在构造时校验素材解析器与文档标题。"""
+        if self.asset_resolver is not None and not callable(self.asset_resolver):
+            raise TypeError("asset_resolver must be callable or None")
+        if self.document_title is not None and not isinstance(self.document_title, str):
+            raise TypeError("document_title must be a string or None")
+
+
+@dataclass(frozen=True, slots=True)
+class StructuredContentRenderOptions:
+    """树形 Markdown Structured Content renderer 的统一入口选项。"""
+
+    latex_delimiters: LatexDelimitersConfig | None = None
+
+    asset_base_url: str = ""
+
+    def __post_init__(self) -> None:
+        """在构造时校验图片资源根地址。"""
+        _validate_asset_base_url(self.asset_base_url)
+
+
+RenderOptions: TypeAlias = (
+    MarkdownRenderOptions
+    | HtmlRenderOptions
+    | LatexRenderOptions
+    | DocxRenderOptions
+    | EpubRenderOptions
+    | PdfRenderOptions
+    | StructuredContentRenderOptions
+)
+RenderOutput: TypeAlias = str | bytes | dict[str, Any]
+
+
+__all__ = [
+    "AssetResolver",
+    "DocxRenderOptions",
+    "EpubRenderOptions",
+    "HtmlRenderOptions",
+    "ImageRenderer",
+    "LatexRenderOptions",
+    "MarkdownRenderOptions",
+    "PdfRenderOptions",
+    "RenderFormat",
+    "RenderMode",
+    "RenderOptions",
+    "RenderOutput",
+    "StructuredContentRenderOptions",
+]

docvortex/render/docx.py

@@ -0,0 +1,38 @@
+"""严格 MiddleJson 到 DOCX 的轻量公共门面与稳定异常。"""
+
+from __future__ import annotations
+
+from ..schema import MiddleJson
+from .contracts import AssetResolver
+
+
+class DocxRenderError(RuntimeError):
+    """表示 renderer 无法在不丢失必需内容的前提下生成 DOCX。"""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        page_idx: int,
+        block_index: int | None,
+        block_type: str,
+    ) -> None:
+        """保存错误消息及稳定的 page/block 定位字段。"""
+        self.page_idx = page_idx
+        self.block_index = block_index
+        self.block_type = block_type
+        super().__init__(f"{message} (page_idx={page_idx}, block_index={block_index}, block_type={block_type})")
+
+
+def render_docx(
+    middle_json: MiddleJson,
+    *,
+    asset_resolver: AssetResolver | None = None,
+) -> bytes:
+    """惰性加载 DOCX 实现并渲染严格 MiddleJson。"""
+    from ._internal.docx.renderer import render_docx as _render_docx
+
+    return _render_docx(middle_json, asset_resolver=asset_resolver)
+
+
+__all__ = ["DocxRenderError", "render_docx"]

docvortex/render/epub.py

@@ -0,0 +1,35 @@
+"""严格 MiddleJson 到 EPUB 3.3 的轻量公共门面。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from ..schema import MiddleJson
+from .contracts import AssetResolver
+
+
+def render_epub(
+    middle_json: MiddleJson,
+    *,
+    title: str | None = None,
+    authors: tuple[str, ...] = (),
+    language: str = "und",
+    identifier: str | None = None,
+    modified_at: datetime | None = None,
+    asset_resolver: AssetResolver | None = None,
+) -> bytes:
+    """惰性加载 EPUB 实现并返回完整 EPUB 3.3 容器字节。"""
+    from ._internal.epub.renderer import render_epub as _render_epub
+
+    return _render_epub(
+        middle_json,
+        title=title,
+        authors=authors,
+        language=language,
+        identifier=identifier,
+        modified_at=modified_at,
+        asset_resolver=asset_resolver,
+    )
+
+
+__all__ = ["render_epub"]

docvortex/render/fragments.py

@@ -0,0 +1,70 @@
+"""公开共享渲染片段操作，供宿主组合专用输出而不依赖私有模块。"""
+
+from __future__ import annotations
+
+from ..options import LatexDelimitersConfig
+from ..schema import ImagePayloadBlock, InlineSpan
+from ._internal.common.list_items import ListItem, ListItemKind, OrderedListStyle
+
+
+def render_inline_content(content: list[InlineSpan], delimiters: LatexDelimitersConfig) -> str:
+    """将行内语义编码为 Markdown，沿用共享的样式与公式规则。"""
+    from ._internal.markdown.inline import render_inline_content as render_value
+
+    return render_value(content, delimiters)
+
+
+def render_internal_link(label: str, anchor: str) -> str:
+    """构造与共享 Markdown renderer 一致的内部链接。"""
+    from ._internal.markdown.inline import render_internal_link as render_value
+
+    return render_value(label, anchor)
+
+
+def resolve_image_source(block: ImagePayloadBlock, asset_base_url: str = "") -> str | None:
+    """按既有素材优先级解析图片引用，不写出文件。"""
+    from ._internal.markdown.assets import resolve_image_source as resolve_value
+
+    return resolve_value(block, asset_base_url)
+
+
+def normalize_image_source(source: str) -> str:
+    """规范化素材路径，保持共享渲染器的 URL 与路径处理行为。"""
+    from ._internal.markdown.assets import normalize_image_source as normalize_value
+
+    return normalize_value(source)
+
+
+def format_embedded_html(markup: str, *, asset_base_url: str, delimiters: LatexDelimitersConfig) -> str:
+    """复用嵌入 HTML 的图片地址和公式分隔符处理。"""
+    from ._internal.markdown.table import format_embedded_html as format_value
+
+    return format_value(markup, asset_base_url=asset_base_url, delimiters=delimiters)
+
+
+def strip_index_page_tail(content: list[InlineSpan]) -> list[InlineSpan]:
+    """剥离目录尾部页码，保持行内样式和链接语义。"""
+    from ._internal.common.index import strip_index_page_tail as strip_value
+
+    return strip_value(content)
+
+
+def parse_list_item_marker(content: list[InlineSpan]) -> ListItem:
+    """解析列表标记并返回共享的不可变条目描述。"""
+    from ._internal.common.list_items import parse_list_item_marker as parse_value
+
+    return parse_value(content)
+
+
+__all__ = [
+    "ListItem",
+    "ListItemKind",
+    "OrderedListStyle",
+    "render_inline_content",
+    "render_internal_link",
+    "resolve_image_source",
+    "normalize_image_source",
+    "format_embedded_html",
+    "strip_index_page_tail",
+    "parse_list_item_marker",
+]

docvortex/render/html.py

@@ -0,0 +1,29 @@
+"""严格 MiddleJson 到 HTML 的轻量公共门面。"""
+
+from __future__ import annotations
+
+from ..schema import MiddleJson
+from .contracts import RenderMode
+
+
+def render_html(
+    middle_json: MiddleJson,
+    *,
+    mode: RenderMode = RenderMode.DEFAULT,
+    asset_base_url: str = "",
+    standalone: bool = True,
+    document_title: str | None = None,
+) -> str:
+    """惰性加载 HTML 实现并渲染严格 MiddleJson。"""
+    from ._internal.html.renderer import render_html as _render_html
+
+    return _render_html(
+        middle_json,
+        mode=mode,
+        asset_base_url=asset_base_url,
+        standalone=standalone,
+        document_title=document_title,
+    )
+
+
+__all__ = ["render_html"]

docvortex/render/latex.py

@@ -0,0 +1,24 @@
+"""严格 MiddleJson 到 TeX Live LaTeX 源码的轻量公共门面。"""
+
+from __future__ import annotations
+
+from ..schema import MiddleJson
+
+
+def render_latex(
+    middle_json: MiddleJson,
+    *,
+    asset_base_path: str = "",
+    document_title: str | None = None,
+) -> str:
+    """惰性加载 LaTeX 实现并返回完整 UTF-8 文档源码。"""
+    from ._internal.latex.renderer import render_latex as _render_latex
+
+    return _render_latex(
+        middle_json,
+        asset_base_path=asset_base_path,
+        document_title=document_title,
+    )
+
+
+__all__ = ["render_latex"]

docvortex/render/markdown.py

@@ -0,0 +1,50 @@
+"""严格 MiddleJson 到 Markdown 的轻量公共门面。"""
+
+from __future__ import annotations
+
+from ..options import LatexDelimitersConfig
+from ..schema import MiddleJson, PageBlock
+from .contracts import ImageRenderer, RenderMode
+
+
+def render_markdown(
+    middle_json: MiddleJson,
+    *,
+    mode: RenderMode = RenderMode.DEFAULT,
+    asset_base_url: str = "",
+    image_renderer: ImageRenderer | None = None,
+    latex_delimiters: LatexDelimitersConfig | None = None,
+) -> str:
+    """惰性加载 Markdown 实现并渲染严格 MiddleJson。"""
+    from ._internal.markdown.renderer import render_markdown as _render_markdown
+
+    return _render_markdown(
+        middle_json,
+        latex_delimiters=latex_delimiters,
+        mode=mode,
+        asset_base_url=asset_base_url,
+        image_renderer=image_renderer,
+    )
+
+
+def render_single_block(
+    block: PageBlock,
+    *,
+    delimiters: LatexDelimitersConfig,
+    asset_base_url: str,
+    image_renderer: ImageRenderer | None = None,
+) -> str:
+    """为文档库等局部读取调用方渲染单个顶层块，不执行文档级合并。"""
+    from ._internal.markdown.blocks import render_single_block as render_block
+
+    return render_block(block, delimiters=delimiters, asset_base_url=asset_base_url, image_renderer=image_renderer)
+
+
+def build_markdown_image(source: str, alt: str = "") -> str:
+    """通过公开接口构造转义后的图片引用，避免调用方依赖 renderer 私有文件。"""
+    from ._internal.markdown.assets import build_markdown_image as build_image
+
+    return build_image(source, alt)
+
+
+__all__ = ["render_markdown", "render_single_block", "build_markdown_image"]

docvortex/render/pdf.py

@@ -0,0 +1,25 @@
+"""严格 MiddleJson 到 PDF bytes 的轻量公共门面。"""
+
+from __future__ import annotations
+
+from ..schema import MiddleJson
+from .contracts import AssetResolver
+
+
+def render_pdf(
+    middle_json: MiddleJson,
+    *,
+    asset_resolver: AssetResolver | None = None,
+    document_title: str | None = None,
+) -> bytes:
+    """惰性加载 PDF 实现并渲染严格 MiddleJson。"""
+    from ._internal.pdf.renderer import render_pdf as _render_pdf
+
+    return _render_pdf(
+        middle_json,
+        asset_resolver=asset_resolver,
+        document_title=document_title,
+    )
+
+
+__all__ = ["render_pdf"]