pre-alpha

Reference

Settings

Updated November 20, 2026 9 min read

hinoki.settings.Settings dataclass

Settings()

Base class: subclasses are keyword-only frozen dataclasses.

load classmethod

load(
    *,
    prefix: str | None = None,
    env: Mapping[str, str] | None = None,
    dotenv: str | PathLike[str] | None = None,
    toml: str | PathLike[str] | None = None,
    overrides: Mapping[str, Any] | None = None,
    strict: bool = True,
) -> Self

Build the settings. Precedence: overrides, env (default: the process environment), dotenv, TOML file, and field defaults.

strict (default) makes a variable that starts with prefix and looks like a setting but names no field an error, which catches typos; other variables that only share the prefix are ignored. With an empty prefix nothing can be told apart from the rest of the environment, so no typo check happens.

prefix, dotenv and toml default to what the class declared.

explain classmethod

explain(
    *,
    prefix: str | None = None,
    env: Mapping[str, str] | None = None,
    dotenv: str | PathLike[str] | None = None,
    toml: str | PathLike[str] | None = None,
    overrides: Mapping[str, Any] | None = None,
    strict: bool = True,
) -> list[SettingRow]

Load like load and say, for every value, where it came from: override, environment, .env, toml, file (a *_FILE variable) or default. Secrets are redacted.

example classmethod

example(prefix: str | None = None) -> str

A .env.example: every variable with its default, required ones and secrets left blank, and a comment with the type.

describe

describe() -> dict[str, Any]

The effective values as plain data, secrets redacted.

validate

validate() -> None

Override to check relations between fields; raise ValueError. The message is shown in SettingsError: never put a field's value in it.

hinoki.settings.Secret

Secret(value: str)

A string that never prints itself: repr and str show ***.

reveal

reveal() -> str

hinoki.settings.SettingsError

SettingsError(problems: list[str])

Bases: ValueError

The configuration is invalid; problems lists every one (no values).

hinoki.settings.AppSettings dataclass

AppSettings()

Bases: Settings

The built-in groups every application has; subclass to add your own.

execution class-attribute instance-attribute

execution: ExecutionSettings = dataclasses.field(
    default_factory=ExecutionSettings
)

lifecycle class-attribute instance-attribute

lifecycle: LifecycleSettings = dataclasses.field(
    default_factory=LifecycleSettings
)

logging class-attribute instance-attribute

logging: LoggingSettings = dataclasses.field(
    default_factory=LoggingSettings
)

docs class-attribute instance-attribute

docs: DocsSettings = dataclasses.field(
    default_factory=DocsSettings
)

server class-attribute instance-attribute

server: ServerSettings = dataclasses.field(
    default_factory=ServerSettings
)

pagination class-attribute instance-attribute

pagination: PaginationSettings = dataclasses.field(
    default_factory=PaginationSettings
)

cors class-attribute instance-attribute

cors: CorsSettings = dataclasses.field(
    default_factory=CorsSettings
)

security class-attribute instance-attribute

security: SecuritySettings = dataclasses.field(
    default_factory=SecuritySettings
)

admin class-attribute instance-attribute

admin: AdminSettings = dataclasses.field(
    default_factory=AdminSettings
)

timezone class-attribute instance-attribute

timezone: str = 'UTC'

debug class-attribute instance-attribute

debug: bool = False

allowed_hosts class-attribute instance-attribute

allowed_hosts: tuple[str, ...] = (ANY,)

runtime_config

runtime_config() -> RuntimeConfig

hinoki.settings.ExecutionSettings dataclass

ExecutionSettings()

Bases: Settings

sync_workers class-attribute instance-attribute

sync_workers: int = 8

sync_queue class-attribute instance-attribute

sync_queue: int = 64

request_timeout class-attribute instance-attribute

request_timeout: float = 30.0

max_body_bytes class-attribute instance-attribute

max_body_bytes: int = 1024 * 1024

max_query_bytes class-attribute instance-attribute

max_query_bytes: int = 8192

max_header_bytes class-attribute instance-attribute

max_header_bytes: int = 32768

hinoki.settings.LifecycleSettings dataclass

