pre-alpha

hinoki check

A Python API framework that checks its own architecture.

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.

pre-alpha · Python 3.12+ · SQLite · PostgreSQL · MySQL · MariaDB · MIT

Read the retained benchmark report
rulesapp.py
tests›projects›rulesapp.py
@http.get("/health")def health(request: Request) -> dict[str, str]:    return {}@http.post("/items")def create(request: Request) -> dict[str, str]:    return {}
TERMINALPROBLEMS 3

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

⎇ mainPython 3.12UTF-8✕ 3 problems

00 The manual

Everything, in six sections.

Open a section to browse its pages.

01 The problem

Architecture drifts. Hinoki turns each promise into a check.

  • 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

One project, end to end.

Source excerpts from the Notes and Tracker examples. File names and line numbers point to the checked-in code.

models.py
examples/notes
@db.ordered_by("title")class Note(Model):    id: UUID = pk(default_factory=uuid4)    title: str = field(max_length=80, index=True)    body: str = ""

Describe the table

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 queries

03 Architecture

How the parts fit together.

You declare once. Routing, validation, the OpenAPI document, rules and development tools read the same declaration. Hover a node for what it does.

Modeltables and queriesSchemaaccepts and returnsEndpointaccess= atomic= errors=One declared contractordinary decoratorsRoutingValidationAccess and transactionsOpenAPI documenthinoki check rulesDevelopment MCPSchema changes: explicit, never at startupModelmigrations planreviewed SQL fileexplicit applyDatabase ModelSchemaEndpointOne declared contractordinary decoratorsRoutingValidationAccess and transactionsOpenAPI documenthinoki check rulesDevelopment MCPSchema changes: explicit, never at startupModelmigrations planreviewed SQL fileexplicit applySelected database
Selected request, schema, crypto and ORM paths run in Rust. The migration lane is separate on purpose.

04 Rules

Five rules ship today. All are optional.

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)

Exceptions live in hinoki-rules.toml, need a reason, an owner and a bounded target, and stay visible as waived.

05 Fit

Who it is for, and who it is not for yet.

A fit today

  • You are evaluating a typed Python API with SQLite, PostgreSQL, MySQL or MariaDB.
  • You want architectural promises that a tool can check, not only review.
  • You can use a source checkout and test against disposable data.

Not yet

  • Production use: the API and migration format may change.
  • SQL Server or Oracle, which are not supported yet.
  • Workloads that need end-to-end performance claims.
  • Implicit many-to-many relations and advanced relation paths.

06 Start

Start from a checkout.

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
  1. Quick startCreate the table with a migration and run the Notes API.
  2. TutorialBuild a task tracker from its models through access checks and tests.
  3. GuidesFocused guidance on each part of an application.
  4. ReferencePublic Python symbols, signatures and docstrings.

Hinoki is pre-alpha.

APIs can still change. The status page lists what is implemented, what is a boundary today, and what is not available.