API Reference

HyperAdmin's public API is organized into these modules:

Module	Description
Application	Admin class — the main entry point
Views	ModelView, PydanticForm, HtmxWidget
Core Components	SiteRegistry, AdminOptions
Adapters	BaseAdapter, SQLModelAdapter, SQLAlchemyAdapter
Routing	HyperAdminRouter — URL generation

---

hyperadmin

Admin

The main entry point for HyperAdmin.

Mounts static files, wires the database engine, optionally discovers admin modules, and registers all model routes on the FastAPI application.

All scalar configuration lives in HyperAdminSettings — pass a settings object or let HyperAdmin auto-instantiate one (which reads from environment variables and a .env file).

Example::

from fastapi import FastAPI
from hyperadmin import Admin, HyperAdminSettings

app = FastAPI()
settings = HyperAdminSettings(secret_key="my-secret", theme="dark")
admin = Admin(app, engine=engine, settings=settings)
admin.mount("/admin")

Source code in src/hyperadmin/core/app.py

class Admin:
    """The main entry point for HyperAdmin.

    Mounts static files, wires the database engine, optionally discovers admin
    modules, and registers all model routes on the FastAPI application.

    All scalar configuration lives in ``HyperAdminSettings`` — pass a settings
    object or let HyperAdmin auto-instantiate one (which reads from environment
    variables and a ``.env`` file).

    Example::

        from fastapi import FastAPI
        from hyperadmin import Admin, HyperAdminSettings

        app = FastAPI()
        settings = HyperAdminSettings(secret_key="my-secret", theme="dark")
        admin = Admin(app, engine=engine, settings=settings)
        admin.mount("/admin")
    """

    def __init__(
        self,
        app: FastAPI,
        engine: Any = None,
        settings: HyperAdminSettings | None = None,
        auth_backend: Any = None,
        permission_checker: Any = None,
        permission_registry: Any = None,
        storage: Any = None,
        otp_service: Any = None,
        realtime: RealtimeSettings | None = None,
    ) -> None:
        """Initialise HyperAdmin and attach it to a FastAPI application.

        Args:
            app: The FastAPI application instance to attach the admin to.
            engine: An async SQLAlchemy engine. Defaults to the built-in
                ``hyperadmin.db.engine`` if not provided.
            settings: A ``HyperAdminSettings`` instance. When ``None``, one is
                auto-instantiated (reads ``HYPERADMIN_*`` env vars and ``.env``).
            auth_backend: An optional authentication backend implementing the
                ``AuthBackend`` protocol. When ``None``, auth is disabled.
            permission_checker: An optional ``PermissionChecker`` implementation.
            permission_registry: An optional ``PermissionRegistry`` implementation.
            storage: An optional ``FileSystemStorage`` (or compatible) instance
                for file uploads. When ``None``, file upload support is disabled.
            otp_service: An optional MFA OTP service (e.g. ``EmailOTPService``).
                When ``None``, the MFA endpoints (``/mfa/challenge`` etc) are
                NOT registered and ``login_view`` skips the MFA branch — apps
                without MFA are entirely unaffected (C3-A, #487).
            realtime: Opt-in ``RealtimeSettings``. When ``None`` (default),
                no SSE / WebSocket endpoints are registered and the status
                widget is not injected — fully backward compatible. See
                ``docs/specs/realtime-connection-foundation.md``.
        """
        self.settings = settings or HyperAdminSettings()
        self.app = app
        self.router = APIRouter()
        self.engine = engine or default_engine
        self.auth_backend = auth_backend
        self.permission_checker = permission_checker
        self.permission_registry = permission_registry
        self.storage = storage
        self.otp_service = otp_service
        self.realtime = realtime
        self._realtime_registry: ConnectionRegistry | None = (
            ConnectionRegistry() if realtime is not None else None
        )

        self._validate_session_secret()

        template_dirs = self.settings.template_dirs
        template_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "templates")
        self.templates = Jinja2Templates(directory=[*template_dirs, template_dir])
        # Wire jinja2.ext.i18n + per-request gettext callables (C1-C). The
        # callables read translations from a context var populated by
        # LocaleMiddleware; outside a request they pass msgids through.
        from hyperadmin.i18n import install_jinja_i18n

        install_jinja_i18n(self.templates.env)

        static_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "static")
        if os.path.exists(static_dir):
            app.mount("/static", StaticFiles(directory=static_dir), name="static")

        if self.settings.create_tables:

            @app.on_event("startup")
            async def startup_event() -> None:
                await self._create_db_and_tables()

        if self.settings.discover_apps:
            discover_admin_modules(self.settings.discover_apps)

    # ── Convenience properties ─────────────────────────────────────────────

    @property
    def theme(self) -> str:
        """Active theme from settings."""
        return self.settings.theme

    # ── Validation helpers ─────────────────────────────────────────────────

    def _validate_session_secret(self) -> None:
        """Enforce session secret security policy when auth is enabled."""
        if not self.auth_backend:
            return
        if not self.settings.is_default_secret_key:
            return
        if self.settings.debug:
            logger.warning(
                "Using default session secret. Set HYPERADMIN_SECRET_KEY for production."
            )
        else:
            msg = (
                "Auth is enabled but no secret_key is configured. "
                "Set HYPERADMIN_SECRET_KEY (or pass HyperAdminSettings(secret_key=...))."
            )
            raise ValueError(msg)

    # ── Internal helpers ───────────────────────────────────────────────────

    async def _create_db_and_tables(self) -> None:
        """Creates the database and all tables using the configured engine."""
        async with self.engine.begin() as conn:
            await conn.run_sync(SQLModel.metadata.create_all)

    def _register_views(self) -> None:
        """Registers the views from the site registry."""
        from hyperadmin.routing import HyperAdminRouter

        admin_router = HyperAdminRouter(
            engine=self.engine,
            templates=self.templates,
            permission_checker=self.permission_checker if self.auth_backend else None,
            storage=self.storage,
        )
        admin_router.generate_routes()
        routers = admin_router.get_routers()
        for router in routers:
            self.router.include_router(router)

    def _register_auth_routes(self, path: str) -> None:
        """Register login/logout (and MFA) routes when auth is enabled."""
        from starlette.requests import Request

        from hyperadmin.auth.views import login_view, logout_view

        admin_prefix = path.rstrip("/")
        templates = self.templates
        auth_backend = self.auth_backend
        otp_service = self.otp_service

        async def login_get(request: Request):
            return await login_view(request, templates, auth_backend, admin_prefix, otp_service)

        async def login_post(request: Request):
            return await login_view(request, templates, auth_backend, admin_prefix, otp_service)

        async def logout_post(request: Request):
            return await logout_view(request, auth_backend, admin_prefix)

        self.router.add_api_route("/login", login_get, methods=["GET"], name="admin-login")
        self.router.add_api_route("/login", login_post, methods=["POST"], name="admin-login-post")
        self.router.add_api_route("/logout", logout_post, methods=["POST"], name="admin-logout")

        if otp_service is not None:
            self._register_mfa_routes(admin_prefix)

    def _register_mfa_routes(self, admin_prefix: str) -> None:
        """Register the MFA challenge / verify / resend / settings endpoints.

        Only called when ``otp_service`` is configured. Apps without MFA see
        no new routes — ``mfa_enabled=True`` users in such apps will hit the
        normal single-factor path because ``login_view`` skips the MFA branch
        unless an ``otp_service`` is provided.
        """
        from starlette.requests import Request

        from hyperadmin.auth.views import (
            mfa_challenge_view,
            mfa_disable_view,
            mfa_enable_view,
            mfa_resend_view,
            mfa_settings_view,
            mfa_verify_view,
        )

        templates = self.templates
        auth_backend = self.auth_backend
        otp_service = self.otp_service

        async def challenge_get(request: Request):
            return await mfa_challenge_view(request, templates, admin_prefix)

        async def verify_post(request: Request):
            return await mfa_verify_view(
                request, templates, auth_backend, otp_service, admin_prefix
            )

        async def resend_post(request: Request):
            return await mfa_resend_view(
                request, templates, auth_backend, otp_service, admin_prefix
            )

        async def settings_get(request: Request):
            return await mfa_settings_view(request, templates, admin_prefix)

        async def enable_post(request: Request):
            return await mfa_enable_view(
                request, templates, auth_backend, otp_service, admin_prefix
            )

        async def disable_post(request: Request):
            return await mfa_disable_view(
                request, templates, auth_backend, otp_service, admin_prefix
            )

        self.router.add_api_route(
            "/mfa/challenge", challenge_get, methods=["GET"], name="admin-mfa-challenge"
        )
        self.router.add_api_route(
            "/mfa/verify", verify_post, methods=["POST"], name="admin-mfa-verify"
        )
        self.router.add_api_route(
            "/mfa/resend", resend_post, methods=["POST"], name="admin-mfa-resend"
        )
        self.router.add_api_route(
            "/mfa/settings", settings_get, methods=["GET"], name="admin-mfa-settings"
        )
        self.router.add_api_route(
            "/mfa/enable", enable_post, methods=["POST"], name="admin-mfa-enable"
        )
        self.router.add_api_route(
            "/mfa/disable", disable_post, methods=["POST"], name="admin-mfa-disable"
        )

    def _register_realtime_routes(self, path: str) -> None:
        """Register the SSE GET route and WebSocket route under the admin prefix.

        Both endpoints share a single ``ConnectionRegistry`` so the lifespan
        shutdown hook can drain every open connection in one pass.
        """
        if self.realtime is None or self._realtime_registry is None:
            return
        admin_prefix = path.rstrip("/")
        registry = self._realtime_registry
        settings = self.realtime

        sse_handler = make_sse_handler(registry, settings)
        self.router.add_api_route(
            "/realtime/sse",
            sse_handler,
            methods=["GET"],
            name="admin-realtime-sse",
        )
        ws_handler = make_ws_handler(registry, settings, self.auth_backend)
        self.app.router.add_websocket_route(
            f"{admin_prefix}/realtime/ws",
            ws_handler,
            name="admin-realtime-ws",
        )

        @self.app.on_event("shutdown")
        async def _drain_realtime() -> None:
            await registry.drain()

        if settings.enable_test_endpoints:
            from hyperadmin.realtime._debug import (
                make_count_handler,
                make_disconnect_all_handler,
                make_disconnect_transport_handler,
            )

            self.router.add_api_route(
                "/_test/realtime/count",
                make_count_handler(registry),
                methods=["GET"],
                name="admin-realtime-test-count",
            )
            self.router.add_api_route(
                "/_test/realtime/disconnect_all",
                make_disconnect_all_handler(registry),
                methods=["POST"],
                name="admin-realtime-test-disconnect-all",
            )
            self.router.add_api_route(
                "/_test/realtime/disconnect/{transport}",
                make_disconnect_transport_handler(registry),
                methods=["POST"],
                name="admin-realtime-test-disconnect-transport",
            )

    def _register_locale_route(self, path: str) -> None:
        """Register the POST /locale route for the locale switcher."""
        from starlette.requests import Request
        from starlette.responses import Response

        from hyperadmin.views.locale import set_locale_view

        admin_prefix = path.rstrip("/")
        settings = self.settings

        async def locale_post(request: Request) -> Response:
            return await set_locale_view(request, settings, admin_prefix)

        self.router.add_api_route(
            "/locale",
            locale_post,
            methods=["POST"],
            name="admin-locale",
        )

    def _add_auth_middleware(self, path: str) -> None:
        """Add session and authentication middleware."""
        from starlette.middleware.sessions import SessionMiddleware

        from hyperadmin.auth.middleware import AuthenticationMiddleware

        admin_prefix = path.rstrip("/")
        self.app.add_middleware(
            AuthenticationMiddleware,
            auth_backend=self.auth_backend,
            admin_prefix=admin_prefix,
        )
        self.app.add_middleware(
            SessionMiddleware,
            secret_key=self.settings.secret_key,
        )

    def _add_locale_middleware(self) -> None:
        """Add the locale-resolution middleware to the FastAPI app."""
        from hyperadmin.i18n import LocaleMiddleware

        self.app.add_middleware(LocaleMiddleware, settings=self.settings)

    def _mount_upload_storage(self) -> None:
        """Mount the upload storage directory as a static-files endpoint."""
        storage_path = getattr(self.storage, "_path", None)
        if storage_path is None:
            return
        storage_path_str = str(storage_path)
        if os.path.isdir(storage_path_str):
            self.app.mount(
                "/uploads",
                StaticFiles(directory=storage_path_str),
                name="uploads",
            )

    async def _sync_permissions(self) -> None:
        """Sync permissions for all registered models to the database."""
        if not self.permission_registry:
            return

        from hyperadmin.core.registry import site

        models = []
        for model, admin_class in site._registry.items():
            model_name = model.__name__.lower()
            models.append((model_name, admin_class))
        await self.permission_registry.sync_permissions(models)

    def _auto_register_models(self) -> None:
        """Auto-register discovered SQLModel models with smart defaults.

        For each model not already in ``site._registry``, generates
        ``AdminOptions`` with inferred list_display, search_fields,
        and list_filter. Called from ``mount()`` when
        ``settings.auto_discover`` is ``True``.
        """
        from hyperadmin.core.model import ModelAdmin
        from hyperadmin.core.options import AdminOptions
        from hyperadmin.core.registry import site

        discovered = discover_sqlmodel_models()
        for model in discovered:
            if model in site._registry:
                continue
            try:
                options = AdminOptions(
                    list_display=infer_list_display(model),
                    search_fields=infer_search_fields(model),
                    list_filter=infer_list_filter(model),
                )
                admin_cls = type(f"{model.__name__}Admin", (ModelAdmin,), {})
                site.register(model, admin_class=admin_cls, options=options)
            except Exception:
                logger.warning("Failed to auto-register model %s", model.__name__)

    def _register_auth_models(self) -> None:
        """Auto-register User, Group, Permission in the admin site.

        Called from ``mount()`` when ``auth_backend`` is configured.
        Skips silently if a model is already registered.
        Each auth model gets its own admin class to avoid shared
        class-level state on the default ``ModelAdmin``.
        """
        from hyperadmin.auth.models import Group, Permission, User
        from hyperadmin.core.model import ModelAdmin
        from hyperadmin.core.options import AdminOptions
        from hyperadmin.core.registry import site

        if User not in site._registry:
            user_admin = type("UserAdmin", (ModelAdmin,), {})
            site.register(
                User,
                admin_class=user_admin,
                options=AdminOptions(
                    can_delete=False,
                    list_filter=["is_active", "is_superuser"],
                ),
            )
        if Group not in site._registry:
            group_admin = type("GroupAdmin", (ModelAdmin,), {})
            site.register(Group, admin_class=group_admin)
        if Permission not in site._registry:
            perm_admin = type("PermissionAdmin", (ModelAdmin,), {})
            site.register(
                Permission,
                admin_class=perm_admin,
                options=AdminOptions(can_create=False, can_delete=False),
            )

    def mount(self, path: str) -> None:
        """Mounts the admin interface on the FastAPI application."""
        if self.storage:
            self._mount_upload_storage()

        if self.auth_backend:
            self._register_auth_routes(path)
            self._register_auth_models()

        if self.settings.auto_discover:
            self._auto_register_models()

        self._register_locale_route(path)
        self._register_realtime_routes(path)
        self._register_views()
        self.templates.env.globals["admin_prefix"] = path.rstrip("/")
        self.templates.env.globals["auth_enabled"] = self.auth_backend is not None
        self.templates.env.globals["realtime_enabled"] = self.realtime is not None
        self.templates.env.globals["theme"] = self.settings.theme
        self.templates.env.globals["site_title"] = self.settings.site_title
        self.templates.env.globals["site_header"] = self.settings.site_header
        self.templates.env.globals["supported_locales"] = self.settings.supported_locales
        from hyperadmin.i18n import RTL_LOCALES

        self.templates.env.globals["rtl_locales"] = RTL_LOCALES

        if self.auth_backend:
            self.router.on_startup.append(self._sync_permissions)

        self.app.include_router(self.router, prefix=path, tags=["HyperAdmin"])

        # LocaleMiddleware runs whether or not auth is configured. It must be
        # added before the auth middleware so the chain is
        # SessionMiddleware -> AuthenticationMiddleware -> LocaleMiddleware -> routes.
        self._add_locale_middleware()

        if self.auth_backend:
            self._add_auth_middleware(path)