LifecycleSettings()

Bases: Settings

startup_timeout class-attribute instance-attribute

startup_timeout: float = 30.0

shutdown_timeout class-attribute instance-attribute

shutdown_timeout: float = 10.0

hinoki.settings.LoggingSettings dataclass

LoggingSettings()

Bases: Settings

level class-attribute instance-attribute

level: Literal[
    "debug", "info", "warning", "error", "critical"
] = "info"

format class-attribute instance-attribute

format: Literal['text', 'json'] = 'text'

include_request_id class-attribute instance-attribute

include_request_id: bool = False

apply

apply() -> None

Configure the hinoki logger tree (not the root logger), then apply config if set; safe to call again, it replaces its own handler.

hinoki.settings.DocsSettings dataclass

DocsSettings()

Bases: Settings

title class-attribute instance-attribute

title: str = 'Hinoki API'

version class-attribute instance-attribute

version: str = '0.1.0'

openapi_url class-attribute instance-attribute

openapi_url: str | None = None

docs_url class-attribute instance-attribute

docs_url: str | None = None

redoc_url class-attribute instance-attribute

redoc_url: str | None = None

hinoki.settings.ServerSettings dataclass

ServerSettings()

Bases: Settings

How hinoki serve and dev run the application. serve applies these; they do nothing when another runner starts the app.

server picks Kiso, Hinoki's Rust server (the default), or Granian. interface is how the server calls the target: asgi (a Hinoki application) or wsgi (a WSGI callable, such as a WSGIAdapter); the --interface flag overrides it. access_log prints one line per request on either server; unset, hinoki dev logs and hinoki serve does not, and True or False decides for both. access_log_format (Rust server only: pretty, plain, json or logger) chooses how a line looks; unset, it is pretty on a colour terminal and plain otherwise, and setting it turns the log on unless access_log is False. json writes one object per line with an RFC 3339 UTC time; logger sends each to the hinoki.access logger. access_log_skip (Rust server only) lists paths the log leaves out, such as health checks: exact, or a prefix when the entry ends with *. access_log_slow_ms keeps only answers at least that slow. Both always keep failures (status 400 and up). recent_requests (Rust server only) is a file that also receives each record as JSON, for hinoki mcp's recent_requests tool. server_timing (Rust server only) adds a Server-Timing header with the time taken and the serving lane: unset means in hinoki dev only. max_connections, header_read_timeout, body_read_timeout, write_timeout, native_dispatch and access_log_format, access_log_skip and access_log_slow_ms belong to the Rust server (None keeps its default). hinoki serve refuses a setting the chosen server cannot honour. tls_cert_file and tls_key_file (PEM files, set together) serve HTTPS on either server; http2 adds HTTP/2 to it (ALPN h2, TLS only, off by default). native_dispatch (unset means on) lets the Rust server run the async def handlers it can prove safe without an asyncio task; False keeps every handler in one.

server class-attribute instance-attribute

server: Literal['granian', 'kiso'] = 'kiso'

host class-attribute instance-attribute

host: str = '127.0.0.1'

port class-attribute instance-attribute

port: int = 8000

workers class-attribute instance-attribute

workers: int = 1

runtime_threads class-attribute instance-attribute

runtime_threads: int = 1

backlog class-attribute instance-attribute

backlog: int = 1024

access_log class-attribute instance-attribute

access_log: bool | None = None

access_log_format class-attribute instance-attribute

access_log_format: (
    Literal["pretty", "plain", "json", "logger"] | None
) = None

access_log_skip class-attribute instance-attribute

access_log_skip: tuple[str, ...] | None = None

access_log_slow_ms class-attribute instance-attribute

access_log_slow_ms: float | None = None

recent_requests class-attribute instance-attribute

recent_requests: str | None = None

server_timing class-attribute instance-attribute

server_timing: bool | None = None

max_connections class-attribute instance-attribute

max_connections: int | None = None

header_read_timeout class-attribute instance-attribute

header_read_timeout: float | None = None

body_read_timeout class-attribute instance-attribute

body_read_timeout: float | None = None

write_timeout class-attribute instance-attribute

