5.9 · Reference
Settings¶
hinoki.settings.Settings
dataclass
¶
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 but
names no field an error, which catches typos; pass strict=False when
another program shares the prefix. 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.
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 ¶
A string that never prints itself: repr and str show ***.
hinoki.settings.SettingsError ¶
Bases: ValueError
The configuration is invalid; problems lists every one (no values).
hinoki.settings.AppSettings
dataclass
¶
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
)
hinoki.settings.LifecycleSettings
dataclass
¶
hinoki.settings.LoggingSettings
dataclass
¶
hinoki.settings.ServerSettings
dataclass
¶
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.
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.
hinoki.settings.PaginationSettings
dataclass
¶
hinoki.settings.CorsSettings
dataclass
¶
Bases: Settings
Which browser origins may read responses. Off while origins is empty.
hinoki.settings.SecuritySettings
dataclass
¶
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
¶
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)
)
hinoki.settings.DatabaseEngine ¶
Bases: StrEnum
The backend that DatabaseSettings.engine selects.