RuntimeContext

class tollan.config.RuntimeContext(config_sources: Path | dict | list | ConfigSourceList | None = None)

Bases: Generic

Entry point for runtime-aware configuration management.

RuntimeContext manages a ConfigSourceList with a four-tier architecture: 1. Default tier (order=-1) - Base defaults, lowest priority 2. User sources (order=0+) - From config files/dicts 3. Info tier (order=1000) - Runtime info dict data 4. Override tier (order=1001) - Runtime overrides, highest priority

It provides: - Lazy-loaded, cached config model object via config cached property - Cached config dict via config_dict cached property - Context management for temporary config overrides - Registration system for ConfigHandler subclasses - Factory methods for common setups (from_cli, etc.)

Type Parameters

RuntimeConfigT: Runtime config class (subclass of RuntimeConfig)

Examples

>>> # Basic usage
>>> rc = RuntimeContext(
...     config_sources=[
...         {"format": "dict", "source": {"app": "test"}, "order": 0},
...         {"format": "dict", "source": {"debug": True}, "order": 1}
...     ]
... )
>>> config = rc.config  # Validated RuntimeConfig model
>>> rc.config_dict['app']
'test'

>>> # Temporary context override
>>> with rc.set_context({"env": "production"}):
...     prod_config = rc.config_dict

Attributes Summary

TIERS	Tier configurations with name and order.
config	Get the validated configuration model.
config_dict	Get the loaded and merged configuration as a dictionary.
config_handler_cls_registry	Registry of ConfigHandler classes for this RuntimeContext.
config_sources	Get the ConfigSourceList.
runtime_info	Get runtime info from the validated config.

Methods Summary

from_cli([config_path, env_files, cli_args])	Create RuntimeContext from CLI arguments.
register_config_handler_cls(config_handler_cls)	Register a ConfigHandler class.
reload()	Reload configuration, invalidating all caches.
set_config(cfg, tier)	Replace a named tier's configuration entirely.
set_context(context)	Context manager to temporarily override validation context.
set_default_config(cfg)	Set default configuration (order=-1 tier).
set_override_config(cfg)	Set override configuration (order=1001 tier).
update_config(cfg, tier)	Merge configuration into a named tier.
update_default_config(cfg)	Merge default configuration (order=-1 tier).
update_override_config(cfg)	Merge override configuration (order=1001 tier).

Attributes Documentation

TIERS: ClassVar[dict[Literal['default', 'info', 'override'], dict[str, str | int]]] = {'default': {'name': 'default', 'order': -1}, 'info': {'name': 'info', 'order': 1000}, 'override': {'name': 'override', 'order': 1001}}

Tier configurations with name and order.

config

Get the validated configuration model.

This validates the merged config dict using the RuntimeConfig model (or a subclass defined in runtime_config_cls). The result is cached.

Return type:

Validated RuntimeConfig instance

config_dict

Get the loaded and merged configuration as a dictionary.

This loads config with the current context and caches the result. Cache is invalidated when context changes or when update_*_config methods are called.

Return type:

Merged configuration dictionary (DictConfigT)

config_handler_cls_registry: ClassVar[set[type[ConfigHandler]]] = {}

Registry of ConfigHandler classes for this RuntimeContext.

config_sources

Get the ConfigSourceList.

This is the underlying source list that can be used to access individual sources, inspect the configuration pipeline, or load configuration with different contexts.

Return type:

ConfigSourceList instance

runtime_info

Get runtime info from the validated config.

Return type:

Runtime info instance from config.runtime_info

Methods Documentation

classmethod from_cli(config_path: Path | None = None, env_files: list[Path] | None = None, cli_args: list[str] | None = None) → RuntimeContext[RuntimeConfigT]

Create RuntimeContext from CLI arguments.

This factory method creates a standard CLI configuration layout: - Config path (file or directory) at order=0 - Env files at order=100+ - CLI args converted to overrides env files at order=200

Parameters:

• config_path (Path | None, optional) – Main config file or directory path. If directory, loads numbered YAML files (e.g., 00_base.yaml, 01_dev.yaml), by default None

• env_files (list[Path] | None, optional) – List of .env file paths, by default None

• cli_args (list[str] | None, optional) – CLI arguments in “–key=value” or “–key value” format. Converted to nested dict (e.g., [”–db.host”, “localhost”] → {“db”: {“host”: “localhost”}}), by default None

Returns:

• RuntimeContext[RuntimeConfigT] – RuntimeContext instance configured for CLI usage

• Example – >>> from pathlib import Path >>> # Create from CLI args >>> rc = RuntimeContext.from_cli( … cli_args=[”–debug”, “true”, “–port”, “8080”] … ) >>> ‘debug’ in rc.config_dict True

classmethod register_config_handler_cls(config_handler_cls: type[ConfigHandler]) → None

Register a ConfigHandler class.

Types registered can be instantiated via the __getitem__ interface.

Parameters:

config_handler_cls (type[ConfigHandler]) – ConfigHandler subclass to register

reload() → dict[str | int, Any]

Reload configuration, invalidating all caches.

This forces a full reload of all config sources, including file-based sources that are normally cached.

Return type:

Reloaded configuration dictionary

set_config(cfg: DictConfigT, tier: Literal['default', 'override']) → None

Replace a named tier’s configuration entirely.

Parameters:

• cfg (DictConfigT) – New configuration for the tier

• tier (Literal["default", "override"]) – Tier to set (“default” or “override”)

set_context(context: dict[str, Any]) → Generator[None]

Context manager to temporarily override validation context.

This is useful for testing different scenarios or loading config under different runtime conditions without permanent changes.

Parameters:

context (dict[str, Any]) – Context dictionary for enable_if expressions. Values are merged with existing context (doesn’t replace entirely).

Yields:

• None – Context is set for duration of with block

• Example – >>> rc = RuntimeContext( … config_sources=[ … {“format”: “dict”, “source”: {“app”: “test”}, “order”: 0} … ] … ) >>> with rc.set_context({“env”: “production”}): … config = rc.config_dict >>> rc.config_dict[‘app’] ‘test’

set_default_config(cfg: DictConfigT) → None

Set default configuration (order=-1 tier).

This only invalidates RuntimeContext caches, not ConfigSourceList source caches (since default tier is not cached in sources).

Parameters:

cfg (DictConfigT) – New default configuration

set_override_config(cfg: DictConfigT) → None

Set override configuration (order=1001 tier).

This only invalidates RuntimeContext caches, not ConfigSourceList source caches (since override tier is not cached in sources).

Parameters:

cfg (DictConfigT) – New override configuration

update_config(cfg: DictConfigT, tier: Literal['default', 'override']) → None

Merge configuration into a named tier.

Parameters:

• cfg (DictConfigT) – Configuration to merge into the tier

• tier (Literal["default", "override"]) – Tier to update (“default” or “override”)

update_default_config(cfg: DictConfigT) → None

Merge default configuration (order=-1 tier).

This only invalidates RuntimeContext caches, not ConfigSourceList source caches (since default tier is not cached in sources).

Parameters:

cfg (DictConfigT) – Configuration to merge into default tier

update_override_config(cfg: DictConfigT) → None

Merge override configuration (order=1001 tier).

This only invalidates RuntimeContext caches, not ConfigSourceList source caches (since override tier is not cached in sources).

Parameters:

cfg (DictConfigT) – Configuration to merge into override tier