lexigram-admin

Modern Python-first admin framework for Lexigram — HTMX, CRUD, dashboards, and extensions.

Overview

Auto-generated admin panel for the Lexigram Framework. Provides CRUD interfaces, bulk actions, role-based access, and audit logging for any domain model — with zero frontend code required.

Built on lexigram-ui for responsive UI components and integrates with lexigram-auth for RBAC permission enforcement. Configure via AdminModule.configure() and register resources with the admin site.

Install

uv add lexigram-admin
# Optional extras
uv add "lexigram-admin[auth,saml,ldap,oauth2,export]"

Quick Start

from lexigram import Application
from lexigram.di.module import Module, module
from lexigram.admin import AdminModule, ModelAdmin, admin_site

@admin_site.register(Product)
class ProductAdmin(ModelAdmin):
    list_display = ["id", "name", "price", "is_active"]
    list_filter = ["is_active", "category"]
    search_fields = ["name", "sku"]

@module(imports=[AdminModule.configure()])
class AppModule(Module):
    pass

app = Application(modules=[AppModule])
if __name__ == "__main__":
    app.run()

Configuration

Zero-config usage: Call AdminModule.configure() with no arguments to use defaults.

Option 1 — YAML file

# application.yaml
admin:
  prefix: /admin
  title: "My App Admin"
  features:
    audit_logging: true

Option 2 — Profiles + Environment Variables (recommended)

export LEX_ADMIN__ENABLED=true
export LEX_ADMIN__TITLE="Production Admin"

Option 3 — Python

from lexigram.admin.config import AdminConfig

config = AdminConfig(
    prefix="/admin",
    title="My App Admin",
    features=AdminFeaturesConfig(audit_logging=True),
)
AdminModule.configure(config)

Config reference

Module Factory Methods

Key Features

• Auto CRUD — List, detail, create, edit, delete with zero boilerplate
• Smart list — Sortable columns, inline filters, pagination, search bar
• Bulk actions — Multi-select operations with progress and error summaries
• Row actions — Per-row buttons for custom single-object operations
• Auth integration — Plugs into lexigram-auth RBAC; per-model permission guards
• Audit log — Every write action logged with user, timestamp, diff
• Change history — Per-object change history with diff viewer
• Password policy — Configurable complexity rules for admin users
• Custom pages — @admin_site.page(path="/reports") for bespoke views

Contributor System

lexigram-admin features a plugin/contributor system that lets third-party packages extend the admin dashboard without modifying the host application.

Any package can become a contributor by:

1. Subclassing BaseAdminContributor from lexigram-contracts
2. Registering it via the lexigram.admin.contributors entry point group
3. Implementing methods like get_resources(), get_dashboard_widgets(), get_navigation_items(), get_management_pages(), get_settings_panels(), get_routes(), and get_actions()

Contributions are automatically namespaced by the contributor's package_source to prevent name collisions. Collision behavior is configurable via AdminConfig.contributor_collision_mode ("warn" | "error").

For a complete walkthrough, see the Extension Developer Guide.

Example (plugin pyproject.toml)

[project.entry-points."lexigram.admin.contributors"]
my_plugin = "my_plugin.contributor:MyContributor"

Testing

async with Application.boot(modules=[AdminModule.stub()]) as app:
    # your test code
    ...

Examples

• examples/lexigram-admin-plugin-demo — A full-featured plugin demo with resources, pages, widgets, settings, actions, and dashboard widgets. See the Extension Developer Guide for a walkthrough.
• examples/platform/ — A simpler one-capability admin example.

Key Source Files

Operations

Production deployment guidance, rollback steps, audit-log backup/restore, session revocation, contributor triage, and metrics names live in OPERATOR_RUNBOOK.md.

| src/lexigram/admin/module.py | AdminModule definition with factory methods | | src/lexigram/admin/di/bundle_provider.py | AdminBundleProvider wiring | | src/lexigram/admin/config.py | AdminConfig and all config sub-models | | src/lexigram/admin/contributors/ | Contributor registry, resource collection |