# Dashboard Lego 🧱
<div align="center">
<img src="example.png" alt="Dashboard Lego v0.15 Showcase - Cyborg Theme" width="800"/>
<p><em>Dashboard Lego v0.15 Showcase Dashboard with Cyborg Theme</em></p>
</div>
A modular Python library for building interactive dashboards using Dash and Plotly.
Dashboard Lego allows you to build complex dashboards from independent, reusable "blocks" like building with LEGO bricks. This simplifies development, improves code readability, and promotes component reusability.
---
## ✨ Key Features
- **Modular Architecture**: Build dashboards from independent blocks (KPIs, charts, text)
- **Reactive State Management**: Built-in state manager for easy interactivity between blocks (filters, drill-down, etc.)
- **Navigation System**: Multi-section dashboards with sidebar/tab navigation and lazy-loaded sections
- **Flexible Grid System**: Position blocks in any configuration using a grid system based on `dash-bootstrap-components`
- **Theme System**: Comprehensive theming with pre-built themes (light, dark, and 10+ Bootstrap themes) and custom theme support
- **Data Caching**: 2-stage pipeline with independent caching (Build → Filter) for optimal performance
- **No Subclassing Required**: Use composition pattern with `DataBuilder` + `DataFilter` instead of inheriting from `BaseDataSource`
- **TypedChartBlock System**: Plot registry pattern for reusable chart components with embedded controls
- **Presets & Layouts**: Pre-built EDA and ML visualization blocks, plus layout presets for common dashboard patterns
- **Comprehensive Testing**: Full test coverage with unit, integration, and performance tests
## 📦 Installation
1. **Clone the repository:**
```bash
git clone https://github.com/your-username/dashboard-lego.git
cd dashboard-lego
```
2. **Create a virtual environment and install dependencies:**
We recommend using `uv` for fast installation.
```bash
# Install uv
pip install uv
# Create environment and install dependencies
uv venv
uv pip install -e .[dev]
```
## 🚀 Quick Start
Below is an example of a simple dashboard. The complete code can be found in `examples/01_simple_dashboard.py`.
```python
# examples/01_simple_dashboard.py
import dash
import dash_bootstrap_components as dbc
import plotly.express as px
import pandas as pd
from dashboard_lego.core import BaseDataSource, DataBuilder, DashboardPage
from dashboard_lego.blocks.metrics import MetricsBlock
from dashboard_lego.blocks.typed_chart import TypedChartBlock
from dashboard_lego.presets.layouts import one_column
# 1. Define a DataBuilder (v0.15+ pattern)
class SalesDataBuilder(DataBuilder):
def __init__(self, file_path):
super().__init__()
self.file_path = file_path
def build(self, params):
"""Load CSV and add calculated fields."""
df = pd.read_csv(self.file_path)
# Add any calculated fields here
return df
# 2. Create datasource using composition (no inheritance!)
datasource = BaseDataSource(
data_builder=SalesDataBuilder("examples/sample_data.csv")
)
# 3. Create blocks using v0.15 API
# MetricsBlock replaces get_kpis() pattern
metrics_block = MetricsBlock(
block_id="sales_metrics",
datasource=datasource,
metrics_spec={
"total_sales": {
"column": "Sales",
"agg": "sum",
"title": "Total Sales",
"color": "success"
},
"total_units": {
"column": "UnitsSold",
"agg": "sum",
"title": "Total Units Sold",
"color": "info"
}
},
subscribes_to="dummy_state"
)
# TypedChartBlock with block-level transform
chart_block = TypedChartBlock(
block_id="sales_chart",
datasource=datasource,
plot_type="bar",
plot_params={"x": "Fruit", "y": "Sales"},
plot_kwargs={"title": "Sales by Fruit"},
title="Fruit Sales",
subscribes_to="dummy_state",
# Optional: aggregate data at block level
transform_fn=lambda df: df.groupby("Fruit")["Sales"].sum().reset_index()
)
# 4. Assemble the dashboard page
dashboard_page = DashboardPage(
title="Simple Sales Dashboard",
blocks=one_column([metrics_block, chart_block]),
theme=dbc.themes.LUX
)
# 5. Run the application
app = dash.Dash(__name__, external_stylesheets=[dashboard_page.theme])
app.layout = dashboard_page.build_layout()
dashboard_page.register_callbacks(app)
if __name__ == "__main__":
app.run_server(debug=True)
```
To run this example:
```bash
python examples/01_simple_dashboard.py
```
For a comprehensive API reference with detailed contracts, hierarchies, and advanced patterns, see **[DASHBOARD_LEGO_GUIDE.md](DASHBOARD_LEGO_GUIDE.md)**.
## 🔗 Interactivity
`dashboard-lego` makes it easy to link blocks together. One block can publish its state (e.g., a filter value), and other blocks can subscribe to that state and update accordingly.
This is implemented through the `StateManager`, which automatically creates Dash callbacks.
See the complete interactive dashboard example in `examples/02_interactive_dashboard.py`.
## 🎨 Presets and Layouts
### EDA Presets
Presets are ready-to-use blocks for standard data analysis tasks (EDA) that significantly reduce boilerplate code:
- **`CorrelationHeatmapPreset`**: Automatically builds a correlation heatmap for all numeric columns in your data
- **`GroupedHistogramPreset`**: Creates an interactive histogram with dropdowns for column and grouping selection
- **`MissingValuesPreset`**: Displays a bar chart showing the percentage of missing values for each column, helping quickly assess data quality
- **`BoxPlotPreset`**: Allows comparing distributions of a numeric feature across different categories using interactive box plot charts
Example usage of presets can be found in `examples/03_presets_dashboard.py`.
### ML Presets
Machine learning visualization presets for common ML workflows:
- **`MetricCardBlock`**: Compact display for ML metrics in a list format
- **`ConfusionMatrixPreset`**: Interactive confusion matrix visualization
- **`FeatureImportancePreset`**: Feature importance charts for model interpretation
- **`ROC_CurvePreset`**: ROC curve visualization for classification models
### Layout Presets
`DashboardPage` supports declarative layout schemas:
- Cell: `Block` or `(Block, { 'xs|sm|md|lg|xl': int, 'offset': int, 'align': str, 'className': str, 'style': dict, 'children': [row_specs] })`
- Row: `[cells]` or `([cells], { 'align': str, 'justify': str, 'g': int, 'className': str, 'style': dict })`
If widths are not specified, for backward compatibility, automatic equal division is set via `width`.
The `presets/layouts.py` module provides common templates: `one_column`, `two_column_8_4`, `three_column_4_4_4`, `kpi_row_top`, etc.
## 📊 Data Sources
Dashboard Lego supports multiple data source types:
- **CSV Source**: Load data from CSV files with automatic caching
- **Parquet Source**: High-performance columnar data loading
- **SQL Source**: Connect to databases via SQLAlchemy
- **Custom Sources**: Inherit from `BaseDataSource` to create your own data providers
## 🧪 Testing
The library is covered by comprehensive tests. To run tests:
```bash
# Make sure you have dev dependencies installed
# uv pip install -e .[dev,docs,ml,sql]
# Run tests
uv run pytest
# Run with coverage
uv run pytest --cov=dashboard_lego --cov-report=html
```
## 📚 Documentation
### API Reference Guide
For AI agents, LLMs, and developers, we provide a comprehensive API reference:
- **[Dashboard Lego API Guide](DASHBOARD_LEGO_GUIDE.md)**: Complete, machine-parseable API documentation with contracts, hierarchies, and examples for all modules
### Building Documentation Locally
```bash
cd docs
# Build and serve locally (opens http://localhost:8000)
make serve
# Just build HTML
make html
# Clean and rebuild
make clean && make html
# Check docs build without errors
make check
```
### Documentation Structure
- **API Reference**: `DASHBOARD_LEGO_GUIDE.md` - Comprehensive API documentation
- **API Documentation**: Automatically generated from docstrings
- **User Guides**: Installation, quick start, and concepts
- **Examples**: Check the `examples/` directory for various use cases
- **Contributing**: See `CONTRIBUTING.md` for development guidelines
- **Changelog**: Track changes in `CHANGELOG.md`
### Publishing Documentation
**Automatic (Recommended):**
- Documentation is automatically built and published to GitHub Pages when tests pass on `main` branch
- Available at: `https://blghtr.github.io/dashboard_lego/`
**Note:** No manual publishing needed! CI handles everything automatically.
## 🛠️ Development
### Prerequisites
- Python 3.10+
- uv (recommended) or pip
### Development Setup
```bash
# Clone and setup
[uv] pip install dashboard-lego
# Run pre-commit hooks
pre-commit install
# Run tests
uv run pytest
```
### Code Style
- **Black** for code formatting
- **Flake8** for linting
- **MyPy** for type checking
- **Pre-commit** hooks for automated checks
## 🤝 Contributing
We welcome contributions! Please see `CONTRIBUTING.md` for detailed information on:
- Development setup and guidelines
- Code style and standards
- Testing requirements
- Pull request process
- Creating presets and custom blocks
## 📄 License
This project is distributed under the MIT License. See the `LICENSE` file for details.
---
**Build amazing dashboards with Dashboard Lego! 🧱✨**
Raw data
{
"_id": null,
"home_page": null,
"name": "dashboard-lego",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.10",
"maintainer_email": "Vitalii Voronov <myrdhin.yates@gmail.com>",
"keywords": "dashboard, dash, plotly, data-visualization, eda",
"author": null,
"author_email": "Vitalii Voronov <myrdhin.yates@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/35/49/91d179cfe8c1d2b6fde63cc325f8e4c236bf8033c60d350e8649f3cd716e/dashboard_lego-0.15.1.tar.gz",
"platform": null,
"description": "# Dashboard Lego \ud83e\uddf1\n\n<div align=\"center\">\n <img src=\"example.png\" alt=\"Dashboard Lego v0.15 Showcase - Cyborg Theme\" width=\"800\"/>\n <p><em>Dashboard Lego v0.15 Showcase Dashboard with Cyborg Theme</em></p>\n</div>\n\nA modular Python library for building interactive dashboards using Dash and Plotly.\n\nDashboard Lego allows you to build complex dashboards from independent, reusable \"blocks\" like building with LEGO bricks. This simplifies development, improves code readability, and promotes component reusability.\n\n---\n\n## \u2728 Key Features\n\n- **Modular Architecture**: Build dashboards from independent blocks (KPIs, charts, text)\n- **Reactive State Management**: Built-in state manager for easy interactivity between blocks (filters, drill-down, etc.)\n- **Navigation System**: Multi-section dashboards with sidebar/tab navigation and lazy-loaded sections\n- **Flexible Grid System**: Position blocks in any configuration using a grid system based on `dash-bootstrap-components`\n- **Theme System**: Comprehensive theming with pre-built themes (light, dark, and 10+ Bootstrap themes) and custom theme support\n- **Data Caching**: 2-stage pipeline with independent caching (Build \u2192 Filter) for optimal performance\n- **No Subclassing Required**: Use composition pattern with `DataBuilder` + `DataFilter` instead of inheriting from `BaseDataSource`\n- **TypedChartBlock System**: Plot registry pattern for reusable chart components with embedded controls\n- **Presets & Layouts**: Pre-built EDA and ML visualization blocks, plus layout presets for common dashboard patterns\n- **Comprehensive Testing**: Full test coverage with unit, integration, and performance tests\n\n## \ud83d\udce6 Installation\n\n1. **Clone the repository:**\n ```bash\n git clone https://github.com/your-username/dashboard-lego.git\n cd dashboard-lego\n ```\n\n2. **Create a virtual environment and install dependencies:**\n We recommend using `uv` for fast installation.\n ```bash\n # Install uv\n pip install uv\n\n # Create environment and install dependencies\n uv venv\n uv pip install -e .[dev]\n ```\n\n## \ud83d\ude80 Quick Start\n\nBelow is an example of a simple dashboard. The complete code can be found in `examples/01_simple_dashboard.py`.\n\n```python\n# examples/01_simple_dashboard.py\n\nimport dash\nimport dash_bootstrap_components as dbc\nimport plotly.express as px\nimport pandas as pd\n\nfrom dashboard_lego.core import BaseDataSource, DataBuilder, DashboardPage\nfrom dashboard_lego.blocks.metrics import MetricsBlock\nfrom dashboard_lego.blocks.typed_chart import TypedChartBlock\nfrom dashboard_lego.presets.layouts import one_column\n\n# 1. Define a DataBuilder (v0.15+ pattern)\nclass SalesDataBuilder(DataBuilder):\n def __init__(self, file_path):\n super().__init__()\n self.file_path = file_path\n\n def build(self, params):\n \"\"\"Load CSV and add calculated fields.\"\"\"\n df = pd.read_csv(self.file_path)\n # Add any calculated fields here\n return df\n\n# 2. Create datasource using composition (no inheritance!)\ndatasource = BaseDataSource(\n data_builder=SalesDataBuilder(\"examples/sample_data.csv\")\n)\n\n# 3. Create blocks using v0.15 API\n# MetricsBlock replaces get_kpis() pattern\nmetrics_block = MetricsBlock(\n block_id=\"sales_metrics\",\n datasource=datasource,\n metrics_spec={\n \"total_sales\": {\n \"column\": \"Sales\",\n \"agg\": \"sum\",\n \"title\": \"Total Sales\",\n \"color\": \"success\"\n },\n \"total_units\": {\n \"column\": \"UnitsSold\",\n \"agg\": \"sum\",\n \"title\": \"Total Units Sold\",\n \"color\": \"info\"\n }\n },\n subscribes_to=\"dummy_state\"\n)\n\n# TypedChartBlock with block-level transform\nchart_block = TypedChartBlock(\n block_id=\"sales_chart\",\n datasource=datasource,\n plot_type=\"bar\",\n plot_params={\"x\": \"Fruit\", \"y\": \"Sales\"},\n plot_kwargs={\"title\": \"Sales by Fruit\"},\n title=\"Fruit Sales\",\n subscribes_to=\"dummy_state\",\n # Optional: aggregate data at block level\n transform_fn=lambda df: df.groupby(\"Fruit\")[\"Sales\"].sum().reset_index()\n)\n\n# 4. Assemble the dashboard page\ndashboard_page = DashboardPage(\n title=\"Simple Sales Dashboard\",\n blocks=one_column([metrics_block, chart_block]),\n theme=dbc.themes.LUX\n)\n\n# 5. Run the application\napp = dash.Dash(__name__, external_stylesheets=[dashboard_page.theme])\napp.layout = dashboard_page.build_layout()\ndashboard_page.register_callbacks(app)\n\nif __name__ == \"__main__\":\n app.run_server(debug=True)\n```\n\nTo run this example:\n```bash\npython examples/01_simple_dashboard.py\n```\n\nFor a comprehensive API reference with detailed contracts, hierarchies, and advanced patterns, see **[DASHBOARD_LEGO_GUIDE.md](DASHBOARD_LEGO_GUIDE.md)**.\n\n## \ud83d\udd17 Interactivity\n\n`dashboard-lego` makes it easy to link blocks together. One block can publish its state (e.g., a filter value), and other blocks can subscribe to that state and update accordingly.\n\nThis is implemented through the `StateManager`, which automatically creates Dash callbacks.\n\nSee the complete interactive dashboard example in `examples/02_interactive_dashboard.py`.\n\n## \ud83c\udfa8 Presets and Layouts\n\n### EDA Presets\n\nPresets are ready-to-use blocks for standard data analysis tasks (EDA) that significantly reduce boilerplate code:\n\n- **`CorrelationHeatmapPreset`**: Automatically builds a correlation heatmap for all numeric columns in your data\n- **`GroupedHistogramPreset`**: Creates an interactive histogram with dropdowns for column and grouping selection\n- **`MissingValuesPreset`**: Displays a bar chart showing the percentage of missing values for each column, helping quickly assess data quality\n- **`BoxPlotPreset`**: Allows comparing distributions of a numeric feature across different categories using interactive box plot charts\n\nExample usage of presets can be found in `examples/03_presets_dashboard.py`.\n\n### ML Presets\n\nMachine learning visualization presets for common ML workflows:\n\n- **`MetricCardBlock`**: Compact display for ML metrics in a list format\n- **`ConfusionMatrixPreset`**: Interactive confusion matrix visualization\n- **`FeatureImportancePreset`**: Feature importance charts for model interpretation\n- **`ROC_CurvePreset`**: ROC curve visualization for classification models\n\n### Layout Presets\n\n`DashboardPage` supports declarative layout schemas:\n\n- Cell: `Block` or `(Block, { 'xs|sm|md|lg|xl': int, 'offset': int, 'align': str, 'className': str, 'style': dict, 'children': [row_specs] })`\n- Row: `[cells]` or `([cells], { 'align': str, 'justify': str, 'g': int, 'className': str, 'style': dict })`\n\nIf widths are not specified, for backward compatibility, automatic equal division is set via `width`.\n\nThe `presets/layouts.py` module provides common templates: `one_column`, `two_column_8_4`, `three_column_4_4_4`, `kpi_row_top`, etc.\n\n## \ud83d\udcca Data Sources\n\nDashboard Lego supports multiple data source types:\n\n- **CSV Source**: Load data from CSV files with automatic caching\n- **Parquet Source**: High-performance columnar data loading\n- **SQL Source**: Connect to databases via SQLAlchemy\n- **Custom Sources**: Inherit from `BaseDataSource` to create your own data providers\n\n## \ud83e\uddea Testing\n\nThe library is covered by comprehensive tests. To run tests:\n\n```bash\n# Make sure you have dev dependencies installed\n# uv pip install -e .[dev,docs,ml,sql]\n\n# Run tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=dashboard_lego --cov-report=html\n```\n\n## \ud83d\udcda Documentation\n\n### API Reference Guide\n\nFor AI agents, LLMs, and developers, we provide a comprehensive API reference:\n- **[Dashboard Lego API Guide](DASHBOARD_LEGO_GUIDE.md)**: Complete, machine-parseable API documentation with contracts, hierarchies, and examples for all modules\n\n### Building Documentation Locally\n\n```bash\ncd docs\n\n# Build and serve locally (opens http://localhost:8000)\nmake serve\n\n# Just build HTML\nmake html\n\n# Clean and rebuild\nmake clean && make html\n\n# Check docs build without errors\nmake check\n```\n\n### Documentation Structure\n\n- **API Reference**: `DASHBOARD_LEGO_GUIDE.md` - Comprehensive API documentation\n- **API Documentation**: Automatically generated from docstrings\n- **User Guides**: Installation, quick start, and concepts\n- **Examples**: Check the `examples/` directory for various use cases\n- **Contributing**: See `CONTRIBUTING.md` for development guidelines\n- **Changelog**: Track changes in `CHANGELOG.md`\n\n### Publishing Documentation\n\n**Automatic (Recommended):**\n- Documentation is automatically built and published to GitHub Pages when tests pass on `main` branch\n- Available at: `https://blghtr.github.io/dashboard_lego/`\n\n**Note:** No manual publishing needed! CI handles everything automatically.\n\n## \ud83d\udee0\ufe0f Development\n\n### Prerequisites\n\n- Python 3.10+\n- uv (recommended) or pip\n\n### Development Setup\n\n```bash\n# Clone and setup\n[uv] pip install dashboard-lego\n\n# Run pre-commit hooks\npre-commit install\n\n# Run tests\nuv run pytest\n```\n\n### Code Style\n\n- **Black** for code formatting\n- **Flake8** for linting\n- **MyPy** for type checking\n- **Pre-commit** hooks for automated checks\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see `CONTRIBUTING.md` for detailed information on:\n\n- Development setup and guidelines\n- Code style and standards\n- Testing requirements\n- Pull request process\n- Creating presets and custom blocks\n\n## \ud83d\udcc4 License\n\nThis project is distributed under the MIT License. See the `LICENSE` file for details.\n\n\n---\n\n**Build amazing dashboards with Dashboard Lego! \ud83e\uddf1\u2728**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modular Python library for building interactive dashboards using Dash and Plotly",
"version": "0.15.1",
"project_urls": {
"Bug Tracker": "https://github.com/blghtr/dashboard_lego/issues",
"Changelog": "https://github.com/blghtr/dashboard_lego/blob/main/CHANGELOG.md",
"Documentation": "https://blghtr.github.io/dashboard_lego/",
"Homepage": "https://github.com/blghtr/dashboard_lego",
"Repository": "https://github.com/blghtr/dashboard_lego"
},
"split_keywords": [
"dashboard",
" dash",
" plotly",
" data-visualization",
" eda"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "abaf76f9404a217bee270c9741c13be297d5e676ec2202c53f40e85b46f0a4e4",
"md5": "30c8e74d993c9d0d9e6e8259c10db769",
"sha256": "b62250e7fa24b636675a3c269cd9ba34bac2c0aab0e99fe474559498b3bdbb61"
},
"downloads": -1,
"filename": "dashboard_lego-0.15.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "30c8e74d993c9d0d9e6e8259c10db769",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.10",
"size": 101437,
"upload_time": "2025-10-11T15:47:48",
"upload_time_iso_8601": "2025-10-11T15:47:48.753061Z",
"url": "https://files.pythonhosted.org/packages/ab/af/76f9404a217bee270c9741c13be297d5e676ec2202c53f40e85b46f0a4e4/dashboard_lego-0.15.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "354991d179cfe8c1d2b6fde63cc325f8e4c236bf8033c60d350e8649f3cd716e",
"md5": "ff7bfc54d470b0f2a8581f5ba4f532a8",
"sha256": "cea8443dec39a551cdd61be5c6426e272332be764736ea00790ed7a8cda920c7"
},
"downloads": -1,
"filename": "dashboard_lego-0.15.1.tar.gz",
"has_sig": false,
"md5_digest": "ff7bfc54d470b0f2a8581f5ba4f532a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.10",
"size": 88185,
"upload_time": "2025-10-11T15:47:50",
"upload_time_iso_8601": "2025-10-11T15:47:50.316013Z",
"url": "https://files.pythonhosted.org/packages/35/49/91d179cfe8c1d2b6fde63cc325f8e4c236bf8033c60d350e8649f3cd716e/dashboard_lego-0.15.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 15:47:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "blghtr",
"github_project": "dashboard_lego",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "dash",
"specs": [
[
">=",
"2.14.0"
]
]
},
{
"name": "dash-bootstrap-components",
"specs": [
[
">=",
"1.5.0"
]
]
},
{
"name": "plotly",
"specs": [
[
">=",
"5.17.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.4.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"4.1.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"23.0.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"1.5.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.24.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.11.0"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "sphinx",
"specs": [
[
">=",
"7.1.0"
]
]
},
{
"name": "sphinx-rtd-theme",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "types-requests",
"specs": [
[
">=",
"2.31.0"
]
]
}
],
"lcname": "dashboard-lego"
}
JSON
