GuidesRuntime
Own resources with modules¶
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.getfor a type nobody provided raisesLookupError: <Type> was not provided; declare the providing module inrequires.- A module class without
from_settingsinmodules=fails at construction: pass an instance instead. hinoki check,routesandmigrationsdo not start modules or run hooks.
See also¶
- Settings: where a module reads its configuration.
- Command line: running management commands.
- Sync and async: where sync hooks run.