Metadata-Version: 2.5
Name: dashboardfy
Version: 0.1.0
Summary: Generate self-contained, interactive HTML dashboards from pandas DataFrames.
Project-URL: Homepage, https://github.com/henryrosales/dashboardfy
Author-email: Henry Rosales <hrosmendez@gmail.com>
License: MIT
License-File: LICENSE
Keywords: dashboard,html,pandas,report,table
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Requires-Dist: pandas>=1.3
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# dashboardfy

Generate beautiful, self-contained, **interactive HTML dashboards** from one or more
pandas DataFrames — no server, no JavaScript build step, just a single `.html` file
you can open in any browser or share by email.

## Features

- **One function call**: pass a DataFrame (or several) and get an HTML file.
- **Tabs**: each DataFrame is rendered in its own tab, with optional title,
  description, KPI cards, and info/warning notices.
- **KPIs**: computed aggregations (`sum`, `mean`, `median`, `min`, `max`, `count`,
  `nunique`, `std`, `first`, `last`) over any column, or explicit values, with
  custom formatting.
- **Interactive tables**:
  - Global search across all columns.
  - Per-column filter inputs.
  - Per-column sort (ascending/descending, numeric-aware) and hide/show buttons.
- **Themes**: `light` (default), `dark`, `minimal`, `ocean`.
- **Safe**: all cell values, titles and descriptions are HTML-escaped.

## Installation

```bash
pip install dashboardfy
```

## Quick start

```python
import pandas as pd
import dashboardfy

df = pd.DataFrame({"product": ["A", "B"], "revenue": [100, 250]})

# Simplest form: one DataFrame -> dashboard.html
dashboardfy.generate(df, "dashboard.html", title="Sales report")

# Several DataFrames as tabs
dashboardfy.generate({"Sales": df, "Inventory": df2}, "report.html", theme="dark")
```

## Full example with tabs, KPIs and notices

```python
import pandas as pd
from dashboardfy import Tab, KPI, generate

sales = pd.DataFrame(...)

tabs = [
    Tab(
        df=sales,
        title="Sales",
        description="Monthly sales by product and region.",
        kpis=[
            KPI(label="Total revenue", column="revenue", agg="sum", fmt="${:,.0f}"),
            KPI(label="Best day", column="units", agg="max", detail="units in one day"),
            KPI(label="Distinct products", column="product", agg="nunique"),
        ],
        info="Data refreshed daily from the warehouse.",
        warning="Returns are not yet included in these figures.",
    ),
    Tab(df=inventory, title="Inventory"),
]

generate(
    tabs,
    "report.html",
    title="Company dashboard",
    description="Key figures for August 2026.",
    theme="ocean",
)
```

If you want the HTML as a string instead of a file, use
`dashboardfy.render_html(...)` with the same arguments (minus `output_path`).

## API

### `generate(data, output_path="dashboard.html", *, title=None, description=None, theme="light") -> Path`

`data` accepts:

| Input | Result |
|---|---|
| `pd.DataFrame` | single tab |
| `dict[str, pd.DataFrame]` | one tab per entry, keys as tab titles |
| `list[pd.DataFrame \| Tab]` | one tab per item |
| `Tab` | single tab |

### `Tab(df, title=None, description=None, kpis=[], info=None, warning=None)`

### `KPI(label, column=None, agg="sum", value=None, fmt=None, detail=None)`

Either give `column` + `agg`, or an explicit `value`. `fmt` is a Python format
string applied to the result, e.g. `"${:,.2f}"` or `"{:.1%}"`.

## Development

```bash
pip install -e .[dev]
pytest
```

## License

MIT
