Loader¶

The loader reads a TOML file, validates it against the typed models, and applies any environment-variable overrides before returning a bound StackConfig.

One entry point: load_stack_config(path). Omit path and it reads the active config path (default ~/.config/omop/config.toml, overridable with OA_CONFIG_PATH); pass a path explicitly when something else supplies one: a --config-path flag, a CLI command, a test fixture. Call active_config_path() to read that same default path without loading the file, e.g. to predict what a no-argument load_stack_config() call will read.

Prefer load_stack_config over reimplementing the read. It warns when the file is group- or world-readable, which matters because the file holds database passwords, and it caches by path and file identity so repeated loads do not re-parse. A hand-rolled tomllib.loads + model_validate gets neither.

It raises ConfigurationError for a file that is present but unusable: malformed TOML, or content that does not validate. The validation case is specifically a StackConfigInvalidError naming the offending field paths. Neither ever echoes the value that was rejected, since a rejected value is often the secret itself and these messages end up in issues and CI logs.

Helpers for loading the shared stack configuration from TOML.

load_stack_config ¶

load_stack_config(
    path: str | Path | None = None,
) -> StackConfig

Load a :class:StackConfig from path. Defaults to :func:active_config_path, which honours the OA_CONFIG_PATH environment variable.

Notes

The default path is resolved per call, so this always loads whatever active_config_path() currently reports. OA_CONFIG_PATH itself is read once, when this module is first imported.

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	Explicit configuration file to load. Omitted uses :func:`active_config_path`.	`None`

Returns:

Type	Description
`StackConfig`	Parsed and validated stack configuration.

Raises:

Type	Description
`FileNotFoundError`	If the resolved path does not exist.
`ConfigurationError`	If the file is not valid TOML. Never echoes the file's contents.
`StackConfigInvalidError`	If the file is valid TOML but does not conform to the StackConfig schema. Names the offending fields and never echoes rejected values.

active_config_path ¶

active_config_path() -> Path

The resolved active config path.

invalidate_cache ¶

invalidate_cache() -> None

Clear the process-local config cache.

Called by :mod:~oa_configurator.io after writing to the config file (save_stack_config), as a guard against filesystems with coarse mtime resolution where a write and the next read could otherwise land in the same cache key.