Metadata-Version: 2.3
Name: django-fusion-analytics
Version: 0.3.4
Summary: Model-aware business intelligence plugin for Django
Author: BlakeFusionCollective
Author-email: BlakeFusionCollective <blake@fusioncollective.net>
Requires-Dist: django>=4.2
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# django-fusion-analytics

Model-aware business intelligence plugin for Django. Visual query builder, joins via FK traversal, charts, and saved queries — all with a Tailwind-styled UI that ships as static assets (no build step at install time).

## Install

```bash
uv add django-fusion-analytics
```

Add to `INSTALLED_APPS` and include URLs:

```python
INSTALLED_APPS = ["fusion_analytics", ...]

# urls.py
urlpatterns = [
    path("analytics/", include("fusion_analytics.urls")),
    ...
]
```

Register models for BI access in any app's `analytics.py`:

```python
from fusion_analytics.registry import site, ModelAnalytics
from .models import Order

@site.register
class OrderAnalytics(ModelAnalytics):
    model = Order
    # optional: explicit field whitelist
    # fields = ["id", "total", "customer__name"]
    # max_depth = 2  # FK traversal depth (default 2)
    # page_size = 100  # rows per page in the results table

    # optional: per-field rendering for the table view
    display_formats = {
        "total": {"type": "currency", "currency": "USD", "decimals": 2},
        "discount_rate": {"type": "percent", "decimals": 1, "scale": "fraction"},
        "ordered_at": {"type": "datetime", "format": "%b %d, %Y %H:%M"},
        "quantity": {"type": "number", "thousands": True, "decimals": 0},
    }
```

`display_formats` keys are full field paths (`customer__name` for traversed
fields). Sort and CSV export always use the underlying raw value, so precision is
preserved.

## Settings

```python
# settings.py — optional
FUSION_ANALYTICS_MAX_CSV_ROWS = 100_000  # cap on rows in a CSV export (default)
```

CSV export re-runs the active query on download (honoring filters, group-by, and
aggregations) and caps the file at `FUSION_ANALYTICS_MAX_CSV_ROWS` rows. Set it to
`None` to remove the cap.

## Develop

```bash
uv sync                                 # install deps
uv run pytest                           # run tests
uv run black src/ tests/ testproject/   # format
uv run ruff check src/ tests/ testproject/  # lint

# Rebuild the bundled CSS after changing Tailwind classes in templates:
bash scripts/build_css.sh
```

The compiled CSS lives at `src/fusion_analytics/static/fusion_analytics/css/fusion.css` and is committed — end users do not run Tailwind.

## Try it

```bash
uv run python testproject/manage.py makemigrations testapp
uv run python testproject/manage.py migrate
uv run python testproject/manage.py createsuperuser  # any creds
uv run python testproject/manage.py seed_demo
uv run python testproject/manage.py runserver
```

Then visit http://localhost:8000/analytics/ and log in.