write_timeout: float | None = None

tls_cert_file class-attribute instance-attribute

tls_cert_file: str | None = None

tls_key_file class-attribute instance-attribute

tls_key_file: str | None = None

http2 class-attribute instance-attribute

http2: bool = False

native_dispatch class-attribute instance-attribute

native_dispatch: bool | None = None

trusted_proxies class-attribute instance-attribute

trusted_proxies: tuple[str, ...] = ()

request_id_header class-attribute instance-attribute

request_id_header: str = 'x-request-id'

trust_request_id class-attribute instance-attribute

trust_request_id: bool = False

hinoki.settings.PaginationSettings dataclass

PaginationSettings()

Bases: Settings

Defaults for PageNumberPagination that an action does not set itself.

page_size class-attribute instance-attribute

page_size: int = 20

max_page_size class-attribute instance-attribute

max_page_size: int = 100

hinoki.settings.CorsSettings dataclass

CorsSettings()

Bases: Settings

Which browser origins may read responses. Off while origins is empty.

origins class-attribute instance-attribute

origins: tuple[str, ...] = ()

methods class-attribute instance-attribute

methods: tuple[str, ...] = (
    "GET",
    "POST",
    "PUT",
    "PATCH",
    "DELETE",
    "QUERY",
)

headers class-attribute instance-attribute

headers: tuple[str, ...] = ("authorization", "content-type")

expose_headers class-attribute instance-attribute

expose_headers: tuple[str, ...] = ()

credentials class-attribute instance-attribute

credentials: bool = False

max_age class-attribute instance-attribute

max_age: int = 600

hinoki.settings.SecuritySettings dataclass

SecuritySettings()

Bases: Settings

Browser response protections and an optional HTTPS redirect.

redirect_https class-attribute instance-attribute

redirect_https: bool = False

hsts_seconds class-attribute instance-attribute

hsts_seconds: int = 0

hsts_include_subdomains class-attribute instance-attribute

hsts_include_subdomains: bool = False

hsts_preload class-attribute instance-attribute

hsts_preload: bool = False

frame_options class-attribute instance-attribute

frame_options: FrameOptions = FrameOptions.SAMEORIGIN

referrer_policy class-attribute instance-attribute

referrer_policy: ReferrerPolicy = ReferrerPolicy.SAME_ORIGIN

hinoki.settings.AdminSettings dataclass

AdminSettings()

Bases: Settings

The admin site: the secret that keys its CSRF tokens and the rules of its own users' sessions and passwords.

secret class-attribute instance-attribute

secret: Secret | None = None

session_hours class-attribute instance-attribute

session_hours: int = 12

idle_minutes class-attribute instance-attribute

idle_minutes: int = 120

min_password_length class-attribute instance-attribute

min_password_length: int = 12

hinoki.settings.FrameOptions

Bases: StrEnum

Values accepted by the X-Frame-Options response policy.

hinoki.settings.ReferrerPolicy

Bases: StrEnum

Values accepted by the Referrer-Policy response policy.

hinoki.settings.DatabaseSettings dataclass

DatabaseSettings()

Bases: Settings

Set either url or engine with its connection fields; with neither, the database is local SQLite at .hinoki/local.sqlite3.

name is the database name, or the file path for SQLite. options are key=value pairs passed in the URL query, such as sslmode=verify-full. With engine, url holds the URL built from the fields.

url class-attribute instance-attribute

url: Secret = dataclasses.field(
    default_factory=lambda: Secret(LOCAL_DATABASE_URL)
)

engine class-attribute instance-attribute

engine: DatabaseEngine | None = None

name class-attribute instance-attribute

name: str = ''

user class-attribute instance-attribute

user: str = ''

password class-attribute instance-attribute

password: Secret | None = None

host class-attribute instance-attribute

host: str = ''

port class-attribute instance-attribute

port: int | None = None

options class-attribute instance-attribute

options: tuple[str, ...] = ()

max_size class-attribute instance-attribute

max_size: int = 10

hinoki.settings.DatabaseEngine

Bases: StrEnum

The backend that DatabaseSettings.engine selects.