ablechart 0.1.0__py3-none-any.whl

ablechart/metadata.py

@@ -0,0 +1,198 @@
+"""Chart metadata persistence.
+
+Belongs to: **metadata** lifecycle per ADR-0007 §1.
+Realises: ADR-0004 §2 (metadata 5-piece round-trip contract)
+          + ADR-0007 §3 (layered metadata strategy).
+
+Single entrypoint for chart-level semantic metadata. Today only **layer 1**
+(embedded workbook hidden sheet) is implemented; the layered strategy goal
+in ADR-0007 §3 is:
+
+    1. embedded workbook hidden sheet   ← layer 1, this module (default)
+    2. chart semantic anchor / invisible shape
+       ← layer 2, lives in ``semantic_anchor.py`` for shape-composition
+         families that have no chart container
+    3. custom XML part                  ← layer 3, requires PRD + compat check
+    4. shape alt text / name            ← layer 4, selector hint only
+
+This module holds the **single source of truth** for ``METADATA_SHEET_NAME``
+and ``METADATA_SCHEMA_VERSION``; previously these were duplicated in
+``api.py`` and ``parser.py``, a real silent-drift hazard.
+
+Public:
+
+- :data:`METADATA_SHEET_NAME`
+- :data:`METADATA_SCHEMA_VERSION`
+- :class:`ChartMetadataV1`
+- :func:`write_chart_metadata`
+
+Backward-compat (kept for existing callers):
+
+- :func:`_write_embedded_metadata` — original signature preserved;
+  internally delegates to layer 1 backend.
+
+ADR-0007 §2: this module avoids Pydantic; uses standard-library
+``dataclasses`` only.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from ._log import debug_print as print
+
+
+# ---------------------------------------------------------------------------
+# Authoritative constants (DO NOT redefine in api.py / parser.py)
+# ---------------------------------------------------------------------------
+
+METADATA_SHEET_NAME: str = "_pptchartengine_meta"
+"""Name of the hidden sheet inside a chart's embedded workbook that holds
+chart-level semantic metadata. Authoritative source; ``api.py`` and
+``parser.py`` re-import this rather than redefining."""
+
+METADATA_SCHEMA_VERSION: str = "2"
+"""Current schema version written to ``B1`` of the metadata sheet.
+Future schema changes must bump this AND maintain a backward-compat reader
+in ``parser.py`` (ADR-0004 backward-compat clause)."""
+
+
+# ---------------------------------------------------------------------------
+# Public schema
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ChartMetadataV1:
+    """Chart-level semantic metadata payload (ADR-0007 §3 layer 1, schema v2).
+
+    All fields are technical-layer only per ADR-0007 §2 — no business slot,
+    no ``user_id``, no prompt.
+    """
+
+    categories_col: str
+    series_config: List[Dict[str, Any]]
+    chart_family: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def write_chart_metadata(chart, metadata: ChartMetadataV1) -> None:
+    """Persist :class:`ChartMetadataV1` into the chart's embedded workbook.
+
+    Routes through layer 1 (embedded workbook hidden sheet). Failure is
+    currently swallowed with a stderr-like log (preserves prior
+    ``_write_embedded_metadata`` semantics); a future schema version should
+    promote this to a typed :class:`ablechart.replace` style result or
+    raise a dedicated ``MetadataWriteError``.
+    """
+    _write_workbook_hidden_sheet(
+        chart=chart,
+        categories_col=metadata.categories_col,
+        series_config=metadata.series_config,
+        chart_family=metadata.chart_family,
+        extra=metadata.extra,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Backward-compat (kept until callers migrate to write_chart_metadata)
+# ---------------------------------------------------------------------------
+
+
+def _write_embedded_metadata(
+    chart,
+    categories_col: str,
+    series_config: List[Dict],
+    metadata: Optional[Dict] = None,
+) -> None:
+    """Legacy signature preserved for ``api.py`` / ``scatter.py`` /
+    ``semantic_family.py`` call sites. Routes to layer 1 backend.
+
+    ``metadata`` here is a free-form dict that historically carried
+    ``chart_family`` plus arbitrary extra fields. We extract ``chart_family``
+    if present, treat the whole dict as ``extra``.
+    """
+    chart_family = None
+    if metadata is not None:
+        chart_family = metadata.get("chart_family")
+    _write_workbook_hidden_sheet(
+        chart=chart,
+        categories_col=categories_col,
+        series_config=series_config,
+        chart_family=chart_family,
+        extra=metadata,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Layer 1 backend — embedded workbook hidden sheet
+# ---------------------------------------------------------------------------
+
+
+def _write_workbook_hidden_sheet(
+    chart,
+    categories_col: str,
+    series_config: List[Dict[str, Any]],
+    chart_family: Optional[str] = None,
+    extra: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Layer 1 implementation: write metadata into a hidden sheet inside
+    chart's embedded xlsx workbook. Preserves the exact byte layout of the
+    legacy ``_write_embedded_metadata`` so round-trip parsers stay happy."""
+    try:
+        from openpyxl import load_workbook
+
+        chart_part = chart.part
+        xlsx_part = chart_part.chart_workbook.xlsx_part
+        xlsx_stream = io.BytesIO(xlsx_part.blob)
+        wb = load_workbook(xlsx_stream)
+
+        if METADATA_SHEET_NAME in wb.sheetnames:
+            del wb[METADATA_SHEET_NAME]
+
+        ws = wb.create_sheet(METADATA_SHEET_NAME)
+        ws.sheet_state = "hidden"
+        ws["A1"] = "schema_version"
+        ws["B1"] = METADATA_SCHEMA_VERSION
+        ws["A2"] = "categories_col"
+        ws["B2"] = categories_col
+        ws["A3"] = "series_count"
+        ws["B3"] = len(series_config)
+        ws["A4"] = "chart_family"
+        ws["B4"] = chart_family
+        ws["A5"] = "chart_metadata_json"
+        # Legacy parity: the json blob is the full ``extra`` dict (which in
+        # practice already carries chart_family); we don't add a second copy.
+        ws["B5"] = json.dumps(extra, ensure_ascii=False) if extra else None
+        ws.append([])
+        ws.append([
+            "series_index", "key", "name", "type",
+            "axis", "grouping", "x_key", "size_key",
+        ])
+
+        for index, series in enumerate(series_config):
+            ws.append([
+                index,
+                series.get("key"),
+                series.get("name"),
+                series.get("type"),
+                series.get("axis"),
+                series.get("grouping"),
+                series.get("x_key"),
+                series.get("size_key"),
+            ])
+
+        output_stream = io.BytesIO()
+        wb.save(output_stream)
+        xlsx_part._blob = output_stream.getvalue()
+
+    except Exception as e:
+        print(f"  ⚠️ 写入图表元数据失败: {e}")

