pachifast 0.15.0__tar.gz

pachifast-0.15.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+site/
+.coverage
+*.egg-info/
+.env
+*.env
+.pytest_cache/
+.ruff_cache/
+*.db
+*.sqlite3
+.idea/
+.vscode/
+.DS_Store
+uploads/

pachifast-0.15.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to pachifast are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [semantic versioning](https://semver.org/)
+(while the major version is 0, minor releases may contain breaking changes).
+
+## [Unreleased]
+
+## [0.15.0] - 2026-10-14
+
+First public release. pachifast is alpha software: see [Stability and support](https://pachifast.ilpachi.it/guides/stability/).
+
+### Added
+
+- **Application factory and modules**: `create_app`, an explicit module registry (`project_modules.py`) and `AppModule`, with routers, settings, migrations, startup and setup hooks, message catalogs, and `requires_pachifast` to declare the pachifast versions a module works with.
+- **Authentication and authorization**: JWT access and refresh tokens, Argon2id passwords, login lockout and rate limiting, users, groups and permissions, a pluggable permission provider, optional MFA (TOTP, email and SMS codes), per-user settings with a UI schema, and a one-to-one user profile for your own columns (`register_profile`).
+- **A uniform API contract**: the response envelope `{success, message, data}`, errors as `{"detail": [{loc, msg, type, code, params?}]}` with stable message codes, camelCase JSON and built-in pagination.
+- **Localized messages**: catalogs per module and per project, and an exporter that produces the JSON files a vue-i18n frontend needs, with a check-only mode for CI.
+- **Generic model admin**, an **activity log** with an index and a retention command (`pachifast audit purge`), lifecycle **signals** (`pachifast.signals`), and live **events** over an authenticated WebSocket with one-time tickets.
+- **Database and migrations**: SQLAlchemy 2.0 with SQLite and PostgreSQL, one Alembic target per database declared by the modules, and a configurable connection pool (`db_pool_*`).
+- **Operations**: `serve` for production, health endpoints (`/`, `/live`, `/ready`), request ids, JSON logs, an optional Redis cache, UDP listeners, and a generated Dockerfile and CI/CD pipelines for GitHub, GitLab and Gitea.
+- **Scaffolding CLI**: `pachifast new` for projects, modules and pipelines, plus commands for migrations, users, settings, i18n and the audit log.
+- **Configuration**: environment variables, `.env` and a `pachifast.yaml` with a JSON Schema.
+- **Extensions**: separate packages named `pachifast-<name>` that export an `AppModule` (for example `pachifast-metrics`).
+- Documentation site with generated reference pages for the CLI, the settings and the message codes.

pachifast-0.15.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ilPachi
+
+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.

pachifast-0.15.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: pachifast
+Version: 0.15.0
+Summary: Modular FastAPI core and scaffolding CLI: projects, apps, auth, migrations.
+Project-URL: Homepage, https://pachifast.ilpachi.it/
+Project-URL: Documentation, https://pachifast.ilpachi.it/
+Project-URL: Repository, https://github.com/ellethee/pachifast
+Project-URL: Source, https://github.com/ellethee/pachifast
+Project-URL: Issues, https://github.com/ellethee/pachifast/issues
+Project-URL: Changelog, https://github.com/ellethee/pachifast/blob/main/CHANGELOG.md
+Author: ilPachi
+Maintainer: ilPachi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alembic,cli,fastapi,framework,scaffolding,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic<2.0.0,>=1.14.1
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: fastapi-pagination<1.0.0,>=0.13.0
+Requires-Dist: fastapi[standard]<1.0.0,>=0.133.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: pwdlib[argon2]>=0.2.1
+Requires-Dist: pydantic-settings<3.0.0,>=2.7.1
+Requires-Dist: pydantic<3.0.0,>=2.11.0
+Requires-Dist: pyjwt<3.0.0,>=2.15.0
+Requires-Dist: pyotp<3.0.0,>=2.9.0
+Requires-Dist: python-multipart>=0.0.31
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.40
+Requires-Dist: starlette<2.0.0,>=1.3.1
+Requires-Dist: typer<1.0.0,>=0.15.0
+Requires-Dist: uvicorn<1.0.0,>=0.34.0
+Provides-Extra: postgres
+Requires-Dist: asyncpg<0.32.0,>=0.30.0; extra == 'postgres'
+Provides-Extra: postgres-sync
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres-sync'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="https://raw.githubusercontent.com/ellethee/pachifast/main/docs/assets/logo.svg" alt="pachifast" width="160"></p>
+
+# pachifast
+
+[Italiano](https://github.com/ellethee/pachifast/blob/main/README.it.md)
+
+An open-source framework for building [FastAPI](https://fastapi.tiangolo.com/) services with a modular structure, a CLI
+that scaffolds projects and modules, built-in authentication with roles and permissions, and multi-database Alembic
+migrations.
+
+Version: **<!-- version -->0.15.0<!-- /version -->** - Author: **ilPachi** - License: **MIT** - Status: **alpha** (0.x: minor releases may contain breaking changes).
+
+## Features
+
+- **Modular by design**: an explicit registry of modules (`project_modules.py`), `apps/` for application modules and
+  `common/` for shared ones; each module brings its routers, settings, migrations, hooks and message catalogs.
+- **Authentication and authorization**: JWT access and refresh tokens, Argon2id passwords, login lockout, users, groups
+  and permissions, optional MFA (TOTP, email and SMS codes), per-user settings with a UI schema.
+- **A uniform API contract**: every success is `{success, message, data}`, every error is a non-2xx response with
+  `{"detail": [{loc, msg, type, code, params?}]}` and a stable `code`; camelCase JSON; pagination built in.
+- **Localized messages**: stable message codes, catalogs per module and per project, and an exporter that produces the
+  JSON files a vue-i18n frontend needs (with a check-only mode for CI).
+- **Live events**: an authenticated WebSocket with one-time tickets, an activity log, and automatic disconnection of
+  users who are deleted, deactivated or demoted.
+- **Migrations**: one Alembic target per database declared by the modules.
+- **Operations**: `serve` for production, generated Dockerfile and CI/CD pipelines (GitHub, GitLab, Gitea), health and
+  version endpoints, optional Redis cache.
+- **Editor-friendly configuration**: environment variables, `.env` and a `pachifast.yaml` with a JSON Schema.
+
+## Install
+
+Python 3.11 or later and [uv](https://docs.astral.sh/uv/) are required:
+
+```bash
+uv tool install pachifast
+pachifast --version
+```
+
+In a project, `uv add pachifast` does the same. To install a specific version from PyPI (replace `X.Y.Z`):
+
+```bash
+uv tool install pachifast==X.Y.Z
+```
+
+Redis cache support is an extra: `pachifast[redis]`; PostgreSQL is `pachifast[postgres]`. Supported databases: SQLite and
+PostgreSQL. See [Getting started](https://pachifast.ilpachi.it/getting-started/) for more installation options.
+
+## Stability
+
+pachifast is **alpha**: the API contract (response envelope, message codes) is protected by tests, but settings, CLI and
+the database schema of the core may change in any 0.x minor release, always announced in the [changelog](https://github.com/ellethee/pachifast/blob/main/CHANGELOG.md)
+and in [Upgrading](https://pachifast.ilpachi.it/guides/upgrading/). Details and the deprecation policy: [Stability](https://pachifast.ilpachi.it/guides/stability/).
+
+## Quick start
+
+```bash
+pachifast new project demo && cd demo   # scaffold a project
+pachifast new app hello                 # add an application module
+pachifast init                          # .env with a secret key, SQLite database, migrations, first superuser
+pachifast dev                           # run with auto-reload
+```
+
+Then open <http://127.0.0.1:8000/docs> (application endpoints) or <http://127.0.0.1:8000/docs/core> (authentication,
+administration, health, version). Application routes require a bearer token by default: log in at
+`POST /api/auth/token`.
+
+Want to see a complete project first? [`examples/demo`](https://github.com/ellethee/pachifast/tree/main/examples/demo) is a working backend (MFA, model admin, a module with
+tables, uploads, bulk actions and per-user settings) that runs on SQLite with no external services.
+
+A project looks like this:
+
+```text
+demo/
+  apps/            # application modules
+  common/          # shared modules
+  main.py          # the ASGI app
+  project_modules.py
+  pachifast.yaml   # optional configuration (with a JSON Schema for editors)
+  pyproject.toml
+```
+
+## Documentation
+
+The documentation is published at <https://pachifast.ilpachi.it/> and lives in [`docs/`](https://github.com/ellethee/pachifast/tree/main/docs):
+
+- [Getting started](https://pachifast.ilpachi.it/getting-started/)
+- Guides: [configuration](https://pachifast.ilpachi.it/guides/configuration/), [modules](https://pachifast.ilpachi.it/guides/modules/),
+  [authentication](https://pachifast.ilpachi.it/guides/authentication/), [routing and responses](https://pachifast.ilpachi.it/guides/routing-and-responses/),
+  [errors and i18n](https://pachifast.ilpachi.it/guides/errors-and-i18n/), [events](https://pachifast.ilpachi.it/guides/events/), [cache](https://pachifast.ilpachi.it/guides/cache/),
+  [database and migrations](https://pachifast.ilpachi.it/guides/database-and-migrations/), [operations](https://pachifast.ilpachi.it/guides/operations/),
+  [deployment](https://pachifast.ilpachi.it/guides/deployment/), [publishing](https://pachifast.ilpachi.it/guides/publishing/),
+  [frontend integration](https://pachifast.ilpachi.it/guides/frontend-integration/)
+- Reference: [CLI](https://pachifast.ilpachi.it/reference/cli/), [settings](https://pachifast.ilpachi.it/reference/settings/),
+  [message codes](https://pachifast.ilpachi.it/reference/error-codes/)
+- [Changelog](https://github.com/ellethee/pachifast/blob/main/CHANGELOG.md) and [contributing](https://pachifast.ilpachi.it/contributing/)
+
+## License
+
+MIT, see [LICENSE](https://github.com/ellethee/pachifast/blob/main/LICENSE).
+
+**Disclaimer.** pachifast is provided "as is", without warranty of any kind. It is alpha software: it can contain bugs
+and change incompatibly between minor releases. You are responsible for reviewing, testing and securing the
+applications you build with it before using them in production. See the [stability policy](https://pachifast.ilpachi.it/guides/stability/).

pachifast-0.15.0/README.it.md

@@ -0,0 +1,95 @@
+<p align="center"><img src="https://raw.githubusercontent.com/ellethee/pachifast/main/docs/assets/logo.svg" alt="pachifast" width="160"></p>
+
+# pachifast
+
+[English](https://github.com/ellethee/pachifast/blob/main/README.md)
+
+Framework open source per costruire servizi [FastAPI](https://fastapi.tiangolo.com/) con una struttura modulare, una CLI
+che genera progetti e moduli, autenticazione integrata con ruoli e permessi e migrazioni Alembic su più database.
+
+Versione: **<!-- version -->0.15.0<!-- /version -->** - Autore: **ilPachi** - Licenza: **MIT** - Stato: **alpha** (0.x: le versioni minori possono contenere modifiche incompatibili).
+
+## Cosa offre
+
+- **Modulare**: registro esplicito dei moduli (`project_modules.py`), `apps/` per i moduli applicativi e `common/` per
+  quelli condivisi; ogni modulo porta router, impostazioni, migrazioni, hook e cataloghi di messaggi.
+- **Autenticazione e autorizzazione**: token JWT di accesso e refresh, password Argon2id, blocco dopo tentativi falliti,
+  utenti, gruppi e permessi, MFA opzionale (TOTP, codici via email e SMS), impostazioni per utente con schema UI.
+- **Un contratto API uniforme**: ogni successo è `{success, message, data}`, ogni errore è una risposta non-2xx con
+  `{"detail": [{loc, msg, type, code, params?}]}` e un `code` stabile; JSON in camelCase; paginazione integrata.
+- **Messaggi localizzati**: codici stabili, cataloghi per modulo e per progetto, ed esportazione dei file JSON per un
+  frontend vue-i18n (con modalità di sola verifica per la CI).
+- **Eventi in tempo reale**: WebSocket autenticato con ticket monouso, activity log e disconnessione automatica degli
+  utenti eliminati, disattivati o declassati.
+- **Migrazioni**: un target Alembic per ogni database dichiarato dai moduli.
+- **Operatività**: `serve` per la produzione, Dockerfile e pipeline CI/CD generati (GitHub, GitLab, Gitea), endpoint di
+  health e versione, cache Redis opzionale.
+- **Configurazione comoda da editor**: variabili d'ambiente, `.env` e un `pachifast.yaml` con JSON Schema.
+
+## Installazione
+
+Servono Python 3.11 o successivo e [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install pachifast
+pachifast --version
+```
+
+In un progetto, `uv add pachifast` fa lo stesso. Per installare una versione specifica da PyPI (sostituisci `X.Y.Z`):
+
+```bash
+uv tool install pachifast==X.Y.Z
+```
+
+La cache Redis è un extra: `pachifast[redis]`; PostgreSQL è `pachifast[postgres]`. Database supportati: SQLite e
+PostgreSQL. Per altre opzioni di installazione vedi [Getting started](https://pachifast.ilpachi.it/getting-started/)
+(in inglese).
+
+## Stabilità
+
+pachifast è in **alpha**: il contratto dell'API (envelope di risposta, codici dei messaggi) è protetto da test, ma
+impostazioni, CLI e schema del database del core possono cambiare in ogni versione minore 0.x, sempre annunciate nel
+[changelog](https://github.com/ellethee/pachifast/blob/main/CHANGELOG.md) e in [Upgrading](https://pachifast.ilpachi.it/guides/upgrading/). Dettagli e politica di deprecazione:
+[Stability](https://pachifast.ilpachi.it/guides/stability/) (in inglese).
+
+## Avvio rapido
+
+```bash
+pachifast new project demo && cd demo   # crea un progetto
+pachifast new app hello                 # aggiunge un modulo applicativo
+pachifast init                          # .env con chiave segreta, database SQLite, migrazioni, primo superuser
+pachifast dev                           # avvio con ricarica automatica
+```
+
+Poi apri <http://127.0.0.1:8000/docs> (endpoint dell'applicazione) o <http://127.0.0.1:8000/docs/core> (autenticazione,
+amministrazione, health, versione). Le rotte dell'applicazione richiedono un token: accedi con `POST /api/auth/token`.
+
+Vuoi vedere prima un progetto completo? [`examples/demo`](https://github.com/ellethee/pachifast/tree/main/examples/demo) è un backend funzionante (MFA, model admin, un modulo con
+tabelle, upload, azioni di massa e impostazioni per utente) che gira su SQLite, senza servizi esterni.
+
+Un progetto ha questa struttura:
+
+```text
+demo/
+  apps/            # moduli applicativi
+  common/          # moduli condivisi
+  main.py          # l'app ASGI
+  project_modules.py
+  pachifast.yaml   # configurazione opzionale (con JSON Schema per gli editor)
+  pyproject.toml
+```
+
+## Documentazione
+
+La documentazione completa (in inglese) è pubblicata su <https://pachifast.ilpachi.it/> e si trova in [`docs/`](https://github.com/ellethee/pachifast/tree/main/docs): guida introduttiva, guide per argomento,
+riferimenti generati dal codice (CLI, impostazioni, codici dei messaggi), [changelog](https://github.com/ellethee/pachifast/blob/main/CHANGELOG.md) e
+[contributi](https://pachifast.ilpachi.it/contributing/).
+
+## Licenza
+
+MIT, vedi [LICENSE](https://github.com/ellethee/pachifast/blob/main/LICENSE).
+
+**Esclusione di garanzia.** pachifast è fornito "così com'è" ("as is"), senza garanzie di alcun tipo. È software alpha:
+può contenere errori e cambiare in modo incompatibile tra versioni minori. Sei responsabile di verificare, testare e
+mettere in sicurezza le applicazioni che costruisci con pachifast prima di usarle in produzione. Vedi la
+[politica di stabilità](https://pachifast.ilpachi.it/guides/stability/).

pachifast-0.15.0/README.md

@@ -0,0 +1,103 @@
+<p align="center"><img src="https://raw.githubusercontent.com/ellethee/pachifast/main/docs/assets/logo.svg" alt="pachifast" width="160"></p>
+
+# pachifast
+
+[Italiano](https://github.com/ellethee/pachifast/blob/main/README.it.md)
+
+An open-source framework for building [FastAPI](https://fastapi.tiangolo.com/) services with a modular structure, a CLI
+that scaffolds projects and modules, built-in authentication with roles and permissions, and multi-database Alembic
+migrations.
+
+Version: **<!-- version -->0.15.0<!-- /version -->** - Author: **ilPachi** - License: **MIT** - Status: **alpha** (0.x: minor releases may contain breaking changes).
+
+## Features
+
+- **Modular by design**: an explicit registry of modules (`project_modules.py`), `apps/` for application modules and
+  `common/` for shared ones; each module brings its routers, settings, migrations, hooks and message catalogs.
+- **Authentication and authorization**: JWT access and refresh tokens, Argon2id passwords, login lockout, users, groups
+  and permissions, optional MFA (TOTP, email and SMS codes), per-user settings with a UI schema.
+- **A uniform API contract**: every success is `{success, message, data}`, every error is a non-2xx response with
+  `{"detail": [{loc, msg, type, code, params?}]}` and a stable `code`; camelCase JSON; pagination built in.
+- **Localized messages**: stable message codes, catalogs per module and per project, and an exporter that produces the
+  JSON files a vue-i18n frontend needs (with a check-only mode for CI).
+- **Live events**: an authenticated WebSocket with one-time tickets, an activity log, and automatic disconnection of
+  users who are deleted, deactivated or demoted.
+- **Migrations**: one Alembic target per database declared by the modules.
+- **Operations**: `serve` for production, generated Dockerfile and CI/CD pipelines (GitHub, GitLab, Gitea), health and
+  version endpoints, optional Redis cache.
+- **Editor-friendly configuration**: environment variables, `.env` and a `pachifast.yaml` with a JSON Schema.
+
+## Install
+
+Python 3.11 or later and [uv](https://docs.astral.sh/uv/) are required:
+
+```bash
+uv tool install pachifast
+pachifast --version
+```
+
+In a project, `uv add pachifast` does the same. To install a specific version from PyPI (replace `X.Y.Z`):
+
+```bash
+uv tool install pachifast==X.Y.Z
+```
+
+Redis cache support is an extra: `pachifast[redis]`; PostgreSQL is `pachifast[postgres]`. Supported databases: SQLite and
+PostgreSQL. See [Getting started](https://pachifast.ilpachi.it/getting-started/) for more installation options.
+
+## Stability
+
+pachifast is **alpha**: the API contract (response envelope, message codes) is protected by tests, but settings, CLI and
+the database schema of the core may change in any 0.x minor release, always announced in the [changelog](https://github.com/ellethee/pachifast/blob/main/CHANGELOG.md)
+and in [Upgrading](https://pachifast.ilpachi.it/guides/upgrading/). Details and the deprecation policy: [Stability](https://pachifast.ilpachi.it/guides/stability/).
+
+## Quick start
+
+```bash
+pachifast new project demo && cd demo   # scaffold a project
+pachifast new app hello                 # add an application module
+pachifast init                          # .env with a secret key, SQLite database, migrations, first superuser
+pachifast dev                           # run with auto-reload
+```
+
+Then open <http://127.0.0.1:8000/docs> (application endpoints) or <http://127.0.0.1:8000/docs/core> (authentication,
+administration, health, version). Application routes require a bearer token by default: log in at
+`POST /api/auth/token`.
+
+Want to see a complete project first? [`examples/demo`](https://github.com/ellethee/pachifast/tree/main/examples/demo) is a working backend (MFA, model admin, a module with
+tables, uploads, bulk actions and per-user settings) that runs on SQLite with no external services.
+
+A project looks like this:
+
+```text
+demo/
+  apps/            # application modules
+  common/          # shared modules
+  main.py          # the ASGI app
+  project_modules.py
+  pachifast.yaml   # optional configuration (with a JSON Schema for editors)
+  pyproject.toml
+```
+
+## Documentation
+
+The documentation is published at <https://pachifast.ilpachi.it/> and lives in [`docs/`](https://github.com/ellethee/pachifast/tree/main/docs):
+
+- [Getting started](https://pachifast.ilpachi.it/getting-started/)
+- Guides: [configuration](https://pachifast.ilpachi.it/guides/configuration/), [modules](https://pachifast.ilpachi.it/guides/modules/),
+  [authentication](https://pachifast.ilpachi.it/guides/authentication/), [routing and responses](https://pachifast.ilpachi.it/guides/routing-and-responses/),
+  [errors and i18n](https://pachifast.ilpachi.it/guides/errors-and-i18n/), [events](https://pachifast.ilpachi.it/guides/events/), [cache](https://pachifast.ilpachi.it/guides/cache/),
+  [database and migrations](https://pachifast.ilpachi.it/guides/database-and-migrations/), [operations](https://pachifast.ilpachi.it/guides/operations/),
+  [deployment](https://pachifast.ilpachi.it/guides/deployment/), [publishing](https://pachifast.ilpachi.it/guides/publishing/),
+  [frontend integration](https://pachifast.ilpachi.it/guides/frontend-integration/)
+- Reference: [CLI](https://pachifast.ilpachi.it/reference/cli/), [settings](https://pachifast.ilpachi.it/reference/settings/),
+  [message codes](https://pachifast.ilpachi.it/reference/error-codes/)
+- [Changelog](https://github.com/ellethee/pachifast/blob/main/CHANGELOG.md) and [contributing](https://pachifast.ilpachi.it/contributing/)
+
+## License
+
+MIT, see [LICENSE](https://github.com/ellethee/pachifast/blob/main/LICENSE).
+
+**Disclaimer.** pachifast is provided "as is", without warranty of any kind. It is alpha software: it can contain bugs
+and change incompatibly between minor releases. You are responsible for reviewing, testing and securing the
+applications you build with it before using them in production. See the [stability policy](https://pachifast.ilpachi.it/guides/stability/).

pachifast-0.15.0/examples/demo/.env.example

@@ -0,0 +1,3 @@
+# Secret used to sign tokens. Required: the app refuses to start without it.
+# Generate one with:  openssl rand -hex 32
+PACHIFAST_SECRET_KEY=

pachifast-0.15.0/examples/demo/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+*.env
+!.env.example
+*.sqlite3
+*.db
+dist/
+.pytest_cache/
+.ruff_cache/
+uploads/

pachifast-0.15.0/examples/demo/README.md

@@ -0,0 +1,36 @@
+# pachifast demo
+
+A complete, self-contained backend built on pachifast. It needs no frontend, and no external database: everything runs on SQLite from this folder.
+
+It shows:
+
+- the core (authentication, users, permissions, refresh tokens), MFA and the generic model admin;
+- an app module (`apps/demo`) with its own tables and migration target, a startup seed, lookups, a paginated and filterable items API with bulk actions, file upload and download, per-user settings and message catalogs in English and Italian.
+
+## Run it
+
+From the repository root:
+
+```bash
+cd examples/demo
+uv sync
+uv run pachifast init --username admin --password change-me-please   # .env, auth migrations, first superuser
+uv run pachifast migrations upgrade --target-name demo               # tables of the demo app
+uv run pachifast dev
+```
+
+Open <http://127.0.0.1:8000/docs> for the API of the demo app and <http://127.0.0.1:8000/docs/core> for the built-in routes. Log in with the superuser you just created:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/auth/token -d "username=admin" -d "password=change-me-please"
+```
+
+`init` prepares the auth database only; every other migration target (here `demo`) is applied with `migrations upgrade`. Both are safe to run again. The sample records are inserted at startup, only when the table is empty.
+
+## Use a published release
+
+The `pyproject.toml` points at the local sources so the demo always matches the repository. To try a released version from PyPI, delete the `[tool.uv.sources]` section; `uv sync` then installs `pachifast` from PyPI.
+
+## A frontend
+
+Any frontend that follows the pachifast contract (response envelope, errors, token refresh, server-side tables) works against this backend: see the [frontend integration guide](../../docs/guides/frontend-integration.md).

pachifast-0.15.0/examples/demo/apps/demo/admin.py

@@ -0,0 +1,42 @@
+"""Model admin of the demo: the generic CRUD screens for items and files (see the pachifast guide "Model admin")."""
+
+from pachifast.admin import ModelAdmin, admin_action, register_admin
+
+from .models import DemoFile, DemoItem
+
+
+@register_admin(DemoItem)
+class ItemAdmin(ModelAdmin):
+    """Items: searchable by name and notes, filterable by status, category and active flag."""
+
+    name = "item"
+    title = "Item"
+    list_display = ["name", "category", "status", "price", "quantity", "active", "created_at"]
+    search_fields = ["name", "notes"]
+    list_filter = ["status", "category", "active"]
+    readonly_fields = ["created_at"]
+    actions = ["archive", "activate"]
+
+    @admin_action(label="Archive selected")
+    async def archive(self, session, rows) -> str:
+        """Set the status of the selected items to archived."""
+        for row in rows:
+            row.status = "archived"
+        return f"{len(rows)} archived"
+
+    @admin_action(label="Activate selected", confirm=False)
+    async def activate(self, session, rows) -> str:
+        """Set the status of the selected items to active."""
+        for row in rows:
+            row.status = "active"
+        return f"{len(rows)} activated"
+
+
+@register_admin(DemoFile)
+class FileAdmin(ModelAdmin):
+    """Files: metadata only, read-only (the content is managed by the upload routes)."""
+
+    name = "file"
+    title = "File"
+    search_fields = ["name"]
+    readonly_fields = ["name", "content_type", "size", "created_at"]

pachifast-0.15.0/examples/demo/apps/demo/data.py

@@ -0,0 +1,62 @@
+"""Static data of the demo: lookups (countries, cities, categories) and the seed of the sample records."""
+
+import random
+
+COUNTRIES: list[dict] = [
+    {"value": 1, "label": "Italia"},
+    {"value": 2, "label": "Francia"},
+    {"value": 3, "label": "Germania"},
+    {"value": 4, "label": "Spagna"},
+]
+
+CITIES: list[dict] = [
+    {"value": 1, "label": "Roma", "countryId": 1},
+    {"value": 2, "label": "Milano", "countryId": 1},
+    {"value": 3, "label": "Napoli", "countryId": 1},
+    {"value": 4, "label": "Parigi", "countryId": 2},
+    {"value": 5, "label": "Lione", "countryId": 2},
+    {"value": 6, "label": "Berlino", "countryId": 3},
+    {"value": 7, "label": "Monaco", "countryId": 3},
+    {"value": 8, "label": "Amburgo", "countryId": 3},
+    {"value": 9, "label": "Madrid", "countryId": 4},
+    {"value": 10, "label": "Barcellona", "countryId": 4},
+]
+
+CATEGORIES: list[dict] = [
+    {"value": "tools", "label": "Strumenti"},
+    {"value": "books", "label": "Libri"},
+    {"value": "toys", "label": "Giochi"},
+    {"value": "food", "label": "Alimentari"},
+    {"value": "clothes", "label": "Abbigliamento"},
+]
+
+STATUSES: list[dict] = [
+    {"value": "draft", "label": "Bozza"},
+    {"value": "active", "label": "Attivo"},
+    {"value": "archived", "label": "Archiviato"},
+]
+
+_ADJECTIVES = ["Piccolo", "Grande", "Rapido", "Antico", "Moderno", "Verde", "Rosso", "Leggero", "Robusto", "Elegante"]
+_NOUNS = ["martello", "libro", "robot", "pane", "giacca", "puzzle", "cacciavite", "romanzo", "casco", "formaggio"]
+
+
+def sample_items(count: int = 120) -> list[dict]:
+    """``count`` reproducible sample records (fixed seed): same data on every database."""
+    rng = random.Random(42)
+    items = []
+    for number in range(1, count + 1):
+        city = rng.choice(CITIES)
+        items.append(
+            {
+                "name": f"{rng.choice(_ADJECTIVES)} {rng.choice(_NOUNS)} {number}",
+                "category": rng.choice(CATEGORIES)["value"],
+                "status": rng.choice(STATUSES)["value"],
+                "price": round(rng.uniform(1, 500), 2),
+                "quantity": rng.randint(0, 200),
+                "active": rng.random() > 0.2,
+                "country_id": city["countryId"],
+                "city_id": city["value"],
+                "notes": None if rng.random() > 0.3 else f"Nota di prova {number}",
+            }
+        )
+    return items