hedron-charts

First-party charts, deterministic exports, and optional plotting-library adapters for Hedron.

Beginner LineChart / BarChart / AreaChart / ScatterChart, Matplotlib static SVG/PNG, Plotly interactive JSON, and Altair/Vega-Lite specifications.

Package maturity: Stable · Package line: 1.0.x · requires hedron-core>=1.0.0,<2.0

Interactive Plotly/Vega full browser runtimes remain experimental: Hedron ships host shims that fail closed when window.Plotly / window.vegaEmbed are missing. Applications may supply pinned local runtimes; first-party offline runtime pins exist for Experimental interactive hosts and are not Supported production Auto defaults.

Phase 0.38 first-party charts

Phase 0.38 ships hedron-charts 0.2.0 with schema-driven ChartSpec / ChartPlan, an ABI-conforming hedron-chart Web Component, semantic server fallbacks, SVG by default, Canvas for dense series, core inspect/focus/select/reset events, deterministic server exports, and bounded payloads. The current host has dedicated paint behavior for line, area, bar, and point; broader schema acceptance does not imply a specialized painter. Matplotlib remains Supported; Plotly/Altair stay Experimental. See RFC-0069 and the phase 0.38 acceptance packet.

Install

# flagship extra:
pip install "hedron[charts]>=1.0.0"
# independent satellite:
pip install "hedron-charts>=1.0.0,<2.0"
# Add a backend when needed:
pip install "hedron-charts[matplotlib]>=1.0.0,<2.0"

For applications, keep the flagship extra on the 1.0.x train; direct package consumers may use the Stable hedron-charts>=1.0.0,<2.0 SemVer range.

Optional backends

Backend extras are optional and should be installed only for the adapter in use.

Choose an entry point

The beginner components do not select Matplotlib automatically. They compile to the first-party ChartSpec / ChartPlan path.

Quick start

from hedron_charts import LineChart

chart = LineChart(
    [{"month": "Jan", "revenue": 10}, {"month": "Feb", "revenue": 14}],
    x="month",
    y="revenue",
    title="Monthly revenue",
    description="Revenue increased during the period.",
)

The response contains a semantic figure, summary, and bounded table fallback. The local hedron-chart module progressively enhances it to SVG or Canvas and remounts after HTMX swaps.

For an explicit Matplotlib figure:

import matplotlib.pyplot as plt
from hedron_charts import MatplotlibChart

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 4, 9])
chart = MatplotlibChart(fig, alt="y = x squared", description="Quadratic growth")

Advanced specification and export

from hedron_charts import Chart, compile_chart, export_csv, parse_chart_spec

spec = parse_chart_spec(
    {
        "data": {
            "rows": [
                {"month": "Jan", "revenue": 10},
                {"month": "Feb", "revenue": 14},
            ]
        },
        "marks": [
            {
                "type": "line",
                "encodings": {
                    "x": {"field": "month", "type": "string"},
                    "y": {"field": "revenue", "type": "number"},
                },
            }
        ],
        "accessibility": {
            "title": "Monthly revenue",
            "description": "Revenue increased from January to February.",
        },
    }
)

chart = Chart(spec)
plan = compile_chart(spec)
csv_text = export_csv(plan, authorized=user_can_export)

Unknown schema fields, mark types, encoding channels, scales, and transform operators fail closed with HED-CHART-* diagnostics. Perform export authorization in application code; the default authorized=True argument is intended for already-authorized internal calls.

The compiler also accepts advanced mark families, guide metadata, and interaction flags that the 0.2.0 browser host does not yet paint or operate with dedicated behavior. Review the runtime coverage matrix before choosing the first-party host for advanced visualizations.

Links

• Package docs
• Chart API
• Chart components
• Charts and HTMX
• What’s ready
• Changelog
• Source
• Issues
• hedron-core · hedron

License

MIT. See the repository license.