tempest-fastapi-sdk 0.71.0__tar.gz → 0.72.0__tar.gz

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.72.0] — 2026-06-26
+
+### Added
+
+- **`AdminTheme` — typed theming for the admin panel.** A new
+  `AdminTheme` dataclass carries appearance overrides (accent /
+  accent_hover / danger colors, header & sidebar backgrounds, page
+  background, border radius, font family, logo image + alt, favicon,
+  footer text, dark mode, and a `custom_css_url` escape hatch) through
+  typed, documented parameters. Pass it via `AdminSite(theme=...)`; the
+  SDK injects a `<style>` block of `:root` overrides after `admin.css`
+  (so it wins) plus the favicon / logo / footer chrome. `AdminTheme()`
+  is a no-op that reproduces the stock look, so existing sites are
+  unchanged. String fields reject `< > { } "` at construction to keep a
+  value from breaking the injected markup. Exported from
+  `tempest_fastapi_sdk` and `tempest_fastapi_sdk.admin`.
+
+## [0.71.1] — 2026-06-26
+
+### Fixed
+
+- **File logging no longer crashes the app on a non-writable filesystem.**
+  `configure_logging` now treats file logging as best-effort: if `log_dir`
+  cannot be created or its files cannot be opened (read-only mount, missing
+  write permission, hardened container, serverless, CI), the file handlers
+  are skipped, a warning is emitted (to the logger when stdout is on, else
+  straight to `stderr`), and the service keeps running with stdout logging
+  instead of dying at import time with
+  `PermissionError: [Errno 13] ... 'logs'`. `_build_file_handlers` also
+  closes any handlers it opened before a mid-build failure so no file
+  descriptors leak.
+- **Scaffold `Dockerfile` fixed so the non-root `app` user can write
+  `logs/`.** `WORKDIR /app` created `/app` as `root` before the
+  `COPY --chown=app:app`, and `--chown` only sets ownership on the copied
+  *contents* — not on the pre-existing `/app` directory node — so the `app`
+  user could not create `logs/` (or the SQLite `app.db`) inside it and the
+  container crash-looped at startup. The template now runs
+  `RUN mkdir -p /app/logs && chown -R app:app /app` after the copy. Existing
+  projects: regenerate with `tempest generate --dockerfile --force` or add
+  that line by hand.
+
 ## [0.71.0] — 2026-06-26
 
 ### Added

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/CLAUDE.md

@@ -129,7 +129,9 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   (`audit_model=...` + `add_audited` / `update_audited` /
   `delete_audited`, same-tx).
 - **Admin panel** — Jinja + HTMX (`AdminSite`, `AdminModel`,
-  `make_admin_router`).
+  `make_admin_router`), typed theming via `AdminTheme` (colors /
+  logo / favicon / font / radius / footer / dark mode /
+  `custom_css_url`, injected as `:root` overrides).
 - **CLI** — `tempest new` (scaffolds layered service +
   docker-compose + multi-stage uv `Dockerfile`/`.dockerignore`),
   `tempest generate --docker` (regen compose) / `--dockerfile`
@@ -160,12 +162,19 @@ mostly wiring, not greenfield.
 Build in tiers. Ship each item, document it (same-commit docs rule),
 then move it up to the covers list.
 
+**Shipped — `AdminTheme` (v0.72.0).** Typed appearance overrides
+(colors / logo / favicon / font / radius / footer / dark mode /
+`custom_css_url`) injected as `:root` CSS-variable overrides via
+`AdminSite(theme=...)`. This is the "beautiful + typed customization"
+foundation the user asked for first; the functional Tier 1 items below
+inherit the look for free. Now in the covers list.
+
 **Tier 1 — high value, reuses an existing engine (low effort):**
 
