openadmin-dev 0.3.0__tar.gz → 0.4.0__tar.gz

{openadmin_dev-0.3.0 → openadmin_dev-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openadmin-dev
-Version: 0.3.0
+Version: 0.4.0
 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
@@ -27,7 +27,7 @@ Description-Content-Type: text/markdown
 # 🚧 Project is under development 🚧
 ---
 
-**OpenAdmin** is a FastAPI-native library for building admin dashboards. Define pages with typed decorators — no frontend code, no templates, no configuration files. Every page is just a router; every widget is just an endpoint.
+**OpenAdmin** is a FastAPI-native library for building admin dashboards. Define pages with typed decorators — no frontend code, no templates, no configuration files. Every page is just a router; every widget is just an endpoint
 
 ## Features
 

{openadmin_dev-0.3.0 → openadmin_dev-0.4.0}/README.md

@@ -12,7 +12,7 @@
 # 🚧 Project is under development 🚧
 ---
 
-**OpenAdmin** is a FastAPI-native library for building admin dashboards. Define pages with typed decorators — no frontend code, no templates, no configuration files. Every page is just a router; every widget is just an endpoint.
+**OpenAdmin** is a FastAPI-native library for building admin dashboards. Define pages with typed decorators — no frontend code, no templates, no configuration files. Every page is just a router; every widget is just an endpoint
 
 ## Features
 

openadmin_dev-0.4.0/examples/admin/analytics.py

@@ -0,0 +1,119 @@
+# SPDX-FileCopyrightText: 2026 OpenAdmin
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from sqlalchemy import func, select
+
+from openadmin.fastapi import AdminPage
+
+from ..lib import models
+from ..lib.database import AsyncSessionDep
+
+page = AdminPage(
+    "Analytics", description="Library-wide publication trends and insights"
+)
+
+
+@page.stat("Earliest Publication")
+async def get_earliest_publication(session: AsyncSessionDep) -> int | str:
+    result = await session.execute(
+        select(func.min(models.Book.published_year)).where(
+            models.Book.published_year.isnot(None)
+        )
+    )
+    return result.scalar_one_or_none() or "N/A"
+
+
+@page.stat("Latest Publication")
+async def get_latest_publication(session: AsyncSessionDep) -> int | str:
+    result = await session.execute(
+        select(func.max(models.Book.published_year)).where(
+            models.Book.published_year.isnot(None)
+        )
+    )
+    return result.scalar_one_or_none() or "N/A"
+
+
+@page.stat("Books with Summary")
+async def get_books_with_summary(session: AsyncSessionDep) -> int:
+    result = await session.execute(
+        select(func.count(models.Book.id)).where(models.Book.summary.isnot(None))
+    )
+    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 = (
+        await session.execute(select(func.count(models.Book.id)))
+    ).scalar_one()
+    total_authors = (
+        await session.execute(select(func.count(models.Author.id)))
+    ).scalar_one()
+    total_publishers = (
+        await session.execute(select(func.count(models.Publisher.id)))
+    ).scalar_one()
+    total_genres = (
+        await session.execute(select(func.count(models.Genre.id)))
+    ).scalar_one()
+    total_tags = (await session.execute(select(func.count(models.Tag.id)))).scalar_one()
+
+    return f"""# Library Overview
+
+This catalog contains **{total_books:,} books** written by **{total_authors} authors**
+and published by **{total_publishers} publishers**.
+
+## Classification
+
+The collection is organized across **{total_genres} genres** and annotated with **{total_tags} tags**,
+enabling precise discovery and filtering across the full catalog.
+
+## Coverage
+
+Books span multiple centuries of publication history, from early historical works through
+contemporary releases, with particular depth in the 20th and 21st century catalog.
+"""

openadmin_dev-0.4.0/examples/admin/authors.py

@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: 2026 OpenAdmin
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from pydantic import BaseModel
+from sqlalchemy import func, select
+
+from openadmin.fastapi import AdminPage
+from openadmin.fastapi.deps import PageDep, SearchQueryDep
+
+from ..lib import models
+from ..lib.database import AsyncSessionDep
+
+page = AdminPage(
+    "Authors", description="Manage book authors and view productivity stats"
+)
+
+
+@page.stat("Total Authors")
+async def get_total_authors(session: AsyncSessionDep) -> int:
+    result = await session.execute(select(func.count(models.Author.id)))
+    return result.scalar_one()
+
+
+@page.stat("Authors with Bio")
+async def get_authors_with_bio(session: AsyncSessionDep) -> int:
+    result = await session.execute(
+        select(func.count(models.Author.id)).where(models.Author.bio.isnot(None))
+    )
+    return result.scalar_one()
+
+
+@page.stat("Avg Books per Author")
+async def get_avg_books_per_author(session: AsyncSessionDep) -> float:
+    subq = (
+        select(func.count(models.Book.id).label("cnt"))
+        .group_by(models.Book.author_id)
+        .subquery()
+    )
+    result = await session.execute(select(func.avg(subq.c.cnt)))
+    return round(float(result.scalar_one() or 0), 2)
+
+
+@page.table("All Authors", description="Browse authors with search and book counts")
+async def get_all_authors(
+    session: AsyncSessionDep, pagination: PageDep, search: SearchQueryDep
+):
+    stmt = (
+        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)
+        .limit(pagination.per_page)
+    )
+    if search:
+        full_name = models.Author.first_name + " " + models.Author.last_name
+        stmt = stmt.where(full_name.ilike(f"%{search}%"))
+    result = await session.execute(stmt)
+    return [
+        {
+            "id": author.id,
+            "name": f"{author.first_name} {author.last_name}",
+            "bio": (author.bio[:80] + "...")
+            if author.bio and len(author.bio) > 80
+            else author.bio,
+            "book_count": count,
+        }
+        for author, count in result.all()
+    ]
+
+
+@page.bar_chart(
+    "Top Authors by Book Count",
+    description="The 10 most prolific authors in the catalog",
+)
+async def get_top_authors(session: AsyncSessionDep):
+    stmt = (
+        select(
+            (models.Author.first_name + " " + models.Author.last_name).label("name"),
+            func.count(models.Book.id).label("count"),
+        )
+        .join(models.Book, models.Book.author_id == models.Author.id)
+        .group_by(models.Author.id)
+        .order_by(func.count(models.Book.id).desc())
+        .limit(10)
+    )
+    result = await session.execute(stmt)
+    return [{"label": row.name, "value": row.count} for row in result]
+
+
+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):
+    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}"}

