Concepts
Use other libraries¶
Hinoki has its own Schema and Model classes. It does not accept Pydantic, SQLAlchemy or Django models as request bodies, responses or tables. This page says why, what that costs, and which extension points exist today.
Why the framework owns them¶
- One declaration feeds every output. Request binding, the response check, OpenAPI, application MCP, the admin and rules read the same
SchemaandModelclasses, so they can promise the same contract. - The hot paths are native. Routing, selected request parsing and ORM execution run in Rust against Hinoki's own declarations, without calling back into a validation library or a foreign ORM per request.
- Rules need known structure. "A response
Schemanever exposespassword_hash" is checkable because theSchemais an inspectable Hinoki class.
What this costs¶
- A library that expects its own model type does not plug in: a Pydantic-based SDK, a SQLAlchemy extension or a Django app cannot be given a Hinoki
ModelorSchema. - There is no adapter from SQLAlchemy, Django or Pydantic models, and no plugin system.
- Databases are SQLite, PostgreSQL, MySQL and MariaDB through Hinoki's own drivers; another ORM's connections are not shared with its pool.
Bring a library anyway¶
Anything that works on plain Python data works with Hinoki. Schema.to_dict() and Schema.dump() return plain data, and a Schema is built from plain values:
# notes/apps/quotes/api.py
from hinoki import Schema, http
from notes.apps.quotes.client import fetch_quote # any library returning plain data
class Quote(Schema):
symbol: str
price: float
@http.get("/{symbol}", access=None)
async def quote(symbol: str) -> Quote:
raw = await fetch_quote(symbol)
return Quote(symbol=raw["symbol"], price=raw["price"])
Keep the translation at the edge of the handler, and keep a second store's connections in a module so their lifetime follows the worker. Hinoki does not time-box what that code does.
Extension points¶
| You want to | Use | Guide |
|---|---|---|
| Add an authentication scheme | Subclass BearerAuth, APIKeyAuth or HeaderAuth |
Authentication |
| Reuse a permission rule | A typed Access policy |
Authentication |
| Accept or answer another body format | A parser or renderer | Parsers and renderers |
| Translate a library's exception | app.error_handler(Kind) |
Errors |
| Own a resource per worker | A module with ctx.provide and ctx.get, or a DatabaseModule subclass |
Modules |
| Enforce a team convention | Subclass hinoki.rules.Rule |
Rules |
| Add typed configuration | settings.AppSettings |
Settings |
| Ship routes in a package | Anything a routes list accepts: a function, a RouteGroup, an API class, a Mount, or an object with an api() method |
Register routes |
| Expose actions to an agent | expose_as_mcp with an allowlist |
Expose actions over MCP |
| Add metrics, tracing or other cross-cutting behaviour | Wrap the ASGI application | Serving |
| Run where only WSGI is available | WSGIAdapter |
Serving |
Cross-cutting behaviour around an action belongs in a middleware, which behaves the same on Kiso and Granian. An ASGI wrapper still works on Granian and sees the request before and after Hinoki. To run another web application next to Hinoki, put it behind the same reverse proxy or dispatch by path in your own ASGI code.