pre-alpha

Reference

Modules and runtime API

Updated November 20, 2026 2 min read

hinoki.modules.Module

Base class for modules. Override lifespan to own resources.

name class-attribute

name: str = ''

requires class-attribute

requires: tuple[type[Module], ...] = ()

apis class-attribute

apis: tuple[type[API], ...] = ()

from_settings classmethod

from_settings(settings: object) -> Module

Build the module from the application's settings. Override it to make Hinoki(modules=[YourModule]) work; the default says it is not supported.

lifespan

lifespan(
    ctx: ModuleContext,
) -> AbstractAsyncContextManager[None]

hinoki.modules.ModuleContext

ModuleContext(settings: object | None = None)

Per-worker context handed to module lifespans.

provide/get is a typed, explicit registry — not a global service locator: one instance per worker, keyed by type.

settings instance-attribute

settings = settings

tasks instance-attribute

tasks = ManagedTasks()

reset

reset() -> None

Forget provided resources and tasks; called between lifespans.

provide

provide(kind: type[T], value: T) -> None

find

find(kind: type[T]) -> T | None

The provided value of this type, or None.

get

get(kind: type[T]) -> T

hinoki.management.Command

A project command with explicit arguments and module requirements.

Set name and optionally help/requires on a subclass. Override add_arguments to define CLI arguments and handle to execute the command. A synchronous or asynchronous handle is supported.

name class-attribute

name: str = ''

help class-attribute

help: str = ''

requires class-attribute

requires: tuple[type[Module], ...] = ()

add_arguments

add_arguments(parser: ArgumentParser) -> None

Add command-specific arguments to the parser.

handle

handle(
    context: CommandContext, args: Namespace
) -> CommandResult

Run the command; return an optional process exit code.

hinoki.management.CommandContext

CommandContext(
    settings: object | None, modules: ModuleContext
)

Settings and resources available during one command invocation.

settings instance-attribute

settings = settings

get

get(kind: type[T]) -> T

Return a module resource or raise LookupError if unavailable.

find

find(kind: type[T]) -> T | None

Return a module resource, or None when it is unavailable.

hinoki.management.CommandError

Bases: Exception

The command could not start or returned an invalid result.

hinoki.runtime.config.RuntimeConfig dataclass

RuntimeConfig(
    sync_workers: int = 8,
    sync_queue: int = 64,
    request_timeout: float = 30.0,
    startup_timeout: float = 30.0,
    shutdown_timeout: float = 10.0,
    max_body_bytes: int = 1024 * 1024,
    max_query_bytes: int = 8192,
    max_header_bytes: int = 32768,
)

hinoki.errors.ModuleGraphError

Bases: RegistrationError

Missing dependency, dependency cycle or duplicate module name.

hinoki.errors.RegistrationError

Bases: Exception

Invalid or conflicting declarations, raised before the app serves.

hinoki.wsgi.WSGIAdapter

WSGIAdapter(app: Any)

start

start() -> None

Start the loop and the application's startup; safe to call twice.

close

close() -> None

Run the application's shutdown and stop the loop; idempotent.