chartcraft 0.1.0

Python-powered dashboards that rival Power BI & Tableau.

 ██████╗██╗  ██╗ █████╗ ██████╗ ████████╗      ╔══════════════════════════════╗
██╔════╝██║  ██║██╔══██╗██╔══██╗╚══██╔══╝      ║  C R A F T C R A F T       ║
██║     ███████║███████║██████╔╝   ██║         ║  ───────────────────────    ║
██║     ██╔══██║██╔══██║██╔══██╗   ██║         ║  Python Dashboard Builder   ║
╚██████╗██║  ██║██║  ██║██║  ██║   ██║         ╚══════════════════════════════╝
 ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝

Python-powered dashboards that rival Power BI & Tableau.

Write Python. Get a stunning, interactive, real-time dashboard — instantly.

Quickstart · Docs · Presets & Builders · Data Sources · API Reference

---

◆ Three API Layers

Choose the level that matches how fast you want to move:

Layer	What it is	Use when
Core classes	cc.Dashboard, cc.Bar, cc.Line, cc.KPI, cc.Filter	You need exact control
Presets & helpers	cc.Page(...), cc.section(...), cc.trend_line(...), cc.sql_kpi(...)	You want clean, readable code
Page builders	cc.executive_page(...), cc.sales_page(...), cc.customer_page(...), cc.product_page(...)	Your dashboard fits a common story

The Dashboard Builder at http://localhost:8050/builder is a full drag-and-drop canvas that generates live Python code as you design — and stays in sync both ways. No build step. No npm. No JavaScript.

---

◆ Quickstart

pip install chartcraft

import chartcraft as cc

app = cc.App("Revenue Review", theme="midnight")

@app.page("/")
def overview():
    monthly = [
        {"month": "Jan", "revenue": 120, "profit": 28},
        {"month": "Feb", "revenue": 138, "profit": 31},
        {"month": "Mar", "revenue": 149, "profit": 36},
    ]

    return cc.Page(
        title="Revenue Review",
        subtitle="Q1 snapshot",
        kpis=[
            cc.stat("Revenue", "$407K", change=11.4),
            cc.stat("Profit Margin", "24%", change=1.8),
        ],
        content=[
            cc.section(
                "Momentum",
                cc.trend_line(
                    monthly,
                    x="month",
                    y=["revenue", "profit"],
                    title="Revenue vs Profit",
                    col=0, colspan=8, height=320,
                ),
                cc.spotlight_donut(
                    {"Direct": 52, "Partner": 31, "Online": 17},
                    title="Channel Mix",
                    col=8, colspan=4,
                    center_text="Q1",
                ),
                subtitle="Tracking ahead of plan",
            ),
            cc.note("Revenue stays ahead of plan while profit improves each month."),
            cc.section(
                "Leaders",
                cc.ranked_bars(
                    [
                        {"rep": "Avery", "revenue": 92},
                        {"rep": "Noah",  "revenue": 84},
                        {"rep": "Mia",   "revenue": 79},
                    ],
                    x="rep", y="revenue",
                    title="Top Reps",
                    col=0, colspan=6,
                ),
                cc.data_table(
                    [
                        {"region": "West",    "revenue": 168, "profit": 43},
                        {"region": "East",    "revenue": 137, "profit": 31},
                        {"region": "Central", "revenue": 102, "profit": 24},
                    ],
                    title="Regional Detail",
                    columns=["region", "revenue", "profit"],
                    col=6, colspan=6, page_size=5,
                ),
            ),
        ],
    )

app.run()
# ◆ ChartCraft  →  http://localhost:8050
# Builder       →  http://localhost:8050/builder

---

◆ Layout Helpers

cc.Page(title, subtitle="", kpis=[], filters=[], content=[], charts=[], cols=12, ...)
cc.section(title, *content, subtitle="", col=0, colspan=12)
cc.note(content, col=0, colspan=12)
cc.stat(title, value=None, **kwargs)       # thin shortcut for cc.KPI(...)

---

◆ Chart Presets

Return standard chart classes with tuned defaults:

cc.trend_line      smooth curve, no dots    — great for time series
cc.trend_area      filled area chart        — shows volume over time
cc.comparison_bars grouped bars             — compare target vs actual
cc.ranked_bars     horizontal, show values  — top-N rankings
cc.spotlight_donut donut with center label  — mix / composition
cc.insight_scatter sized scatter            — correlation analysis
cc.data_table      sortable + searchable    — tabular detail

---

◆ SQL Helpers

Wire a connector to charts so queries re-run on every refresh or filter change:

db = cc.connect_sql("sqlite:///sales.db")

