# Ushka

> Ushka is an async (ASGI) Python web framework with filesystem routing whose main feature is Ushka Guard: request data and LLM output are `Untrusted` strings, and dangerous sinks (raw HTML, |safe, redirect, file paths, raw SQL) refuse them with an error that states the risk and the fix. Low dependency (uvicorn, jinja2, python-multipart), batteries included.

Rules for generating Ushka code:

- Routes: `routes/index.py` → `/`; `routes/users/[user_id].py` → `/users/<user_id>`; export `async def get(request): ...` (also post/put/patch/delete). Or `@app.get("/path")` on `app = Ushka()`.
- Return str, dict/list (JSON), `(body, status)`, None (204), a t-string (3.14, escaped HTML) or `Response`.
- Never pass request values straight to `redirect()`, raw HTML strings, `|safe` or SQL. Use `from ushka.guard import safe`: `safe.url(v, allow=["/"], default="/")`, `safe.path(v, root)`, `safe.integer(v, min=, max=)`, `safe.choice(v, options)`, `safe.html(v)`.
- Render HTML with `await render(request, "page.html", {...})` (`from ushka import render`).
- Mark model output with `guard.llm(text)` (`from ushka import guard`).
- Config: `ushka.toml` (no secrets) < `.env` < env vars `USHKA_<SECTION>_<KEY>`. Secret: `USHKA_APP_SECRET_KEY`.
- If you hit `UnsafeValueError USHKA-G00x`, apply the `fix` it gives; do not disable the guard.

## Docs

- [Why Ushka changed](https://ushka.satela.com.br/docs/why-ushka-changed/): purpose and direction
- [Ushka Guard](https://ushka.satela.com.br/docs/guide/guard/): sources, sinks, sanitisers, error codes G001–G005, limits
- [Routing](https://ushka.satela.com.br/docs/guide/routing/): file and decorator routes, parameters, return values
- [Configuration](https://ushka.satela.com.br/docs/guide/configuration/): all keys, .env, environment variables
- [Templates](https://ushka.satela.com.br/docs/guide/templates/): Jinja2, filters, context processors
- [ORM](https://ushka.satela.com.br/docs/guide/orm/): models, queries, migrations
- [CLI](https://ushka.satela.com.br/docs/guide/cli/): new, dev, run, check, routes, db
- [Ushka Docs](https://ushka.satela.com.br/docs/guide/docs/): documentation sites from Markdown, built in
- [Error handling](https://ushka.satela.com.br/docs/guide/error_handling/): HTTP errors, custom pages

## Optional

- [Changelog](https://github.com/kleber-code/ushka/blob/main/CHANGELOG.md)
- [Roadmap](https://ushka.satela.com.br/docs/roadmap/)