ablechart/oxml/__init__.py

@@ -0,0 +1,22 @@
+"""
+OXML 包 - 底层 XML 操作
+
+这个包负责所有的 lxml 操作，不关心业务逻辑（主轴/次轴）。
+只知道如何根据指令创建标准的 OOXML 结构。
+"""
+
+from .axes import extract_axis_ids, create_value_axis, optimize_axis_labels, optimize_category_axis
+from .plots import create_plot_element, add_axis_refs, add_plot_categories
+from .series import add_series_to_plot
+
+__all__ = [
+    'extract_axis_ids',
+    'create_value_axis',
+    'optimize_axis_labels',
+    'optimize_category_axis',
+    'create_plot_element',
+    'add_axis_refs',
+    'add_plot_categories',
+    'add_series_to_plot',
+]
+

ablechart/oxml/axes.py

@@ -0,0 +1,219 @@
+"""
+坐标轴 XML 操作模块
+
+负责创建、提取和优化坐标轴元素。
+"""
+
+from lxml import etree
+from typing import Tuple
+
+from .._log import debug_print as print
+from ..oxml_ns import NAMESPACES
+
+
+def extract_axis_ids(plotArea) -> Tuple[int, int]:
+    """
+    提取现有坐标轴的 ID
+    
+    Args:
+        plotArea: 绘图区元素 (lxml Element)
+        
+    Returns:
+        (cat_ax_id, val_ax_id) 元组
+        
+    Raises:
+        ValueError: 如果无法找到坐标轴 ID
+    """
+    # python-pptx 的 BaseOxmlElement.xpath() 已经注册了命名空间
+    cat_ax_elements = plotArea.xpath('.//c:catAx/c:axId')
+    val_ax_elements = plotArea.xpath('.//c:valAx/c:axId')
+    
+    if cat_ax_elements and val_ax_elements:
+        cat_ax_id = int(cat_ax_elements[0].get('val'))
+        val_ax_id = int(val_ax_elements[0].get('val'))
+        return cat_ax_id, val_ax_id
+
+    if len(val_ax_elements) >= 2:
+        x_axis_id = int(val_ax_elements[0].get('val'))
+        y_axis_id = int(val_ax_elements[1].get('val'))
+        return x_axis_id, y_axis_id
+
+    raise ValueError("无法找到现有坐标轴 ID")
+
+
+def create_value_axis(
+    plotArea,
+    ax_id: int,
+    cross_ax_id: int,
+    position: str = 'r',
+    tick_label_position: str = 'high',
+    crosses_at: str = 'max',
+) -> int:
+    """
+    创建一个新的值轴 (Y轴)
+    
+    Args:
+        plotArea: 绘图区元素 (lxml Element)
+        ax_id: 新轴的 ID
+        cross_ax_id: 交叉轴的 ID（通常是分类轴）
+        position: 轴位置 ('l'=左, 'r'=右, 't'=顶, 'b'=底)
+        tick_label_position: 标签位置 ('low'=左/底, 'high'=右/顶, 'nextTo'=靠近轴)
+        crosses_at: 交叉位置 ('min'=最小值/左边, 'max'=最大值/右边)
+        
+    Returns:
+        创建的轴 ID
+        
+    Notes:
+        - 严格按照 OOXML 规范 (ISO/IEC 29500-1:2016) 的元素顺序
+        - 'low' 和 'high' 用于双轴图，确保标签不重叠
+        - crosses_at='min' 让轴线在图表左边，'max' 让轴线在图表右边
+    """
+    # 创建值轴元素
+    valAx = etree.SubElement(plotArea, f"{{{NAMESPACES['c']}}}valAx")
+    
+    # ⭐ 严格按照 OOXML 规范顺序添加子元素
+    
+    # 1. axId (轴 ID) - 必需
+    axId_elem = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}axId")
+    axId_elem.set('val', str(ax_id))
+    
+    # 2. scaling (缩放) - 必需
+    scaling = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}scaling")
+    orientation = etree.SubElement(scaling, f"{{{NAMESPACES['c']}}}orientation")
+    orientation.set('val', 'minMax')
+    
+    # 3. delete (是否隐藏) - 必需
+    delete = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}delete")
+    delete.set('val', '0')
+    
+    # 4. axPos (轴位置) - 必需
+    axPos = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}axPos")
+    axPos.set('val', position)
+    
+    # 5. majorGridlines (主网格线) - 可选
+    # 次轴通常不显示网格线，避免与主轴重叠
+    # 如果需要，调用方可以手动添加
+    
+    # 6. numFmt (数字格式) - 可选
+    numFmt = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}numFmt")
+    numFmt.set('formatCode', 'General')
+    numFmt.set('sourceLinked', '0')
+    
+    # 7. majorTickMark (主刻度线) - 可选
+    majorTickMark = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}majorTickMark")
+    majorTickMark.set('val', 'out')
+    
+    # 8. minorTickMark (次刻度线) - 可选
+    minorTickMark = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}minorTickMark")
+    minorTickMark.set('val', 'none')
+    
+    # 9. tickLblPos (标签位置) - 可选
+    tickLblPos = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}tickLblPos")
+    tickLblPos.set('val', tick_label_position)
+    
+    # 10. crossAx (交叉轴 ID) - 必需
+    crossAx = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}crossAx")
+    crossAx.set('val', str(cross_ax_id))
+    
+    # 11. crosses (交叉方式) - 可选
+    # ⭐ 关键修复：根据 crosses_at 参数决定交叉位置
+    # 'min' = 在最小值（左边）交叉，'max' = 在最大值（右边）交叉
+    crosses = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}crosses")
+    crosses.set('val', crosses_at)
+    
+    # 12. crossBetween (交叉位置) - 可选
+    crossBetween = etree.SubElement(valAx, f"{{{NAMESPACES['c']}}}crossBetween")
+    crossBetween.set('val', 'between')
+    
+    return ax_id
+
+
+def optimize_axis_labels(
+    plotArea,
+    ax_id: int,
+    tick_label_position: str = 'low',
+    crosses_at: str = 'min',
+    remove_gridlines: bool = True,
+):
+    """
+    优化现有轴的标签位置和交叉位置
+    
+    Args:
+        plotArea: 绘图区元素
+        ax_id: 要优化的轴 ID
+        tick_label_position: 标签位置 ('low'=左/底, 'high'=右/顶)
+        crosses_at: 交叉位置 ('min'=最小值/左边, 'max'=最大值/右边)
+        remove_gridlines: 是否移除网格线（默认移除）
+        
+    Notes:
+        主要用于优化主值轴，使其与次值轴协调
+        crosses_at='min' 让主轴线在图表左边，'max' 让次轴线在图表右边
+    """
+    # 查找指定的值轴
+    val_ax_elements = plotArea.xpath(f'.//c:valAx[c:axId[@val="{ax_id}"]]')
+    if not val_ax_elements:
+        return  # 轴不存在，跳过
+    
+    val_ax = val_ax_elements[0]
+    
+    # ⭐ 设置 crosses 位置
+    crosses_elements = val_ax.xpath('./c:crosses')
+    if crosses_elements:
+        crosses_elements[0].set('val', crosses_at)
+    
+    # 设置标签位置
+    tickLblPos_elements = val_ax.xpath('./c:tickLblPos')
+    if tickLblPos_elements:
+        tickLblPos_elements[0].set('val', tick_label_position)
+    else:
+        # 如果不存在，创建一个
+        tickLblPos = etree.Element(f"{{{NAMESPACES['c']}}}tickLblPos")
+        tickLblPos.set('val', tick_label_position)
+        # 插入到 crossAx 之前（保持正确顺序）
+        cross_ax_elements = val_ax.xpath('./c:crossAx')
+        if cross_ax_elements:
+            cross_ax_elements[0].addprevious(tickLblPos)
+    
+    # ⭐ 移除网格线（取消内部横框）
+    if remove_gridlines:
+        gridlines = val_ax.xpath('./c:majorGridlines')
+        for gridline in gridlines:
+            val_ax.remove(gridline)
+            print(f"  → 已移除主值轴网格线")
+
+
+def optimize_category_axis(
+    plotArea,
+    cat_ax_id: int,
+    remove_tick_marks: bool = True,
+):
+    """
+    优化分类轴（X轴）的显示
+    
+    Args:
+        plotArea: 绘图区元素
+        cat_ax_id: 分类轴 ID
+        remove_tick_marks: 是否移除主刻度线（默认移除，即取消日期间的小竖线）
+        
+    Notes:
+        用于清理分类轴的视觉元素，让图表更简洁
+    """
+    # 查找分类轴
+    cat_ax_elements = plotArea.xpath(f'.//c:catAx[c:axId[@val="{cat_ax_id}"]]')
+    if not cat_ax_elements:
+        return  # 轴不存在，跳过
+    
+    cat_ax = cat_ax_elements[0]
+    
+    # ⭐ 移除或设置主刻度线为 'none'（取消日期间的小竖线）
+    if remove_tick_marks:
+        majorTickMark_elements = cat_ax.xpath('./c:majorTickMark')
+        if majorTickMark_elements:
+            # 修改为 'none' 而不是删除元素
+            majorTickMark_elements[0].set('val', 'none')
+            print(f"  → 已移除分类轴主刻度线（日期间的小竖线）")
+        
+        # 同时也设置次刻度线为 'none'
+        minorTickMark_elements = cat_ax.xpath('./c:minorTickMark')
+        if minorTickMark_elements:
+            minorTickMark_elements[0].set('val', 'none')