OVAPortableText 0.1.0__py3-none-any.whl

ova_portable_text/document.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+"""
+Top-level document models for OVAPortableText.
+OVAPortableText 的顶层文档模型。
+
+This module intentionally keeps the document object as the primary user entry.
+本模块刻意让 document 对象成为用户的主入口。
+
+Why design it this way?
+为什么这样设计？
+Because the target usage style of this package is close to common document libraries:
+因为本包希望尽量接近常见文档库的使用方式：
+- create one top-level document object / 先创建一个顶层 document 对象
+- keep appending sections and resources / 再不断 append section 与资源
+- finally validate, resolve, number, and export / 最后统一校验、解析、编号、导出
+
+This file therefore contains:
+因此本文件同时承载：
+1. top-level document state / 顶层文档状态
+2. typed-but-extensible metadata / 强类型但可扩展的元信息模型
+3. convenience methods for append-style authoring / 便于 append 风格写作的快捷方法
+"""
+
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from .base import OvaBaseModel
+from .numbering import DocumentNumbering, NumberingConfig
+from .registry import (
+    AssetsRegistry,
+    AttachmentAsset,
+    BackgroundAsset,
+    BibliographyEntry,
+    DatasetsRegistry,
+    FootnoteEntry,
+    GlossaryEntry,
+    IconAsset,
+    ImageAsset,
+    LogoAsset,
+    MetricDataset,
+    PieChartDataset,
+    TableDataset,
+)
+from .section import Section
+from .theme import ThemeConfig
+
+
+class DocumentMeta(OvaBaseModel):
+    """
+    Top-level document metadata.
+    文档顶层元数据。
+
+    Why keep this model "typed but extensible"?
+    为什么把它设计成“强类型但可扩展”？
+    Because the protocol explicitly lists common metadata directions,
+    but also states that the full detailed field table is not frozen in v1.0.
+    因为协议已经明确列出了常见元信息方向，
+    但同时也说明 v1.0 尚未冻结完整字段表。
+
+    Therefore / 因此：
+    - common fields get typed access / 常见字段提供强类型访问
+    - unknown extra fields are still allowed / 仍允许附加未知扩展字段
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    title: str | None = None
+    subtitle: str | None = None
+    language: str | None = None
+    author: str | None = None
+    date: str | None = None
+    reportNumber: str | None = None
+    documentType: str | None = None
+    confidentiality: str | None = None
+    generatedBy: str | None = None
+    generatedAt: str | None = None
+    clientId: str | None = None
+    projectId: str | None = None
+
+    # Protocol-mentioned likely extension directions.
+    # 协议中明确提到、后续大概率会继续使用的扩展方向。
+    reportType: str | None = None
+    clientName: str | None = None
+    locale: str | None = None
+    source: str | None = None
+
+
+class Document(OvaBaseModel):
+    """
+    Top-level report document.
+    顶层报告文档对象。
+
+    Important protocol alignment / 关键协议对齐点：
+    - `schemaVersion` defaults to `report.v1`
+      `schemaVersion` 默认值为 `report.v1`
+    - `theme` is preserved as a placeholder, but now has a lightweight typed model
+      `theme` 仍然是占位层，但现在有一个轻量强类型模型
+    - top-level registries should always exist, even when empty
+      顶层 registry 即使为空也应存在
+    """
+
+    schemaVersion: str = "report.v1"
+    meta: DocumentMeta = Field(default_factory=DocumentMeta)
+    theme: ThemeConfig = Field(default_factory=ThemeConfig)
+    assets: AssetsRegistry = Field(default_factory=AssetsRegistry)
+    datasets: DatasetsRegistry = Field(default_factory=DatasetsRegistry)
+    bibliography: list[BibliographyEntry] = Field(default_factory=list)
+    footnotes: list[FootnoteEntry] = Field(default_factory=list)
+    glossary: list[GlossaryEntry] = Field(default_factory=list)
+    sections: list[Section] = Field(default_factory=list)
+
+    def append_section(self, section: Section) -> "Document":
+        """
+        Append one top-level section.
+        追加一个顶层 section。
+        """
+        self.sections.append(section)
+        return self
+
+    def append_sections(self, *sections: Section) -> "Document":
+        """
+        Append multiple top-level sections in one call.
+        一次追加多个顶层 section。
+        """
+        self.sections.extend(sections)
+        return self
+
+    def new_section(
+        self,
+        *,
+        id: str,
+        level: int,
+        title: str,
+        numbering: str = "auto",
+        anchor: str | None = None,
+        append: bool = True,
+    ) -> Section:
+        """
+        Create a new top-level section and optionally append it immediately.
+        创建一个新的顶层 section，并可选择立刻 append 到 document。
+
+        Why return the section object?
+        为什么返回 section 对象？
+        So callers can immediately continue writing content like:
+        这样调用者可以立刻继续写内容，例如：
+
+            sec = doc.new_section(...)
+            sec.append_paragraph(...)
+        """
+        section = Section(id=id, level=level, title=title, numbering=numbering, anchor=anchor)
+        if append:
+            self.append_section(section)
+        return section
+
+    # ------------------------------------------------------------------
+    # Asset registry helpers / 资源 registry helper
+    # ------------------------------------------------------------------
+    def add_image_asset(self, asset: ImageAsset) -> "Document":
+        """
+        Append an `assets.images` entry.
+        追加一个 `assets.images` 条目。
+        """
+        self.assets.append_image(asset)
+        return self
+
+    def add_logo_asset(self, asset: LogoAsset) -> "Document":
+        """
+        Append an `assets.logos` entry.
+        追加一个 `assets.logos` 条目。
+        """
+        self.assets.append_logo(asset)
+        return self
+
+    def add_background_asset(self, asset: BackgroundAsset) -> "Document":
+        """
+        Append an `assets.backgrounds` entry.
+        追加一个 `assets.backgrounds` 条目。
+        """
+        self.assets.append_background(asset)
+        return self
+
+    def add_icon_asset(self, asset: IconAsset) -> "Document":
+        """
+        Append an `assets.icons` entry.
+        追加一个 `assets.icons` 条目。
+        """
+        self.assets.append_icon(asset)
+        return self
+
+    def add_attachment_asset(self, asset: AttachmentAsset) -> "Document":
+        """
+        Append an `assets.attachments` entry.
+        追加一个 `assets.attachments` 条目。
+        """
+        self.assets.append_attachment(asset)
+        return self
+
+    # ------------------------------------------------------------------
+    # Dataset registry helpers / 数据 registry helper
+    # ------------------------------------------------------------------
+    def add_table_dataset(self, table: TableDataset) -> "Document":
+        """
+        Append a `datasets.tables` entry.
+        追加一个 `datasets.tables` 条目。
+        """
+        self.datasets.append_table(table)
+        return self
+
+    def add_chart_dataset(self, chart: PieChartDataset) -> "Document":
+        """
+        Append a `datasets.charts` entry.
+        追加一个 `datasets.charts` 条目。
+        """
+        self.datasets.append_chart(chart)
+        return self
+
+    def add_metric_dataset(self, metric: MetricDataset) -> "Document":
+        """
+        Append a `datasets.metrics` entry.
+        追加一个 `datasets.metrics` 条目。
+        """
+        self.datasets.append_metric(metric)
+        return self
+
+    # ------------------------------------------------------------------
+    # Academic / auxiliary registry helpers / 学术与辅助 registry helper
+    # ------------------------------------------------------------------
+    def add_bibliography_entry(self, entry: BibliographyEntry) -> "Document":
+        """
+        Append one bibliography entry.
+        追加一个 bibliography 条目。
+        """
+        self.bibliography.append(entry)
+        return self
+
+    def add_footnote(self, entry: FootnoteEntry) -> "Document":
+        """
+        Append one footnote entry.
+        追加一个 footnote 条目。
+        """
+        self.footnotes.append(entry)
+        return self
+
+    def add_glossary_entry(self, entry: GlossaryEntry) -> "Document":
+        """
+        Append one glossary entry.
+        追加一个 glossary 条目。
+        """
+        self.glossary.append(entry)
+        return self
+
+    def build_resolver(self):
+        """
+        Build a global resolver / index for the current document.
+        为当前文档构建全局 resolver / 索引器。
+        """
+        from .resolver import DocumentResolver
+        return DocumentResolver.from_document(self)
+
+    def build_numbering(self, config: NumberingConfig | None = None) -> DocumentNumbering:
+        """
+        Build logical numbering hints for sections / figures / tables / equations.
+        为 sections / figures / tables / equations 构建逻辑编号辅助。
+
+        Important boundary / 重要边界：
+        this method only computes logical display-number hints.
+        这个方法只计算逻辑层 display number 辅助。
+        It does NOT decide final renderer wording such as "Figure 3" vs "Fig. 3".
+        它不会决定最终渲染层文本，例如到底显示为 “Figure 3” 还是 “Fig. 3”。
+        """
+        return DocumentNumbering.from_document(self, config=config)
+
+    def validate(self):
+        """
+        Validate the whole document and return a structured report.
+        校验整份文档并返回结构化报告。
+        """
+        from .validator import validate_document
+        return validate_document(self)
+
+    def assert_valid(self) -> "Document":
+        """
+        Validate the document and raise if invalid.
+        校验文档；若无效则抛错。
+        """
+        from .validator import assert_valid_document
+        return assert_valid_document(self)
+
+    @classmethod
+    def from_meta(
+        cls,
+        *,
+        theme: ThemeConfig | dict[str, Any] | None = None,
+        **meta_fields: Any,
+    ) -> "Document":
+        """
+        Alternate constructor that builds a document from metadata fields directly.
+        一个备用构造器：直接从 metadata 字段创建 document。
+        """
+        theme_value = theme if isinstance(theme, ThemeConfig) else ThemeConfig(**(theme or {}))
+        return cls(meta=DocumentMeta(**meta_fields), theme=theme_value)

ova_portable_text/exceptions.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+"""
+Validation-related exception and report models for OVAPortableText.
+OVAPortableText 的校验异常与报告模型。
+
+This file is intentionally part of the public API.
+本文件刻意作为公开 API 的一部分。
+
+Why?
+为什么？
+Because validation is not only an internal implementation detail.
+因为校验并不只是内部实现细节。
+For this package, validation is one of the core user-facing workflows:
+对本包而言，校验本身就是核心对外工作流之一：
+- build a document / 构建文档
+- inspect a structured validation report / 查看结构化校验报告
+- optionally fail fast / 必要时快速抛错中止
+
+Step 8 extends the report so issues carry more maintenance-friendly context,
+which is especially useful when the user later debugs large report documents.
+第 8 步进一步扩展了报告结构，让 issue 带有更多便于维护的上下文；
+当后续调试大型报告文档时，这会非常有帮助。
+"""
+
+from collections import Counter
+from typing import Literal
+
+from pydantic import Field
+
+from .base import OvaBaseModel
+
+
+class ValidationIssue(OvaBaseModel):
+    """
+    One validation issue found in the document.
+    文档中发现的一条校验问题。
+
+    Besides the basic code / message / path fields,
+    Step 8 also carries optional context that helps users quickly locate the
+    problematic semantic object.
+    除了基础的 code / message / path 字段外，
+    第 8 步还补充了若干可选上下文字段，便于用户快速定位出问题的语义对象。
+
+    Common examples / 常见示例：
+    - which section the issue belongs to / 属于哪个 section
+    - which object id or anchor is involved / 涉及哪个对象 id 或 anchor
+    - what kind of object it is / 它属于哪种对象类型
+    - what to try next / 建议下一步怎么修
+    """
+
+    code: str
+    message: str
+    path: str | None = None
+    severity: Literal["error", "warning"] = "error"
+
+    # Maintenance-oriented context fields.
+    # 面向维护与调试的上下文字段。
+    location: str | None = None
+    contextType: str | None = None
+    contextId: str | None = None
+    contextAnchor: str | None = None
+    sectionId: str | None = None
+    sectionTitle: str | None = None
+    suggestion: str | None = None
+
+    def to_text(self) -> str:
+        """
+        Render one issue as a compact human-readable line.
+        将单条 issue 渲染为便于人工阅读的简洁文本。
+        """
+        pieces: list[str] = [f"[{self.severity.upper()}] [{self.code}] {self.message}"]
+        if self.path:
+            pieces.append(f"path={self.path}")
+        if self.sectionId:
+            section_text = self.sectionId
+            if self.sectionTitle:
+                section_text += f" ({self.sectionTitle})"
+            pieces.append(f"section={section_text}")
+        if self.contextType:
+            pieces.append(f"contextType={self.contextType}")
+        if self.contextId:
+            pieces.append(f"contextId={self.contextId}")
+        if self.contextAnchor:
+            pieces.append(f"contextAnchor={self.contextAnchor}")
+        if self.suggestion:
+            pieces.append(f"suggestion={self.suggestion}")
+        return " | ".join(pieces)
+
+
+class ValidationReport(OvaBaseModel):
+    """
+    Structured validation report for an entire document.
+    整份文档的结构化校验报告。
+
+    Design intent / 设计意图：
+    - keep the raw issue list machine-friendly / 保持 issue 列表机器可读
+    - but also offer direct summary helpers / 同时提供直接可用的摘要 helper
+    - so the report can be used in tests, logs, CLI output, or notebooks
+      从而既可用于测试，也可用于日志、CLI 输出或 notebook 调试
+    """
+
+    isValid: bool = True
+    issues: list[ValidationIssue] = Field(default_factory=list)
+
+    def add_issue(
+        self,
+        *,
+        code: str,
+        message: str,
+        path: str | None = None,
+        severity: Literal["error", "warning"] = "error",
+        location: str | None = None,
+        contextType: str | None = None,
+        contextId: str | None = None,
+        contextAnchor: str | None = None,
+        sectionId: str | None = None,
+        sectionTitle: str | None = None,
+        suggestion: str | None = None,
+    ) -> "ValidationReport":
+        """
+        Append one issue into the report.
+        向报告中追加一条问题记录。
+
+        `location` defaults to `path` when omitted.
+        若未显式提供 `location`，则默认回退到 `path`。
+        """
+        self.issues.append(
+            ValidationIssue(
+                code=code,
+                message=message,
+                path=path,
+                severity=severity,
+                location=location or path,
+                contextType=contextType,
+                contextId=contextId,
+                contextAnchor=contextAnchor,
+                sectionId=sectionId,
+                sectionTitle=sectionTitle,
+                suggestion=suggestion,
+            )
+        )
+        if severity == "error":
+            self.isValid = False
+        return self
+
+    @property
+    def is_valid(self) -> bool:
+        """
+        Python-friendly alias for `isValid`.
+        提供一个更符合 Python 命名习惯的 `isValid` 别名。
+
+        Why keep both names?
+        为什么同时保留两个名字？
+        - `isValid` matches the JSON-facing protocol field shape.
+          `isValid` 对齐 JSON / 协议输出字段风格。
+        - `is_valid` feels more natural when the report is used as a Python object.
+          当把报告当作 Python 对象使用时，`is_valid` 更顺手。
+        """
+        return self.isValid
+
+    @property
+    def error_count(self) -> int:
+        """
+        Number of issues with severity = error.
+        严重级别为 error 的问题数量。
+        """
+        return sum(1 for issue in self.issues if issue.severity == "error")
+
+    @property
+    def warning_count(self) -> int:
+        """
+        Number of issues with severity = warning.
+        严重级别为 warning 的问题数量。
+        """
+        return sum(1 for issue in self.issues if issue.severity == "warning")
+
+    def codes(self) -> list[str]:
+        """
+        Return issue codes in order.
+        按原顺序返回全部 issue code。
+        """
+        return [issue.code for issue in self.issues]
+
+    def counts_by_code(self) -> dict[str, int]:
+        """
+        Return a frequency mapping grouped by code.
+        返回按 code 聚合的出现次数映射。
+        """
+        return dict(Counter(self.codes()))
+
+    def to_text(self, *, include_warnings: bool = True) -> str:
+        """
+        Render the whole report into a readable multi-line string.
+        将整份报告渲染为便于阅读的多行文本。
+        """
+        lines = [
+            "OVAPortableText validation report:",
+            f"isValid={self.isValid}",
+            f"errors={self.error_count}",
+            f"warnings={self.warning_count}",
+        ]
+        for idx, issue in enumerate(self.issues, start=1):
+            if issue.severity == "warning" and not include_warnings:
+                continue
+            lines.append(f"{idx}. {issue.to_text()}")
+        return "\n".join(lines)
+
+    def raise_for_errors(self) -> "ValidationReport":
+        """
+        Raise `DocumentValidationError` if the report is invalid.
+        若报告包含错误，则抛出 `DocumentValidationError`。
+        """
+        if not self.isValid:
+            raise DocumentValidationError(self)
+        return self
+
+
+class DocumentValidationError(ValueError):
+    """
+    Exception raised when document validation fails.
+    当文档校验失败时抛出的异常。
+    """
+
+    def __init__(self, report_or_issues: ValidationReport | list[ValidationIssue]):
+        if isinstance(report_or_issues, ValidationReport):
+            self.report = report_or_issues
+            self.issues = report_or_issues.issues
+            message = report_or_issues.to_text(include_warnings=True)
+        else:
+            self.issues = report_or_issues
+            self.report = ValidationReport(isValid=False, issues=report_or_issues)
+            message = self.report.to_text(include_warnings=True)
+        super().__init__(message)