OVAPortableText 0.1.0__py3-none-any.whl

ova_portable_text/__init__.py

@@ -0,0 +1,93 @@
+"""
+Public package exports for OVAPortableText.
+OVAPortableText 的公开导出入口。
+"""
+
+from .base import OvaBaseModel
+from .block_objects import BlockObject, CalloutBlock, ChartBlock, ImageBlock, MathBlock, TableBlock
+from .content import (
+    ALLOWED_DECORATOR_MARKS,
+    ALLOWED_TEXT_STYLES,
+    AnnotationMarkDef,
+    BlockElement,
+    ContentItem,
+    DecoratorMark,
+    LinkMarkDef,
+    ListItemStyle,
+    MarkDef,
+    Span,
+    TextBlock,
+    TextStyle,
+)
+from .document import Document, DocumentMeta
+from .exceptions import DocumentValidationError, ValidationIssue, ValidationReport
+from .helpers import (
+    annotation_def,
+    attachment_asset,
+    background_asset,
+    bibliography_entry,
+    blocks_from_items,
+    bullet_item,
+    callout,
+    chart_block,
+    citation_ref,
+    code_span,
+    create_document,
+    document,
+    em,
+    footnote_entry,
+    footnote_ref,
+    glossary_entry,
+    glossary_term,
+    hard_break,
+    icon_asset,
+    image_asset,
+    image_block,
+    link_def,
+    logo_asset,
+    marked,
+    math_block,
+    metric_dataset,
+    metric_value,
+    number_item,
+    paragraph,
+    pie_chart_dataset,
+    pie_chart_from_parallel_arrays,
+    pie_slice,
+    section,
+    span,
+    strong,
+    table_block,
+    table_column,
+    table_dataset,
+    underline,
+    xref,
+)
+from .inline import CitationRef, FootnoteRef, GlossaryTerm, HardBreak, InlineObject, XRef
+from .numbering import DocumentNumbering, NumberingConfig, NumberedTarget
+from .registry import (
+    AssetsRegistry,
+    AttachmentAsset,
+    BackgroundAsset,
+    BibliographyEntry,
+    DatasetsRegistry,
+    FootnoteEntry,
+    GlossaryEntry,
+    IconAsset,
+    ImageAsset,
+    LogoAsset,
+    MetricDataset,
+    MetricValue,
+    PieChartDataset,
+    PieSlice,
+    RegistryEntryBase,
+    TableColumn,
+    TableDataset,
+)
+from .resolver import DocumentResolver, ResolvedTarget
+from .section import Section
+from .theme import ThemeConfig
+from .validator import assert_valid_document, validate_document
+from .version import __version__
+
+__all__ = [name for name in globals() if not name.startswith("_")]

