OVAPortableText 0.3.0__tar.gz → 0.4.0__tar.gz

{ovaportabletext-0.3.0 → ovaportabletext-0.4.0}/CHANGELOG.md

@@ -4,6 +4,29 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-14
+
+### Added
+
+* aligned the package with `report.v1.3`
+* added typed chart models for `bar`, `line`, and `matrix_bubble` datasets
+* added shared `ChartAxis`, `ChartCategory`, `MatrixBubbleCategory`, and `SizeMetric` models
+* added chart helper functions for bar, horizontal bar, line, and matrix bubble datasets
+* added validation coverage for v1.3 chart category references, series keys, and matrix bubble size values
+* added tests covering v1.3 schema defaults, `pie.slices[].colorHint`, bar variants, line points, and matrix bubble output
+
+### Changed
+
+* default `schemaVersion` is now `report.v1.3`
+* package metadata and public version now reflect `v0.4.0` / `report.v1.3`
+* `datasets.charts` now has first-class Python models for all v1.3 formal chart types while keeping the generic chart fallback
+
+### Fixed
+
+* preserved `pie.slices[].colorHint` while avoiding new visual-style fields for v1.3 chart types
+* normalized legacy `sizeMetric.valueUnit` input to `sizeMetric.unit` without emitting `valueUnit` in new matrix-bubble output
+* avoided any `chartType = "bubble"` helper for v1.3; classification bubble charts now use `chartType = "matrix_bubble"`
+
 ## [0.3.0] - 2026-04-08
 
 ### Added

