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 · Rust server Kiso · 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.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.

03

Guides

One page for each part of an application.

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")@db.table("notes")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.

Define models

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
Kiso, the default server, is native Rust. Handwritten handlers run in Python; only an 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

What is implemented today.

Pre-alpha, and exercised in the examples. The status page lists every boundary.

  • Databases

    SQLite, PostgreSQL, MySQL and MariaDB through the Rust ORM, with relations, querysets and reviewed, file-based migrations.

    Databases
  • Sync and async

    Plain def and async def handlers, with bounded execution for the synchronous ones.

    Sync and async
  • Atomic writes

    atomic=True on an action, or db.atomic as a block or a decorator, in sync and async code.

    Transactions
  • Model hooks

    Lifecycle hooks with instance state, and callbacks that run after the commit.

    Lifecycle hooks
  • Bulk writes

    bulk_create, bulk_update and bulk_delete, and their abulk_* forms, each in one transaction.

    Query and write rows
  • Checked responses

    Every response is checked at runtime against its return annotation. An annotation that cannot be checked stops the app at startup.

    Requests and responses
  • Optional admin

    An extra you activate explicitly, with four styles, its own users, a sign-in page and per-model permissions.

    Admin
  • Kiso server

    The default server is Kiso, Hinoki's Rust HTTP server. Granian stays available with --server granian.

    Kiso server
  • MCP and OpenAPI

    A generated OpenAPI document, a development MCP server and an application MCP server.

    Development MCP

05 Rules

Eleven 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.

06 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.

07 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 a project, run its tests and serve it.
  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.