GuidesRuntime
Configure an application with settings¶
Settings are typed, immutable classes. You declare the fields your application
needs; Hinoki adds the groups every application has, reads values from the
environment, .env and TOML once, and refuses to start when something is wrong.
# notes/settings.py
from typing import Literal
from hinoki import settings
class ProjectSettings(settings.AppSettings, prefix="NOTES_", dotenv=".env"):
database: settings.DatabaseSettings
support_email: str = "support@example.com"
stripe_key: settings.Secret | None = None
theme: Literal["light", "dark"] = "light"
notes/main.py passes the class with Hinoki(settings=ProjectSettings), which
loads it while building the application. Your fields are then on app.settings,
and modules read them as ctx.settings.
Declare fields¶
A field without a default is required. Use plain types (str, int, bool,
tuple[str, ...], Literal[...], X | None), settings.Secret for anything
confidential, and a settings.Settings subclass for a group of your own. Settings
types live in the hinoki.settings namespace (settings.AppSettings,
settings.DatabaseSettings, settings.Secret, settings.Settings,
settings.SettingsError); name your loaded value app_settings so the namespace
is not shadowed.
settings.AppSettings brings the built-in groups: execution, lifecycle,
logging, docs, server, pagination, cors, security and admin, plus
timezone, debug and allowed_hosts (see Hosts, CORS and HTTPS).
docs.openapi_url, docs.docs_url and docs.redoc_url default to None; the
generated main.py sets them with Hinoki(...) arguments, which win over settings.
Built-in fields and defaults¶
| Group | Field | Default | Constraint or effect |
|---|---|---|---|
execution |
sync_workers |
8 |
1 to 1024 worker threads |
execution |
sync_queue |
64 |
0 or greater queued calls |
execution |
request_timeout |
30.0 seconds |
Must be positive; request expiry returns 504 |
execution |
max_body_bytes |
1048576 (1 MiB) |
1 to 1073741824 bytes; larger request bodies return 413 |
execution |
max_query_bytes |
8192 (8 KiB) |
1 to 1048576 raw query-string bytes; larger queries return 414 |
execution |
max_header_bytes |
32768 (32 KiB) |
1 to 1048576 combined header bytes; larger headers return 431 |
lifecycle |
startup_timeout |
30.0 seconds |
Must be positive |
lifecycle |
shutdown_timeout |
10.0 seconds |
Must be positive |
logging |
level |
info |
debug, info, warning, error or critical |
logging |
format |
text |
text or json |
logging |
config |
unset | module:attribute of a logging.config.dictConfig mapping (or a function returning one) for your own loggers, handlers and formatters |
logging |
include_request_id |
false |
Add the active request ID to Hinoki log records for request correlation |
docs |
title |
Hinoki API |
OpenAPI info title |
docs |
version |
0.1.0 |
OpenAPI info version |
docs |
openapi_url |
None |
JSON document route; disabled when None |
docs |
docs_url |
None |
Swagger UI route; requires openapi_url |
docs |
redoc_url |
None |
ReDoc route; requires openapi_url |
server |
server |
kiso |
granian or kiso; --server overrides it. See Kiso server |
server |
interface |
asgi |
asgi or wsgi: what hinoki serve calls (a Hinoki application or a WSGI callable); --interface overrides it. See WSGI |
pagination |
page_size |
20 |
Page size an action's PageNumberPagination() leaves out; 1 to max_page_size. See Pagination |
pagination |
max_page_size |
100 |
Largest page_size a client may ask for |
server |
host |
127.0.0.1 |
Bind address used by hinoki dev/serve |
server |
port |
8000 |
1 to 65535 |
server |
workers |
1 |
1 to 256; dev uses one worker for reload |
server |
runtime_threads |
1 |
Must be positive |
server |
backlog |
1024 |
Must be positive |
server |
access_log |
unset | One line per request on either server. Unset logs in hinoki dev only (or whenever access_log_format is set); true or false decides for dev and serve |
server |
access_log_skip |
unset | Kiso only: paths the log leaves out, exact or a * prefix; failures are still logged |
server |
server_timing |
unset | Kiso only: add a Server-Timing header with the time taken and the serving lane; unset means hinoki dev only, so browser developer tools show it |
server |
recent_requests |
unset | Kiso only: file that also receives each request as a JSON line for hinoki mcp's recent_requests tool; works with the access log off |
server |
access_log_slow_ms |
unset | Kiso only: keep only answers at least this slow (ms); failures are still logged |
server |
access_log_format |
unset | Kiso only (Granian refuses it): pretty, plain, json or logger (route to the hinoki.access Python logger). Unset is pretty on a colour terminal and plain otherwise |
server |
max_connections |
unset (10000) | Kiso only: open-connection limit, 1 to 1000000; refused under Granian |
server |
header_read_timeout |
unset (10 seconds) | Kiso only: time to receive request headers, and the keep-alive idle limit; refused under Granian |
server |
body_read_timeout |
unset (10 seconds) | Kiso only: silence allowed while a body is read (at most half of execution.request_timeout); refused under Granian |
server |
write_timeout |
unset (30 seconds) | Kiso only: how long a response write may make no progress before the connection is closed; above 0 and at most 3600; refused under Granian |
server |
native_dispatch |
unset (on) | Kiso only: run the async def handlers it can prove safe without an asyncio task (see the native handler lane); false keeps every handler in an asyncio task; refused under Granian |
server |
tls_cert_file, tls_key_file |
unset | PEM certificate chain and private key; both or neither, and both must exist. Serves HTTPS on either server; Kiso reads them once at start |
server |
http2 |
false |
Serve HTTP/2 over TLS (ALPN h2, with http/1.1 as fallback); needs tls_cert_file and tls_key_file, otherwise refused when settings load. No cleartext HTTP/2; on either server |
server |
trusted_proxies |
empty | IP addresses or CIDRs allowed to supply forwarded client/protocol metadata; an IPv6 zone id (fe80::1%lo0) is refused when settings load, whichever server runs |
server |
request_id_header |
x-request-id |
HTTP header used for generated request IDs; other framework-owned names are refused |
server |
trust_request_id |
false |
Accept a validated inbound ID only from a peer in trusted_proxies |
cors |
origins |
empty | Allowed browser origins (scheme://host[:port]), or the single entry *; empty disables CORS |
cors |
methods |
GET, POST, PUT, PATCH, DELETE, QUERY |
Methods a preflight allows |
cors |
headers |
authorization, content-type |
Request headers a preflight allows |
cors |
expose_headers |
empty | Response headers a browser script may read |
cors |
credentials |
false |
Allow cookies and HTTP authentication; refused together with * |
cors |
max_age |
600 seconds |
0 to 86400; how long a browser may cache a preflight |
admin |
secret |
unset | The server secret (32+ bytes, from the environment or *_FILE) that keys the admin's CSRF tokens; an admin without its own secret= needs it |
admin |
session_hours |
12 |
1 to 720; a signed-in admin session ends this long after sign-in, whatever else happens |
admin |
idle_minutes |
120 |
1 to session_hours * 60; ... or this long after its last request |
admin |
min_password_length |
12 |
8 to 128; the shortest password the admin's own users may have |
security |
redirect_https |
false |
Send known HTTP requests to HTTPS with 308; requires explicit allowed_hosts |
security |
hsts_seconds |
0 |
0 to 63072000; emit HSTS only when the effective scheme is HTTPS |
security |
hsts_include_subdomains |
false |
Add includeSubDomains; requires nonzero hsts_seconds |
security |
hsts_preload |
false |
Add preload; requires subdomains and at least one year of HSTS |
security |
frame_options |
sameorigin |
settings.FrameOptions.DENY or .SAMEORIGIN |
security |
referrer_policy |
same-origin |
A supported settings.ReferrerPolicy enum value |
| (top level) | timezone |
UTC |
IANA timezone name used by app.now() |
| (top level) | debug |
false |
Adds exception details to 500 answers; development only |
| (top level) | allowed_hosts |
* |
Host names, .domain or *; other Host values receive 400 |
settings.DatabaseSettings is an optional field you declare in your own settings class, not a settings.AppSettings group. Its url defaults to sqlite://./.hinoki/local.sqlite3; max_size defaults to 10 connections per worker and must be at least 1.
Where values come from¶
load is the only place configuration is read; Hinoki(settings=ProjectSettings)
calls it for you. Highest first:
| Source | Example |
|---|---|
overrides= in code (tests) |
ProjectSettings.load(overrides={"theme": "dark"}) |
| the process environment | NOTES_THEME=dark |
a *_FILE variable (container secrets) |
NOTES_STRIPE_KEY_FILE=/run/secrets/stripe |
the .env file the class names |
NOTES_THEME=dark in .env |
| the TOML file the class names | theme = "dark" in settings.toml |
| the default in the class | theme: ... = "light" |
Name a TOML file on the class with toml="settings.toml" (a project created with
--server granian already does). Tables map to groups: [database] with
max_size = 12 sets database.max_size. TOML cannot hold settings.Secret
values or the database URL; keep those in the environment or *_FILE files.
load(prefix=..., dotenv=..., toml=...) overrides what the class declared. A
TOML file named on the class or passed to load must exist and parse (an empty
file is fine); a missing .env is skipped. Relative .env and TOML paths
resolve from the current directory, so start the server from the project root.
Load the class yourself when module code needs a typed value before the application exists:
# notes/main.py
from hinoki import Hinoki
from hinoki.project import manifest_routes
from notes.settings import ProjectSettings
settings = ProjectSettings.load()
app = Hinoki(
settings=settings, title=f"Notes ({settings.theme})", include=manifest_routes()
)
Variable names¶
The variable is the prefix plus the field name in capitals; a group nests with a double underscore.
| Field | Variable |
|---|---|
support_email |
NOTES_SUPPORT_EMAIL |
stripe_key |
NOTES_STRIPE_KEY |
database.url |
NOTES_DATABASE__URL |
execution.sync_workers |
NOTES_EXECUTION__SYNC_WORKERS |
logging.format |
NOTES_LOGGING__FORMAT |
Values are converted strictly: integers are ASCII digits (no 1_000, no 0x10), booleans are true/false/yes/no/on/off/1/0, lists are comma separated (use tuple[str, ...] to keep them immutable), Literal[...] takes one of its choices, and an empty value for X | None means None.
Mistakes fail at startup, all at once¶
A variable that starts with your prefix and looks like one of your settings but names no field is an error (a typo guard; strict=False turns it off). It looks like a setting when its first word starts a field's variable (NOTES_DATABASE_URL, NOTES_SERVER__PROT) or when it is spelt close to one (NOTES_THEMES). Other variables that only share the prefix belong to another program and are ignored: systemd's JOURNAL_STREAM does not break a project whose prefix is JOURNAL_. A missing required value, a bad number or a value that is not one of the choices is an error too, and every problem is listed together, with variable names and reasons but never values:
invalid settings:
NOTES_EXECUTION__SYNC_WORKERS: must be an integer
NOTES_DATABASE__MAX_SIZE: must be an integer
NOTES_THEMES: unknown setting
Keep secrets secret¶
- Declare them as
settings.Secret(orsettings.Secret | None). Asettings.Secretprints as***inrepr,str, logs, error messages,describe()and the settings command; you get the real text only withsecret.reveal(), at the one place that needs it (where the payment client is built:app_settings.stripe_key.reveal()). - Put secrets in the environment, a secret manager that exports variables, or files: with Docker or Kubernetes secrets set
NOTES_STRIPE_KEY_FILE=/run/secrets/stripe; the file's content (without the trailing newline) is the value. Only a regular file up to 64 KiB is read; setting bothNOTES_STRIPE_KEYandNOTES_STRIPE_KEY_FILEis an error. - A
.envfile is for development; never commit it. Pickling or serialising a settings object stores its secrets in plain text, so don't. - A
validate()method you add to a group shows its message in errors, so never put a field's value in it.
See what is in effect¶
hinoki settings
NOTES_DATABASE__URL environment ***
NOTES_EXECUTION__SYNC_WORKERS default 8
NOTES_STRIPE_KEY file ***
NOTES_THEME .env dark
The second column is where each value came from: override, environment,
.env, toml, file or default. The command reads the prefix, .env and
TOML file the class declares; --prefix, --dotenv and --toml override them.
--format json prints the same for tools, and --example writes a ready
.env.example: every variable with its default and type, required values blank
to fill in, and the optional ones with no printable default (secrets such as the
database URL, values that default to unset) commented out, so a copied file
keeps their defaults:
hinoki settings --example > .env.example
Logging and your own loggers¶
Declare loggers, handlers and formatters the way Django's LOGGING does, with a standard logging.config.dictConfig mapping, and point logging.config at it:
# notes/logs.py
LOGGING = {
"version": 1,
"formatters": {"short": {"format": "%(levelname)s %(name)s %(message)s"}},
"handlers": {"console": {"class": "logging.StreamHandler", "formatter": "short"}},
"loggers": {"orders": {"handlers": ["console"], "level": "INFO"}},
}
NOTES_LOGGING__CONFIG=notes.logs:LOGGING
The value may also name a function that returns the mapping. It is applied when each worker starts, right after Hinoki's own hinoki logger setup, with disable_existing_loggers off unless your mapping sets it. A mapping that configures the hinoki logger replaces Hinoki's handler on it. A target that cannot be imported or is not a mapping raises during startup. Kiso's access log is written by Kiso; set server.access_log_format = "logger" to route it through the hinoki.access logger.
Database connection ownership¶
A database: settings.DatabaseSettings field is all it takes: Hinoki installs
DatabaseModule for it (a module declared in modules= replaces it). With
nothing configured, the URL is the local SQLite file
sqlite://./.hinoki/local.sqlite3, and the module creates its hidden directory
and file when it starts. Configure a database covers the URL,
the connection fields, TLS and each backend.
The module opens a pool in each worker's startup lifespan, fails startup if the
database is unreachable, and closes that worker's pool on shutdown. Nothing
connects when modules or models are imported. Each worker owns its own pool,
so budget replicas × workers × max_size against the server database's
connection limit.
One-off scripts have a different lifecycle: they open a short-lived Database
themselves (use the database from a script).
examples/blog/seed.py does so, applies migrations, inserts synthetic rows and
closes the pool in finally. It is a one-time seed for a fresh disposable
database, not a repeatable reset:
cd examples
export BLOG_DATABASE__URL=postgresql://app:password@localhost/blog
uv run python -m blog.seed
Use a disposable database for the example. The seed command is not a production migration mechanism and is not run at app startup.
Errors and edge cases¶
- Setting both
NOTES_STRIPE_KEYandNOTES_STRIPE_KEY_FILEis an error; only a regular file up to 64 KiB is read. - A variable with your prefix that looks like a setting (same first word, or a close spelling) but names no field is an error; other variables that only share the prefix, such as
JOURNAL_STREAM, are ignored. Passstrict=Falsetoloadto turn the check off. - The
servergroup is applied byhinoki devandhinoki serve, not by other ASGI servers (Serving).