openadmin_dev-0.4.0/examples/admin/books.py

@@ -0,0 +1,90 @@
+# SPDX-FileCopyrightText: 2026 OpenAdmin
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from fastapi import Query
+from pydantic import BaseModel
+from sqlalchemy import func, select
+
+from openadmin.fastapi import AdminPage
+from openadmin.fastapi.deps import PageDep, SearchQueryDep
+
+from ..lib import models
+from ..lib.database import AsyncSessionDep
+
+page = AdminPage("Books", description="Browse and manage the book catalog")
+
+
+@page.stat("Total Books")
+async def get_total_books(session: AsyncSessionDep) -> int:
+    result = await session.execute(select(func.count(models.Book.id)))
+    return result.scalar_one()
+
+
+@page.stat("Published Books")
+async def get_published_books(session: AsyncSessionDep) -> int:
+    result = await session.execute(
+        select(func.count(models.Book.id)).where(models.Book.published_year.isnot(None))
+    )
+    return result.scalar_one()
+
+
+@page.stat("Books Without Publisher")
+async def get_books_without_publisher(session: AsyncSessionDep) -> int:
+    result = await session.execute(
+        select(func.count(models.Book.id)).where(models.Book.publisher_id.is_(None))
+    )
+    return result.scalar_one()
+
+
+@page.table("All Books", description="Browse all books with search and pagination")
+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)
+        .limit(pagination.per_page)
+    )
+    if search:
+        stmt = stmt.where(models.Book.title.ilike(f"%{search}%"))
+    result = await session.execute(stmt)
+    return [
+        {
+            "id": book.id,
+            "title": book.title,
+            "author": f"{author.first_name} {author.last_name}",
+            "published_year": book.published_year,
+        }
+        for book, author in result.all()
+    ]
+
+
+class AddBookBody(BaseModel):
+    title: str
+    author_id: int
+    published_year: int | None = None
+    summary: str | None = None
+    publisher_id: int | None = None
+
+
+@page.form_post("Add Book", description="Add a new book to the catalog")
+async def add_book(body: AddBookBody, session: AsyncSessionDep):
+    book = models.Book(**body.model_dump())
+    session.add(book)
+    await session.commit()
+    await session.refresh(book)
+    return {"id": book.id, "title": book.title}
+
+
+@page.action_delete("Delete Book", description="Remove a book by ID")
+async def delete_book(
+    session: AsyncSessionDep,
+    book_id: int = Query(..., description="Book ID to delete"),
+):
+    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}

openadmin_dev-0.4.0/examples/admin/genres.py

