bigb-django (0.1.0.dev0)
Installation
pip install --index-url About this package
Dashboards configurables pour Django : requêtes JSON sur les modèles, rendu JSON/SVG, dashboards en grille partageables par utilisateur ou groupe
bigb-django
Configurable dashboards for Django: declarative JSON queries against a Django project's models (explicitly whitelisted, no implicit access), JSON or SVG rendering (via pygal), named saved queries, and grid dashboards shareable by user or group. The Vue 3 frontend counterpart is bigb-vue.
Installation
pip install bigb-django
# settings.py
INSTALLED_APPS = [
...,
"django.contrib.auth",
"bigb",
]
BIGB_MAX_LIMIT = 1000 # cap applied to `limit` in a QuerySpec
# urls.py
urlpatterns = [
...,
path("bigb/", include("bigb.urls")),
]
Don't forget python manage.py migrate (SavedQuery, Dashboard,
DashboardTile models).
Declaring queryable models
Nothing is queryable by default. Each app explicitly declares what it
exposes, in a bigb_queries.py module (auto-discovered at startup, the
same way admin.py is for the Django admin):
# myapp/bigb_queries.py
from bigb import registry
from .models import Order
registry.register(
Order,
fields=["id", "status", "amount", "created_at"],
filterable=["status", "created_at"],
aggregatable=["amount"],
# Optional: called back on EVERY execution (not just when the query
# is saved), so it protects already-saved queries too.
scope=lambda qs, user: qs.filter(tenant=user.tenant),
)
QuerySpec (JSON)
{
"model": "orders.Order",
"filters": [{"field": "status", "op": "eq", "value": "paid"}],
"group_by": ["status"],
"aggregates": [{"func": "sum", "field": "amount", "as": "total"}],
"order_by": ["-total"],
"limit": 100
}
op:eq,neq,gt,gte,lt,lte,in,contains,isnull.func:count,sum,avg,min,max.{"func": "count"}withoutfieldcounts all rows (count_all).- Every field referenced must be in the model's whitelist in the
registry (
fields/filterable/aggregatable), otherwise a 400.
API
All routes require an authenticated session.
| Method | Route | Description |
|---|---|---|
| POST | /bigb/query/ |
Run an ad hoc QuerySpec (execute_query) |
| GET/POST | /bigb/queries/ |
List / create a saved query |
| GET/PATCH/DELETE | /bigb/queries/<slug>/ |
Detail / update / delete |
| GET | /bigb/queries/<slug>/data/?format=json|svg&chart=line |
Result (view_savedquery_results) |
| GET/POST | /bigb/dashboards/ |
List / create a dashboard |
| GET | /bigb/dashboards/default/ |
The current user's default dashboard -- their own is_default one, or else the first is_default one shared with one of their groups. 404 if neither exists |
| GET/PATCH/DELETE | /bigb/dashboards/<slug>/ |
Detail (with tiles) / update / delete |
| POST | /bigb/dashboards/<slug>/tiles/ |
Add a tile |
| PATCH/DELETE | /bigb/dashboards/<slug>/tiles/<id>/ |
Update / delete a tile |
| GET | /bigb/dashboards/<slug>/tiles/<id>/data/?format=json|svg |
Tile result |
| GET | /bigb/registry/ |
Available models/fields/aggregates |
format=svg accepts chart=line\|bar\|pie, title=..., label_field=....
Permissions
Standard Django permissions, assignable per user or per group (so
manageable from the Django admin). Each resource has a base permission,
scoped to "my objects, or ones shared with my user/my groups"
(shared_users/shared_groups), and an *_all permission that lifts
that scoping:
| Permission | Effect |
|---|---|
view_savedquery |
View queries you own or are a sharing recipient of |
view_all_savedquery |
View everyone's queries |
view_savedquery_results |
Run/view the data of an already-visible query |
execute_query |
Run an ad hoc (unsaved) query |
add_savedquery |
Create a query |
change_savedquery / change_all_savedquery |
Edit your own queries / everyone's |
delete_savedquery / delete_all_savedquery |
Delete your own queries / everyone's |
view_dashboard / view_all_dashboard |
View your dashboards (+ shared) / everyone's |
add_dashboard |
Create a dashboard |
change_dashboard / change_all_dashboard |
Edit your own dashboards / everyone's |
delete_dashboard / delete_all_dashboard |
Delete your own dashboards / everyone's |
manage_group_dashboard |
Create a dashboard shared with a group, or change/delete one that already is -- a separate gate from change_dashboard/change_all_dashboard, which only ever lift the ownership scoping. Without it, sharing a dashboard with a group (or editing one someone else already shared with a group) is refused even for its own owner |
A Dashboard.is_default flag marks the one to show automatically for
its owner (or, for a group-shared dashboard, for members of that group
who have no personal default of their own) -- see /bigb/dashboards/ default/ above. Setting it follows the same rules as any other field:
no extra permission for your own dashboard, manage_group_dashboard
for a group-shared one.
Development
make dev # venv + editable install + [dev] extras
make test # pytest
make lint # pylint (pylint-django)
make format # autopep8 --in-place
make bandit # static security analysis
make tox # every environment (py311-py315 + lint + format + bandit)