polyadmin 0.1.0b1__tar.gz

polyadmin-0.1.0b1/.github/workflows/notify-docs.yml

@@ -0,0 +1,21 @@
+name: Notify documentation site
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+
+permissions:
+  contents: read
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger documentation rebuild
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.DOCS_REPO_TOKEN }}
+          repository: MagicRodri/polyadmin-docs
+          event-type: source-docs-updated

polyadmin-0.1.0b1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish Python package
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

polyadmin-0.1.0b1/.gitignore

@@ -0,0 +1,17 @@
+# Python
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Editors / OS
+.DS_Store
+.idea/
+
+# Isolated worktrees for in-progress work
+.worktrees/

polyadmin-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MagicRodri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

polyadmin-0.1.0b1/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: polyadmin
+Version: 0.1.0b1
+Summary: PolyAdmin: cross-language server-rendered admin framework (Python core)
+Project-URL: Documentation, https://magicrodri.github.io/polyadmin-docs/
+Project-URL: Source, https://github.com/MagicRodri/polyadmin
+Project-URL: Issues, https://github.com/MagicRodri/polyadmin/issues
+License: MIT
+License-File: LICENSE
+Keywords: admin,fastapi,htmx,server-rendered
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1
+Provides-Extra: export-xlsx
+Requires-Dist: openpyxl>=3.1; extra == 'export-xlsx'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Requires-Dist: python-multipart>=0.0.9; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# PolyAdmin
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![CI](https://github.com/MagicRodri/polyadmin/actions/workflows/publish.yml/badge.svg)](https://github.com/MagicRodri/polyadmin/actions/workflows/publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![GitHub Repo stars](https://img.shields.io/github/stars/MagicRodri/polyadmin?style=flat-square)](https://github.com/MagicRodri/polyadmin)
+
+A Django-admin-style, server-rendered admin framework for
+[FastAPI](https://fastapi.tiangolo.com). See [`docs/`](docs/) for
+reference documentation, or visit the [PolyAdmin documentation site](https://magicrodri.github.io/polyadmin-docs/)
+for the shared Python and Go guides.
+
+## What you get from declaring a `ModelAdmin`
+
+Point one at your model (fields, `list_display`, search/filter config,
+permissions) and you get:
+
+- Full CRUD with search, filter, sort, and pagination, all swapped in
+  via HTMX partials — no full-page reloads
+- A dashboard of pluggable widgets: metric, stat (value + trend),
+  progress bar, bar chart, donut/pie breakdown, table, activity feed,
+  timeline, and tabs (several widgets in one card)
+- Sidebar grouping — resources sharing a `category` collapse into one
+  collapsible accordion section, e.g. everything CRUD-shaped under
+  one "Directory" group
+- Custom admin pages (`admin.route`) for functionality that isn't
+  resource CRUD — reports, wizards, internal tools — rendered inside
+  the same layout, auth, and sidebar grouping as everything else
+- Relation fields rendered as links, or as a searchable shadcn/ui
+  Command-style autocomplete backed by a server-side `/lookup` route
+  (never dumps the target model's full queryset into the page)
+- Inline related records (`StackedInline`/`TabularInline`) — a
+  parent's create/detail/edit pages can show and manage a child's
+  records that point back at it, Django-admin style
+- Record and bulk Actions, with a shadcn/ui Dialog confirmation step for
+  destructive ones
+- Delete previews: the confirmation page says what else a delete takes
+  with it, and protected records block it
+- List niceties: a date drill-down, restricted sorting, chosen link
+  columns, and filters that survive the trip to a record and back
+- Authentication/authorization hooks gating every route *and* every
+  control the templates render
+- CSV and XLSX export
+- Internationalisation: per-request locale, language switcher, French
+  and Russian
+- Toast notifications for every create/update/delete/action
+- Per-resource (and per-widget) template overrides, so an application
+  can replace one view's markup without forking the framework
+
+Styling is [shadcn/ui](https://ui.shadcn.com), hand-ported to
+Alpine.js + Tailwind — its CSS-variable token system and component
+markup, without React or Radix. That gives the admin **dark mode and
+themability**: every color resolves through a CSS variable, so restyling
+the whole thing is a change to one template. The layout is mobile-first
+with a collapsible sidebar (a Sheet below `md`), a Django-admin-style
+right-hand filter panel on wider screens, and breadcrumbs as the page
+title. Tailwind/Alpine/HTMX are all CDN-loaded — no frontend build step.
+See [`docs/components.md`](docs/components.md).
+
+## Quickstart
+
+The first beta release is available on PyPI:
+
+```bash
+pip install "polyadmin[fastapi]==0.1.0b1"
+```
+
+For the latest unreleased code, install from Git:
+
+```bash
+pip install "polyadmin[fastapi] @ git+https://github.com/MagicRodri/polyadmin.git"
+```
+
+Declare a `ModelAdmin` against your own storage and mount it on a
+FastAPI app:
+
+```python
+from dataclasses import dataclass
+
+from fastapi import FastAPI
+from polyadmin import BooleanField, EmailField, ModelAdmin
+from polyadmin.core.admin import Admin
+from polyadmin.fastapi.router import create_router
+
+
+@dataclass
+class User:
+    id: int
+    email: str
+    is_active: bool = True
+
+
+_users: list[User] = []
+
+
+class UserAdmin(ModelAdmin):
+    model = User
+    list_display = ("id", "email", "is_active")
+    form_fields = ("email", "is_active")
+    search_fields = ("email",)
+    fields = (
+        EmailField("email", required=True),
+        BooleanField("is_active", default=True),
+    )
+
+    def get_queryset(self):
+        return _users
+
+    def get_object(self, pk):
+        return next((u for u in _users if u.id == int(pk)), None)
+
+    def create(self, data):
+        user = User(id=len(_users) + 1, **data)
+        _users.append(user)
+        return user
+
+    def update(self, obj, data):
+        obj.email = data["email"]
+        obj.is_active = data["is_active"]
+        return obj
+
+    def delete(self, obj):
+        _users.remove(obj)
+
+
+admin = Admin(model_admins=[UserAdmin()])
+
+app = FastAPI()
+app.include_router(create_router(admin, base_path="/admin"), prefix="/admin")
+```
+
+```bash
+uv run uvicorn main:app --reload
+# open http://127.0.0.1:8000/admin
+```
+
+That's a full CRUD admin for `User` — search, sort, create, edit,
+delete, CSV/XLSX export, all with zero routes or templates of your
+own. With no `authenticator`/`authorizer` set, every request is
+allowed by default (fine for exploring locally, not for anything
+real) — see [`docs/authentication.md`](docs/authentication.md)
+and [`docs/permissions.md`](docs/permissions.md) before
+deploying. For everything else a `ModelAdmin` supports (relations,
+filters, actions, a dashboard, exports, delete previews), see
+[`docs/model-admin.md`](docs/model-admin.md); for the UI components and
+theming, [`docs/components.md`](docs/components.md); and for the rest,
+[`docs/`](docs/).
+
+## Languages
+
+French and Russian are **on by default** next to English: a visitor
+whose browser asks for either gets the admin's own text in it, and the
+language switcher appears in the header. Their catalogs are **drafts,
+awaiting review by native speakers** — corrections are welcome. To keep
+an admin English-only, restrict the supported set:
+
+```python
+admin = Admin(model_admins=[...], locales=["en"])
+```
+
+See [`docs/i18n.md`](docs/i18n.md) for the rest: translating your own
+strings, the switcher, and how a request's language is chosen.
+
+## Upgrading: CSRF protection
+
+Every mutating route now requires a CSRF token, on by default. The
+framework's own pages carry it automatically; a **custom `AdminPage` that
+renders its own `<form>`** must add the hidden field, or its posts will be
+rejected with `403`:
+
+```html
+{% from "admin/components/csrf-field.html" import csrf_field %}
+{{ csrf_field(csrf_token) }}
+```
+
+Forms that only submit via `hx-post` need no change. Every admin response
+also sends `X-Frame-Options: DENY`. See
+[`docs/authentication.md`](docs/authentication.md#csrf-protection) for the
+cookie/header/field names, the proxy caveat (`X-Forwarded-Proto`), and how
+to opt out.
+
+## Status
+
+All 9 implementation phases are done:
+
+- **Core** (`polyadmin/core/`): `Admin`, `ModelAdmin`, `Field` (incl. relation
+  field types), `Relation`, `Filter`, the list query pipeline (`query.py`),
+  `Paginator`, `Authenticator`/`Principal`, `Authorizer`, `Dashboard`/`Widget`,
+  `Exporter` (CSV + XLSX).
+- **Rendering** (`polyadmin/templating.py`, `polyadmin/templates/`): Jinja2
+  templates with framework/app/resource override resolution and
+  `TemplateContext` builders. Tailwind/Alpine/HTMX are CDN-loaded
+  — no frontend build step required.
+- **FastAPI adapter** (`polyadmin/fastapi/`): `create_router` mounts full CRUD +
+  list/detail/create/edit/delete + relation lookup + CSV/XLSX export routes,
+  with HTMX partial-swap for list search/filter/sort/pagination and for
+  forms, flash messages surviving a redirect, delete previews (see what a
+  delete takes with it; protected records block it), and auth/permission
+  enforcement on every route (also gates which controls the templates show).
+
+See [`examples/fastapi`](examples/fastapi) for a full runnable
+reference app exercising all of this.
+
+## Development
+
+```bash
+uv sync
+uv run pytest   # 205 tests
+```

polyadmin-0.1.0b1/README.md

@@ -0,0 +1,209 @@
+# PolyAdmin
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![CI](https://github.com/MagicRodri/polyadmin/actions/workflows/publish.yml/badge.svg)](https://github.com/MagicRodri/polyadmin/actions/workflows/publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![GitHub Repo stars](https://img.shields.io/github/stars/MagicRodri/polyadmin?style=flat-square)](https://github.com/MagicRodri/polyadmin)
+
+A Django-admin-style, server-rendered admin framework for
+[FastAPI](https://fastapi.tiangolo.com). See [`docs/`](docs/) for
+reference documentation, or visit the [PolyAdmin documentation site](https://magicrodri.github.io/polyadmin-docs/)
+for the shared Python and Go guides.
+
+## What you get from declaring a `ModelAdmin`
+
+Point one at your model (fields, `list_display`, search/filter config,
+permissions) and you get:
+
+- Full CRUD with search, filter, sort, and pagination, all swapped in
+  via HTMX partials — no full-page reloads
+- A dashboard of pluggable widgets: metric, stat (value + trend),
+  progress bar, bar chart, donut/pie breakdown, table, activity feed,
+  timeline, and tabs (several widgets in one card)
+- Sidebar grouping — resources sharing a `category` collapse into one
+  collapsible accordion section, e.g. everything CRUD-shaped under
+  one "Directory" group
+- Custom admin pages (`admin.route`) for functionality that isn't
+  resource CRUD — reports, wizards, internal tools — rendered inside
+  the same layout, auth, and sidebar grouping as everything else
+- Relation fields rendered as links, or as a searchable shadcn/ui
+  Command-style autocomplete backed by a server-side `/lookup` route
+  (never dumps the target model's full queryset into the page)
+- Inline related records (`StackedInline`/`TabularInline`) — a
+  parent's create/detail/edit pages can show and manage a child's
+  records that point back at it, Django-admin style
+- Record and bulk Actions, with a shadcn/ui Dialog confirmation step for
+  destructive ones
+- Delete previews: the confirmation page says what else a delete takes
+  with it, and protected records block it
+- List niceties: a date drill-down, restricted sorting, chosen link
+  columns, and filters that survive the trip to a record and back
+- Authentication/authorization hooks gating every route *and* every
+  control the templates render
+- CSV and XLSX export
+- Internationalisation: per-request locale, language switcher, French
+  and Russian
+- Toast notifications for every create/update/delete/action
+- Per-resource (and per-widget) template overrides, so an application
+  can replace one view's markup without forking the framework
+
+Styling is [shadcn/ui](https://ui.shadcn.com), hand-ported to
+Alpine.js + Tailwind — its CSS-variable token system and component
+markup, without React or Radix. That gives the admin **dark mode and
+themability**: every color resolves through a CSS variable, so restyling
+the whole thing is a change to one template. The layout is mobile-first
+with a collapsible sidebar (a Sheet below `md`), a Django-admin-style
+right-hand filter panel on wider screens, and breadcrumbs as the page
+title. Tailwind/Alpine/HTMX are all CDN-loaded — no frontend build step.
+See [`docs/components.md`](docs/components.md).
+
+## Quickstart
+
+The first beta release is available on PyPI:
+
+```bash
+pip install "polyadmin[fastapi]==0.1.0b1"
+```
+
+For the latest unreleased code, install from Git:
+
+```bash
+pip install "polyadmin[fastapi] @ git+https://github.com/MagicRodri/polyadmin.git"
+```
+
+Declare a `ModelAdmin` against your own storage and mount it on a
+FastAPI app:
+
+```python
+from dataclasses import dataclass
+
+from fastapi import FastAPI
+from polyadmin import BooleanField, EmailField, ModelAdmin
+from polyadmin.core.admin import Admin
+from polyadmin.fastapi.router import create_router
+
+
+@dataclass
+class User:
+    id: int
+    email: str
+    is_active: bool = True
+
+
+_users: list[User] = []
+
+
+class UserAdmin(ModelAdmin):
+    model = User
+    list_display = ("id", "email", "is_active")
+    form_fields = ("email", "is_active")
+    search_fields = ("email",)
+    fields = (
+        EmailField("email", required=True),
+        BooleanField("is_active", default=True),
+    )
+
+    def get_queryset(self):
+        return _users
+
+    def get_object(self, pk):
+        return next((u for u in _users if u.id == int(pk)), None)
+
+    def create(self, data):
+        user = User(id=len(_users) + 1, **data)
+        _users.append(user)
+        return user
+
+    def update(self, obj, data):
+        obj.email = data["email"]
+        obj.is_active = data["is_active"]
+        return obj
+
+    def delete(self, obj):
+        _users.remove(obj)
+
+
+admin = Admin(model_admins=[UserAdmin()])
+
+app = FastAPI()
+app.include_router(create_router(admin, base_path="/admin"), prefix="/admin")
+```
+
+```bash
+uv run uvicorn main:app --reload
+# open http://127.0.0.1:8000/admin
+```
+
+That's a full CRUD admin for `User` — search, sort, create, edit,
+delete, CSV/XLSX export, all with zero routes or templates of your
+own. With no `authenticator`/`authorizer` set, every request is
+allowed by default (fine for exploring locally, not for anything
+real) — see [`docs/authentication.md`](docs/authentication.md)
+and [`docs/permissions.md`](docs/permissions.md) before
+deploying. For everything else a `ModelAdmin` supports (relations,
+filters, actions, a dashboard, exports, delete previews), see
+[`docs/model-admin.md`](docs/model-admin.md); for the UI components and
+theming, [`docs/components.md`](docs/components.md); and for the rest,
+[`docs/`](docs/).
+
+## Languages
+
+French and Russian are **on by default** next to English: a visitor
+whose browser asks for either gets the admin's own text in it, and the
+language switcher appears in the header. Their catalogs are **drafts,
+awaiting review by native speakers** — corrections are welcome. To keep
+an admin English-only, restrict the supported set:
+
+```python
+admin = Admin(model_admins=[...], locales=["en"])
+```
+
+See [`docs/i18n.md`](docs/i18n.md) for the rest: translating your own
+strings, the switcher, and how a request's language is chosen.
+
+## Upgrading: CSRF protection
+
+Every mutating route now requires a CSRF token, on by default. The
+framework's own pages carry it automatically; a **custom `AdminPage` that
+renders its own `<form>`** must add the hidden field, or its posts will be
+rejected with `403`:
+
+```html
+{% from "admin/components/csrf-field.html" import csrf_field %}
+{{ csrf_field(csrf_token) }}
+```
+
+Forms that only submit via `hx-post` need no change. Every admin response
+also sends `X-Frame-Options: DENY`. See
+[`docs/authentication.md`](docs/authentication.md#csrf-protection) for the
+cookie/header/field names, the proxy caveat (`X-Forwarded-Proto`), and how
+to opt out.
+
+## Status
+
+All 9 implementation phases are done:
+
+- **Core** (`polyadmin/core/`): `Admin`, `ModelAdmin`, `Field` (incl. relation
+  field types), `Relation`, `Filter`, the list query pipeline (`query.py`),
+  `Paginator`, `Authenticator`/`Principal`, `Authorizer`, `Dashboard`/`Widget`,
+  `Exporter` (CSV + XLSX).
+- **Rendering** (`polyadmin/templating.py`, `polyadmin/templates/`): Jinja2
+  templates with framework/app/resource override resolution and
+  `TemplateContext` builders. Tailwind/Alpine/HTMX are CDN-loaded
+  — no frontend build step required.
+- **FastAPI adapter** (`polyadmin/fastapi/`): `create_router` mounts full CRUD +
+  list/detail/create/edit/delete + relation lookup + CSV/XLSX export routes,
+  with HTMX partial-swap for list search/filter/sort/pagination and for
+  forms, flash messages surviving a redirect, delete previews (see what a
+  delete takes with it; protected records block it), and auth/permission
+  enforcement on every route (also gates which controls the templates show).
+
+See [`examples/fastapi`](examples/fastapi) for a full runnable
+reference app exercising all of this.
+
+## Development
+
+```bash
+uv sync
+uv run pytest   # 205 tests
+```

polyadmin-0.1.0b1/babel.cfg

@@ -0,0 +1,4 @@
+[python: polyadmin/**.py]
+
+[jinja2: polyadmin/templates/**.html]
+extensions = jinja2.ext.i18n

polyadmin-0.1.0b1/browsertests/README.md

@@ -0,0 +1,31 @@
+# browsertests
+
+Playwright coverage for the flows a unit test cannot see: the login
+gate, the five mutating flows, the htmx-driven list, the error pages,
+and the layout facts only a browser can measure.
+
+## Running
+
+```bash
+pip install playwright pytest-playwright
+playwright install chromium
+pytest browsertests
+```
+
+The suite starts the reference app itself on port 3100 (override with
+`POLYADMIN_TEST_PORT`) and stops it afterwards, so nothing needs to be
+running first.
+
+## The rule these tests follow
+
+Every assertion checks state the server actually holds, or a style the
+browser actually resolved. Two failures are the reason:
+
+- throwaway scripts that asserted the absence of an error string, and
+  passed against a form that had never been submitted;
+- a login page that shipped with a panel the same colour as the page
+  behind it, past twenty passing assertions and two unit suites.
+
+So after a mutation, reload and count the rows. For layout, read
+`getComputedStyle` or a bounding box and compare — never assert on a
+class name.