pre-alpha

3.1 · Guides

Guides

One page for each part of an application. Start with the data and endpoint guides, then add access, rules and runtime concerns as you need them. New to Hinoki? Take the tutorial first, or follow the quick start.

Data

  • Models and queries: Models map Python classes to derived or explicitly named database tables, with typed queries and opt-in write-time field validation.
  • Configure a database: Set the backend URL, install the database module and apply migrations safely.
  • Schemas and validation: A Schema describes API data, with typed validation, normalization, rejection checks and class-level unknown-field policies.
  • Model-derived schemas: A Schema can take its fields and constraints from a Model.
  • Model options: Options that describe a model beyond its columns are decorators, read like the action decorators.
  • Utilities: Hinoki includes a small set of helpers where the framework can define clear behavior.
  • Relations: Foreign keys, explicit many-to-many association models, and how to load related rows.
  • Migrations: Hinoki uses model declarations and recorded migration state to write SQL migration files.

Endpoints

  • Endpoint declarations: Hinoki endpoints are ordinary Python functions decorated with an HTTP method.
  • Generate CRUD routes: Generate model-backed list, retrieve and selected write actions, with access and ownership rules.
  • OpenAPI: The OpenAPI 3.1 document is generated from registered routes, signatures and schema declarations.
  • Errors: Hinoki separates malformed requests, authentication failures and application errors.
  • Pagination: An action opts into page-number pagination with PageNumberPagination().
  • Parsers and renderers: A parser turns a request body into Python data; a renderer turns a handler's result into response bytes.

Security and checks

  • Authentication and access: Hinoki keeps credential parsing in an authentication provider and permission checks in an Access policy.
  • Rules: Rules are optional, typed promises about your application that a tool checks and that fail with a stable ID, a location and an explanation.

Runtime

  • Application modules: Modules own resources whose lifetime belongs to a worker, such as a database pool.
  • Transactions: An action opts into a database transaction with atomic=True; application code uses db.atomic as a block or a decorator.
  • Settings: Typed, immutable settings classes with environment, dotenv and TOML sources, and redacted secrets.
  • Serving: Run an application with hinoki dev while you work and hinoki serve in production-style runs, on Kiso (the default) or Granian.
  • Testing: Hinoki has two useful levels of application tests: call the operation functions directly, then exercise the app through its ASGI interface.
  • Command line: Run framework tools and app-defined management commands from the project directory.
  • Interactive shell: Explore app settings and models with a persistent, async-capable Python prompt.
  • Typing: Hinoki's public APIs use Python annotations so a type checker can catch mistakes in handlers, decorators and schema construction.

Integrations

  • Admin: An optional module that gives staff a list, search, create, edit, bulk delete and a dashboard for your models; it is included in the framework package and mounted explicitly.
  • Application MCP: expose_as_mcp turns selected HTTP actions into tools for an MCP client.
  • Development MCP: CLI-hosted tools describe an app and its rules to an agent.
  • Development tools: Scaffold a project and give a coding agent rules, error explanations and an MCP server.

Operating

  • Sync and async: Hinoki runs on one event loop per worker; synchronous handlers run on a bounded worker pool.
  • Benchmarks: retained measurements with their environment, method and limits, including a separate native CRUD orientation run.

Where to go next

  • Concepts: the request lifecycle, architecture patterns and the vocabulary.
  • Own schemas and ORM: what owning Schema and Model means for other libraries, and the extension points that exist.
  • Reference: public symbols, signatures and docstrings.
  • Status: what works today and what does not yet.