databloom

Beautiful Excel reports from pandas DataFrames — 18 themes, 9 chart types, smart auto-detection, formula tables, and scheduled generation.

Table of Contents

• Features
• Installation
• Quick Start
• Available Themes
• Customising Themes
• API Reference
• Built-in Datasets
• Development
• License

Features

• Two modes: quick_report(df) one-liner or full Report builder API
• 18 themes: professionally designed color palettes for finance, healthcare, government, tech, creative, and more
• 9 chart types: column, bar, line, pie, doughnut, area, scatter, radar, stock — plus combo charts (bar+line dual Y-axis)
• Smart detection: auto-infers column types, number formats, alignments, chart types, and layout
• Formula tables: append SUM/AVERAGE/MAX/MIN footer rows via native Excel formulas (add_formula_table())
• Scheduled generation: BloomScheduler for daily/weekly/monthly recurring report jobs
• Structured tables: alternating row colors, auto-alignment (numbers right, text left, dates center), freeze panes
• Combo charts: bar/column + line on dual Y-axes — ideal for volume-vs-rate dashboards
• Image insertion: embed PNG/JPG images from local files
• Built-in datasets: 5 business datasets (finance, sales, HR, supply chain) — auto-cached as pickle
• Theme serialization: JSON/YAML-ready to_dict()/from_dict() for team sharing and CI/CD
• Page setup: print configuration (orientation, margins, fit-to-pages, repeat headers)
• Type-safe: full mypy strict-mode annotations, zero runtime surprises

Installation

pip install databloom

With optional scheduler support:

pip install "databloom[scheduler]"

For development:

pip install -e ".[dev]"

Quick Start

Level 1 — One-liner

from databloom import quick_report
import pandas as pd

df = pd.DataFrame({
    "Product": ["Widget A", "Widget B", "Widget C"],
    "Sales": [15000, 23000, 18000],
    "Growth": [0.12, 0.08, 0.15],
})

quick_report(df, output="./output/report.xlsx")

Level 2 — Declarative Builder

from databloom import Report

report = (
    Report(title="Monthly Sales Analysis", theme="business_blue")
    .set_page_setup(orientation="landscape", fit_to_width=1)
    .add_sheet("Overview")
    .add_title("2026 Q3 Sales Overview")
    .add_table(summary_df)
    .add_combo_chart(
        trend_df,
        category_col="Month",
        bar_cols=["Revenue", "Cost"],
        line_cols=["Margin%"],
        bar_title="Revenue & Cost",
        line_title="Margin %",
        title="Revenue vs Margin",
    )
    .add_sheet("Details")
    .add_title("Product Details")
    .add_table(detail_df)
    .add_formula_table(
        detail_df,
        formulas={"Revenue": "SUM", "Cost": "SUM"},
        formula_label="Total",
    )
    .build("./output/sales_report.xlsx")
)

Level 3 — Scheduled Reports

from databloom.scheduler import BloomScheduler, ReportConfig

config = ReportConfig(
    title="Weekly Sales Dashboard",
    theme="business_blue",
    output_path="./output/weekly_sales.xlsx",
    data_factory=lambda: pd.read_sql("SELECT * FROM sales", conn),
)

scheduler = BloomScheduler()
scheduler.weekly(config, day="monday", at="09:00")
scheduler.start()  # blocking loop — use Ctrl+C to stop

Available Themes

Customising Themes

You can create, save, and share custom themes:

from databloom import get_theme
import json

# Export a built-in theme as JSON
theme = get_theme("business_blue")
theme.table.data_font.size = 12  # safe to mutate — it's a deep copy!

with open("my_theme.json", "w") as f:
    json.dump(theme.to_dict(), f, indent=2)

# Load a custom theme later
from databloom.theme.base import Theme

with open("my_theme.json") as f:
    custom_theme = Theme.from_dict(json.load(f))

report = Report(title="Custom", theme=custom_theme)

API Reference

quick_report(*dataframes, output, theme, title, chart_type) → bytes | None

Auto-analyzes DataFrames and picks the best layout and chart types.

Report(title, theme) — Builder

BloomScheduler — Scheduled Generation

from databloom.scheduler import BloomScheduler, ReportConfig

Built-in Datasets

from databloom.data import load_dataset, list_datasets

print(list_datasets())
# ['finance_metrics', 'finance_profit', 'hr_workforce', 'sales_orders', 'supply_chain']

df = load_dataset("hr_workforce")  # 200 rows × 8 columns

Development

# Run tests
pytest

# With coverage
pytest --cov=databloom --cov-report=term-missing

# Lint
ruff check src/ tests/
ruff format src/ tests/

# Type check
mypy src/databloom/

License

MIT — see LICENSE for details.