Skip to content

Muffin-Admin

Muffin-Admin mounts a react-admin single page application on top of Muffin-REST resources. A resource that already has a REST API gets list, create, edit and delete screens without writing any JavaScript.

Muffin-Admin screenshot

The Python side describes resources, actions and authorization in Meta classes; the bundled frontend renders them. Everything the frontend needs is served from {prefix}/ra.json, so a resource is a subclass and a model:

from muffin_admin import Plugin, PWAdminHandler

admin = Plugin(app)


@admin.route
class UserResource(PWAdminHandler):
    class Meta(PWAdminHandler.Meta):
        model = User
        filters = "email", "is_active"
        columns = "email", "name", "is_active", "created"

Start here

  • Quickstart: from an empty project to a working admin over Peewee or SQLAlchemy Core.
  • Configuration: every plugin option, config keys and environment variables.
  • Resources: AdminHandler.Meta in full.
  • Custom actions: buttons, forms, confirmation and file downloads.
  • Authentication: check_auth, get_identity, login and logout.
  • Dashboard: cards on the start page.
  • Customization: CSS, JS, translations and building the frontend.
  • Custom frontend: extending the stock bundle or building your own SPA on the muffin-admin package.
  • API reference: classes, options and hook signatures.
  • Development: setup, tests, examples, release.

Requirements

  • Python >= 3.11 (tested on 3.11, 3.12, 3.13, 3.14 and 3.15)
  • Muffin >= 3.1
  • Muffin-REST >= 14.2
  • Peewee (muffin-peewee-aio) or SQLAlchemy Core (muffin-databases) for the storage backends

Muffin 3 keeps handler routes as (paths, methods, hosts) tuples and Muffin-REST 14.2 follows it; older releases are not supported.

How the pieces fit

Application
├── Plugin                 /admin page, /admin/ra.json, auth routes, actions
│   ├── API                /admin/api, a Muffin-REST API without OpenAPI
│   │   ├── PWAdminHandler Peewee models
│   │   └── SAAdminHandler SQLAlchemy Core tables
│   └── dashboard          cards on the start page
└── frontend/main.js       react-admin bundle, served from the package

Plugin.setup() mounts the admin page, the ra.json description, the login and identity routes, and the Muffin-REST API. Handlers registered with @admin.route are serialized into ra.json; the frontend builds the screens from that description. See Resources and API reference for the details.

Install

pip install muffin-admin                # core
pip install "muffin-admin[peewee]"      # Peewee ORM
pip install "muffin-admin[sqlalchemy]"  # SQLAlchemy Core

The package ships main.js built from frontend/. Without it the admin page loads but react-admin has nothing to run; see Customization for building a bundle from a source checkout.