cc.Page(
    title="SQL Example",
    filters=[cc.Filter("year", options=["All", "2024", "2025"])],
    kpis=[
        cc.sql_kpi(
            "Revenue", db,
            lambda f: (
                "SELECT SUM(revenue) FROM monthly_sales"
                if f.get("year") in (None, "All")
                else f"SELECT SUM(revenue) FROM monthly_sales WHERE year = {f['year']}"
            ),
            field="revenue",
            formatter=lambda v, _f: f"${v:,.0f}",
            linked_filters=["year"],
        )
    ],
    content=[
        cc.section(
            "Trend",
            cc.sql_line(
                db,
                "SELECT month, revenue, profit FROM monthly_sales ORDER BY month",
                x="month", y=["revenue", "profit"],
                title="Monthly Performance",
                col=0, colspan=8,
            ),
            cc.sql_table(
                db,
                "SELECT month, revenue, profit FROM monthly_sales ORDER BY month",
                title="Rows",
                columns=["month", "revenue", "profit"],
                col=8, colspan=4,
            ),
        )
    ],
)

All helpers: sql_kpi · sql_line · sql_area · sql_bar · sql_donut · sql_scatter · sql_table

Core classes also support .from_sql(...) at runtime:

cc.Bar.from_sql(db, "SELECT region, revenue FROM sales ORDER BY revenue DESC", x="region", y="revenue")

---

◆ Page Builders

Drop in a complete sectioned dashboard when your story fits a common narrative:

cc.executive_page(title, kpis=[...], hero=[...], performance=[...], note_text="...")
cc.sales_page(title, kpis=[...], trend=[...], analysis=[...], ranking=[...])
cc.customer_page(title, kpis=[...], mix=[...], geography=[...], accounts=[...])
cc.product_page(title, kpis=[...], overview=[...], profitability=[...], leaders=[...])

---

◆ Real-Time Streaming

Server-Sent Events push full chart specs to every browser — no WebSocket, no polling, no frontend code:

cc.Line(
    data_fn=lambda: db.query_dict("SELECT ts, value FROM metrics ORDER BY ts DESC LIMIT 100"),
    x="ts", y="value",
    title="Live Stream",
    refresh=3,          # push new data every 3 seconds
    smooth=True,
)

Each component refreshes on its own interval independently.

---

◆ Connect to Anything

db  = cc.connect_sql("sqlite:///analytics.db")       # zero deps
db  = cc.connect_sql("postgresql://user:pass@host:5432/db")   # pip install "chartcraft[pg]"
csv = cc.connect_csv("sales.csv")
csv = cc.connect_csv("./data/")                      # load entire directory
api = cc.connect_api("https://api.example.com", headers={"Authorization": "Bearer ..."})

---

◆ Themes

11 built-in themes, switch live in the browser:

dark themes ──────────────────────────────────────────────────────────────
  midnight   ████  deep purple bg  · purple accent
  obsidian   ████  pitch black     · cyan accent
  default    ████  dark zinc      · indigo accent
  ember      ████  warm dark       · orange accent
  jade       ████  forest dark    · green accent
  candy      ████  pink dark       · magenta accent
  arctic     ████  ice dark        · sky blue accent
  retro      ████  vintage teal   · gold accent
light themes ─────────────────────────────────────────────────────────────
  frost      ░░░░  clean light    · blue accent
  slate      ░░░░  professional    · navy accent
  scientific ░░░░  academic        · slate accent

---

◆ How It Compares

	ChartCraft	Power BI	Tableau	Plotly Dash	Streamlit
Pure Python API	✅	❌	❌	✅	✅
Drag-and-drop visual builder	✅	✅	✅	❌	❌
Bidirectional code ↔ canvas	✅	❌	❌	❌	❌
Zero required dependencies	✅	❌	❌	❌	❌
Real-time SSE push	✅	❌	❌	✅	✅
Export to standalone HTML	✅	limited	limited	❌	❌
No build step / no npm	✅	✅	✅	❌	✅
PDF / Jupyter / Docker export	✅	partial	partial	❌	❌

---

◆ Tech Stack

  Python 3.11+  ──  stdlib only · threading · sqlite3
  ECharts 5.5  ──  GPU canvas · 18+ chart types · CDN only
  Preact 10     ──  3KB React-compatible · no build step
  SSE           ──  text/event-stream · auto-reconnect

---

◆ Documentation

	Guide
🚀 Getting Started	Install, first dashboard, core concepts
📊 Presets & Page Builders	Layout helpers, chart presets, SQL helpers, page builders
🗃 Data Sources	SQL, CSV, REST connectors, filter-linked queries
📈 Chart Types	All 18+ chart types, options, data formats
🎨 Themes & Colors	Themes, palettes, custom branding, color utilities
🎛 Filters & Interactivity	Filter types, cross-filtering, URL state
⚡ Real-Time Data	SSE internals, refresh intervals, LIVE badge
🖱 Visual Builder	Canvas, color picker, code sync, shortcuts
📦 Export & Deployment	HTML, PDF, Jupyter, Docker, nginx
🔒 Authentication	Basic auth, bearer tokens, env vars
📖 API Reference	Every class, method, parameter, HTTP endpoint

---

pip install chartcraft

MIT License · Built with Python · Powered by ECharts