Get started
Install from a checkout and create your first project.
hinoki check
Typed Python declarations become one contract shared by routing, validation, access policies, transactions, OpenAPI and development tools. Optional rules check the architectural promises you make.
Read the retained benchmark report@http.get("/health")def health(request: Request) -> dict[str, str]: return {}@http.post("/items")def create(request: Request) -> dict[str, str]: return {}
from tests.projects.policies import staff@http.get("/health", access=staff)def health(request: Request) -> dict[str, str]: return {}@http.post("/items", access=staff, atomic=True)def create(request: Request) -> dict[str, str]: return {}
[[waiver]]rule = "HNK-ACC-001"target = "tests.projects.rulesapp.health"reason = "liveness probe is public by design"owner = "platform-team"expires = 2027-01-31
hinoki check
tests/projects/rulesapp.py:7: HNK-ACC-001 [violated] GET /health (health) declares no access policy
fix: add access=<policy> to the action (or list it in except_ when it is public on purpose)
tests/projects/rulesapp.py:12: HNK-ACC-001 [violated] POST /items (create) declares no access policy
fix: add access=<policy> to the action (or list it in except_ when it is public on purpose)
tests/projects/rulesapp.py:12: HNK-TXN-001 [violated] POST /items (create) does not declare atomic=True
fix: add atomic=True to the action (or declare it on a RouteGroup(..., atomic=True) group)
2 rule(s): 3 violated, 0 unverifiable, 0 waived exit 1
2 rule(s): 0 violated, 0 unverifiable, 0 waived exit 0
tests/projects/rulesapp.py:7: HNK-ACC-001 [waived] GET /health (health) declares no access policy
fix: add access=<policy> to the action (or list it in except_ when it is public on purpose)
tests/projects/rulesapp.py:12: HNK-ACC-001 [violated] POST /items (create) declares no access policy
fix: add access=<policy> to the action (or list it in except_ when it is public on purpose)
tests/projects/rulesapp.py:12: HNK-TXN-001 [violated] POST /items (create) does not declare atomic=True
fix: add atomic=True to the action (or declare it on a RouteGroup(..., atomic=True) group)
waived: liveness probe is public by design (platform-team, until 2027-01-31)
2 rule(s): 2 violated, 0 unverifiable, 1 waived exit 1
00 The manual
Open a section to browse its pages.
Install from a checkout and create your first project.
Follow a task tracker from models to access checks and tests.
One page for each part of an application.
Request lifecycle, patterns and the vocabulary.
Public symbols, signatures and docstrings.
Status, roadmap, troubleshooting and toolchain.
01 The problem
An endpoint that forgot its access policy is public by default.
Declare access=; HNK-ACC-001 fails the check when it is missing.
A write that should be atomic is not.
Declare atomic=True; HNK-TXN-001 reports every state-changing action without it.
A response leaks a token or a whole model.
HNK-SCH-001 and HNK-API-001 keep named fields out of responses and models out of handlers.
Layers drift: models start importing the API.
HNK-IMP-001 reads the source files and reports forbidden imports.
02 A project
Source excerpts from the Notes and Tracker examples. File names and line numbers point to the checked-in code.
@db.ordered_by("title")@db.table("notes")class Note(Model): id: UUID = pk(default_factory=uuid4) title: str = field(max_length=80, index=True) body: str = ""A model is a typed class. Hinoki compiles its queries for the configured database in the Rust ORM, and nothing touches a database at import.
Define modelsclass NoteIn(Schema): title: Annotated[str, Field(min_length=1, max_length=80)] body: str = ""class NoteOut(Schema): id: UUID title: str body: strValidation is strict, with no coercion. A response exposes only the fields its Schema names.
notes = RouteGroup("/notes", atomic=True)@notes.post("/", status=201)async def create_note(data: NoteIn) -> NoteOut: return NoteOut.from_model(await Note.acreate(data))tasks = RouteGroup( "/tasks", access=member_only, atomic=True) # stated once for the groupAccess, transactions and errors are options of the decorator or defaults of a group. The same declaration feeds routing, OpenAPI and the rules.
Requests and responsestracker_rules = RuleSet( Actions.require_access(match="tracker.*", except_=["tracker.api.health"]), Actions.forbid_model_responses(match="tracker.*"),▸ 14 more lines)$ cd examples$ uv run hinoki check tracker.main:app13 rule(s): 0 violated, 0 unverifiable, 0 waived-- hinoki migration 0001-initial-- generated from the models; review it. -- create table tracker_membersCREATE TABLE "tracker_members" ( "id" uuid PRIMARY KEY, "name" varchar(80) NOT NULL, "token" text NOT NULL UNIQUE);Run rules from the example project. Migrations are SQL files you review and apply explicitly; startup never changes tables.
Migrations03 Architecture
You declare once. Routing, validation, the OpenAPI document, rules and development tools read the same declaration. Hover a node for what it does.
async def handler limited to ORM calls, and eligible generated CRUD writes, are driven from Rust. The migration lane is separate on purpose.04 Included
Pre-alpha, and exercised in the examples. The status page lists every boundary.
SQLite, PostgreSQL, MySQL and MariaDB through the Rust ORM, with relations, querysets and reviewed, file-based migrations.
DatabasesPlain def and async def handlers, with bounded execution for the synchronous ones.
atomic=True on an action, or db.atomic as a block or a decorator, in sync and async code.
Lifecycle hooks with instance state, and callbacks that run after the commit.
Lifecycle hooksbulk_create, bulk_update and bulk_delete, and their abulk_* forms, each in one transaction.
Every response is checked at runtime against its return annotation. An annotation that cannot be checked stops the app at startup.
Requests and responsesAn extra you activate explicitly, with four styles, its own users, a sign-in page and per-model permissions.
AdminThe default server is Kiso, Hinoki's Rust HTTP server. Granian stays available with --server granian.
A generated OpenAPI document, a development MCP server and an application MCP server.
Development MCP05 Rules
declaration
Actions.require_access(match, except_)
violated
tests/projects/rulesapp.py:7: HNK-ACC-001 [violated] GET /health (health) declares no access policy
waived
tests/projects/rulesapp.py:7: HNK-ACC-001 [waived] GET /health (health) declares no access policy
waived: liveness probe is public by design (platform-team, until 2027-01-31)
declaration
Actions.require_permissions(match, except_)
An Access policy without permissions would mean any authenticated caller; the rule makes that explicit. See the Rules guide.
declaration
Transactions.require_atomic(methods)
violated
tests/projects/rulesapp.py:12: HNK-TXN-001 [violated] POST /items (create) does not declare atomic=True
declaration
Actions.forbid_model_responses(match, except_)
Used by the Tracker example. Example output: see the Rules guide.
declaration
Actions.require_return_type(match, except_)
A missing return annotation, Any or object is reported; None is fine for a 204. Example output: see the Rules guide.
declaration
Actions.require_pagination(match, except_)
Used by the Tracker example. Example output: see the Rules guide.
declaration
Schemas.forbid_exposure("token")
Used by the Tracker example. Example output: see the Rules guide.
declaration
Schemas.require_string_limits()
A text field passes with max_length, or when it is an Enum or Literal. Example output: see the Rules guide.
declaration
Models.require_explicit_table(match)
Renaming a class then cannot change its physical table. Example output: see the Rules guide.
declaration
Models.require_foreign_key_index(match)
The column must lead an index, a primary key or a unique constraint. Example output: see the Rules guide.
declaration
Imports.forbid(
source="tracker.models", target="tracker.api"
)
Read from the source files; dynamic imports are reported, not ignored. Example output: see the Rules guide.
Exceptions live in hinoki-rules.toml, need a reason, an owner and a bounded target, and stay visible as waived.
06 Fit
07 Start
This repository's Hinoki framework is not published on PyPI; the hinoki name belongs to an unrelated legacy package. These commands come from the README and the quick start.
$ git clone https://github.com/caspel26/hinoki$ cd hinoki$ uv sync --locked$ cd examples$ uv run hinoki migrations apply notes$ uv run hinoki dev notes.main:app$ cd examples$ uv run hinoki check tracker.main:appAPIs can still change. The status page lists what is implemented, what is a boundary today, and what is not available.