Metadata-Version: 2.4
Name: ablechart
Version: 0.1.0
Summary: Editable PowerPoint chart engine for dual-axis financial charts
Author: ablechart contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/hanlinlibham/ablechart
Project-URL: Repository, https://github.com/hanlinlibham/ablechart
Project-URL: Issues, https://github.com/hanlinlibham/ablechart/issues
Project-URL: Changelog, https://github.com/hanlinlibham/ablechart/blob/main/CHANGELOG.md
Keywords: powerpoint,pptx,charts,finance,openxml
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-pptx<1.1,>=1.0.2
Requires-Dist: pandas<3,>=2.2
Requires-Dist: numpy<2,>=1.26
Requires-Dist: lxml<6,>=5
Requires-Dist: openpyxl<4,>=3.1
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: tomli; python_version < "3.11" and extra == "test"
Dynamic: license-file

# 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.

![Dual-axis combo chart generated by ablechart](https://raw.githubusercontent.com/hanlinlibham/ablechart/main/docs/assets/hero-combo.png)

*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

```bash
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:

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

## Quickstart

### Create an editable combo chart

```python
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

```python
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

```python
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

| Family | Entry point | Notes |
| --- | --- | --- |
| Combo | `create_combo_chart()` | Bar, line, area, stacked, percent-stacked, dual-axis, date-axis presets |
| Waterfall | `create_waterfall_chart()` | Editable bridge chart with total and relative measures |
| Scatter | `create_scatter_chart()` | Native scatter chart with parse helpers |
| Bubble | `create_bubble_chart()` | Native bubble chart with parse helpers |
| Range snapshot | `create_range_snapshot_chart()` | Valuation range snapshot with min/max/average/current markers |

![ablechart chart families gallery](https://raw.githubusercontent.com/hanlinlibham/ablechart/main/docs/assets/gallery.png)

*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:

| Lifecycle | Representative APIs |
| --- | --- |
| Create | `create_combo_chart()`, `create_waterfall_chart()`, `create_semantic_chart()` |
| Parse | `parse_chart_from_pptx()`, `parse_all_charts_from_pptx()`, `get_semantic_chart_spec()` |
| Metadata | `ChartMetadataV1`, `write_chart_metadata`, `METADATA_SCHEMA_VERSION` |
| Inspect | `inspect_pptx_charts()`, `ChartInventoryItem`, `ChartSelector` |
| Replace | `replace_pptx_chart_data()`, `SeriesData`, `ReplaceResult` |

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.

| Project | Main strength | How `ablechart` differs |
| --- | --- | --- |
| [`python-pptx`](https://python-pptx.readthedocs.io/en/latest/user/charts.html) | General Python library for creating and updating `.pptx` files, including adding charts and replacing chart data. | `ablechart` builds on the PowerPoint-native path but adds financial chart families, semantic metadata, chart round-trip parsing, inventory, and template-safe replacement contracts. |
| [`PptxGenJS`](https://gitbrent.github.io/PptxGenJS/) | Broad JavaScript presentation generation for Node.js, browser, React, Electron, charts, tables, images, and HTML-to-PPTX workflows. | `ablechart` is Python-only and intentionally narrower: it does not generate full decks from layouts, but focuses on editable chart assets and parse/update lifecycles. |
| [`mschart`](https://ardata-fr.github.io/mschart/) | R package for native editable Microsoft Office charts, commonly used with `officer`. | `ablechart` targets Python financial-report workflows and adds inspect/replace and metadata round-trip APIs for existing `.pptx` chart assets. |
| [`Aspose.Slides for Python via .NET`](https://docs.aspose.com/slides/python-net/) | Commercial, full-featured presentation processing SDK with broad PowerPoint manipulation, chart modules, export, animation, SmartArt, VBA, and conversion features. | `ablechart` is MIT-licensed and much smaller. It does not aim to cover the whole PowerPoint object model or rendering/export conversion. |
| [`Spire.Presentation for Python`](https://www.e-iceblue.com/Introduce/presentation-for-python.html) | Commercial presentation API covering creation, editing, conversion, and chart operations. | `ablechart` avoids broad document processing scope and concentrates on deterministic chart creation, chart metadata, and safe data replacement. |

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.

## Development

Run the test suite:

```bash
python -m pytest
```

Build the distribution artifacts:

```bash
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](./LICENSE).
