Get started
Install from a checkout and run the Notes API.
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 {}
@http.get("/health")def health(request: Request) -> dict[str, str]: ... @http.post("/items", access=staff, atomic=True)def create(request: Request) -> dict[str, str]: ... rules = RuleSet( Actions.require_access(except_=["*.health"]), Transactions.require_atomic(),)
[[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:create_app
--rules tests.projects.rulesapp:rules
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
✓ HNK-ACC-001 access policy declared
✓ HNK-TXN-001 write is atomic
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
waived: liveness probe is public by design (platform-team, until 2027-01-31)
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): 2 violated, 0 unverifiable, 1 waived exit 1
00 The manual
Open a section to browse its pages.
Install from a checkout and run the Notes API.
Build 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")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.
Models and queriesclass 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.
@http.post("/notes", status=201, atomic=True)async def create(data: NoteIn) -> NoteOut: return 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.
Endpoint declarationstracker_rules = RuleSet( Actions.require_access(match="tracker.*", except_=["tracker.api.health"]), Actions.forbid_model_responses(match="tracker.*"),▸ 6 more lines)$ cd examples$ uv run --project .. hinoki check tracker.app:create_app-- 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.
04 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
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
Schemas.forbid_exposure("token")
Used by the Tracker example. 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.
05 Fit
06 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 --project .. hinoki migrations plan --app notes$ uv run --project .. hinoki migrations sql --app notes 0001-create-table-notes$ uv run --project .. hinoki migrations apply --app notes$ uv run --project .. hinoki dev notes.main:app$ cd examples$ uv run --project .. hinoki check tracker.app:create_appAPIs can still change. The status page lists what is implemented, what is a boundary today, and what is not available.