theme property

Active theme from settings.

__init__(app, engine=None, settings=None, auth_backend=None, permission_checker=None, permission_registry=None, storage=None, otp_service=None, realtime=None)

Initialise HyperAdmin and attach it to a FastAPI application.

Parameters:

Name	Type	Description	Default
app	FastAPI	The FastAPI application instance to attach the admin to.	required
engine	Any	An async SQLAlchemy engine. Defaults to the built-in hyperadmin.db.engine if not provided.	None
settings	HyperAdminSettings | None	A HyperAdminSettings instance. When None, one is auto-instantiated (reads HYPERADMIN_* env vars and .env).	None
auth_backend	Any	An optional authentication backend implementing the AuthBackend protocol. When None, auth is disabled.	None
permission_checker	Any	An optional PermissionChecker implementation.	None
permission_registry	Any	An optional PermissionRegistry implementation.	None
storage	Any	An optional FileSystemStorage (or compatible) instance for file uploads. When None, file upload support is disabled.	None
otp_service	Any	An optional MFA OTP service (e.g. EmailOTPService). When None, the MFA endpoints (/mfa/challenge etc) are NOT registered and login_view skips the MFA branch — apps without MFA are entirely unaffected (C3-A, #487).	None
realtime	RealtimeSettings | None	Opt-in RealtimeSettings. When None (default), no SSE / WebSocket endpoints are registered and the status widget is not injected — fully backward compatible. See docs/specs/realtime-connection-foundation.md.	None

Source code in src/hyperadmin/core/app.py

def __init__(
    self,
    app: FastAPI,
    engine: Any = None,
    settings: HyperAdminSettings | None = None,
    auth_backend: Any = None,
    permission_checker: Any = None,
    permission_registry: Any = None,
    storage: Any = None,
    otp_service: Any = None,
    realtime: RealtimeSettings | None = None,
) -> None:
    """Initialise HyperAdmin and attach it to a FastAPI application.

    Args:
        app: The FastAPI application instance to attach the admin to.
        engine: An async SQLAlchemy engine. Defaults to the built-in
            ``hyperadmin.db.engine`` if not provided.
        settings: A ``HyperAdminSettings`` instance. When ``None``, one is
            auto-instantiated (reads ``HYPERADMIN_*`` env vars and ``.env``).
        auth_backend: An optional authentication backend implementing the
            ``AuthBackend`` protocol. When ``None``, auth is disabled.
        permission_checker: An optional ``PermissionChecker`` implementation.
        permission_registry: An optional ``PermissionRegistry`` implementation.
        storage: An optional ``FileSystemStorage`` (or compatible) instance
            for file uploads. When ``None``, file upload support is disabled.
        otp_service: An optional MFA OTP service (e.g. ``EmailOTPService``).
            When ``None``, the MFA endpoints (``/mfa/challenge`` etc) are
            NOT registered and ``login_view`` skips the MFA branch — apps
            without MFA are entirely unaffected (C3-A, #487).
        realtime: Opt-in ``RealtimeSettings``. When ``None`` (default),
            no SSE / WebSocket endpoints are registered and the status
            widget is not injected — fully backward compatible. See
            ``docs/specs/realtime-connection-foundation.md``.
    """
    self.settings = settings or HyperAdminSettings()
    self.app = app
    self.router = APIRouter()
    self.engine = engine or default_engine
    self.auth_backend = auth_backend
    self.permission_checker = permission_checker
    self.permission_registry = permission_registry
    self.storage = storage
    self.otp_service = otp_service
    self.realtime = realtime
    self._realtime_registry: ConnectionRegistry | None = (
        ConnectionRegistry() if realtime is not None else None
    )

    self._validate_session_secret()

    template_dirs = self.settings.template_dirs
    template_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "templates")
    self.templates = Jinja2Templates(directory=[*template_dirs, template_dir])
    # Wire jinja2.ext.i18n + per-request gettext callables (C1-C). The
    # callables read translations from a context var populated by
    # LocaleMiddleware; outside a request they pass msgids through.
    from hyperadmin.i18n import install_jinja_i18n

    install_jinja_i18n(self.templates.env)

    static_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "static")
    if os.path.exists(static_dir):
        app.mount("/static", StaticFiles(directory=static_dir), name="static")

    if self.settings.create_tables:

        @app.on_event("startup")
        async def startup_event() -> None:
            await self._create_db_and_tables()

    if self.settings.discover_apps:
        discover_admin_modules(self.settings.discover_apps)

