openadmin-dev 0.7.8__tar.gz → 0.7.10__tar.gz

{openadmin_dev-0.7.8 → openadmin_dev-0.7.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openadmin-dev
-Version: 0.7.8
+Version: 0.7.10
 Summary: Add your description here
 Project-URL: Homepage, https://github.com/openadmin-team/openadmin-py
 Project-URL: Issues, https://github.com/openadmin-team/openadmin-py/issues

{openadmin_dev-0.7.8 → openadmin_dev-0.7.10}/examples/admin/analytics.py

@@ -63,50 +63,6 @@ async def get_books_with_summary(session: AsyncSessionDep) -> int:
     return result.scalar_one()
 
 
-@page.line_chart(
-    "Publications by Decade", description="Number of books published per decade"
-)
-async def get_publications_by_decade(session: AsyncSessionDep):
-    stmt = (
-        select(
-            (func.floor(models.Book.published_year / 10) * 10).label("decade"),
-            func.count(models.Book.id).label("count"),
-        )
-        .where(models.Book.published_year.isnot(None))
-        .group_by("decade")
-        .order_by("decade")
-    )
-    result = await session.execute(stmt)
-    return [{"label": f"{int(row.decade)}s", "value": row.count} for row in result]
-
-
-@page.area_chart(
-    "Books Published by Era", description="Book volume across broad historical eras"
-)
-async def get_books_by_era(session: AsyncSessionDep):
-    eras: list[tuple[str, int | None, int | None]] = [
-        ("Pre-1900", None, 1900),
-        ("1900–1950", 1900, 1950),
-        ("1950–1980", 1950, 1980),
-        ("1980–2000", 1980, 2000),
-        ("2000–2010", 2000, 2010),
-        ("2010–2020", 2010, 2020),
-        ("2020+", 2020, None),
-    ]
-    rows = []
-    for label, start, end in eras:
-        stmt = select(func.count(models.Book.id)).where(
-            models.Book.published_year.isnot(None)
-        )
-        if start is not None:
-            stmt = stmt.where(models.Book.published_year >= start)
-        if end is not None:
-            stmt = stmt.where(models.Book.published_year < end)
-        count = (await session.execute(stmt)).scalar_one()
-        rows.append({"label": label, "value": count})
-    return rows
-
-
 @page.markdown("Library Overview")
 async def get_library_overview(session: AsyncSessionDep) -> str:
     total_books = (

{openadmin_dev-0.7.8 → openadmin_dev-0.7.10}/examples/admin/authors.py

@@ -31,7 +31,7 @@ async def get_total_authors(session: AsyncSessionDep) -> spec.StatResponse:
     color="emerald",
     description="Authors that have a biography on file",
 )
-async def get_authors_with_bio(session: AsyncSessionDep) -> int:
+async def get_authors_with_bio(session: AsyncSessionDep):
     result = await session.execute(
         select(func.count(models.Author.id)).where(models.Author.bio.isnot(None))
     )
@@ -54,7 +54,12 @@ async def get_avg_books_per_author(session: AsyncSessionDep) -> float:
     return round(float(result.scalar_one() or 0), 2)
 
 
-@page.table("All Authors", description="Browse authors with search and book counts")
+@page.table(
+    "All Authors",
+    description="Browse authors with search and book counts",
+    icon="user-pen",
+    color="indigo",
+)
 async def get_all_authors(
     session: AsyncSessionDep, pagination: PageDep, search: SearchQueryDep
 ):
@@ -62,7 +67,7 @@ async def get_all_authors(
         select(models.Author, func.count(models.Book.id).label("book_count"))
         .outerjoin(models.Book, models.Book.author_id == models.Author.id)
         .group_by(models.Author.id)
-        .offset(pagination.page * pagination.per_page)
+        .offset((pagination.page - 1) * pagination.per_page)
         .limit(pagination.per_page)
     )
     if search:
@@ -105,12 +110,28 @@ class AddAuthorBody(BaseModel):
     first_name: str
     last_name: str
     bio: str | None = None
-
-
-@page.form_post("Add Author", description="Register a new author in the catalog")
-async def add_author(body: AddAuthorBody, session: AsyncSessionDep):
+    friend: int
+
+
+@page.form(
+    "Add Author",
+    description="Register a new author in the catalog",
+    fields={
+        "friend": {
+            "reference": get_all_authors,
+            "icon": "user",
+            "color": "blue",
+            "reference_field": "id",
+        }
+    },
+)
+async def add_author(body: AddAuthorBody, session: AsyncSessionDep) -> spec.Form:
     author = models.Author(**body.model_dump())
     session.add(author)
     await session.commit()
     await session.refresh(author)
-    return {"id": author.id, "name": f"{author.first_name} {author.last_name}"}
+    name = f"{author.first_name} {author.last_name}"
+    return {
+        "message": f"Added author '{name}'",
+        "table": {"id": author.id, "name": name},
+    }

{openadmin_dev-0.7.8 → openadmin_dev-0.7.10}/examples/admin/books.py

@@ -6,6 +6,7 @@ from fastapi import Query
 from pydantic import BaseModel
 from sqlalchemy import func, select
 
+from openadmin import spec
 from openadmin.fastapi import AdminPage
 from openadmin.fastapi.deps import PageDep, SearchQueryDep
 
@@ -37,14 +38,19 @@ async def get_books_without_publisher(session: AsyncSessionDep) -> int:
     return result.scalar_one()
 
 
-@page.table("All Books", description="Browse all books with search and pagination")
+@page.table(
+    "All Books",
+    description="Browse all books with search and pagination",
+    icon="book",
+    color="blue",
+)
 async def get_all_books(
     session: AsyncSessionDep, pagination: PageDep, search: SearchQueryDep
 ):
     stmt = (
         select(models.Book, models.Author)
         .join(models.Author, models.Author.id == models.Book.author_id)
-        .offset(pagination.page * pagination.per_page)
+        .offset((pagination.page - 1) * pagination.per_page)
         .limit(pagination.per_page)
     )
     if search:
@@ -69,14 +75,19 @@ class AddBookBody(BaseModel):
     publisher_id: int | None = None
 
 
-@page.table("Books by Author", description="Number of books per author")
+@page.table(
+    "Books by Author",
+    description="Number of books per author",
+    icon="users-round",
+    color="violet",
+)
 async def get_books_by_author(session: AsyncSessionDep, pagination: PageDep):
     stmt = (
         select(models.Author, func.count(models.Book.id).label("book_count"))
         .join(models.Book, models.Book.author_id == models.Author.id)
         .group_by(models.Author.id)
         .order_by(func.count(models.Book.id).desc())
-        .offset(pagination.page * pagination.per_page)
+        .offset((pagination.page - 1) * pagination.per_page)
         .limit(pagination.per_page)
     )
     result = await session.execute(stmt)
@@ -89,22 +100,31 @@ async def get_books_by_author(session: AsyncSessionDep, pagination: PageDep):
     ]
 
 