-1. **Custom actions** — `@admin_action` decorator on `AdminModel` for
-   user-defined row / bulk operations (Django `actions`, Nova actions).
-   Today only 3 are hardcoded (activate / deactivate / delete). This is
-   the foundation the rest build on.
+1. **Custom actions (NEXT)** — `@admin_action` decorator on `AdminModel`
+   for user-defined row / bulk operations (Django `actions`, Nova
+   actions). Today only 3 are hardcoded (activate / deactivate /
+   delete). This is the foundation the rest build on.
 2. **File / image upload field** — a new form widget wired to the
    existing `UploadUtils` (`LocalUploadStorage` / `MinIOUploadStorage`).
    Engine is already shipped; admin just needs the widget + storage

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.71.0
+Version: 0.72.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/docs/recipes/admin.en.md

@@ -271,3 +271,73 @@ class OAuthAdminBackend(AdminAuthBackend):
 
 Pass the instance via `auth_backend=` and the rest of the admin pipeline (sessions, dashboard, list, detail) keeps working unchanged.
 
+#### 6. Customize the look — `AdminTheme`
+
+The admin CSS is driven entirely by **CSS custom properties** on `:root`. Instead of forking the stylesheet, you pass an `AdminTheme` with **typed, documented parameters** — colors, logo, favicon, font, radius, footer, dark mode — and the SDK injects a `<style>` block in the `<head>` (after `admin.css`, so it wins).
+
+```python
+# src/admin/site.py
+from tempest_fastapi_sdk import AdminSite, AdminTheme
+
+theme: AdminTheme = AdminTheme(
+    accent="#7c3aed",                       # primary color (links, buttons, active item)
+    accent_hover="#6d28d9",                 # hover shade of the accent
+    header_bg="#1e1b4b",                    # header/sidebar background
+    radius="10px",                          # radius of buttons, inputs, cards, tables
+    font_family="'Inter', system-ui, sans-serif",
+    logo_url="/admin/static/logo.svg",      # header image (instead of the text brand)
+    favicon_url="/admin/static/favicon.ico",
+    footer_text="Servus | 2026",
+    dark_mode=False,                         # dark content surfaces
+)
+
+site: AdminSite = AdminSite(title="Servus Admin", brand="Servus", theme=theme)
+```
+
+`AdminTheme()` with no arguments is a **no-op**: it reproduces the stock look. You only set what you want to change.
+
+!!! tip "The golden rule"
+    Every `AdminTheme` field maps to a `:root` CSS variable (or to a piece
+    of chrome, like the logo). It is all typed — the editor autocompletes
+    the options and mypy validates — and no string ever needs to be a CSS
+    class name or selector.
+
+| Field | Type | Default | Effect |
+|-------|------|---------|--------|
+| `accent` | `str` | `"#2563eb"` | Primary color: links, buttons, active sidebar item |
+| `accent_hover` | `str` | `"#1d4ed8"` | Hover/active shade of `accent` |
+| `danger` | `str` | `"#b91c1c"` | Destructive actions and error messages |
+| `header_bg` | `str` | `"#0f172a"` | Header background |
+| `sidebar_bg` | `str \| None` | `None` | Sidebar background (falls back to `header_bg`) |
+| `page_bg` | `str \| None` | `None` | Content background (mode default) |
+| `radius` | `str` | `"6px"` | Radius of buttons, inputs, cards, tables |
+| `font_family` | `str \| None` | `None` | `font-family` for the whole panel |
+| `logo_url` | `str \| None` | `None` | Header image instead of the text brand |
+| `logo_alt` | `str` | `"Logo"` | `alt` text for the logo image |
+| `favicon_url` | `str \| None` | `None` | Browser-tab favicon |
+| `footer_text` | `str` | `"Powered by tempest-fastapi-sdk"` | Footer text |
+| `dark_mode` | `bool` | `False` | Dark content surfaces |
+| `custom_css_url` | `str \| None` | `None` | Extra stylesheet, linked last |
+
+!!! info "Dark mode"
+    `dark_mode=True` switches the **content surfaces** (page background,
+    text, table rows, inputs, borders) to a dark palette. The
+    header/sidebar are already dark, so they are unaffected; `accent` and
+    the other colors still apply. An explicit `page_bg` wins over dark mode.
+
+!!! warning "Escape hatch for the rest"
+    For anything the fields do not cover, point `custom_css_url` at your own
+    stylesheet. It is linked **after** the theme, so it overrides
+    everything — including `AdminTheme`.
+
+!!! danger "Values are developer-set, not end-user input"
+    The characters `< > { } "` are rejected in any string field
+    (`ValueError` at construction), because they would break the injected
+    `<style>` block or an HTML attribute. Never derive `AdminTheme` values
+    from end-user input.
+
+**Recap:** instantiate `AdminTheme` with the fields you want to change,
+pass it via `AdminSite(theme=...)`, and the look changes across every page
+(login, dashboard, list, detail, forms) without touching CSS. For full
+control, `custom_css_url`.
+

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/docs/recipes/admin.md