@@ -0,0 +1,81 @@
+# SPDX-FileCopyrightText: 2026 OpenAdmin
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from sqlalchemy import func, select
+
+from openadmin.fastapi import AdminPage
+from openadmin.fastapi.deps import PageDep
+
+from ..lib import models
+from ..lib.database import AsyncSessionDep
+
+page = AdminPage("Genres", description="Browse and analyze the genre taxonomy")
+
+
+@page.stat("Total Genres")
+async def get_total_genres(session: AsyncSessionDep) -> int:
+    result = await session.execute(select(func.count(models.Genre.id)))
+    return result.scalar_one()
+
+
+@page.stat("Most Popular Genre")
+async def get_most_popular_genre(session: AsyncSessionDep) -> str:
+    stmt = (
+        select(models.Genre.name)
+        .join(models.BookToGenre, models.BookToGenre.genre_id == models.Genre.id)
+        .group_by(models.Genre.id)
+        .order_by(func.count(models.BookToGenre.book_id).desc())
+        .limit(1)
+    )
+    result = await session.execute(stmt)
+    return result.scalar_one_or_none() or "N/A"
+
+
+@page.stat("Books Without Genre")
+async def get_books_without_genre(session: AsyncSessionDep) -> int:
+    subq = select(models.BookToGenre.book_id)
+    result = await session.execute(
+        select(func.count(models.Book.id)).where(models.Book.id.not_in(subq))
+    )
+    return result.scalar_one()
+
+
+@page.table("All Genres", description="All genres sorted by book count")
+async def get_all_genres(session: AsyncSessionDep, pagination: PageDep):
+    stmt = (
+        select(models.Genre, func.count(models.BookToGenre.book_id).label("book_count"))
+        .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)
+        .limit(pagination.per_page)
+    )
+    result = await session.execute(stmt)
+    return [
+        {"id": g.id, "name": g.name, "book_count": count} for g, count in result.all()
+    ]
+
+
+@page.pie_chart("Genre Distribution", description="Share of books across all genres")
+async def get_genre_distribution(session: AsyncSessionDep):
+    stmt = (
+        select(models.Genre.name, func.count(models.BookToGenre.book_id).label("count"))
+        .join(models.BookToGenre, models.BookToGenre.genre_id == models.Genre.id)
+        .group_by(models.Genre.id)
+        .order_by(func.count(models.BookToGenre.book_id).desc())
+    )
+    result = await session.execute(stmt)
+    return [{"label": row.name, "value": row.count} for row in result]
+
+
+@page.bar_chart("Books per Genre", description="Absolute book count for each genre")
+async def get_books_per_genre(session: AsyncSessionDep):
+    stmt = (
+        select(models.Genre.name, func.count(models.BookToGenre.book_id).label("count"))
+        .join(models.BookToGenre, models.BookToGenre.genre_id == models.Genre.id)
+        .group_by(models.Genre.id)
+        .order_by(models.Genre.name)
+    )
+    result = await session.execute(stmt)
+    return [{"label": row.name, "value": row.count} for row in result]

openadmin_dev-0.4.0/examples/admin/health.py

@@ -0,0 +1,74 @@
+# SPDX-FileCopyrightText: 2026 OpenAdmin
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from openadmin.fastapi import AdminPage
+
+page = AdminPage("Health", description="System health and infrastructure metrics")
+
+
+@page.stat("API Uptime (%)")
+async def get_api_uptime() -> float:
+    return 99.97
+
+
+@page.stat("Avg Response Time (ms)")
+async def get_avg_response_time() -> int:
+    return 84
+
+
+@page.stat("Active Connections")
+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
+
+All services are operating normally.
+
+| Service        | Status  | Latency |
+|----------------|---------|---------|
+| API            | ✅ Up   | 84 ms   |
+| Database       | ✅ Up   | 3 ms    |
+| Cache          | ✅ Up   | 1 ms    |
+| Queue          | ✅ Up   | 12 ms   |
+
+Last checked: just now.
+"""

openadmin_dev-0.4.0/examples/admin/overview.py

@@ -0,0 +1,99 @@
+# SPDX-FileCopyrightText: 2026 OpenAdmin
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from sqlalchemy import func, select, text
+
+from openadmin.fastapi import AdminPage
+
+from ..lib import models
+from ..lib.database import AsyncSessionDep
+
+page = AdminPage("Overview", description="High-level database and catalog statistics")
+
+
+@page.stat("Total Records")
+async def get_total_records(session: AsyncSessionDep) -> int:
+    counts = await _all_table_counts(session)
+    return sum(c for _, c in counts)
+
+
+@page.stat("Schema Tables")
+async def get_schema_tables() -> int:
+    return 7  # Book, Author, Publisher, Genre, Tag, BookToGenre, BookToTag
+
+
+@page.stat("Catalog Completeness (%)")
+async def get_catalog_completeness(session: AsyncSessionDep) -> float:
+    total = (await session.execute(select(func.count(models.Book.id)))).scalar_one()
+    if not total:
+        return 0.0
+    complete = (
+        await session.execute(
+            select(func.count(models.Book.id)).where(
+                models.Book.summary.isnot(None),
+                models.Book.published_year.isnot(None),
+                models.Book.publisher_id.isnot(None),
+            )
+        )
+    ).scalar_one()
+    return round(complete / total * 100, 1)
+
+
+@page.bar_chart(
+    "Records per Table", description="Row count for every table in the schema"
+)
+async def get_records_per_table(session: AsyncSessionDep):
+    counts = await _all_table_counts(session)
+    return [{"label": label, "value": count} for label, count in counts]
+
+
+@page.markdown("Schema Reference")
+async def get_schema_reference() -> str:
+    return """# Database Schema
+
+## Core tables
+
+| Table           | Description                                    |
+|-----------------|------------------------------------------------|
+| `book`          | Central entity — title, year, summary          |
+| `author`        | Author first/last name and optional bio        |
+| `publisher`     | Publisher name and country                     |
+| `genre`         | Genre name (unique)                            |
+| `tag`           | Tag name (unique)                              |
+
+## Association tables
+
+| Table           | Links                                          |
+|-----------------|------------------------------------------------|
+| `book_to_genre` | Many-to-many: book ↔ genre                    |
+| `book_to_tag`   | Many-to-many: book ↔ tag, with `added_at`     |
+
+All primary keys are auto-incrementing integers.
+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):
+    await session.execute(text("SELECT 1"))
+    return {"status": "ok", "message": "Database is reachable"}
+
+
+async def _all_table_counts(session: AsyncSessionDep) -> list[tuple[str, int]]:
+    tables: list[tuple[str, type]] = [
+        ("book", models.Book),
+        ("author", models.Author),
+        ("publisher", models.Publisher),
+        ("genre", models.Genre),
+        ("tag", models.Tag),
+        ("book_to_genre", models.BookToGenre),
+        ("book_to_tag", models.BookToTag),
+    ]
+    results = []
+    for label, model in tables:
+        count = (
+            await session.execute(select(func.count()).select_from(model))
+        ).scalar_one()
+        results.append((label, count))
+    return results

