pre-alpha

GuidesRuntime

Own resources with modules

implemented Updated November 20, 2026 5 min read

A module owns something that lives as long as a worker or a command run: a connection pool, a client, a thread pool. It opens the resource at startup, provides it to the rest of the application and closes it when the run ends. Nothing is opened at import time.

# notes/passwords.py
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

from hinoki import Module, ModuleContext
from hinoki.crypto import PasswordHasher


class Passwords(Module):
    name = "passwords"

    @asynccontextmanager
    async def lifespan(self, ctx: ModuleContext) -> AsyncIterator[None]:
        hasher = PasswordHasher()
        ctx.provide(PasswordHasher, hasher)
        try:
            yield
        finally:
            hasher.close()

Install it on the application:

# notes/main.py
app = Hinoki(
    settings=ProjectSettings,
    title="Notes",
    rules=project_rules,
    modules=[Passwords()],
)

Each worker runs lifespan up to yield before it answers requests, and the finally block when it stops, even if a later module fails to start.

Use what a module provides

ctx.provide(Type, value) registers a value under its type; ctx.get(Type) returns it (or raises LookupError) and ctx.find(Type) returns None instead. The value is reachable from:

Where How
Another module's lifespan ctx.get(PasswordHasher), with requires = (Passwords,)
A startup or shutdown hook ctx.get(PasswordHasher)
A management command context.get(PasswordHasher), with requires = (Passwords,)
A rate-limit policy context.resource(PasswordHasher)
# notes/commands.py
from argparse import ArgumentParser, Namespace

from hinoki.crypto import PasswordHasher
from hinoki.management import Command, CommandContext

from notes.passwords import Passwords


class HashPassword(Command):
    name = "hash-password"
    help = "print the Argon2id hash of a password"
    requires = (Passwords,)

    def add_arguments(self, parser: ArgumentParser) -> None:
        parser.add_argument("password")

    async def handle(self, context: CommandContext, args: Namespace) -> None:
        print(await context.get(PasswordHasher).hash(args.password))

With commands=[HashPassword] on the application, hinoki manage hash-password s3cret starts only Passwords (and what it requires), runs the command and closes it. Request handlers do not receive module values as parameters; the database is the exception, because model methods find the worker's Database themselves.

The database module

A database: settings.DatabaseSettings field on your settings class is enough: Hinoki installs DatabaseModule (from hinoki.db) before any declared module, so a module with requires = (DatabaseModule,) can call ctx.get(Database) in its lifespan. Declaring DatabaseModule, or a subclass of it, in modules= replaces the automatic one; modules that require DatabaseModule still start after it. See database connection ownership.

Declare modules

modules= accepts instances and classes. An instance is the plain choice; a class is built with its from_settings(settings) classmethod, which you override to read your settings (the default raises TypeError and says so).

requires decides the order: dependencies start first and stop last. An empty or duplicate name, a missing requirement, a cycle, or a type provided twice fails startup with ModuleGraphError. A module whose class extends a required class satisfies that requirement.

Keep lifespan bounded (it shares lifecycle.startup_timeout), fail fast when a required service is unavailable, and close what you own in finally.

Startup and shutdown hooks

For an action at the edge of a worker's life that owns no resource, such as warming a cache, logging the build or flushing a counter, list functions on the application instead of writing a module (ProjectSettings here declares a database field, so the database module is installed):

# notes/main.py
import logging

from hinoki import Hinoki, ModuleContext
from hinoki.db import Database

from notes.settings import ProjectSettings

log = logging.getLogger("notes")


async def warm_cache(ctx: ModuleContext) -> None:
    await ctx.get(Database).fetch("SELECT 1")


def say_goodbye(ctx: ModuleContext) -> None:
    log.info("worker stopping")


app = Hinoki(
    settings=ProjectSettings, on_startup=[warm_cache], on_shutdown=[say_goodbye]
)

A hook takes the worker's ModuleContext (ctx.settings, ctx.get(Type), ctx.tasks). It is async def, or a plain def that runs on the bounded sync executor like a sync handler. Model methods reach the worker's database inside a hook as they do inside a request.

Pass hooks as a list or tuple when constructing Hinoki; the app's on_startup and on_shutdown tuples are read-only. Hooks must be callables, not async generators, and must return None. A plain def may instead return an awaitable, which Hinoki awaits; use async def when the hook needs to await work directly.

Startup hooks Shutdown hooks
Run Once per worker, after every module has started, in the listed order Once per worker, before background tasks, the sync executor and the modules are closed, in the listed order
Time limit Share lifecycle.startup_timeout with the modules Each has its own lifecycle.shutdown_timeout
Requests Answered 503 not_ready until the last hook returns Answered 503 not_ready from the moment shutdown begins
A hook fails or times out Startup fails: later hooks do not run, no shutdown hook runs, the modules already started are closed, and the server is told that startup failed. The log has the traceback; the message names the hook (startup hook 'warm_cache' failed to start: TimeoutError) It is logged and reported as a shutdown error; the remaining hooks and the module cleanup still run

Shutdown hooks run only after a startup that completed, and a shutdown hook is not the finally of a startup hook. Use this rule to choose: a resource you own is a module (its lifespan closes it even when a later step of startup fails); an action is a hook. A plain def hook that is still running when its time limit passes cannot be interrupted; it keeps its executor thread until it returns.

Hooks run where the application serves requests: under hinoki dev/serve and any ASGI server, on the first request of each WSGI worker, and in the test clients. hinoki manage commands, check, routes and migrations do not run them.

Scripts outside the server

For app maintenance tasks, declare a management command and list its required module classes in Command.requires. Hinoki starts only those modules and their dependencies for one command run, so a database module is opened and closed without starting the HTTP server or unrelated modules.

Standalone scripts outside Hinoki's server or management-command runner have no module lifespan. Open their own Database and close it explicitly; do not import a module-global pool. The blog seed script demonstrates this pattern.

Errors and edge cases

  • ctx.get for a type nobody provided raises LookupError: <Type> was not provided; declare the providing module in requires.
  • A module class without from_settings in modules= fails at construction: pass an instance instead.
  • hinoki check, routes and migrations do not start modules or run hooks.

See also