@@ -252,3 +252,73 @@ class OAuthAdminBackend(AdminAuthBackend):
 ```
 
 Passe a instância via `auth_backend=` e o resto do pipeline do admin (sessões, dashboard, list, detail) segue funcionando sem mudanças.
+
+#### 6. Customizar a aparência — `AdminTheme`
+
+O CSS do admin é todo dirigido por **CSS custom properties** em `:root`. Em vez de forkar a folha de estilo, você passa um `AdminTheme` com **parâmetros tipados e documentados** — cores, logo, favicon, fonte, raio, rodapé, modo escuro — e a SDK injeta um bloco `<style>` no `<head>` (depois do `admin.css`, então ele vence).
+
+```python
+# src/admin/site.py
+from tempest_fastapi_sdk import AdminSite, AdminTheme
+
+theme: AdminTheme = AdminTheme(
+    accent="#7c3aed",                       # cor primária (links, botões, item ativo)
+    accent_hover="#6d28d9",                 # tom de hover do accent
+    header_bg="#1e1b4b",                    # fundo do header/sidebar
+    radius="10px",                          # raio de botões, inputs, cards, tabelas
+    font_family="'Inter', system-ui, sans-serif",
+    logo_url="/admin/static/logo.svg",      # imagem no header (no lugar do texto)
+    favicon_url="/admin/static/favicon.ico",
+    footer_text="Servus | 2026",
+    dark_mode=False,                         # superfícies de conteúdo escuras
+)
+
+site: AdminSite = AdminSite(title="Servus Admin", brand="Servus", theme=theme)
+```
+
+`AdminTheme()` sem argumentos é um **no-op**: reproduz a aparência padrão. Você só define o que quer mudar.
+
+!!! tip "A regra de ouro"
+    Cada campo do `AdminTheme` mapeia para uma variável CSS de `:root` (ou
+    para um pedaço de chrome, como o logo). É tudo tipado — o autocomplete
+    do editor lista as opções e o mypy valida — e nenhuma string precisa
+    ser um nome de classe CSS ou seletor.
+
+| Campo | Tipo | Padrão | Efeito |
+|-------|------|--------|--------|
+| `accent` | `str` | `"#2563eb"` | Cor primária: links, botões, item ativo da sidebar |
+| `accent_hover` | `str` | `"#1d4ed8"` | Tom de hover/ativo do `accent` |
+| `danger` | `str` | `"#b91c1c"` | Ações destrutivas e mensagens de erro |
+| `header_bg` | `str` | `"#0f172a"` | Fundo do header |
+| `sidebar_bg` | `str \| None` | `None` | Fundo da sidebar (cai pra `header_bg`) |
+| `page_bg` | `str \| None` | `None` | Fundo do conteúdo (padrão do modo) |
+| `radius` | `str` | `"6px"` | Raio de botões, inputs, cards, tabelas |
+| `font_family` | `str \| None` | `None` | `font-family` do painel inteiro |
+| `logo_url` | `str \| None` | `None` | Imagem no header em vez do texto |
+| `logo_alt` | `str` | `"Logo"` | `alt` da imagem do logo |
+| `favicon_url` | `str \| None` | `None` | Favicon da aba |
+| `footer_text` | `str` | `"Powered by tempest-fastapi-sdk"` | Texto do rodapé |
+| `dark_mode` | `bool` | `False` | Superfícies de conteúdo escuras |
+| `custom_css_url` | `str \| None` | `None` | Folha de estilo extra, linkada por último |
+
+!!! info "Modo escuro"
+    `dark_mode=True` troca as **superfícies de conteúdo** (fundo da página,
+    texto, linhas da tabela, inputs, bordas) para uma paleta escura. O
+    header/sidebar já são escuros, então não mudam; `accent` e as outras
+    cores continuam valendo. Um `page_bg` explícito vence o modo escuro.
+
+!!! warning "Escape hatch para o resto"
+    Para o que os campos não cobrem, aponte `custom_css_url` para a sua
+    própria folha de estilo. Ela é linkada **depois** do tema, então
+    sobrescreve tudo — inclusive o `AdminTheme`.
+
+!!! danger "Valores são do desenvolvedor, não do usuário final"
+    Os caracteres `< > { } "` são rejeitados em qualquer campo de texto
+    (`ValueError` na construção), porque quebrariam o `<style>` injetado ou
+    um atributo HTML. Nunca derive valores de `AdminTheme` de entrada de
+    usuário final.
+
+**Recap:** instancie `AdminTheme` com os campos que quer mudar, passe via
+`AdminSite(theme=...)`, e a aparência muda em todas as páginas (login,
+dashboard, list, detail, forms) sem tocar em CSS. Para customização total,
+`custom_css_url`.

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/docs/recipes/logging.en.md

