ablechart

ablechart

ablechart is a focused Python SDK for creating, inspecting, parsing, and updating editable PowerPoint chart assets.

It is built for workflows where a chart must stay a real PowerPoint chart, not a screenshot:

• editable in Microsoft PowerPoint after generation
• backed by an embedded workbook
• able to carry semantic metadata for round-trip parsing
• replaceable in an existing .pptx without rebuilding the whole slide
• shaped around financial reporting chart families rather than a generic chart zoo

The project is intentionally narrow. It is a chart asset kernel, not a full presentation generation framework, report builder, template library, or AI slide generator.

A real, editable PowerPoint chart rendered from a .pptx produced by ablechart — stacked columns and two lines on a second value axis, with per-axis number formats. Data: CATL (300750.SZ) FY2019–2024 annual filings (source: Tushare).

Install

pip install ablechart

Python >=3.10 is required.

Core dependencies:

• python-pptx>=1.0.2,<1.1
• pandas>=2.2,<3
• numpy>=1.26,<2
• lxml>=5,<6
• openpyxl>=3.1,<4

For local development:

git clone https://github.com/hanlinlibham/ablechart.git
cd ablechart
pip install -e .
python -m pytest

Quickstart

Create an editable combo chart

import pandas as pd
from pptx import Presentation
from ablechart import create_combo_chart

df = pd.DataFrame(
    {
        "Year": [2021, 2022, 2023, 2024],
        "Revenue": [100, 110, 120, 140],
        "Profit": [10, 12, 15, 18],
    }
)

prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[6])

create_combo_chart(
    slide=slide,
    df=df,
    categories_col="Year",
    series_config=[
        {"key": "Revenue", "name": "Revenue", "type": "bar", "axis": "primary"},
        {"key": "Profit", "name": "Profit", "type": "line", "axis": "secondary"},
    ],
    title="Revenue and profit",
)

prs.save("combo-demo.pptx")

Parse a chart back into data and metadata

from ablechart import parse_chart_from_pptx

df, series_config, chart_type, layout_info = parse_chart_from_pptx("combo-demo.pptx")

print(chart_type)
print(df.head())
print(series_config)

Inspect and update charts in an existing deck

from ablechart import SeriesData, inspect_pptx_charts, replace_pptx_chart_data

inventory = inspect_pptx_charts("template.pptx")
target = next(item for item in inventory if item.replaceable)

result = replace_pptx_chart_data(
    input_pptx="template.pptx",
    output_pptx="updated.pptx",
    selector=target.selector,
    categories=["2026Q1", "2026Q2", "2026Q3"],
    series=[
        SeriesData(name="Revenue", values=[120.0, 132.0, 141.0]),
        SeriesData(name="Cost", values=[82.0, 88.0, 91.0]),
    ],
)

assert result.status == "ok", result.error_detail

What It Supports

Chart families

Each panel is a real, editable PowerPoint chart produced by ablechart, then rendered to an image. Every one can be parsed back into a DataFrame and updated in place. All four use the same real dataset (CATL 300750.SZ, source: Tushare); regenerate with python scripts/make_gallery.py.

Semantic financial families

create_semantic_chart() and the family-specific helpers provide a higher level mapping from financial-report concepts to native chart or shape composition primitives.

Currently exposed families include:

• performance_compare
• distribution_plus_history
• style_box
• style_allocation
• factor_exposure
• score_overlay
• concentration
• event_timeline
• attribution_decomposition
• ranked_tile_matrix
• heatmap_matrix
• table_plus_chart_composite
• factor_attribution_panel
• regime_table_panel
• manager_timeline_profile
• award_timeline_panel
• selection_timing_grid
• dual_chart_panel
• holding_detail

This layer is useful for single-slide financial report components. It is not a report orchestration engine.

Public API Shape

The public API is organized around the chart asset lifecycle:

The design goal is that a generated chart can become a durable asset: created once, opened and edited in PowerPoint, parsed again later, and updated without losing its position, size, identity, or basic editability.

How This Differs From Similar Packages

ablechart is not trying to replace broad PowerPoint SDKs. It is a small layer for high-quality chart assets and template-safe chart updates.

In short:

• Use python-pptx when you need a general Python PowerPoint building block.
• Use PptxGenJS when your stack is JavaScript or browser-side PPTX generation.
• Use Aspose or Spire when you need broad commercial document processing, conversion, or complete PowerPoint object-model coverage.
• Use ablechart when your hard problem is editable, updateable, inspectable PowerPoint charts for data-heavy reports.

Current Limits

ablechart does not currently provide:

• full report assembly
• slide template management
• data connectors
• CLI job orchestration
• PDF or image export
• AI prompt-to-deck generation
• complete coverage of every PowerPoint chart type
• HTML or interactive web output

Unsupported chart replacement cases fail explicitly rather than silently rebuilding the chart. The first-batch replacement path is focused on common embedded-workbook chart types such as bar, line, combo, area, pie, scatter, and bubble charts.

Styling granularity also has known gaps. Supported: legend (5 preset positions), per-axis number format / font / range / gridlines / tick marks (primary and secondary), axis titles (category + both value axes), and tick-label rotation, and hiding a single series from the legend (show_in_legend=False). Not yet implemented: log scale, native display units (thousands / millions), and manual (XY) legend placement.

Development

Run the test suite:

python -m pytest

Build the distribution artifacts:

python -m build --sdist --wheel
python -m twine check dist/*

The repository keeps contract tests for:

• public exports
• generated chart round-trips
• semantic metadata recovery
• existing-deck chart inspection
• in-place chart data replacement
• checked-in .pptx fixture behavior

License

MIT License. See LICENSE.