Metadata-Version: 2.4
Name: pillarz
Version: 0.6.0
Summary: Shared foundation for FastAPI web services: sign-in, accounts, sessions, translations and app chrome
License-Expression: AGPL-3.0-or-later
Keywords: fastapi,authentication,oidc,authentik,sessions,accounts,i18n,framework
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: German
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: pydantic>=2.7
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: jinja2>=3.1
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: httpx>=0.27
Requires-Dist: joserfc>=1.0
Requires-Dist: itsdangerous>=2.2
Requires-Dist: psycopg[binary,pool]>=3.2
Requires-Dist: Babel>=2.16
Requires-Dist: cryptography>=43
Requires-Dist: webauthn>=3.0.1
Dynamic: license-file

# pillarz

*A shared foundation for FastAPI web services: sign-in, accounts, sessions, translations and app chrome, extended only through documented hooks, events and configuration.*

Every web service needs the same things before its first feature. pillarz ships them as one versioned package, so your app contains only what is specific to it.

- **Sign-in:** username and password, OpenID Connect (authentik), email magic link and passkeys, each switchable per app. Optional TOTP second factor with recovery codes, recovery links, invitations. No public registration.
- **Accounts:** admin, user and guest roles, an admin UI, account deletion with hand-over of data through events.
- **Sessions:** stored server-side with a device list, optional idle timeout, login throttling in the database. Several workers are the normal case.
- **Safe by default:** every route is protected unless marked public, strict CSP without inline scripts, CSRF checks, body limits, security headers on every response.
- **App chrome:** page frame, navigation, error pages, themes, a "What's new" dialog from your changelog, event log, update notice, help popovers, settings, `/healthz`.
- **Scheduled jobs:** with dry runs for destructive work, in the web process or a separate worker container. Missed runs are not caught up.
- **Translations:** gettext for Python, Jinja and JavaScript, regional formats. German and English included, German by default.
- **Database:** SQLite or PostgreSQL (psycopg 3) with no code change, versioned migrations per component, no ORM.
- **Testing:** fake OIDC provider, mail sink, software passkeys, frozen clock, route audit, browser test base.

The frontend needs no build step and no CDN. The UI and the developer documentation are German.

> **Status: alpha (0.x).** The public API may change between 0.x versions without a deprecation period; every such change is listed under "Breaking" in the changelog. From 1.0.0 on, semantic versioning and deprecation rules apply.

## Quick start

Python ≥ 3.12.

```sh
python3.12 -m venv .venv
.venv/bin/pip install pillarz
```

`app.py`:

```python
from fastapi import APIRouter, Depends, Request

from pillarz import NavItem, Pillarz
from pillarz.i18n import lazy
from pillarz.web import current_user, require_member

pz = Pillarz(name="hello", title="Hello", version="0.1.0")
pz.nav(NavItem("home", "/", lazy("Start"), icon="house"))

router = APIRouter(dependencies=[Depends(require_member)])


@router.get("/api/hello")
def hello(request: Request):
    return {"hello": current_user(request).name}


app = pz.create_app()
app.include_router(router)
```

```sh
DATA_DIR=./data PUBLIC_URLS=http://localhost:8000 .venv/bin/uvicorn app:app --port 8000
```

Open `http://localhost:8000/setup` to create the first admin account. Whoever submits that page first becomes admin, so set up the app before exposing it, or set `SETUP_TOKEN` or `ADMIN_USERNAME` and `ADMIN_PASSWORD`. Once signed in you have `/account`, `/admin` and `/api/hello`, and `/healthz` answers without sign-in.

Routes, hooks and events live in the public modules `pillarz`, `pillarz.web`, `pillarz.db`, `pillarz.accounts`, `pillarz.events`, `pillarz.i18n`, `pillarz.mail`, `pillarz.jobs`, `pillarz.text`, `pillarz.settings`, `pillarz.config` and `pillarz.testing`, all documented in their docstrings. Anything with a leading underscore is private.

## Guide

The full guide (German) covers getting started, routes and roles, data, sign-in, events, UI, translations, mail, jobs, testing, a complete reference, operations and migrating an existing app. It ships in the sdist under `docs/guide/`, together with a runnable demo app in `examples/demo/` and a Compose template in `examples/compose/`:

```sh
pip download --no-deps --no-binary :all: pillarz==X.Y.Z
```

## Installing for production

Pin pillarz exactly and with a hash, e.g. in `requirements.txt`:

```
pillarz==X.Y.Z --hash=sha256:…
```

and install with `pip install --require-hashes -r requirements.txt`. Your image needs `ca-certificates`. All settings are environment variables, listed with comments in `env.example` in the sdist.

## License

[GNU Affero General Public License v3.0 or later](https://www.gnu.org/licenses/agpl-3.0.html) (`AGPL-3.0-or-later`, file `LICENSE`). If you modify pillarz and run it as a network service, you must offer your users the source code of the modified version (AGPL §13).

## Source and changelog

The complete source code is the sdist on PyPI (`pip download --no-binary :all: pillarz==X.Y.Z`); it includes `CHANGELOG.md` with breaking changes and upgrade notes for app developers, `env.example`, `LICENSE`, the guide and the examples.