@@ -66,6 +66,15 @@ configure_logging(level="INFO", stdout=False)
     `ValueError` — silencing every handler leaves the application
     blind.
 
+!!! check "File logging is best-effort — it never crashes startup"
+    If `log_dir` cannot be created or its files cannot be opened
+    (read-only filesystem, missing write permission, hardened container,
+    serverless, CI), the SDK **skips** the file handlers, emits a warning
+    (to the logger when stdout is on, otherwise straight to `stderr`) and
+    keeps running with stdout only — instead of dying at import with
+    `PermissionError: [Errno 13] ... 'logs'`. Pass `file_output=False` to
+    opt out of file logging explicitly.
+
 On disk:
 
 ```text

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/docs/recipes/logging.md

@@ -66,6 +66,15 @@ configure_logging(level="INFO", stdout=False)
     `ValueError` — silenciar todos os handlers deixa a aplicação
     cega.
 
+!!! check "Log em arquivo é best-effort — nunca derruba o boot"
+    Se o `log_dir` não puder ser criado ou seus arquivos não puderem ser
+    abertos (FS read-only, falta de permissão de escrita, container
+    endurecido, serverless, CI), o SDK **pula** os handlers de arquivo,
+    emite um aviso (no logger quando o stdout está ligado, senão direto no
+    `stderr`) e segue rodando só com stdout — em vez de morrer no import com
+    `PermissionError: [Errno 13] ... 'logs'`. Para abrir mão do log em
+    arquivo de forma explícita, passe `file_output=False`.
+
 O resultado em disco:
 
 ```text

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.71.0"
+version = "0.72.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/tempest_fastapi_sdk/__init__.py

