Loader¶

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

Two entry points, differing only in where the path comes from:

Function	Use when
`load_stack_config()`	The application has no config-path option of its own. Reads `CONFIG_PATH` (default `~/.config/omop/config.toml`, overridable with `OA_CONFIG_PATH`).
`load_stack_config_from_path(path)`	Something supplies a path — a `--config-path` flag, a CLI command, a test fixture.

Prefer load_stack_config_from_path 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.

Both raise ConfigurationError for a file that is present but unusable: malformed TOML, or content that does not validate. The validation case is a StackConfigValidationError 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() -> StackConfig

Load a :class:StackConfig from CONFIG_PATH (default ~/.config/omop/config.toml, overridable via OA_CONFIG_PATH).

OA_CONFIG_PATH is resolved when this module is first imported. Set it before starting the process; changing it at runtime does not change CONFIG_PATH.

Raises:

Type	Description
`FileNotFoundError`	If `CONFIG_PATH` does not exist.

load_stack_config_from_path ¶

load_stack_config_from_path(
    path: str | Path,
) -> StackConfig

Load a :class:StackConfig from an explicit path.

For anything that accepts a config path of its own -- a --config-path flag, a CLI command, a test fixture. Application code with no such flag should use :func:load_stack_config, which reads CONFIG_PATH.

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	File to load. `~` is expanded and the path resolved.	required

Returns:

Type	Description
`StackConfig`	A deep copy, so a caller can mutate it without disturbing the cache or any other holder.

Raises:

Type	Description
`FileNotFoundError`	If path does not exist.
`ConfigurationError`	If the file is not valid TOML, or does not validate as a :class:`StackConfig`. Both carry the file path; the validation case is a :class:`~oa_configurator.StackConfigValidationError` naming the offending fields. Neither echoes a rejected value.

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.