mount(path)

Mounts the admin interface on the FastAPI application.

Source code in src/hyperadmin/core/app.py

def mount(self, path: str) -> None:
    """Mounts the admin interface on the FastAPI application."""
    if self.storage:
        self._mount_upload_storage()

    if self.auth_backend:
        self._register_auth_routes(path)
        self._register_auth_models()

    if self.settings.auto_discover:
        self._auto_register_models()

    self._register_locale_route(path)
    self._register_realtime_routes(path)
    self._register_views()
    self.templates.env.globals["admin_prefix"] = path.rstrip("/")
    self.templates.env.globals["auth_enabled"] = self.auth_backend is not None
    self.templates.env.globals["realtime_enabled"] = self.realtime is not None
    self.templates.env.globals["theme"] = self.settings.theme
    self.templates.env.globals["site_title"] = self.settings.site_title
    self.templates.env.globals["site_header"] = self.settings.site_header
    self.templates.env.globals["supported_locales"] = self.settings.supported_locales
    from hyperadmin.i18n import RTL_LOCALES

    self.templates.env.globals["rtl_locales"] = RTL_LOCALES

    if self.auth_backend:
        self.router.on_startup.append(self._sync_permissions)

    self.app.include_router(self.router, prefix=path, tags=["HyperAdmin"])

    # LocaleMiddleware runs whether or not auth is configured. It must be
    # added before the auth middleware so the chain is
    # SessionMiddleware -> AuthenticationMiddleware -> LocaleMiddleware -> routes.
    self._add_locale_middleware()

    if self.auth_backend:
        self._add_auth_middleware(path)