@@ -5,6 +5,7 @@ from tempest_fastapi_sdk.admin import (
     AdminAuthError,
     AdminModel,
     AdminSite,
+    AdminTheme,
     FieldRef,
     OrderRef,
     UserModelAuthBackend,
@@ -315,7 +316,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.71.0"
+__version__: str = "0.72.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -344,6 +345,7 @@ __all__: list[str] = [
     "AdminAuthError",
     "AdminModel",
     "AdminSite",
+    "AdminTheme",
     "AlembicHelper",
     "AppException",
     "AsyncDatabaseManager",

tempest_fastapi_sdk-0.72.0/tempest_fastapi_sdk/admin/__init__.py

@@ -0,0 +1,45 @@
+"""Django-admin-style management UI for FastAPI services.
+
+Mount via :func:`make_admin_router`; register one :class:`AdminModel`
+per SQLAlchemy model on the :class:`AdminSite` instance. The site
+auto-derives list/detail views from the existing
+:class:`tempest_fastapi_sdk.BaseRepository` so no extra controllers
+are needed for read-only management.
+
+Requires the ``[admin]`` optional extra (``jinja2`` +
+``itsdangerous``). Authentication relies on
+:class:`tempest_fastapi_sdk.BaseUserModel`: any user with
+``is_admin=True`` may sign in.
+"""
+
+from tempest_fastapi_sdk.admin.auth import AdminAuthBackend as AdminAuthBackend
+from tempest_fastapi_sdk.admin.auth import AdminAuthError as AdminAuthError
+from tempest_fastapi_sdk.admin.auth import UserModelAuthBackend as UserModelAuthBackend
+from tempest_fastapi_sdk.admin.config import AdminModel as AdminModel
+from tempest_fastapi_sdk.admin.config import FieldRef as FieldRef
+from tempest_fastapi_sdk.admin.config import OrderRef as OrderRef
+from tempest_fastapi_sdk.admin.discovery import discover_models as discover_models
+from tempest_fastapi_sdk.admin.router import make_admin_router as make_admin_router
+from tempest_fastapi_sdk.admin.session import AdminSession as AdminSession
+from tempest_fastapi_sdk.admin.session import SessionStore as SessionStore
+from tempest_fastapi_sdk.admin.session import (
+    SignedCookieSessionStore as SignedCookieSessionStore,
+)
+from tempest_fastapi_sdk.admin.site import AdminSite as AdminSite
+from tempest_fastapi_sdk.admin.theme import AdminTheme as AdminTheme
+
+__all__: list[str] = [
+    "AdminAuthBackend",
+    "AdminAuthError",
+    "AdminModel",
+    "AdminSession",
+    "AdminSite",
+    "AdminTheme",
+    "FieldRef",
+    "OrderRef",
+    "SessionStore",
+    "SignedCookieSessionStore",
+    "UserModelAuthBackend",
+    "discover_models",
+    "make_admin_router",
+]

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/tempest_fastapi_sdk/admin/site.py

@@ -6,6 +6,7 @@ from types import ModuleType
 from typing import TYPE_CHECKING, Any
 
 from tempest_fastapi_sdk.admin.config import AdminModel
+from tempest_fastapi_sdk.admin.theme import AdminTheme
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -30,6 +31,9 @@ class AdminSite:
         index_subtitle (str): Optional subtitle for the dashboard.
         site_url (str | None): Optional "View site" link rendered in
             the admin header.
+        theme (AdminTheme): Typed appearance overrides (colors, logo,
+            favicon, font, footer, dark mode). Defaults to a stock
+            :class:`AdminTheme`, so the look is unchanged when omitted.
     """
 
     def __init__(
@@ -39,6 +43,7 @@ class AdminSite:
         brand: str | None = None,
         index_subtitle: str = "Site administration",
         site_url: str | None = None,
+        theme: AdminTheme | None = None,
     ) -> None:
         """Initialize the site.
 
@@ -53,11 +58,15 @@ class AdminSite:
             index_subtitle (str): Dashboard subtitle.
             site_url (str | None): Optional outbound link rendered
                 in the admin header.
+            theme (AdminTheme | None): Typed appearance overrides.
+                ``None`` (default) uses a stock :class:`AdminTheme`,
+                leaving the look identical to earlier versions.
         """
         self.title: str = title
         self.brand: str | None = brand
         self.index_subtitle: str = index_subtitle
         self.site_url: str | None = site_url
+        self.theme: AdminTheme = theme or AdminTheme()
         self._registry: dict[str, AdminModel[Any]] = {}
 
     @property

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/tempest_fastapi_sdk/admin/static/admin.css

@@ -18,10 +18,10 @@
 
 body {
   margin: 0;
-  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  font-family: var(--tempest-font, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif);
   font-size: 14px;
   color: var(--tempest-fg);
-  background: #f8fafc;
+  background: var(--tempest-page-bg, #f8fafc);
   /* Sticky-footer column so the layout (and its sidebar) fills the
      viewport even when the page content is short. */
   min-height: 100vh;
@@ -90,6 +90,16 @@ textarea {
   font-weight: 600;
   font-size: 1.1rem;
   pointer-events: auto;
+  display: inline-flex;
+  align-items: center;
+}
+
+/* Logo image (shown instead of the brand text when theme.logo_url is
+   set). Capped to the header height so any aspect ratio fits cleanly. */
+.tempest-admin-header__logo {
+  display: block;
+  max-height: 32px;
+  width: auto;
 }
 
 .tempest-admin-header__nav {

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/tempest_fastapi_sdk/admin/templates/base.html

@@ -4,7 +4,14 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>{% block title %}{{ site.title }}{% endblock %}</title>
+  {% if site.theme.favicon_url %}
+  <link rel="icon" href="{{ site.theme.favicon_url }}">
+  {% endif %}
   <link rel="stylesheet" href="{{ static_url }}/admin.css">
+  <style>{{ site.theme.to_css() }}</style>
+  {% if site.theme.custom_css_url %}
+  <link rel="stylesheet" href="{{ site.theme.custom_css_url }}">
+  {% endif %}
   <script src="https://unpkg.com/htmx.org@2.0.3" defer></script>
 </head>
 <body>
@@ -19,7 +26,14 @@
       </label>
       {% endif %}
       <div class="tempest-admin-header__brand">
-        <a href="{{ url_for('admin_index') }}">{{ site.brand_text }}</a>
+        <a href="{{ url_for('admin_index') }}">
+          {% if site.theme.logo_url %}
+          <img src="{{ site.theme.logo_url }}" alt="{{ site.theme.logo_alt }}"
+               class="tempest-admin-header__logo">
+          {% else %}
+          {{ site.brand_text }}
+          {% endif %}
+        </a>
       </div>
     </div>
     {% if user %}
@@ -76,7 +90,7 @@
     </main>
   </div>
   <footer class="tempest-admin-footer">
-    <small>Powered by tempest-fastapi-sdk</small>
+    <small>{{ site.theme.footer_text }}</small>
   </footer>
 </body>
 </html>

tempest_fastapi_sdk-0.72.0/tempest_fastapi_sdk/admin/theme.py

@@ -0,0 +1,184 @@
+"""Typed theming for the admin panel.
+
+The bundled stylesheet (``static/admin.css``) is driven entirely by CSS
+custom properties declared on ``:root``. :class:`AdminTheme` lets a
+project override those properties — plus the logo, favicon, font and
+footer — through **typed, documented parameters** instead of forking the
+stylesheet. The values are injected as a ``<style>`` block in the page
+``<head>`` (after ``admin.css``, so they win), which means:
+
+* no CSS file to maintain on the project side,
+* every knob is type-checked and discoverable in the IDE,
+* the default look is unchanged when no theme is passed.
+
+Example::
+
+    from tempest_fastapi_sdk.admin import AdminSite, AdminTheme
+
+    site = AdminSite(
+        title="Servus Admin",
+        theme=AdminTheme(
+            accent="#7c3aed",
+            header_bg="#1e1b4b",
+            logo_url="/static/logo.svg",
+            font_family="'Inter', sans-serif",
+            radius="10px",
+            footer_text="Servus | 2026",
+        ),
+    )
+
+For anything the parameters do not cover, point :attr:`custom_css_url`
+at your own stylesheet — it is linked last, so it overrides everything,
+including this theme.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+
+# Characters that would let a theme value break out of the injected
+# ``<style>`` block or an HTML attribute. Theme values are developer-set
+# (not end-user input), but rejecting these keeps a careless value from
+# silently producing broken — or injectable — markup.
+_FORBIDDEN_CHARS: tuple[str, ...] = ("<", ">", "{", "}", '"')
+
+
+@dataclass(frozen=True)
+class AdminTheme:
+    """Typed appearance overrides for the admin panel.
+
+    Every field maps to a CSS custom property on ``:root`` (or to a
+    piece of chrome like the logo / footer). All fields have sensible
+    defaults that reproduce the stock look, so ``AdminTheme()`` is a
+    no-op and you only set what you want to change.
+
+    Attributes:
+        accent (str): Primary accent color — links, primary buttons,
+            active sidebar item. Any CSS color (``"#7c3aed"``,
+            ``"rebeccapurple"``, ``"rgb(124 58 237)"``).
+        accent_hover (str): Hover/active shade of :attr:`accent`.
+        danger (str): Color for destructive actions and error messages.
+        header_bg (str): Background of the top header band.
+        sidebar_bg (str | None): Background of the left sidebar. Falls
+            back to :attr:`header_bg` when ``None`` so the chrome reads
+            as one surface.
+        page_bg (str | None): Main content background. ``None`` uses the
+            mode default (light grey, or near-black when
+            :attr:`dark_mode` is on).
+        radius (str): Border-radius applied to buttons, inputs, cards
+            and tables (``"6px"``, ``"0.75rem"``, ``"0"`` for square).
+        font_family (str | None): CSS ``font-family`` for the whole
+            panel. ``None`` keeps the system font stack.
+        logo_url (str | None): URL of an image shown in the header
+            instead of the brand text. ``None`` shows the text brand.
+        logo_alt (str): ``alt`` text for the logo image.
+        favicon_url (str | None): URL of the browser-tab favicon.
+            ``None`` lets the browser use its default.
+        footer_text (str): Text shown in the page footer.
+        dark_mode (bool): When ``True``, the content surfaces (page
+            background, text, table rows, inputs, borders) switch to a
+            dark palette. The header/sidebar are already dark, so they
+            are unaffected; :attr:`accent` and the other colors still
+            apply.
+        custom_css_url (str | None): URL of an extra stylesheet linked
+            **after** the theme, so it overrides everything. The escape
+            hatch for anything the typed fields do not cover.
+    """
+
+    accent: str = "#2563eb"
+    accent_hover: str = "#1d4ed8"
+    danger: str = "#b91c1c"
+    header_bg: str = "#0f172a"
+    sidebar_bg: str | None = None
+    page_bg: str | None = None
+    radius: str = "6px"
+    font_family: str | None = None
+    logo_url: str | None = None
+    logo_alt: str = "Logo"
+    favicon_url: str | None = None
+    footer_text: str = "Powered by tempest-fastapi-sdk"
+    dark_mode: bool = False
+    custom_css_url: str | None = None
+
+    def __post_init__(self) -> None:
+        """Validate that no string field can break out of the markup.
+
+        Raises:
+            ValueError: When any string field contains a character from
+                :data:`_FORBIDDEN_CHARS` (``< > { } "``), which would
+                corrupt the injected ``<style>`` block or an HTML
+                attribute.
+        """
+        for field in fields(self):
+            value = getattr(self, field.name)
+            if isinstance(value, str):
+                bad = [c for c in _FORBIDDEN_CHARS if c in value]
+                if bad:
+                    raise ValueError(
+                        f"AdminTheme.{field.name} contains forbidden "
+                        f"character(s) {bad!r}; these would break the "
+                        f"injected <style>/HTML. Got: {value!r}"
+                    )
+
+    def css_variables(self) -> dict[str, str]:
+        """Return the ``:root`` custom properties this theme sets.
+
+        Returns:
+            dict[str, str]: Mapping of CSS variable name to value. Only
+            the always-present variables are included here; mode- and
+            font-dependent rules are emitted by :meth:`to_css`.
+        """
+        variables: dict[str, str] = {
+            "--tempest-accent": self.accent,
+            "--tempest-accent-hover": self.accent_hover,
+            "--tempest-danger": self.danger,
+            "--tempest-bg": self.header_bg,
+            "--tempest-bg-soft": self.sidebar_bg or self.header_bg,
+            "--tempest-radius": self.radius,
+        }
+        if self.font_family is not None:
+            variables["--tempest-font"] = self.font_family
+        if self.page_bg is not None:
+            variables["--tempest-page-bg"] = self.page_bg
+        return variables
+
+    def to_css(self) -> str:
+        """Render the full ``<style>`` body for this theme.
+
+        Combines the :meth:`css_variables` ``:root`` block with the
+        optional dark-mode surface overrides. The result is injected
+        verbatim inside a ``<style>`` element in the page ``<head>``.
+
+        Returns:
+            str: CSS text. Empty-safe — a default ``AdminTheme()`` still
+            returns a valid (no-op-equivalent) block.
+        """
+        root_lines = "\n".join(
+            f"  {name}: {value};" for name, value in self.css_variables().items()
+        )
+        blocks: list[str] = [f":root {{\n{root_lines}\n}}"]
+
+        if self.dark_mode and self.page_bg is None:
+            # Dark surfaces for the content area. The header/sidebar are
+            # already dark via --tempest-bg. Skipped when the project
+            # pinned its own page_bg (explicit value wins).
+            blocks.append(
+                ":root {\n"
+                "  --tempest-page-bg: #0b1120;\n"
+                "  --tempest-bg-row: #1e293b;\n"
+                "  --tempest-bg-row-alt: #172033;\n"
+                "  --tempest-fg: #e2e8f0;\n"
+                "  --tempest-fg-soft: #94a3b8;\n"
+                "}\n"
+                "body { color: var(--tempest-fg); }\n"
+                "input, select, textarea {\n"
+                "  background: #1e293b;\n"
+                "  color: var(--tempest-fg);\n"
+                "  border-color: #334155;\n"
+                "}"
+            )
+
+        if self.font_family is not None:
+            blocks.append("body { font-family: var(--tempest-font); }")
+
+        return "\n".join(blocks)

{tempest_fastapi_sdk-0.71.0 → tempest_fastapi_sdk-0.72.0}/tempest_fastapi_sdk/cli/_templates/Dockerfile.tmpl

@@ -45,6 +45,14 @@ RUN useradd --create-home --uid 1000 app
 WORKDIR /app
 COPY --from=builder --chown=app:app /app /app
 
+# WORKDIR created /app as root before the COPY, and `COPY --chown` only sets
+# ownership on the copied *contents* — not on the pre-existing /app directory
+# node itself. So the app user cannot create new entries (the runtime logs/
+# dir, the default SQLite app.db, etc.) inside /app and the app crashes at
+# startup with `PermissionError: [Errno 13] ... 'logs'`. Chown the directory
+# and pre-create logs/ so the SDK's file logging (LOG_DIR=logs) works.
+RUN mkdir -p /app/logs && chown -R app:app /app
+
 # Put the venv on PATH so `python` resolves to the project interpreter.
 # SERVER_HOST=0.0.0.0 binds all interfaces inside the container so the app
 # is reachable from the host (overridable via .env / `environment:`).