{ovaportabletext-0.3.0 → ovaportabletext-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OVAPortableText
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python builder for generating OVAPortableText / Report Profile v1 JSON documents
 Author: FENG QU
 License-Expression: MIT

{ovaportabletext-0.3.0 → ovaportabletext-0.4.0}/docs/API_REFERENCE.md

@@ -1,7 +1,7 @@
 # API Reference / API 参考
 
-This page is a practical map of the public API in OVAPortableText `v0.3.0`, aligned to `report.v1.2`.
-本文档是 OVAPortableText `v0.3.0` 的实用 API 地图，对齐 `report.v1.2`。
+This page is a practical map of the public API in OVAPortableText `v0.4.0`, aligned to `report.v1.3`.
+本文档是 OVAPortableText `v0.4.0` 的实用 API 地图，对齐 `report.v1.3`。
 
 ---
 
@@ -17,7 +17,7 @@ This page is a practical map of the public API in OVAPortableText `v0.3.0`, alig
 
 Default schema version:
 
-- `Document.schemaVersion == "report.v1.2"`
+- `Document.schemaVersion == "report.v1.3"`
 
 Common arguments / 常用参数：
 
@@ -46,7 +46,7 @@ Body block objects / 正文块对象：
 - `MathBlock`
 - `CalloutBlock`
 
-Important v1.2 note / v1.2 重点：
+Important v1.3 note / v1.3 重点：
 
 - `ImageBlock(imageRef="...")` remains valid
 - `ChartBlock(chartRef="...")`, `TableBlock(tableRef="...")`, and `MathBlock(latex="...")` may now omit instance `id`
@@ -209,10 +209,39 @@ Supported length units:
 - `table_layout(*column_specs)`
 - `pie_slice(...)`
 - `pie_chart_dataset(...)`
+- `doughnut_chart_dataset(...)`
 - `pie_chart_from_parallel_arrays(...)`
+- `chart_axis(...)`
+- `chart_category(...)`
+- `bar_data_point(...)`
+- `bar_series(...)`
+- `bar_chart_dataset(...)`
+- `horizontal_bar_chart_dataset(...)`
+- `line_point(...)`
+- `line_series(...)`
+- `line_chart_dataset(...)`
+- `matrix_bubble_category(...)`
+- `size_metric(...)`
+- `matrix_bubble_point(...)`
+- `matrix_bubble_series(...)`
+- `matrix_bubble_chart_dataset(...)`
 - `metric_value(...)`
 - `metric_dataset(...)`
 
+
+### v1.3 chart models / v1.3 图表模型
+
+`datasets.charts[]` now has typed helpers for the five formal chart types: `pie`, `doughnut`, `bar`, `line`, and `matrix_bubble`.
+`datasets.charts[]` 现在为五类正式图表提供 typed helper：`pie`、`doughnut`、`bar`、`line`、`matrix_bubble`。
+
+Key boundaries / 关键边界：
+
+- horizontal bar charts still use `chartType = "bar"` with `orientation = "horizontal"`
+- line charts use `points[].xValue / yValue / label`, not `categories[]`
+- classification bubble charts use `chartType = "matrix_bubble"`, never `bubble`
+- `matrix_bubble.sizeValue` uses `sizeMetric.unit`; new output does not emit `sizeMetric.valueUnit`
+- v1.2 `pie.slices[].colorHint` remains supported; new chart types intentionally avoid visual styling fields
+
 ### Registry-backed block instances / 正文引用实例
 
 - `image_block(image_ref=..., id=None, anchor=None)`

{ovaportabletext-0.3.0 → ovaportabletext-0.4.0}/docs/PROTOCOL_ALIGNMENT.md

@@ -1,7 +1,7 @@
 # Protocol Alignment / 协议对齐说明
 
-This page explains how OVAPortableText 0.3.0 aligns with the current Report Profile v1.2 protocol maintained in this repository.  
-本文档说明 OVAPortableText 0.3.0 与当前仓库内维护的 Report Profile v1.2 正式协议之间的对齐关系。
+This page explains how OVAPortableText 0.4.0 aligns with the current Report Profile v1.3 protocol maintained in this repository.  
+本文档说明 OVAPortableText 0.4.0 与当前仓库内维护的 Report Profile v1.3 正式协议之间的对齐关系。
 
 ---
 
@@ -20,8 +20,8 @@ The package aligns to this top-level shape:
 - `glossary`
 - `sections`
 
-`schemaVersion` defaults to `report.v1.2`.  
-`schemaVersion` 默认值为 `report.v1.2`。
+`schemaVersion` defaults to `report.v1.3`.  
+`schemaVersion` 默认值为 `report.v1.3`。
 
 ---
 

{ovaportabletext-0.3.0 → ovaportabletext-0.4.0}/docs/QUICKSTART.md

@@ -50,8 +50,8 @@ What happens here / 这里发生了什么：
 
 ## 3. Add registry-backed content / 添加引用型内容
 
-The protocol separates top-level registries from body instances. In `report.v1.2`, image / chart / table / math instances may omit instance `id` where the protocol allows it, text blocks can carry `layout`, sections can carry `sectionRole / navigation / pagination / presentation`, and grid cells can now contain charts.  
-协议把“顶层 registry”与“正文实例”分开处理。在 `report.v1.2` 中，协议允许的图片 / 图表 / 表格 / 公式实例都可以省略实例 `id`，文本块可携带 `layout`，section 可携带 `sectionRole / navigation / pagination / presentation`，grid 单元格现在还可以放图表。
+The protocol separates top-level registries from body instances. In `report.v1.3`, image / chart / table / math instances may omit instance `id` where the protocol allows it, text blocks can carry `layout`, sections can carry `sectionRole / navigation / pagination / presentation`, and grid cells can now contain charts.  
+协议把“顶层 registry”与“正文实例”分开处理。在 `report.v1.3` 中，协议允许的图片 / 图表 / 表格 / 公式实例都可以省略实例 `id`，文本块可携带 `layout`，section 可携带 `sectionRole / navigation / pagination / presentation`，grid 单元格现在还可以放图表。
 
 ### Example / 示例
 

ovaportabletext-0.4.0/examples/v13_charts_demo.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from ova_portable_text import (
+    bar_chart_dataset,
+    bar_data_point,
+    bar_series,
+    chart_axis,
+    chart_category,
+    create_document,
+    line_chart_dataset,
+    line_point,
+    line_series,
+    matrix_bubble_category,
+    matrix_bubble_chart_dataset,
+    matrix_bubble_point,
+    matrix_bubble_series,
+    section,
+    size_metric,
+)
+
+
+def build_report():
+    report = create_document(title="OVA Portable Text v1.3 Charts Demo", language="en")
+
+    bar = bar_chart_dataset(
+        id="chart-patent-counts-by-year",
+        value_unit="count",
+        categories=[
+            chart_category(key="2024", en="2024", zh="2024"),
+            chart_category(key="2025", en="2025", zh="2025"),
+        ],
+        series=[
+            bar_series(
+                key="applications",
+                en="Patent Applications",
+                zh="申请专利数量",
+                data=[
+                    bar_data_point(category_key="2024", value=7),
+                    bar_data_point(category_key="2025", value=9),
+                ],
+            )
+        ],
+        x_axis=chart_axis(en="Application Year", zh="申请年", value_type="year"),
+        y_axis=chart_axis(en="Patent Count", zh="专利数量", value_type="number", unit="count"),
+    )
+
+    line = line_chart_dataset(
+        id="chart-lifecycle-line",
+        value_unit="count",
+        x_axis=chart_axis(en="Patent Count", zh="专利数量", value_type="number", unit="count"),
+        y_axis=chart_axis(en="Applicant Count", zh="申请人数量", value_type="number", unit="count"),
+        series=[
+            line_series(
+                key="lifecycle",
+                en="Lifecycle",
+                zh="生命周期",
+                points=[
+                    line_point(key="2016", x_value=300, y_value=180, en="2016", zh="2016"),
+                    line_point(key="2017", x_value=700, y_value=400, en="2017", zh="2017"),
+                ],
+            )
+        ],
+    )
+
+    matrix = matrix_bubble_chart_dataset(
+        id="chart-category-matrix-bubble",
+        x_axis=chart_axis(en="Technology Category", zh="技术分类", value_type="category"),
+        y_axis=chart_axis(en="Market Region", zh="市场区域", value_type="category"),
+        x_categories=[matrix_bubble_category(key="ai", en="AI", zh="人工智能")],
+        y_categories=[matrix_bubble_category(key="china", en="China", zh="中国")],
+        size_metric=size_metric(en="Patent Count", zh="专利数量", unit="count"),
+        series=[
+            matrix_bubble_series(
+                key="patent-count",
+                en="Patent Count",
+                zh="专利数量",
+                points=[
+                    matrix_bubble_point(
+                        key="ai-china",
+                        x_category_key="ai",
+                        y_category_key="china",
+                        size_value=45,
+                    )
+                ],
+            )
+        ],
+    )
+
+    report.add_chart_dataset(bar).add_chart_dataset(line).add_chart_dataset(matrix)
+
+    charts = section(id="sec-v13-charts", level=1, title="v1.3 Charts")
+    charts.append_chart(chart_ref="chart-patent-counts-by-year")
+    charts.append_chart(chart_ref="chart-lifecycle-line")
+    charts.append_chart(chart_ref="chart-category-matrix-bubble")
+    report.append_section(charts)
+    return report
+
+
+if __name__ == "__main__":
+    print(build_report().to_json())

{ovaportabletext-0.3.0 → ovaportabletext-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "OVAPortableText"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python builder for generating OVAPortableText / Report Profile v1 JSON documents"
 readme = "README.md"
 requires-python = ">=3.10"

{ovaportabletext-0.3.0 → ovaportabletext-0.4.0}/src/ova_portable_text/__init__.py

@@ -24,6 +24,9 @@ from .exceptions import DocumentValidationError, ValidationIssue, ValidationRepo
 from .helpers import (
     block_layout,
     annotation_def,
+    bar_chart_dataset,
+    bar_data_point,
+    bar_series,
     attachment_asset,
     background_asset,
     background_asset_embedded,
@@ -36,6 +39,8 @@ from .helpers import (
     length_pt,
     callout,
     chart_block,
+    chart_axis,
+    chart_category,
     doughnut_chart_dataset,
     citation_ref,
     code_span,
@@ -48,6 +53,7 @@ from .helpers import (
     grid_table_dataset,
     grid_table_row,
     glossary_entry,
+    horizontal_bar_chart_dataset,
     glossary_term,
     hard_break,
     icon_asset,
@@ -65,10 +71,17 @@ from .helpers import (
     logo_asset_embedded,
     logo_asset_from_file,
     logo_asset_url,
+    line_chart_dataset,
+    line_point,
+    line_series,
     marked,
     math_block,
     metric_dataset,
     metric_value,
+    matrix_bubble_category,
+    matrix_bubble_chart_dataset,
+    matrix_bubble_point,
+    matrix_bubble_series,
     number_item,
     paragraph,
     pie_chart_dataset,
@@ -77,6 +90,7 @@ from .helpers import (
     pie_slice,
     record_table_dataset,
     section,
+    size_metric,
     span,
     strong,
     table_block,
@@ -94,7 +108,12 @@ from .registry import (
     AssetsRegistry,
     AttachmentAsset,
     BackgroundAsset,
+    BarChartDataset,
+    BarDataPoint,
+    BarSeries,
     BibliographyEntry,
+    ChartAxis,
+    ChartCategory,
     ChartDataset,
     DatasetsRegistry,
     FootnoteEntry,
@@ -110,13 +129,21 @@ from .registry import (
     ImageSource,
     ImageSourceEmbedded,
     ImageSourceUrl,
+    LineChartDataset,
+    LinePoint,
+    LineSeries,
     LogoAsset,
+    MatrixBubbleCategory,
+    MatrixBubbleChartDataset,
+    MatrixBubblePoint,
+    MatrixBubbleSeries,
     MetricDataset,
     MetricValue,
     PieChartDataset,
     PieSlice,
     RecordTableDataset,
     RegistryEntryBase,
+    SizeMetric,
     TableColumn,
     TableColumnSpec,
     TableColumnWidth,

{ovaportabletext-0.3.0 → ovaportabletext-0.4.0}/src/ova_portable_text/document.py

@@ -112,7 +112,7 @@ class Document(OvaBaseModel):
       顶层 registry 即使为空也应存在
     """
 
-    schemaVersion: str = "report.v1.2"
+    schemaVersion: str = "report.v1.3"
     strict_ids: bool = Field(default=False, exclude=True, repr=False)
     meta: DocumentMeta = Field(default_factory=DocumentMeta)
     theme: ThemeConfig = Field(default_factory=ThemeConfig)