Skip to content

orama

όραμα

Greek; noun

Vision, goal.

Declarative, metadata-driven charting library for Python.

orama produces Plotly figures from structured Polars DataFrames using a pluggable strategy pattern, fields-metadata-driven field discovery, therismos-based query descriptors, and composable color strategies (using polychromos and armonia). It is designed to be embedded in any Python application regardless of domain model or data-access layer.

Overview

orama sits between your data layer and your presentation layer. You describe which fields to group and aggregate; orama builds the corresponding QueryParams for you to execute, then turns the resulting Polars DataFrames into fully themed, i18n-aware Plotly figures.

What orama does

  • Provides a catalogue of chart strategies: bar, grouped bar, line, categorical line, pie, sunburst, heatmap, boxplot, grouped boxplot, and choropleth map.
  • Provides KPI indicator strategies: text, bar, circle, and arc — rendered as themed HTML5+CSS3 widgets with optional delta, color rules, and nanoplot graphics.
  • Derives query parameters (group-by fields, aggregations, expected schema) directly from the strategy configuration.
  • Renders themed, i18n-aware go.Figure objects and IndicatorView HTML from the query results you supply.

What orama does NOT do

  • Execute queries or fetch data — callers are responsible for running the queries and returning the results as Polars DataFrames.
  • Provide a web layer by default — dynamic WTForms form generation and HTTP serialization are available via orama[web] (orama.web).
Section Description
Installation Install orama and optional extras
Quick Start Render your first chart in minutes
Core Concepts Understand the three-step workflow
User Guide Labels, callbacks, variables, color system, theming, i18n
Chart Types Reference for all 10 chart strategy classes
Indicators KPI indicator widgets: text, bar, circle, arc
Web Layer WTForms binding and HTTP serialization
Dependencies All dependencies and their roles