-@page.form_post("Add Book", description="Add a new book to the catalog")
-async def add_book(body: AddBookBody, session: AsyncSessionDep):
+@page.form("Add Book", description="Add a new book to the catalog")
+async def add_book(body: AddBookBody, session: AsyncSessionDep) -> spec.Form:
     book = models.Book(**body.model_dump())
     session.add(book)
     await session.commit()
     await session.refresh(book)
-    return {"id": book.id, "title": book.title}
+    return {
+        "message": f"Added book '{book.title}'",
+        "table": {"id": book.id, "title": book.title},
+    }
 
 
-@page.action_delete("Delete Book", description="Remove a book by ID")
+@page.action("Delete Book", method="delete", description="Remove a book by ID")
 async def delete_book(
     session: AsyncSessionDep,
     book_id: int = Query(..., description="Book ID to delete"),
-):
+) -> spec.Action:
     book = await session.get(models.Book, book_id)
     if book:
         await session.delete(book)
         await session.commit()
-    return {"deleted": book_id, "found": book is not None}
+    found = book is not None
+    return {
+        "message": f"Deleted book #{book_id}"
+        if found
+        else f"Book #{book_id} not found",
+        "table": {"deleted": book_id, "found": found},
+    }

openadmin_dev-0.7.10/examples/admin/control_panel.py