HyperAdminSettings

Bases: BaseSettings

Django-like centralised settings for HyperAdmin.

All scalar configuration lives here — no duplicate params on Admin(). Values can be provided via environment variables (HYPERADMIN_* prefix), a .env file, or explicit keyword arguments (highest priority).

Example::

settings = HyperAdminSettings(secret_key="my-secret", theme="dark")
Admin(app, engine=engine, settings=settings)

# Or rely entirely on env vars / .env:
Admin(app, engine=engine)

Source code in src/hyperadmin/core/settings.py

class HyperAdminSettings(BaseSettings):
    """Django-like centralised settings for HyperAdmin.

    All scalar configuration lives here — no duplicate params on ``Admin()``.
    Values can be provided via environment variables (``HYPERADMIN_*`` prefix),
    a ``.env`` file, or explicit keyword arguments (highest priority).

    Example::

        settings = HyperAdminSettings(secret_key="my-secret", theme="dark")
        Admin(app, engine=engine, settings=settings)

        # Or rely entirely on env vars / .env:
        Admin(app, engine=engine)
    """

    model_config = SettingsConfigDict(
        env_prefix="HYPERADMIN_",
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
        extra="ignore",
    )

    # ── Branding ─────────────────────────────────────────────────────────────
    site_title: str = "HyperAdmin"
    site_header: str = "HyperAdmin"

    # ── Security ─────────────────────────────────────────────────────────────
    secret_key: str = Field(default=_DEFAULT_SECRET_KEY)

    # ── Database ─────────────────────────────────────────────────────────────
    database_url: str = _DEFAULT_DATABASE_URL

    # ── Runtime behaviour ─────────────────────────────────────────────────────
    debug: bool = False
    create_tables: bool = True

    # ── Discovery ─────────────────────────────────────────────────────────────
    auto_discover: bool = False
    discover_apps: list[str] = Field(default_factory=list)

    # ── Templates ─────────────────────────────────────────────────────────────
    template_dirs: list[str] = Field(default_factory=list)

    # ── UI ────────────────────────────────────────────────────────────────────
    theme: ThemeLiteral = "auto"
    items_per_page: int = Field(default=20, gt=0)

    # ── Uploads ───────────────────────────────────────────────────────────────
    upload_dir: str = "uploads"

    # ── Formatting ────────────────────────────────────────────────────────────
    date_format: str = "%Y-%m-%d"
    datetime_format: str = "%Y-%m-%d %H:%M:%S"

    # ── Internationalization ──────────────────────────────────────────────────
    default_locale: str = "en"
    supported_locales: list[str] = Field(default_factory=lambda: list(_DEFAULT_SUPPORTED_LOCALES))
    locale_response_header: bool = True

    # ── Derived helpers ───────────────────────────────────────────────────────
    @property
    def is_default_secret_key(self) -> bool:
        """Return ``True`` when ``secret_key`` has not been changed from the default."""
        return self.secret_key == _DEFAULT_SECRET_KEY

    @field_validator("theme", mode="before")
    @classmethod
    def _validate_theme(cls, value: str) -> str:
        valid = ("auto", "light", "dark")
        if value not in valid:
            msg = f"Invalid theme {value!r}. Must be one of {valid}"
            raise ValueError(msg)
        return value

