OVAPortableText 0.1.0__py3-none-any.whl

ova_portable_text/helpers.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from .block_objects import CalloutBlock, ChartBlock, ImageBlock, MathBlock, TableBlock
+from .document import Document, DocumentMeta
+from .inline import CitationRef, FootnoteRef, GlossaryTerm, HardBreak, XRef
+from .registry import (
+    AttachmentAsset,
+    BackgroundAsset,
+    BibliographyEntry,
+    FootnoteEntry,
+    GlossaryEntry,
+    IconAsset,
+    ImageAsset,
+    LogoAsset,
+    MetricDataset,
+    MetricValue,
+    PieChartDataset,
+    PieSlice,
+    TableColumn,
+    TableDataset,
+)
+from .section import Section
+from .theme import ThemeConfig
+from .text import (
+    AnnotationMarkDef,
+    LinkMarkDef,
+    ListItemStyle,
+    MarkDef,
+    Span,
+    TextBlock,
+    TextChild,
+    TextStyle,
+)
+
+
+def create_document(*, title: str | None = None, language: str | None = None, theme: ThemeConfig | dict[str, Any] | None = None, **meta_fields) -> Document:
+    meta = DocumentMeta(title=title, language=language, **meta_fields)
+    theme_value = theme if isinstance(theme, ThemeConfig) else ThemeConfig(**(theme or {}))
+    return Document(meta=meta, theme=theme_value)
+
+
+document = create_document
+
+
+def section(*, id: str, level: int, title: str, numbering: str = "auto", anchor: str | None = None) -> Section:
+    return Section(id=id, level=level, title=title, numbering=numbering, anchor=anchor)
+
+
+def span(text: str, *, marks: list[str] | None = None) -> Span:
+    return Span(text=text, marks=marks or [])
+
+
+def marked(text: str, *marks: str) -> Span:
+    return Span(text=text, marks=list(marks))
+
+
+def strong(text: str) -> Span:
+    return Span(text=text, marks=["strong"])
+
+
+def em(text: str) -> Span:
+    return Span(text=text, marks=["em"])
+
+
+def underline(text: str) -> Span:
+    return Span(text=text, marks=["underline"])
+
+
+def code_span(text: str) -> Span:
+    return Span(text=text, marks=["code"])
+
+
+def link_def(*, key: str, href: str, title: str | None = None, open_in_new_tab: bool | None = None, rel: str | None = None) -> LinkMarkDef:
+    return LinkMarkDef(_key=key, href=href, title=title, openInNewTab=open_in_new_tab, rel=rel)
+
+
+def annotation_def(*, key: str, type: str, data: dict[str, Any] | None = None) -> AnnotationMarkDef:
+    return AnnotationMarkDef(_key=key, _type=type, data=data or {})
+
+
+def paragraph(*parts: str | TextChild, style: TextStyle = "normal", mark_defs: list[MarkDef] | None = None, list_item: ListItemStyle | None = None, level: int | None = None) -> TextBlock:
+    return TextBlock.from_parts(*parts, style=style, mark_defs=mark_defs, list_item=list_item, level=level)
+
+
+def bullet_item(*parts: str | TextChild, level: int = 1, mark_defs: list[MarkDef] | None = None) -> TextBlock:
+    return TextBlock.list_block(*parts, list_item="bullet", level=level, mark_defs=mark_defs)
+
+
+def number_item(*parts: str | TextChild, level: int = 1, mark_defs: list[MarkDef] | None = None) -> TextBlock:
+    return TextBlock.list_block(*parts, list_item="number", level=level, mark_defs=mark_defs)
+
+
+def blocks_from_items(items: Iterable[str | tuple[str | TextChild, ...] | list[str | TextChild]], *, list_item: ListItemStyle, level: int = 1, mark_defs: list[MarkDef] | None = None) -> list[TextBlock]:
+    output: list[TextBlock] = []
+    for item in items:
+        parts = (item,) if isinstance(item, str) else tuple(item)
+        output.append(TextBlock.list_block(*parts, list_item=list_item, level=level, mark_defs=mark_defs))
+    return output
+
+
+def hard_break() -> HardBreak:
+    return HardBreak()
+
+
+def xref(*, target_type: str, target_id: str) -> XRef:
+    return XRef(targetType=target_type, targetId=target_id)
+
+
+def citation_ref(*ref_ids: str, mode: str = "parenthetical") -> CitationRef:
+    return CitationRef(refIds=list(ref_ids), mode=mode)
+
+
+def footnote_ref(ref_id: str) -> FootnoteRef:
+    return FootnoteRef(refId=ref_id)
+
+
+def glossary_term(term_id: str) -> GlossaryTerm:
+    return GlossaryTerm(termId=term_id)
+
+
+def image_block(*, id: str, image_ref: str, anchor: str | None = None) -> ImageBlock:
+    return ImageBlock(id=id, anchor=anchor, imageRef=image_ref)
+
+
+def chart_block(*, id: str, chart_ref: str, anchor: str | None = None) -> ChartBlock:
+    return ChartBlock(id=id, anchor=anchor, chartRef=chart_ref)
+
+
+def table_block(*, id: str, table_ref: str, anchor: str | None = None) -> TableBlock:
+    return TableBlock(id=id, anchor=anchor, tableRef=table_ref)
+
+
+def math_block(*, id: str, latex: str, anchor: str | None = None) -> MathBlock:
+    return MathBlock(id=id, anchor=anchor, latex=latex)
+
+
+def callout(*, id: str, blocks: list[TextBlock] | None = None, anchor: str | None = None) -> CalloutBlock:
+    return CalloutBlock(id=id, anchor=anchor, blocks=blocks or [])
+
+
+def image_asset(*, id: str, src: str, alt: str | None = None, label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, **extra) -> ImageAsset:
+    return ImageAsset(id=id, src=src, alt=alt, label=label, anchor=anchor, meta=meta or {}, **extra)
+
+
+def logo_asset(*, id: str, src: str, alt: str | None = None, label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, **extra) -> LogoAsset:
+    return LogoAsset(id=id, src=src, alt=alt, label=label, anchor=anchor, meta=meta or {}, **extra)
+
+
+def background_asset(*, id: str, src: str, label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, **extra) -> BackgroundAsset:
+    return BackgroundAsset(id=id, src=src, label=label, anchor=anchor, meta=meta or {}, **extra)
+
+
+def icon_asset(*, id: str, src: str, alt: str | None = None, label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, **extra) -> IconAsset:
+    return IconAsset(id=id, src=src, alt=alt, label=label, anchor=anchor, meta=meta or {}, **extra)
+
+
+def attachment_asset(*, id: str, src: str, file_name: str | None = None, description: str | None = None, label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, **extra) -> AttachmentAsset:
+    return AttachmentAsset(id=id, src=src, fileName=file_name, description=description, label=label, anchor=anchor, meta=meta or {}, **extra)
+
+
+def table_column(*, key: str, header: str) -> TableColumn:
+    return TableColumn(key=key, header=header)
+
+
+def table_dataset(*, id: str, columns: list[TableColumn], rows: list[dict], label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, **extra) -> TableDataset:
+    return TableDataset(id=id, columns=columns, rows=rows, label=label, anchor=anchor, meta=meta or {}, **extra)
+
+
+def metric_value(*, key: str, value: str | int | float | bool | None, label: str | None = None, unit: str | None = None) -> MetricValue:
+    return MetricValue(key=key, value=value, label=label, unit=unit)
+
+
+def metric_dataset(*, id: str, values: list[MetricValue], label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, **extra) -> MetricDataset:
+    return MetricDataset(id=id, values=values, label=label, anchor=anchor, meta=meta or {}, **extra)
+
+
+def pie_slice(*, key: str, value: int | float, en: str | None = None, zh: str | None = None, description_en: str | None = None, description_zh: str | None = None) -> PieSlice:
+    return PieSlice(key=key, label={k: v for k, v in {"en": en, "zh": zh}.items() if v}, value=value, description={k: v for k, v in {"en": description_en, "zh": description_zh}.items() if v})
+
+
+def pie_chart_dataset(*, id: str, slices: list[PieSlice], label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, value_unit: str | None = None) -> PieChartDataset:
+    return PieChartDataset(id=id, slices=slices, label=label, anchor=anchor, meta=meta or {}, valueUnit=value_unit)
+
+
+def pie_chart_from_parallel_arrays(*, id: str, area_en: list[str], area_zh: list[str] | None, value: list[int | float], description_en: list[str] | None = None, description_zh: list[str] | None = None, label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, value_unit: str | None = None, sort_desc: bool = True) -> PieChartDataset:
+    return PieChartDataset.from_parallel_arrays(id=id, area_en=area_en, area_zh=area_zh, value=value, description_en=description_en, description_zh=description_zh, label=label, anchor=anchor, meta=meta, valueUnit=value_unit, sort_desc=sort_desc)
+
+
+def bibliography_entry(*, id: str, title: str | None = None, authors: list[str] | None = None, year: int | None = None, type: str = "misc", text: str | None = None, label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, **extra) -> BibliographyEntry:
+    final_title = title or text
+    if not final_title:
+        raise ValueError("`bibliography_entry` requires either `title` or legacy `text`.")
+    return BibliographyEntry(id=id, title=final_title, authors=authors or [], year=year, type=type, text=text, label=label, anchor=anchor, meta=meta or {}, **extra)
+
+
+def footnote_entry(*, id: str, blocks: list[TextBlock], label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None) -> FootnoteEntry:
+    return FootnoteEntry(id=id, blocks=blocks, label=label, anchor=anchor, meta=meta or {})
+
+
+def glossary_entry(*, id: str, term: str, definition: str, aliases: list[str] | None = None, short: str | None = None, label: str | None = None, anchor: str | None = None, meta: dict[str, Any] | None = None, **extra) -> GlossaryEntry:
+    return GlossaryEntry(id=id, term=term, definition=definition, aliases=aliases, short=short, label=label, anchor=anchor, meta=meta or {}, **extra)