@@ -0,0 +1,213 @@
+# SPDX-FileCopyrightText: 2026 OpenAdmin
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from typing import Annotated
+
+from fastapi import Body, Depends, Form, Query
+from pydantic import BaseModel
+
+from openadmin import spec
+from openadmin.fastapi import AdminPage
+
+page = AdminPage(
+    "Control Panel",
+    icon="settings",
+    description="Every action/form parameter and response shape, demoed with example data",
+)
+
+
+def current_actor(
+    actor: str = Query("system", description="Who is performing this operation"),
+) -> str:
+    return actor
+
+
+ActorDep = Annotated[str, Depends(current_actor)]
+
+
+# ---------------------------------------------------------------------------
+# Actions — one per HTTP verb, each showing a different param source and a
+# different Action response shape. Nothing here mutates real state.
+# ---------------------------------------------------------------------------
+
+
+@page.action(
+    "Ping Service",
+    method="get",
+    description="Check whether a downstream service is reachable",
+    icon="activity",
+    color="green",
+    is_hidden=False,
+)
+async def ping_service(
+    target: str = Query("api", description="Service name to ping"),
+) -> spec.Action:
+    return {
+        "icon": "activity",
+        "color": "green",
+        "toast": f"{target} responded in 12ms",
+        "message": f"Pinged '{target}' — reachable (example response, nothing was contacted)",
+    }
+
+
+class NotificationBody(BaseModel):
+    title: str
+    body: str
+    recipient: str | None = None
+
+
+@page.action(
+    "Send Test Notification",
+    method="post",
+    description="Send a one-off notification through the messaging provider",
+    icon="send",
+    color="blue",
+)
+async def send_test_notification(
+    body: NotificationBody,
+    actor: ActorDep,
+    dry_run: bool = Query(True, description="Simulate without actually sending"),
+) -> str:
+    target = body.recipient or "all subscribers"
+    verb = "Would send" if dry_run else "Sent"
+    return (
+        f"{verb} '{body.title}' to {target} (requested by {actor}) — "
+        "example only, nothing was sent"
+    )
+
+
+@page.action(
+    "Update Feature Flag",
+    method="put",
+    description="Flip a feature flag on or off for every user",
+    icon="toggle-left",
+    color="violet",
+    is_hidden=True,
+)
+async def update_feature_flag(
+    flag_name: str = Query(..., description="Flag key, e.g. new-dashboard"),
+    enabled: bool = Query(..., description="New flag state"),
+) -> spec.Action:
+    return {
+        "toast": f"{flag_name} -> {enabled}",
+        "message": "Preview of the change below (example data, flag was not modified)",
+        "table": [{"flag": flag_name, "previous": not enabled, "new": enabled}],
+    }
+
+
+@page.action(
+    "Rotate API Key",
+    method="patch",
+    description="Issue a new API key and retire the previous one",
+    icon="key",
+    color="amber",
+)
+async def rotate_api_key(
+    key_name: str = Form(..., description="Key to rotate"),
+    expires_in_days: int = Form(30, description="Validity period for the new key"),
+) -> spec.Action:
+    return None
+
+
+@page.action(
+    "Purge Temp Files",
+    method="delete",
+    description="Delete temporary files older than a given age",
+    icon="trash-2",
+    color="red",
+)
+async def purge_temp_files(
+    older_than_days: int = Query(7, ge=0, description="Age threshold in days"),
+) -> spec.Action:
+    return {
+        "message": (
+            f"Would delete files older than {older_than_days} days "
+            "(example — nothing was purged)"
+        )
+    }
+
+
+# ---------------------------------------------------------------------------
+# Forms — one per HTTP verb (post/put/patch/delete demoed here).
+# ---------------------------------------------------------------------------
+
+
+class WebhookBody(BaseModel):
+    url: str
+    event: str
+    secret: str | None = None
+
+
+@page.form(
+    "Create Webhook",
+    method="post",
+    description="Register a new outgoing webhook",
+    icon="webhook",
+    color="teal",
+)
+async def create_webhook(body: WebhookBody) -> spec.Form:
+    return {
+        "icon": "webhook",
+        "color": "teal",
+        "toast": "Webhook created",
+        "message": f"Would create a webhook for '{body.event}' -> {body.url}",
+        "table": {
+            "data": [{"id": 1, "url": body.url, "event": body.event}],
+            "icon": "webhook",
+            "color": "teal",
+        },
+    }
+
+
+class RateLimitBody(BaseModel):
+    requests_per_minute: int
+    burst_size: int = 0
+
+
+@page.form(
+    "Update Rate Limit",
+    method="put",
+    description="Replace the current API rate-limit configuration",
+    icon="gauge",
+    color="cyan",
+    is_hidden=True,
+)
+async def update_rate_limit(body: RateLimitBody) -> spec.Form:
+    return {
+        "icon": "gauge",
+        "color": "cyan",
+        "toast": f"Rate limit set to {body.requests_per_minute}/min "
+        f"(burst {body.burst_size}) — example only, nothing was saved",
+    }
+
+
+@page.form(
+    "Rename Environment",
+    method="patch",
+    description="Rename an existing deployment environment",
+    icon="pencil",
+    color="orange",
+)
+async def rename_environment(
+    environment_id: int = Query(..., description="Environment to rename"),
+    new_name: str = Body(..., embed=True, description="New environment name"),
+) -> str:
+    return (
+        f"Would rename environment #{environment_id} to '{new_name}' "
+        "(example only, nothing was renamed)"
+    )
+
+
+@page.form(
+    "Schedule Config Reset",
+    method="delete",
+    description="Queue a configuration reset for the next maintenance window",
+    icon="rotate-ccw",
+    color="rose",
+    is_hidden=False,
+)
+async def schedule_config_reset(
+    config_id: int = Query(..., description="Config entry to reset"),
+) -> spec.Form:
+    return None

