ConfigHandler#

class tollan.config.ConfigHandler(runtime_context: RuntimeContextT)[source]#

Bases: Generic

Base class for domain-specific configuration handlers.

ConfigHandler provides a pattern for consuming RuntimeContext and validating its raw config against domain-specific models. It offers:

Lazy-loaded, cached domain config via config property
Auto-reset cached properties when config updates
Unified interface for specialized config management
Subconfig extraction via SubConfigKeyTransformer pattern

Type Parameters:

ConfigModelT: Domain config model class (Pydantic BaseModel) RuntimeContextT: RuntimeContext for type hint only (default: RuntimeContext)

Subclasses must:

Define ConfigModelT type parameter
Implement prepare_config_data() to extract config from runtime config
Implement prepare_runtime_config_data() to wrap config for updates

Example

>>> from pydantic import BaseModel
>>> from tollan.config import ConfigHandler, RuntimeContext
>>>
>>> class MyConfigModel(BaseModel):
...     database_url: str
...     max_connections: int = 10
>>>
>>> class MyConfigHandler(ConfigHandler[MyConfigModel]):
...     @classmethod
...     def prepare_config_data(cls, runtime_config):
...         return {
...             "database_url": "postgresql://localhost/db",
...             "max_connections": 20,
...         }
>>>
>>> rc = RuntimeContext(config_sources={"format": "dict", "source": {}})
>>> handler = MyConfigHandler(rc)
>>> handler.config.database_url
'postgresql://localhost/db'

Initialize config handler.

Parameters:: runtime_context (RuntimeContext) – RuntimeContext instance

Attributes Summary

`config`	Lazy-loaded, cached domain config.
`rc`	Get the underlying runtime context.
`runtime_config`	Get the underlying runtime config model.
`runtime_info`	Get the runtime info.

Methods Summary

`auto_cache_reset`(prop)	Mark cached property for auto-reset on config reload.
`load_config`()	Load and validate config from runtime config.
`prepare_config_data`(runtime_config)	Prepare config data from runtime config.
`prepare_runtime_config_data`(config_data)	Prepare runtime config data from config data.
`update_config`(cfg[, tier])	Update config with provided config dict.
`update_runtime_config`(cfg[, tier])	Update runtime config with provided dict.

Attributes Documentation

config[source]#

Lazy-loaded, cached domain config.

Calls load_config() on first access and caches the result. Cache is cleared when update_config() is called.

Return type:: Validated config model instance

rc#

Get the underlying runtime context.

Return type:: RuntimeContext instance

runtime_config#

Get the underlying runtime config model.

Return type:: RuntimeConfig instance

runtime_info#

Get the runtime info.

Return type:: Runtime info instance

Methods Documentation

classmethod auto_cache_reset(prop: cached_property) → cached_property[source]#

Mark cached property for auto-reset on config reload.

Parameters:

prop (cached_property) – Cached property to mark

Returns:

Same cached property (for chaining)

Return type:

cached_property

Raises:

TypeError – If prop is not a cached_property

Example: –

>>> from functools import cached_property
    >>> from pydantic import BaseModel
    >>> class MyConfig(BaseModel):
    ...     value: str = "test"
    >>> class MyHandler(ConfigHandler[MyConfig]):
    ...     @classmethod
    ...     def prepare_config_data(cls, runtime_config):
    ...         return {"value": "test"}
    ...     @ConfigHandler.auto_cache_reset
    ...     @cached_property
    ...     def expensive_computation(self):
    ...         return "computed"
    >>> # Property will auto-reset when config updates

load_config() → ConfigModelT[source]#

Load and validate config from runtime config.

Return type:: Validated config model instance

classmethod prepare_config_data(runtime_config: RuntimeConfig) → dict[source]#

Prepare config data from runtime config.

Subclasses must implement this to extract their specific config from the runtime config model.

Parameters:: runtime_config (RuntimeConfig) – RuntimeConfig model instance
Returns:: Config data dict for validation
Return type:: dict
Raises:: NotImplementedError – If not overridden by subclass

classmethod prepare_runtime_config_data(config_data: DictConfigT) → DictConfigT[source]#

Prepare runtime config data from config data.

Subclasses must implement this to wrap their config data for updating the runtime config.

Parameters:: config_data (DictConfigT) – Domain config data
Returns:: Runtime config data dict
Return type:: DictConfigT
Raises:: NotImplementedError – If not overridden by subclass

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

Update config with provided config dict.

This wraps the config under the appropriate runtime config key and calls update_runtime_config().

Parameters:

cfg (dict) – Config data to apply
tier (Literal["override", "default"], optional) – Update tier (“override” or “default”), by default “override”

update_runtime_config(cfg: DictConfigT, tier: Literal['override', 'default'] = 'override') → None[source]#

Update runtime config with provided dict.

Parameters:

cfg (DictConfigT) – Runtime config data to apply
tier (Literal["override", "default"], optional) – Update tier, by default “override”: - “override”: Override existing values - “default”: Use as default for unspecified values

Raises:

ValueError – If tier is invalid

ConfigHandler

Contents

ConfigHandler#