ova_portable_text/inline.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+"""
+Inline object models for OVAPortableText.
+OVAPortableText 的行内对象模型。
+
+In the protocol, inline objects can only appear inside `block.children[]`.
+根据协议，行内对象只能出现在 `block.children[]` 中。
+"""
+
+from typing import Literal, TypeAlias
+
+from pydantic import Field, field_validator
+
+from .base import OvaBaseModel
+
+
+class HardBreak(OvaBaseModel):
+    """
+    Force a line break inside the same paragraph block.
+    表示同一段落内部的强制换行。
+
+    This is NOT a new paragraph.
+    它不是新段落。
+    """
+
+    type_: Literal["hard_break"] = Field(default="hard_break", alias="_type", serialization_alias="_type")
+
+
+class XRef(OvaBaseModel):
+    """
+    Cross-reference to a resolvable target, such as a section or figure.
+    指向可解析目标的交叉引用，例如 section 或 figure。
+    """
+
+    type_: Literal["xref"] = Field(default="xref", alias="_type", serialization_alias="_type")
+    targetType: str
+    targetId: str
+
+
+class CitationRef(OvaBaseModel):
+    """
+    Reference one or more bibliography entries.
+    引用一个或多个 bibliography 条目。
+    """
+
+    type_: Literal["citation_ref"] = Field(default="citation_ref", alias="_type", serialization_alias="_type")
+    refIds: list[str]
+    mode: Literal["parenthetical", "narrative"] = "parenthetical"
+
+    @field_validator("refIds")
+    @classmethod
+    def validate_ref_ids(cls, value: list[str]) -> list[str]:
+        """
+        Require at least one bibliography target.
+        至少需要一个 bibliography 目标。
+        """
+        if not value:
+            raise ValueError("citation_ref.refIds must contain at least one bibliography id")
+        return value
+
+
+class FootnoteRef(OvaBaseModel):
+    """
+    Reference a footnote entry.
+    引用一个脚注条目。
+    """
+
+    type_: Literal["footnote_ref"] = Field(default="footnote_ref", alias="_type", serialization_alias="_type")
+    refId: str
+
+
+class GlossaryTerm(OvaBaseModel):
+    """
+    Reference a glossary entry or abbreviation entry.
+    引用 glossary 中的术语或缩写条目。
+    """
+
+    type_: Literal["glossary_term"] = Field(default="glossary_term", alias="_type", serialization_alias="_type")
+    termId: str
+
+
+InlineObject: TypeAlias = HardBreak | XRef | CitationRef | FootnoteRef | GlossaryTerm
+"""
+Union type of all currently supported inline objects.
+当前已支持的全部行内对象联合类型。
+"""