{openadmin_dev-0.7.8 → openadmin_dev-0.7.10}/examples/admin/genres.py

@@ -56,7 +56,7 @@ async def get_all_genres(session: AsyncSessionDep, pagination: PageDep):
         .outerjoin(models.BookToGenre, models.BookToGenre.genre_id == models.Genre.id)
         .group_by(models.Genre.id)
         .order_by(func.count(models.BookToGenre.book_id).desc())
-        .offset(pagination.page * pagination.per_page)
+        .offset((pagination.page - 1) * pagination.per_page)
         .limit(pagination.per_page)
     )
     result = await session.execute(stmt)
@@ -74,7 +74,7 @@ async def get_all_genres(session: AsyncSessionDep, pagination: PageDep):
 @page.pie_chart(
     "Genre Distribution 1",
     description="Share of books across all genres",
-    name_key="name",
+    name_key="genre",
     value_key="count",
 )
 async def get_genre_distribution_1(session: AsyncSessionDep):
@@ -85,7 +85,7 @@ async def get_genre_distribution_1(session: AsyncSessionDep):
         .order_by(func.count(models.BookToGenre.book_id).desc())
     )
     result = await session.execute(stmt)
-    return [{**g, "count": count} for g, count in result.all()]
+    return [{"genre": g.name, "count": count} for g, count in result.all()]
 
 
 @page.pie_chart("Genre Distribution 2", description="Share of books across all genres")

{openadmin_dev-0.7.8 → openadmin_dev-0.7.10}/examples/admin/health.py

@@ -39,41 +39,6 @@ async def get_active_connections() -> int:
     return 12
 
 
-@page.line_chart(
-    "Response Time (last 24h)",
-    description="Simulated p95 latency over the past 24 hours",
-)
-async def get_response_time_chart():
-    hours = [f"{h:02d}:00" for h in range(24)]
-    values = [
-        72,
-        68,
-        65,
-        63,
-        61,
-        60,
-        66,
-        78,
-        95,
-        110,
-        105,
-        98,
-        101,
-        99,
-        97,
-        102,
-        108,
-        115,
-        112,
-        104,
-        98,
-        91,
-        84,
-        79,
-    ]
-    return [{"label": label, "value": value} for label, value in zip(hours, values)]
-
-
 @page.markdown("Health Status")
 async def get_health_status() -> str:
     return """# System Health

{openadmin_dev-0.7.8 → openadmin_dev-0.7.10}/examples/admin/overview.py

@@ -4,6 +4,7 @@
 
 from sqlalchemy import func, select, text
 
+from openadmin import spec
 from openadmin.fastapi import AdminPage
 
 from ..lib import models
@@ -78,10 +79,14 @@ Foreign keys are enforced at the application layer.
 """
 
 
-@page.action_get("Ping Database", description="Verify the database connection is alive")
-async def ping_database(session: AsyncSessionDep):
+@page.action(
+    "Ping Database",
+    method="get",
+    description="Verify the database connection is alive",
+)
+async def ping_database(session: AsyncSessionDep) -> spec.Action:
     await session.execute(text("SELECT 1"))
-    return {"status": "ok", "message": "Database is reachable"}
+    return {"message": "Database is reachable"}
 
 
 async def _all_table_counts(session: AsyncSessionDep) -> list[tuple[str, int]]:

{openadmin_dev-0.7.8 → openadmin_dev-0.7.10}/examples/admin/publishers.py