openadmin_dev-0.4.0/examples/admin/publishers.py

@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: 2026 OpenAdmin
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from pydantic import BaseModel
+from sqlalchemy import func, select
+
+from openadmin.fastapi import AdminPage
+from openadmin.fastapi.deps import PageDep, SearchQueryDep
+
+from ..lib import models
+from ..lib.database import AsyncSessionDep
+
+page = AdminPage("Publishers", description="Manage publishers and their catalog share")
+
+
+@page.stat("Total Publishers")
+async def get_total_publishers(session: AsyncSessionDep) -> int:
+    result = await session.execute(select(func.count(models.Publisher.id)))
+    return result.scalar_one()
+
+
+@page.stat("Countries Represented")
+async def get_countries_represented(session: AsyncSessionDep) -> int:
+    result = await session.execute(
+        select(func.count(func.distinct(models.Publisher.country))).where(
+            models.Publisher.country.isnot(None)
+        )
+    )
+    return result.scalar_one()
+
+
+@page.stat("Books Without Publisher")
+async def get_books_without_publisher(session: AsyncSessionDep) -> int:
+    result = await session.execute(
+        select(func.count(models.Book.id)).where(models.Book.publisher_id.is_(None))
+    )
+    return result.scalar_one()
+
+
+@page.table("All Publishers", description="Browse publishers with their book counts")
+async def get_all_publishers(
+    session: AsyncSessionDep, pagination: PageDep, search: SearchQueryDep
+):
+    stmt = (
+        select(models.Publisher, func.count(models.Book.id).label("book_count"))
+        .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)
+        .limit(pagination.per_page)
+    )
+    if search:
+        stmt = stmt.where(models.Publisher.name.ilike(f"%{search}%"))
+    result = await session.execute(stmt)
+    return [
+        {"id": pub.id, "name": pub.name, "country": pub.country, "book_count": count}
+        for pub, count in result.all()
+    ]
+
+
+@page.pie_chart("Books by Publisher", description="Top 10 publishers by book count")
+async def get_books_by_publisher(session: AsyncSessionDep):
+    stmt = (
+        select(models.Publisher.name, func.count(models.Book.id).label("count"))
+        .join(models.Book, models.Book.publisher_id == models.Publisher.id)
+        .group_by(models.Publisher.id)
+        .order_by(func.count(models.Book.id).desc())
+        .limit(10)
+    )
+    result = await session.execute(stmt)
+    return [{"label": row.name, "value": row.count} for row in result]
+
+
+class AddPublisherBody(BaseModel):
+    name: str
+    country: str | None = None
+
+
+@page.form_post("Add Publisher", description="Register a new publisher")
+async def add_publisher(body: AddPublisherBody, session: AsyncSessionDep):
+    publisher = models.Publisher(**body.model_dump())
+    session.add(publisher)
+    await session.commit()
+    await session.refresh(publisher)
+    return {"id": publisher.id, "name": publisher.name}