ova_portable_text/numbering.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+"""
+Display-number helper layer for OVAPortableText.
+OVAPortableText 的显示编号辅助层。
+
+Important boundary / 重要边界：
+The protocol separates:
+协议明确分离了以下三层：
+- stable system ID / 稳定系统 ID
+- anchor / 锚点
+- display number / 面向读者的显示编号
+
+This module only computes helper-side display numbers.
+本模块只负责计算 helper 层的显示编号。
+It does NOT write display numbers back into the protocol JSON.
+它不会把显示编号直接写回协议 JSON。
+"""
+
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import Field
+
+from .base import OvaBaseModel
+from .block_objects import ChartBlock, ImageBlock, MathBlock, TableBlock
+from .content import ContentItem
+from .section import Section, SubsectionItem
+
+if TYPE_CHECKING:
+    from .document import Document
+
+ObjectNumberingMode = Literal["global", "section"]
+
+
+class NumberingConfig(OvaBaseModel):
+    """
+    Configuration for helper-side display numbering.
+    helper 层显示编号的配置对象。
+
+    Current default / 当前默认值：
+    - sections: always hierarchical by tree structure
+      section 始终按章节树层级推导
+    - figure / table / equation: global continuous numbering
+      figure / table / equation 默认全局连续编号
+
+    Why not freeze one universal rule in the protocol?
+    为什么不把这些规则直接冻结进协议本体？
+    Because the protocol intentionally leaves those renderer-facing choices open.
+    因为协议本身刻意没有把这些更偏渲染侧的策略写死。
+    """
+
+    figureMode: ObjectNumberingMode = "global"
+    tableMode: ObjectNumberingMode = "global"
+    equationMode: ObjectNumberingMode = "global"
+
+
+class NumberedTarget(OvaBaseModel):
+    """
+    One computed display-number entry.
+    一条计算得到的显示编号记录。
+    """
+
+    id: str
+    category: Literal["section", "figure", "table", "equation"]
+    displayNumber: str | None = None
+    anchor: str | None = None
+    path: str
+
+
+class DocumentNumbering(OvaBaseModel):
+    """
+    Computed numbering snapshot for one whole document.
+    整份文档的一次编号快照。
+
+    This object is intentionally read-only in spirit.
+    这个对象在设计意图上是“只读快照”。
+    You compute it from a document, then query it.
+    它由 document 计算出来，然后供调用方查询。
+    """
+
+    config: NumberingConfig = Field(default_factory=NumberingConfig)
+    itemsById: dict[str, NumberedTarget] = Field(default_factory=dict)
+
+    @classmethod
+    def from_document(
+        cls,
+        document: Document,
+        config: NumberingConfig | None = None,
+    ) -> "DocumentNumbering":
+        """
+        Compute a numbering snapshot from the given document.
+        从给定 document 计算一份编号快照。
+        """
+        config = config or NumberingConfig()
+        items: dict[str, NumberedTarget] = {}
+        global_counts = {"figure": 0, "table": 0, "equation": 0}
+
+        def allocate_object_number(
+            *,
+            category: Literal["figure", "table", "equation"],
+            section_path_numbers: list[int],
+            local_counts: dict[str, int],
+        ) -> str:
+            mode: ObjectNumberingMode
+            if category == "figure":
+                mode = config.figureMode
+            elif category == "table":
+                mode = config.tableMode
+            else:
+                mode = config.equationMode
+
+            if mode == "section":
+                local_counts[category] += 1
+                prefix = ".".join(str(x) for x in section_path_numbers)
+                return f"{prefix}-{local_counts[category]}"
+
+            global_counts[category] += 1
+            return str(global_counts[category])
+
+        def walk_section(section: Section, *, path: str, structural_numbers: list[int]) -> None:
+            section_display_number = ".".join(str(x) for x in structural_numbers) if section.numbering == "auto" else None
+            items[section.id] = NumberedTarget(
+                id=section.id,
+                category="section",
+                displayNumber=section_display_number,
+                anchor=section.anchor,
+                path=path,
+            )
+
+            local_counts = {"figure": 0, "table": 0, "equation": 0}
+
+            for body_index, item in enumerate(section.body):
+                item_path = f"{path}.body[{body_index}]"
+                if isinstance(item, ContentItem):
+                    for block_index, block in enumerate(item.blocks):
+                        block_path = f"{item_path}.blocks[{block_index}]"
+                        if isinstance(block, (ImageBlock, ChartBlock)):
+                            items[block.id] = NumberedTarget(
+                                id=block.id,
+                                category="figure",
+                                displayNumber=allocate_object_number(
+                                    category="figure",
+                                    section_path_numbers=structural_numbers,
+                                    local_counts=local_counts,
+                                ),
+                                anchor=block.anchor,
+                                path=block_path,
+                            )
+                        elif isinstance(block, TableBlock):
+                            items[block.id] = NumberedTarget(
+                                id=block.id,
+                                category="table",
+                                displayNumber=allocate_object_number(
+                                    category="table",
+                                    section_path_numbers=structural_numbers,
+                                    local_counts=local_counts,
+                                ),
+                                anchor=block.anchor,
+                                path=block_path,
+                            )
+                        elif isinstance(block, MathBlock):
+                            items[block.id] = NumberedTarget(
+                                id=block.id,
+                                category="equation",
+                                displayNumber=allocate_object_number(
+                                    category="equation",
+                                    section_path_numbers=structural_numbers,
+                                    local_counts=local_counts,
+                                ),
+                                anchor=block.anchor,
+                                path=block_path,
+                            )
+                elif isinstance(item, SubsectionItem):
+                    sibling_index = _next_child_index(section=item.section, parent=section)
+                    # The actual structural path is already known from array order below.
+                    # 真正的结构路径会由下面的顺序遍历统一给出。
+                    walk_section(
+                        item.section,
+                        path=f"{item_path}.section",
+                        structural_numbers=structural_numbers + [sibling_index],
+                    )
+
+        def walk_section_list(sections: list[Section], *, parent_numbers: list[int], parent_path: str) -> None:
+            for index, section in enumerate(sections, start=1):
+                walk_section(
+                    section,
+                    path=f"{parent_path}[{index - 1}]",
+                    structural_numbers=parent_numbers + [index],
+                )
+
+        def _next_child_index(section: Section, parent: Section) -> int:
+            """
+            Compute the direct-child index of `section` under `parent`.
+            计算 `section` 在 `parent` 下的“直接子章节序号”。
+
+            Why do this by scanning the parent body?
+            为什么通过扫描 parent.body 来做？
+            Because `body` can interleave content items and subsection items.
+            因为 `body` 里可以交错出现 content item 与 subsection item。
+            We only count direct subsection items.
+            我们这里只统计直接 `subsection` 项。
+            """
+            count = 0
+            for item in parent.body:
+                if isinstance(item, SubsectionItem):
+                    count += 1
+                    if item.section is section:
+                        return count
+            return count or 1
+
+        walk_section_list(document.sections, parent_numbers=[], parent_path="sections")
+        return cls(config=config, itemsById=items)
+
+    def get(self, id_value: str) -> NumberedTarget | None:
+        """
+        Return the numbering record of one target by ID.
+        通过 ID 返回某个目标的编号记录。
+        """
+        return self.itemsById.get(id_value)
+
+    def get_display_number(self, id_value: str) -> str | None:
+        """
+        Return only the display number string of one target.
+        仅返回某个目标的显示编号字符串。
+        """
+        item = self.get(id_value)
+        return item.displayNumber if item else None