@@ -5,6 +5,7 @@
 from pydantic import BaseModel
 from sqlalchemy import func, select
 
+from openadmin import spec
 from openadmin.fastapi import AdminPage
 from openadmin.fastapi.deps import PageDep, SearchQueryDep
 
@@ -42,7 +43,12 @@ async def get_books_without_publisher(session: AsyncSessionDep) -> int:
     return result.scalar_one()
 
 
-@page.table("All Publishers", description="Browse publishers with their book counts")
+@page.table(
+    "All Publishers",
+    description="Browse publishers with their book counts",
+    icon="building-2",
+    color="amber",
+)
 async def get_all_publishers(
     session: AsyncSessionDep, pagination: PageDep, search: SearchQueryDep
 ):
@@ -51,7 +57,7 @@ async def get_all_publishers(
         .outerjoin(models.Book, models.Book.publisher_id == models.Publisher.id)
         .group_by(models.Publisher.id)
         .order_by(func.count(models.Book.id).desc())
-        .offset(pagination.page * pagination.per_page)
+        .offset((pagination.page - 1) * pagination.per_page)
         .limit(pagination.per_page)
     )
     if search:
@@ -81,10 +87,13 @@ class AddPublisherBody(BaseModel):
     country: str | None = None
 
 
-@page.form_post("Add Publisher", description="Register a new publisher")
-async def add_publisher(body: AddPublisherBody, session: AsyncSessionDep):
+@page.form("Add Publisher", description="Register a new publisher")
+async def add_publisher(body: AddPublisherBody, session: AsyncSessionDep) -> spec.Form:
     publisher = models.Publisher(**body.model_dump())
     session.add(publisher)
     await session.commit()
     await session.refresh(publisher)
-    return {"id": publisher.id, "name": publisher.name}
+    return {
+        "message": f"Added publisher '{publisher.name}'",
+        "table": {"id": publisher.id, "name": publisher.name},
+    }

{openadmin_dev-0.7.8 → openadmin_dev-0.7.10}/examples/admin/reports.py

@@ -47,7 +47,10 @@ async def get_heavily_tagged_books(session: AsyncSessionDep) -> int:
 
 
 @page.table(
-    "Most Tagged Books", description="Books with the highest number of tag assignments"
+    "Most Tagged Books",
+    description="Books with the highest number of tag assignments",
+    icon="tags",
+    color="orange",
 )
 async def get_most_tagged_books(session: AsyncSessionDep, pagination: PageDep):
     stmt = (
@@ -59,7 +62,7 @@ async def get_most_tagged_books(session: AsyncSessionDep, pagination: PageDep):
         .join(models.BookToTag, models.BookToTag.book_id == models.Book.id)
         .group_by(models.Book.id)
         .order_by(func.count(models.BookToTag.tag_id).desc())
-        .offset(pagination.page * pagination.per_page)
+        .offset((pagination.page - 1) * pagination.per_page)
         .limit(pagination.per_page)
     )
     result = await session.execute(stmt)
@@ -107,39 +110,3 @@ async def get_tag_count_distribution(session: AsyncSessionDep):
             ).scalar_one()
         rows.append({"label": label, "value": count})
     return rows
-
-
-@page.area_chart(
-    "Catalog Coverage", description="Books with genre, tag, and summary metadata"
-)
-async def get_catalog_coverage(session: AsyncSessionDep):
-    total = (await session.execute(select(func.count(models.Book.id)))).scalar_one()
-    with_genre = (
-        await session.execute(
-            select(func.count(func.distinct(models.BookToGenre.book_id)))
-        )
-    ).scalar_one()
-    with_tag = (
-        await session.execute(
-            select(func.count(func.distinct(models.BookToTag.book_id)))
-        )
-    ).scalar_one()
-    with_summary = (
-        await session.execute(
-            select(func.count(models.Book.id)).where(models.Book.summary.isnot(None))
-        )
-    ).scalar_one()
-    with_publisher = (
-        await session.execute(
-            select(func.count(models.Book.id)).where(
-                models.Book.publisher_id.isnot(None)
-            )
-        )
-    ).scalar_one()
-    return [
-        {"label": "Total Books", "value": total},
-        {"label": "Has Genre", "value": with_genre},
-        {"label": "Has Tag", "value": with_tag},
-        {"label": "Has Summary", "value": with_summary},
-        {"label": "Has Publisher", "value": with_publisher},
-    ]