xllayout 1.0.0

Composable framework for building styled Excel reports with openpyxl and matplotlib.

xllayout

Composable framework to build styled Excel reports with openpyxl and matplotlib.

Philosophy

xllayout is split into three layers:

1. Theme: centralized visual tokens (fonts, fills, borders, number formats, spacing).
2. Components: reusable blocks (TitleBlock, KpiCard, TableBlock, MatplotlibChart, etc.).
3. Layouts: sheet composition using absolute canvas coordinates or Grid12.

This lets you place components at any coordinate without relying on cursor-based writing.

Structure

xllayout/
  pyproject.toml
  xllayout/
    __init__.py
    core/
      canvas.py
      grid.py
      theme.py
      formats.py
      utils.py
    components/
      title.py
      text.py
      section.py
      kpi.py
      table.py
      chart.py
    layouts/
      summary.py
    writer/
      workbook.py
  examples/
    build_summary.py

Install

Editable (recommended for development):

pip install -e ".[charts]"

Standard install:

pip install ".[charts]"

• Base dependency: openpyxl
• Optional extra charts: matplotlib, Pillow

Quick API

from xllayout.core.theme import LightTheme
from xllayout.layouts.summary import ExecutiveSummaryData
from xllayout.writer.workbook import ReportWriter

writer = ReportWriter(theme=LightTheme(), detect_collisions=True)
wb = writer.new_workbook()
writer.build_summary_sheet(wb, data)  # data: ExecutiveSummaryData
wb.save("report.xlsx")

Canvas vs Grid12

Absolute placement:

from xllayout.core.canvas import SheetCanvas

canvas = SheetCanvas(ws, theme, detect_collisions=True)
canvas.put(component, row=5, col=3)

Grid placement:

from xllayout.core.grid import Grid12

grid = Grid12(canvas)  # 12 tracks
grid.put(component, y=4, x=1, w=6, h=5)

If detect_collisions=True, overlapping components raise ValueError.

Build a New Layout

1. Create a typed input dataclass under layouts/.
2. In build(ws), initialize SheetCanvas and optionally Grid12.
3. Place components with canvas.put(...) or grid.put(...).
4. Expose a facade method in ReportWriter.

Run the example

python examples/build_summary.py

Output:

examples/output/summary_report_example.xlsx

Versioning and publishing

• Uses SemVer (1.0.0, 1.0.1, 1.1.0, ...).
• Recommended for teams: publish to a private PyPI-compatible registry.