ablechart 0.1.0__py3-none-any.whl

ablechart/builder.py

@@ -0,0 +1,370 @@
+"""
+图表构建器 - 有状态的编排器
+
+这是重构后的核心，使用有状态的构建器模式来编排 oxml 层的调用。
+解决 P(n,2) 组合爆炸问题。
+"""
+
+from typing import List, Dict, Optional
+from pptx.chart.chart import Chart
+import pandas as pd
+from collections import defaultdict
+
+from ._log import debug_print as print
+from .oxml import (
+    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,
+)
+
+# 导入样式模块
+try:
+    from .styles import DEFAULT_STYLE_CONFIG
+except ImportError:
+    # 如果样式模块不存在，设置为 None
+    DEFAULT_STYLE_CONFIG = None
+
+
+class ChartBuilder:
+    """
+    有状态的图表构建器
+    
+    职责：
+    1. 管理坐标轴（主轴/次轴）
+    2. 按 (type, axis) 分组系列
+    3. 委托 oxml 层创建 XML 元素
+    
+    优势：
+    - 解决 P(n,2) 组合问题：不需要为每种组合写代码
+    - 只需为每种图表类型实现一次 XML 生成
+    - 主函数动态组合它们
+    """
+    
+    def __init__(self, chart: Chart, df: pd.DataFrame, categories_col: str, style_config=None, layout_config=None, polish: bool = True, date_format: str = None, orientation: str = 'vertical'):
+        """
+        初始化构建器
+        
+        Args:
+            chart: python-pptx 创建的基础图表（用于激活 XML 结构）
+            df: 数据源 DataFrame
+            categories_col: 分类列名
+            style_config: 样式配置对象（可选，默认使用 DEFAULT_STYLE_CONFIG）
+            layout_config: 布局配置对象（可选，包含图例、轴配置）
+        """
+        self.chart = chart
+        self.df = df
+        self.categories_col = categories_col
+        self.style_config = style_config if style_config is not None else DEFAULT_STYLE_CONFIG
+        self.layout_config = layout_config  # 布局配置
+        self.polish = polish  # 报告级收尾处理
+        self.date_format = date_format  # 日期分类的 strftime 格式（如 '%Y/%m'）
+        self.orientation = orientation  # 'vertical' | 'horizontal'（条形图）
+        
+        # 访问 XML 结构
+        self.chartSpace = chart._chartSpace
+        self.plotArea = self.chartSpace.plotArea
+        
+        # 提取现有坐标轴 ID
+        self.cat_ax_id, self.pri_val_ax_id = extract_axis_ids(self.plotArea)
+        self.sec_val_ax_id = None
+        
+        # 系列计数器（用于 Excel 列索引）
+        self._series_counter = 0
+        
+        print(f"\n📊 ChartBuilder 初始化完成")
+        print(f"  - 分类轴 ID: {self.cat_ax_id}")
+        print(f"  - 主值轴 ID: {self.pri_val_ax_id}")
+        if self.style_config is not None:
+            print(f"  - 样式配置: 已启用")
+        else:
+            print(f"  - 样式配置: 默认")
+        if self.layout_config is not None:
+            print(f"  - 布局配置: 已启用")
+    
+    def ensure_secondary_axis(self) -> int:
+        """
+        确保次值轴存在（只创建一次）
+        
+        Returns:
+            次值轴 ID
+        """
+        if self.sec_val_ax_id is None:
+            # 生成新的轴 ID
+            new_ax_id = max(self.cat_ax_id, self.pri_val_ax_id) + 1000
+            
+            # ⭐ 创建次值轴（右侧，标签在右边，crosses='max'）
+            self.sec_val_ax_id = create_value_axis(
+                self.plotArea,
+                ax_id=new_ax_id,
+                cross_ax_id=self.cat_ax_id,
+                position='r',
+                tick_label_position='high',
+                crosses_at='max'  # 右轴线在图表右边
+            )
+            
+            # ⭐ 优化主值轴（左侧，标签在左边，crosses='min'，移除网格线）
+            optimize_axis_labels(
+                self.plotArea,
+                self.pri_val_ax_id,
+                tick_label_position='low',
+                crosses_at='min',  # 左轴线在图表左边
+                remove_gridlines=True  # 移除内部横框
+            )
+            
+            # ⭐ 优化分类轴（移除日期间的小竖线）
+            optimize_category_axis(
+                self.plotArea,
+                self.cat_ax_id,
+                remove_tick_marks=True  # 移除底部日期间的小竖线
+            )
+            
+            print(f"\n⭐ 次值轴已创建")
+            print(f"  - 次值轴 ID: {self.sec_val_ax_id}")
+            print(f"  - 位置: 右侧 (position='r', crosses='max')")
+            print(f"  - 标签: 右侧 (tickLblPos='high')")
+            print(f"  - 主值轴已优化: 左侧 (tickLblPos='low', crosses='min')")
+        
+        return self.sec_val_ax_id
+    
+    def clear_bootstrap_chart(self):
+        """
+        清理引导时创建的图表元素
+        
+        Note: 
+            使用 python-pptx 创建基础图表时，会自动创建一个图表元素。
+            我们需要清理它，以便完全通过 XML 自定义。
+        """
+        # 查找并删除 python-pptx 自动创建的图表元素
+        # 这些通常是 <c:barChart>, <c:lineChart> 等
+        
+        # 获取所有可能的图表类型元素
+        chart_types = ['barChart', 'lineChart', 'areaChart', 'scatterChart', 'bubbleChart', 'pieChart']
+        
+        for chart_type in chart_types:
+            # 查找所有该类型的图表元素
+            elements = self.plotArea.xpath(f'./c:{chart_type}')
+            for elem in elements:
+                # 删除这个元素
+                self.plotArea.remove(elem)
+                print(f"  → 清理引导图表元素: <c:{chart_type}>")
+        
+        print(f"  → 引导图表已清理")
+    
+    def add_plot(self, series_group: List[Dict], plot_order_index: int = 0):
+        """
+        添加一组系列（同类型、同轴）
+        
+        Args:
+            series_group: 系列配置列表
+                [
+                    {"key": "col1", "name": "系列1", "type": "bar", "axis": "primary"},
+                    {"key": "col2", "name": "系列2", "type": "bar", "axis": "primary"}
+                ]
+            plot_order_index: 绘图顺序索引（0=最底层，1=上一层，依此类推）
+                
+        Notes:
+            - 组内所有系列必须有相同的 type 和 axis
+            - 会创建一个新的绘图元素 (<c:barChart>, <c:lineChart> 等)
+            - 并为每个系列添加 <c:ser> 元素
+        """
+        if not series_group:
+            return
+        
+        # 从第一个系列获取共享属性
+        first_cfg = series_group[0]
+        chart_type = first_cfg.get("type", "bar")
+        axis_type = first_cfg.get("axis", "primary")
+        grouping = first_cfg.get("grouping")
+        
+        # 决定使用哪个值轴
+        if axis_type == 'primary':
+            val_ax_id = self.pri_val_ax_id
+        elif axis_type == 'secondary':
+            val_ax_id = self.ensure_secondary_axis()
+        else:
+            raise ValueError(f"未知的轴类型: {axis_type}")
+        
+        print(f"\n➕ 添加绘图组: type={chart_type}, axis={axis_type}, order={plot_order_index}")
+        print(f"  - 使用值轴 ID: {val_ax_id}")
+        
+        # 创建绘图元素（不包含轴引用）
+        plot_element = create_plot_element(
+            self.plotArea,
+            chart_type,
+            self.cat_ax_id,
+            val_ax_id,
+            order_index=plot_order_index,  # ⭐ 传递 order_index
+            grouping=grouping,
+            bar_dir='bar' if self.orientation == 'horizontal' else 'col',
+        )
+        
+        # ⭐ 新方案：不在 plot 级别添加共享分类数据
+        # 每个系列有自己的 <c:cat> 元素，避免重复
+        # categories = self.df[self.categories_col].tolist()
+        # add_plot_categories(plot_element, categories)
+        # print(f"  - 添加共享分类数据（{len(categories)} 个分类）")
+        
+        # 为每个系列添加 <c:ser>
+        for series_cfg in series_group:
+            add_series_to_plot(
+                plot_element,
+                chart_type,
+                series_cfg,
+                self._series_counter,
+                self.df,
+                self.categories_col,
+                self.style_config,  # ⭐ 传递样式配置
+                date_format=self.date_format,
+            )
+            print(f"  - 添加系列: '{series_cfg['name']}' (索引 {self._series_counter})")
+            self._series_counter += 1
+        
+        # ⭐ 关键修复：在所有系列添加完成后，再添加轴引用
+        # 确保 XML 元素顺序正确：<c:cat> <c:ser> ... <c:ser> <c:axId> <c:axId>
+        add_axis_refs(plot_element, self.cat_ax_id, val_ax_id)
+        print(f"  - 添加轴引用: cat_ax={self.cat_ax_id}, val_ax={val_ax_id}")
+    
+    def build(self, series_config: List[Dict]):
+        """
+        构建完整的组合图
+        
+        Args:
+            series_config: 系列配置列表
+                [
+                    {"key": "col1", "name": "系列1", "type": "bar", "axis": "primary"},
+                    {"key": "col2", "name": "系列2", "type": "line", "axis": "secondary"},
+                ]
+                
+        Returns:
+            构建后的 Chart 对象
+        """
+        print("\n" + "=" * 80)
+        print("🔨 开始构建组合图")
+        print("=" * 80)
+        
+        # 1. 按 (type, axis) 分组
+        plot_groups = self._group_series(series_config)
+        
+        print(f"\n📦 系列分组结果:")
+        for key, group in plot_groups.items():
+            print(f"  - {key}: {len(group)} 个系列")
+        
+        # 2. 清理引导图表（可选）
+        self.clear_bootstrap_chart()
+        
+        # 3. ⭐ 按堆叠顺序添加绘图组
+        # 规则：先添加的绘图组在底层，后添加的在上层
+        # 策略：先画"背景"（柱状图/面积图），再画"前景"（折线图/散点图）
+        plot_order_counter = 0
+        
+        # 3.1 先添加所有"背景"图表 (bar, area, bubble)
+        for (plot_type, axis_type, grouping), series_group in plot_groups.items():
+            if plot_type in ('bar', 'column', 'area', 'bubble'):
+                self.add_plot(series_group, plot_order_counter)
+                plot_order_counter += 1
+        
+        # 3.2 再添加所有"前景"图表 (line, scatter)
+        for (plot_type, axis_type, grouping), series_group in plot_groups.items():
+            if plot_type in ('line', 'scatter'):
+                self.add_plot(series_group, plot_order_counter)
+                plot_order_counter += 1
+        
+        # 4. ⭐ 应用布局配置（图例、轴格式等）
+        if self.layout_config is not None:
+            self.layout_config.apply_to_chart(self.chart)
+
+        # ⭐ 单系列时渲染器会在 autoTitleDeleted≠1 时自动生成"系列名"大标题
+        # → 未显式配置标题则无条件关闭（写入 <c:autoTitleDeleted val="1"/>）
+        if self.layout_config is None or not getattr(self.layout_config, "title", None):
+            self.chart.has_title = False
+
+        # 5. ⭐ ChartJunkCleaner: 自动清洗默认 PPT 样式
+        try:
+            from .cleaner import clean_chart
+            clean_chart(self.chart)
+            print(f"  → ChartJunkCleaner applied")
+        except Exception as e:
+            print(f"  → ChartJunkCleaner skipped: {e}")
+
+        # 6. ⭐ 报告级收尾：智能轴范围、双轴对齐、柱宽、排版降噪
+        if self.polish:
+            try:
+                from .polish import polish_combo_chart
+                skip_primary = (
+                    self.layout_config is not None
+                    and self.layout_config.value_axis_config is not None
+                    and (self.layout_config.value_axis_config.min_value is not None
+                         or self.layout_config.value_axis_config.max_value is not None)
+                )
+                skip_secondary = (
+                    self.layout_config is not None
+                    and self.layout_config.secondary_value_axis_config is not None
+                    and (self.layout_config.secondary_value_axis_config.min_value is not None
+                         or self.layout_config.secondary_value_axis_config.max_value is not None)
+                )
+                def _text_pref(cfg):
+                    if cfg is None or not getattr(cfg, "font_name", None):
+                        return None
+                    return (cfg.font_name, cfg.font_size_pt or 9)
+
+                lc = self.layout_config
+                polish_combo_chart(
+                    self.chart,
+                    self.df,
+                    self.categories_col,
+                    series_config,
+                    skip_primary_scale=skip_primary,
+                    skip_secondary_scale=skip_secondary,
+                    cat_text=_text_pref(lc.category_axis_config) if lc else None,
+                    val_text=_text_pref(lc.value_axis_config) if lc else None,
+                    sec_text=_text_pref(lc.secondary_value_axis_config) if lc else None,
+                )
+                print(f"  → polish applied")
+            except Exception as e:
+                print(f"  → polish skipped: {e}")
+
+        print("\n" + "=" * 80)
+        print("✅ 组合图构建完成！")
+        print("=" * 80)
+
+        return self.chart
+    
+    @staticmethod
+    def _group_series(series_config: List[Dict]) -> Dict[tuple, List[Dict]]:
+        """
+        按 (type, axis) 分组系列
+        
+        Args:
+            series_config: 系列配置列表
+            
+        Returns:
+            分组后的字典 {(type, axis): [series_cfg, ...]}
+            
+        Examples:
+            输入:
+            [
+                {"key": "s1", "type": "bar", "axis": "primary"},
+                {"key": "s2", "type": "bar", "axis": "primary"},
+                {"key": "s3", "type": "line", "axis": "secondary"},
+            ]
+            
+            输出:
+            {
+                ("bar", "primary"): [{"key": "s1", ...}, {"key": "s2", ...}],
+                ("line", "secondary"): [{"key": "s3", ...}]
+            }
+        """
+        groups = defaultdict(list)
+        for cfg in series_config:
+            key = (
+                cfg.get("type", "bar"),
+                cfg.get("axis", "primary"),
+                cfg.get("grouping"),
+            )
+            groups[key].append(cfg)
+        return dict(groups)