ova_portable_text/base.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+"""
+Base model infrastructure for OVAPortableText.
+OVAPortableText 的基础模型设施。
+
+This module contains the common base class used by almost all public models.
+本模块包含几乎所有公开模型都会继承的公共基类。
+"""
+
+from pathlib import Path
+from typing import Any, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+
+ModelT = TypeVar("ModelT", bound="OvaBaseModel")
+
+
+class OvaBaseModel(BaseModel):
+    """
+    Common base model for all OVAPortableText models.
+    OVAPortableText 所有模型共用的基础类。
+
+    Design goals / 设计目标：
+    1. Forbid unexpected fields by default, so protocol mistakes are caught early.
+       默认禁止未声明字段，尽早暴露协议拼写或结构错误。
+    2. Allow population by alias, because Portable Text uses `_type`.
+       允许通过别名赋值，因为 Portable Text 使用 `_type` 这类字段。
+    3. Provide convenient export helpers for dict / JSON output.
+       提供统一的 dict / JSON 导出辅助方法。
+    4. Provide round-trip helpers used by this package's document-builder workflow.
+       提供 round-trip 辅助方法，便于本包的“生成 → 导出 → 读回”工作流。
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    def to_dict(self, *, exclude_none: bool = True) -> dict[str, Any]:
+        """
+        Export the model as a plain Python dictionary.
+        将模型导出为普通 Python 字典。
+
+        Args:
+            exclude_none:
+                Whether to omit fields whose value is None.
+                是否忽略值为 None 的字段。
+
+        Returns:
+            A JSON-serializable dictionary using protocol aliases.
+            一个可直接 JSON 序列化、并使用协议别名字段的字典。
+        """
+        return self.model_dump(by_alias=True, exclude_none=exclude_none)
+
+    def to_json(
+        self,
+        *,
+        indent: int | None = 2,
+        exclude_none: bool = True,
+    ) -> str:
+        """
+        Export the model as a JSON string.
+        将模型导出为 JSON 字符串。
+
+        Args:
+            indent:
+                JSON indentation width.
+                JSON 缩进宽度。
+            exclude_none:
+                Whether to omit fields whose value is None.
+                是否忽略值为 None 的字段。
+
+        Returns:
+            A JSON string using protocol aliases.
+            一个使用协议别名字段的 JSON 字符串。
+        """
+        return self.model_dump_json(by_alias=True, exclude_none=exclude_none, indent=indent)
+
+    def save_json(
+        self,
+        path: str | Path,
+        *,
+        indent: int | None = 2,
+        exclude_none: bool = True,
+        encoding: str = "utf-8",
+    ) -> Path:
+        """
+        Save the current model as a JSON file.
+        将当前模型保存为 JSON 文件。
+
+        Why add file I/O at the base-model layer?
+        为什么把文件读写能力放在基础模型层？
+        Because package users often need a very practical workflow:
+        因为本包用户经常需要一个非常实用的工作流：
+        - build the document in Python / 在 Python 中构建文档
+        - save the JSON to disk / 把 JSON 落盘
+        - hand the file to Java or inspect it manually / 交给 Java 或手工检查
+        - reload it later for debugging or regression tests / 后续再读回做调试或回归测试
+
+        Args:
+            path:
+                Output file path.
+                输出文件路径。
+            indent:
+                JSON indentation width.
+                JSON 缩进宽度。
+            exclude_none:
+                Whether to omit fields whose value is None.
+                是否忽略值为 None 的字段。
+            encoding:
+                Text encoding used when writing the file.
+                写文件时使用的文本编码。
+
+        Returns:
+            The normalized ``Path`` object that was written.
+            实际写入的标准化 ``Path`` 对象。
+        """
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(
+            self.to_json(indent=indent, exclude_none=exclude_none),
+            encoding=encoding,
+        )
+        return target
+
+    @classmethod
+    def load_json(
+        cls: type[ModelT],
+        path: str | Path,
+        *,
+        encoding: str = "utf-8",
+    ) -> ModelT:
+        """
+        Read a JSON file from disk and rebuild the model.
+        从磁盘读取 JSON 文件并重建模型。
+
+        This is the file-based counterpart of ``from_json``.
+        这是 ``from_json`` 的文件版对应方法。
+        """
+        source = Path(path)
+        return cls.from_json(source.read_text(encoding=encoding))
+
+    @classmethod
+    def from_dict(cls: type[ModelT], data: dict[str, Any]) -> ModelT:
+        """
+        Rebuild a model object from a Python dictionary.
+        从 Python 字典重建模型对象。
+
+        Why provide this helper when Pydantic already has `model_validate`?
+        为什么在已有 `model_validate` 的情况下还要封装这个 helper？
+        Because package users often think in terms of:
+        因为本包用户更容易按下面的心智理解：
+        - `to_dict()` / 导出 dict
+        - `from_dict()` / 再从 dict 读回
+
+        This makes the round-trip API more discoverable.
+        这样 round-trip API 会更直观、更容易发现。
+        """
+        return cls.model_validate(data)
+
+    @classmethod
+    def from_json(cls: type[ModelT], json_text: str | bytes | bytearray) -> ModelT:
+        """
+        Rebuild a model object from a JSON string / bytes payload.
+        从 JSON 字符串 / 字节串重建模型对象。
+        """
+        return cls.model_validate_json(json_text)

ova_portable_text/block_objects.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+"""
+Block-object models for OVAPortableText.
+OVAPortableText 的块级对象模型。
+
+In the protocol, these block objects can appear inside `content.blocks[]`
+alongside normal text blocks in reading order.
+根据协议，这些块级对象可以和普通文本块一起，按阅读顺序出现在 `content.blocks[]` 中。
+
+This module covers the first batch of block objects:
+本模块覆盖第一批块级对象：
+- image
+- chart
+- table
+- math_block
+- callout
+"""
+
+from typing import Literal, TypeAlias
+
+from pydantic import Field, model_validator
+
+from .base import OvaBaseModel
+from .text import TextBlock
+
+
+class ReferenceableBlockBase(OvaBaseModel):
+    """
+    Common base for block objects that may become cross-reference targets.
+    可作为交叉引用目标的块级对象公共基类。
+
+    Most visual objects in the body should have:
+    正文中的大多数可视对象都应该具备：
+    - `id`: instance identity in the body / 正文实例身份
+    - `anchor`: anchor used by renderer / 渲染侧锚点
+
+    Design note / 设计说明：
+    `id` here belongs to the body instance, not the underlying registry entry.
+    这里的 `id` 属于正文实例本身，不是底层 registry 条目 ID。
+    """
+
+    id: str
+    anchor: str | None = None
+
+    @model_validator(mode="after")
+    def set_default_anchor(self) -> "ReferenceableBlockBase":
+        """
+        Reuse `id` as default anchor when anchor is omitted.
+        当未提供 anchor 时，默认复用 `id`。
+        """
+        if self.anchor is None:
+            self.anchor = self.id
+        return self
+
+
+class ImageBlock(ReferenceableBlockBase):
+    """
+    Body image instance.
+    正文中的图片实例。
+
+    `imageRef` points to an entry in `assets.images`.
+    `imageRef` 指向 `assets.images` 中的图片资源条目。
+    """
+
+    type_: Literal["image"] = Field(default="image", alias="_type", serialization_alias="_type")
+    imageRef: str
+
+
+class ChartBlock(ReferenceableBlockBase):
+    """
+    Body chart instance.
+    正文中的图表实例。
+
+    `chartRef` points to an entry in `datasets.charts`.
+    `chartRef` 指向 `datasets.charts` 中的图表数据条目。
+    """
+
+    type_: Literal["chart"] = Field(default="chart", alias="_type", serialization_alias="_type")
+    chartRef: str
+
+
+class TableBlock(ReferenceableBlockBase):
+    """
+    Body table instance.
+    正文中的表格实例。
+
+    `tableRef` points to an entry in `datasets.tables`.
+    `tableRef` 指向 `datasets.tables` 中的表格数据条目。
+    """
+
+    type_: Literal["table"] = Field(default="table", alias="_type", serialization_alias="_type")
+    tableRef: str
+
+
+class MathBlock(ReferenceableBlockBase):
+    """
+    Embedded LaTeX math block.
+    内嵌 LaTeX 公式块。
+
+    Current v1 decision / 当前 v1 决策：
+    we directly embed `latex` inside the body object.
+    当前直接在正文对象里内嵌 `latex`。
+    """
+
+    type_: Literal["math_block"] = Field(default="math_block", alias="_type", serialization_alias="_type")
+    latex: str
+
+
+class CalloutBlock(ReferenceableBlockBase):
+    """
+    Callout block containing its own text blocks.
+    带自有文本块数组的 callout 块。
+
+    Boundary / 边界：
+    `callout.blocks` reuses a restricted subset of the normal text-block rules.
+    `callout.blocks` 复用正文文本块规则的受限子集。
+
+    In this implementation we only allow `TextBlock` inside callout for clarity.
+    当前实现为了保持清晰，只允许 `TextBlock` 作为 callout 内部的 block。
+    """
+
+    type_: Literal["callout"] = Field(default="callout", alias="_type", serialization_alias="_type")
+    blocks: list[TextBlock] = Field(default_factory=list)
+
+    def append_block(self, block: TextBlock) -> "CalloutBlock":
+        """
+        Append a text block into the callout.
+        向 callout 中追加一个文本块。
+        """
+        self.blocks.append(block)
+        return self
+
+
+BlockObject: TypeAlias = ImageBlock | ChartBlock | TableBlock | MathBlock | CalloutBlock
+"""
+Union of all currently supported block objects.
+当前已支持的全部块级对象联合类型。
+"""

ova_portable_text/content.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+"""
+Body-content models for OVAPortableText.
+OVAPortableText 的正文内容模型。
+
+This module plays two roles:
+本模块承担两个角色：
+1. Define `ContentItem`, the body-item type for continuous content flow.
+   定义 `ContentItem`，即“连续内容流”对应的 body-item 类型。
+2. Re-export common text-layer classes for user convenience.
+   为了方便使用者导入，顺手重新导出常见文本层类。
+
+Why `ContentItem.blocks` is not text-only?
+为什么 `ContentItem.blocks` 不再只允许文本块？
+Because the protocol explicitly allows text blocks and object blocks to share
+one reading order inside the same content flow.
+因为协议明确允许文本块与块级对象共享同一内容流中的阅读顺序。
+"""
+
+from typing import Literal, TypeAlias
+
+from pydantic import Field
+
+from .base import OvaBaseModel
+from .block_objects import CalloutBlock, ChartBlock, ImageBlock, MathBlock, TableBlock
+from .text import (
+    ALLOWED_DECORATOR_MARKS,
+    ALLOWED_TEXT_STYLES,
+    AnnotationMarkDef,
+    DecoratorMark,
+    LinkMarkDef,
+    ListItemStyle,
+    MarkDef,
+    Span,
+    TextBlock,
+    TextChild,
+    TextStyle,
+)
+
+BlockElement: TypeAlias = TextBlock | ImageBlock | ChartBlock | TableBlock | MathBlock | CalloutBlock
+"""
+Any block-level element allowed inside `content.blocks[]`.
+`content.blocks[]` 中允许出现的任意块级元素类型。
+"""
+
+
+class ContentItem(OvaBaseModel):
+    """
+    One continuous content-flow body item.
+    一个连续内容流 body item。
+
+    A section body may contain multiple `ContentItem`s and `SubsectionItem`s.
+    一个 section 的 body 中可以混排多个 `ContentItem` 与 `SubsectionItem`。
+    """
+
+    itemType: Literal["content"] = "content"
+    blocks: list[BlockElement] = Field(default_factory=list)
+
+    def append_block(self, block: BlockElement) -> "ContentItem":
+        """
+        Append one block-level element.
+        追加一个块级元素。
+        """
+        self.blocks.append(block)
+        return self
+
+    def append_text_block(self, block: TextBlock) -> "ContentItem":
+        """
+        Explicit helper for appending a text block.
+        针对文本块的显式追加辅助方法。
+        """
+        self.blocks.append(block)
+        return self