is_default_secret_key property

Return True when secret_key has not been changed from the default.

RealtimeSettings

Bases: BaseModel

Opt-in configuration for real-time SSE / WebSocket endpoints.

Pass an instance to Admin(realtime=...) to enable real-time. Leaving the kwarg as None (the default) disables every code path in the realtime module — fully backward compatible.

Source code in src/hyperadmin/realtime/config.py

class RealtimeSettings(BaseModel):
    """Opt-in configuration for real-time SSE / WebSocket endpoints.

    Pass an instance to ``Admin(realtime=...)`` to enable real-time. Leaving
    the kwarg as ``None`` (the default) disables every code path in the
    ``realtime`` module — fully backward compatible.
    """

    heartbeat_interval: float = Field(
        default=15.0,
        gt=0,
        description=(
            "Seconds between heartbeats on both SSE (`:keepalive` comments) and "
            "WS (zero-byte ping). Default 15 s sits comfortably under the 60 s "
            "nginx `proxy_read_timeout` default."
        ),
    )
    max_connections: int | None = Field(
        default=None,
        ge=1,
        description=(
            "Optional cap on simultaneous connections per process. ``None`` "
            "(default) means unlimited; the cap exists as a circuit-breaker for "
            "deployments that want to fail-fast under unexpected load."
        ),
    )
    enable_test_endpoints: bool = Field(
        default=False,
        description=(
            "When ``True``, mounts ``/_test/realtime/*`` endpoints used by the "
            "Playwright suite to introspect the registry and simulate server-"
            "initiated drops. Must remain ``False`` in production."
        ),
    )

gettext_lazy(message)

Return a lazy proxy that translates message on each str(...) call.

Required for class-body strings (model verbose_name, field labels) where evaluation must defer until a request is active. enable_cache=False so the proxy re-translates every render -- otherwise the first locale wins.

Source code in src/hyperadmin/i18n/loader.py

def gettext_lazy(message: str) -> babel.support.LazyProxy:
    """Return a lazy proxy that translates ``message`` on each ``str(...)`` call.

    Required for class-body strings (model ``verbose_name``, field labels)
    where evaluation must defer until a request is active. ``enable_cache=False``
    so the proxy re-translates every render -- otherwise the first locale wins.
    """
    return babel.support.LazyProxy(lambda: gettext(message), enable_cache=False)