ablechart/cleaner.py

@@ -0,0 +1,144 @@
+"""ChartJunkCleaner — 自动清洗图表，去除默认 PPT 味
+
+在 ChartBuilder.build() 完成后自动执行：
+- 移除图表外边框
+- Y 轴网格线 -> 极浅虚线或隐藏
+- 坐标轴刻度线 -> inside 或 none
+- 图例框边框 -> 移除
+- 默认线宽 -> 1.5pt
+"""
+
+from lxml import etree
+
+from .oxml_ns import NAMESPACES
+from .tokens import get_chart_token  # 颜色真源
+
+
+class ChartJunkCleaner:
+    """清洗图表默认样式，向 JP 标准靠拢"""
+
+    # 网格线色取自 tokens.CHART_TOKENS["gridline"]（渲染时读取）
+    GRID_WIDTH = 6350     # 0.5pt in EMUs
+    LINE_WIDTH = 19050    # 1.5pt in EMUs
+
+    def __init__(self, chart):
+        self.chart = chart
+        self.chartSpace = chart._chartSpace
+        self.plotArea = self.chartSpace.plotArea
+
+    def clean(self):
+        """执行全部清洗步骤"""
+        self._remove_chart_border()
+        self._clean_gridlines()
+        self._clean_tick_marks()
+        self._clean_legend_border()
+        self._clean_plot_area_border()
+        return self.chart
+
+    def _remove_chart_border(self):
+        """移除图表外边框"""
+        spPr = self.chartSpace.find('c:spPr', namespaces=NAMESPACES)
+        if spPr is None:
+            spPr = etree.SubElement(self.chartSpace, f"{{{NAMESPACES['c']}}}spPr")
+
+        # 移除线条
+        ln = spPr.find('a:ln', namespaces=NAMESPACES)
+        if ln is not None:
+            spPr.remove(ln)
+        ln = etree.SubElement(spPr, f"{{{NAMESPACES['a']}}}ln")
+        etree.SubElement(ln, f"{{{NAMESPACES['a']}}}noFill")
+
+    def _clean_gridlines(self):
+        """将 Y 轴网格线设为极浅虚线或隐藏"""
+        # 处理所有值轴的主要网格线
+        for axis_tag in ['valAx', 'catAx']:
+            for axis in self.plotArea.findall(f'c:{axis_tag}', namespaces=NAMESPACES):
+                major_gl = axis.find('c:majorGridlines', namespaces=NAMESPACES)
+                if major_gl is not None:
+                    self._set_light_gridline(major_gl)
+
+                # 移除次要网格线
+                minor_gl = axis.find('c:minorGridlines', namespaces=NAMESPACES)
+                if minor_gl is not None:
+                    axis.remove(minor_gl)
+
+    def _set_light_gridline(self, gridline_elem):
+        """将网格线设为极浅灰色虚线"""
+        # 清除现有 spPr
+        spPr = gridline_elem.find('c:spPr', namespaces=NAMESPACES)
+        if spPr is not None:
+            gridline_elem.remove(spPr)
+
+        spPr = etree.SubElement(gridline_elem, f"{{{NAMESPACES['c']}}}spPr")
+        ln = etree.SubElement(spPr, f"{{{NAMESPACES['a']}}}ln")
+        ln.set('w', str(self.GRID_WIDTH))
+
+        # 颜色
+        solidFill = etree.SubElement(ln, f"{{{NAMESPACES['a']}}}solidFill")
+        srgbClr = etree.SubElement(solidFill, f"{{{NAMESPACES['a']}}}srgbClr")
+        srgbClr.set('val', get_chart_token("gridline"))
+
+        # 虚线样式
+        prstDash = etree.SubElement(ln, f"{{{NAMESPACES['a']}}}prstDash")
+        prstDash.set('val', 'dot')
+
+    def _clean_tick_marks(self):
+        """坐标轴刻度线 -> none"""
+        for axis_tag in ['valAx', 'catAx']:
+            for axis in self.plotArea.findall(f'c:{axis_tag}', namespaces=NAMESPACES):
+                # 主刻度线
+                major_tick = axis.find('c:majorTickMark', namespaces=NAMESPACES)
+                if major_tick is not None:
+                    major_tick.set('val', 'none')
+                else:
+                    mt = etree.SubElement(axis, f"{{{NAMESPACES['c']}}}majorTickMark")
+                    mt.set('val', 'none')
+
+                # 次刻度线
+                minor_tick = axis.find('c:minorTickMark', namespaces=NAMESPACES)
+                if minor_tick is not None:
+                    minor_tick.set('val', 'none')
+                else:
+                    mt = etree.SubElement(axis, f"{{{NAMESPACES['c']}}}minorTickMark")
+                    mt.set('val', 'none')
+
+    def _clean_legend_border(self):
+        """移除图例框边框"""
+        legend = self.chartSpace.find('.//c:legend', namespaces=NAMESPACES)
+        if legend is None:
+            return
+
+        spPr = legend.find('c:spPr', namespaces=NAMESPACES)
+        if spPr is None:
+            spPr = etree.SubElement(legend, f"{{{NAMESPACES['c']}}}spPr")
+
+        # 移除线条
+        ln = spPr.find('a:ln', namespaces=NAMESPACES)
+        if ln is not None:
+            spPr.remove(ln)
+        ln = etree.SubElement(spPr, f"{{{NAMESPACES['a']}}}ln")
+        etree.SubElement(ln, f"{{{NAMESPACES['a']}}}noFill")
+
+        # 移除填充
+        for fill_tag in ['solidFill', 'gradFill', 'pattFill']:
+            fill = spPr.find(f'a:{fill_tag}', namespaces=NAMESPACES)
+            if fill is not None:
+                spPr.remove(fill)
+        etree.SubElement(spPr, f"{{{NAMESPACES['a']}}}noFill")
+
+    def _clean_plot_area_border(self):
+        """移除 plotArea 边框"""
+        spPr = self.plotArea.find('c:spPr', namespaces=NAMESPACES)
+        if spPr is None:
+            spPr = etree.SubElement(self.plotArea, f"{{{NAMESPACES['c']}}}spPr")
+
+        ln = spPr.find('a:ln', namespaces=NAMESPACES)
+        if ln is not None:
+            spPr.remove(ln)
+        ln = etree.SubElement(spPr, f"{{{NAMESPACES['a']}}}ln")
+        etree.SubElement(ln, f"{{{NAMESPACES['a']}}}noFill")
+
+
+def clean_chart(chart):
+    """便捷函数: 对 chart 执行全部清洗"""
+    return ChartJunkCleaner(chart).clean()