Skip to content

Config

Configuration management for lst_tools.

Functions

read_config

1
2
3
from lst_tools import read_config

config = read_config("lst.cfg")

Read a TOML configuration file and return a typed Config dataclass.

lst_tools.config.read_config

Load and return an lst_tools configuration.

This module is the public entry-point for config loading. The heavy lifting lives in schema.py (dataclasses + coercion).

read_config 

read_config(path: str | Path | None = None) -> Config

Load configuration from a TOML file.

Parameters:

Name Type Description Default
path str | Path | None

Explicit TOML path. If omitted, searches for common config filenames in the CWD (lst.cfg, lst.toml, …).

 None

Returns:

Name Type Description
Config Config

A Config dataclass. Missing keys use built-in defaults.

Raises:

Type Description
FileNotFoundError

If path is given but does not exist on disk.

write_config

1
2
3
from lst_tools import write_config

write_config("lst.cfg", overwrite=True, cfg_data=config.to_dict())

Write configuration data to a TOML file.

lst_tools.config.write_config

Write a TOML configuration file.

Serialises a config dictionary into a TOML file on disk.

write_config 

write_config(path: str | Path = 'lst.cfg', overwrite: bool = False, cfg_data: dict[str, Any] | None = None) -> Path

Write a TOML configuration file to path.

Parameters:

Name Type Description Default
path str | Path

Destination path for the config file.

 'lst.cfg'
overwrite bool

If False and path already exists, return immediately without writing.

 False
cfg_data dict

Config dictionary to serialise.

 None

Returns:

Name Type Description
Path Path

The path the config was written to (or already existed at).

Config

1
2
3
from lst_tools.config import Config

cfg = Config.from_toml("lst.cfg")

Typed configuration schema and validation.

lst_tools.config.Config dataclass 

Config(input_file: str = 'base_flow.hdf5', lst_exe: str = 'lst.x', flow_conditions: FlowConditions = FlowConditions(), geometry: Geometry = Geometry(), meanflow_conversion: MeanflowConversion = MeanflowConversion(), lst: LstConfig = LstConfig(), hpc: HpcConfig = HpcConfig(), processing: Processing = Processing(), seed_table: SeedTable = SeedTable(), extract: ExtractConfig = ExtractConfig())

Bases: _ConfigBase

Complete lst_tools configuration.

Build from a raw dict::

1
cfg = Config.from_dict(raw)

Build directly from a TOML file::

1
cfg = Config.from_toml("lst.cfg")

Access fields as attributes::

1
2
cfg.lst.solver.type
cfg.flow_conditions.mach

from_dict classmethod 

from_dict(d: dict[str, Any]) -> Config

Build a validated Config from a plain nested dict.

Each top-level key in d is dispatched to the corresponding section dataclass (e.g. d["flow_conditions"] is forwarded to FlowConditions.from_dict). Missing sections get their default values. The resulting Config is validated before being returned.

Parameters:

Name Type Description Default
d dict[str, Any]

Raw config dictionary, typically the output of tomllib.loads().

 required

Returns:

Name Type Description
Config Config

Fully populated and validated configuration.

Raises:

Type Description
ValueError

If validation finds constraint violations.

from_toml classmethod 

from_toml(path: str | Path) -> Config

Parse a TOML file into a Config.

Parameters:

Name Type Description Default
path str | Path

Path to a TOML configuration file.

 required

Returns:

Name Type Description
Config Config

Validated configuration object.

validate 

validate() -> Config

Check value constraints; raise ValueError listing all violations.

find_config

1
2
3
from lst_tools import find_config

path = find_config(".")

Search for a configuration file in the current directory and parent directories.

lst_tools.config.find_config

Locate a configuration file by scanning for known filenames.

Fallback routine used when no explicit --cfg path is passed to a CLI command. Searches search_path for commonly used config file names (lst.cfg, lst.toml, config.toml) and returns the first match.

find_config 

find_config(search_path: str | Path = '.') -> Path | None

Search search_path for a recognised configuration file.

Iterates over a priority-ordered list of candidate filenames and returns the first one that exists on disk.

Parameters

search_path : str | Path, optional Directory to scan (default: current working directory).

Returns

Path | None Path to the first matching config file, or None if no candidates are found.

check_consistency

1
2
3
4
from lst_tools import check_consistency, format_report

report = check_consistency(config)
print(format_report(report))

Check configuration for internal consistency and return a diagnostic report.

lst_tools.config.check_consistency

Validate configuration consistency.

Defines a registry of named checks that inspect a config dictionary for contradictions (e.g. geometry type vs. solver switch). Results are returned as typed Issue objects split into errors and warnings.

Issue dataclass 

Issue(level: IssueLevel, path: str, message: str, hint: str = '')

Single consistency problem found in a configuration.

IssueLevel

Bases: Enum

Severity level for a consistency issue.

check_consistency 

check_consistency(cfg: dict[str, Any], *, enabled: Iterable[str] | None = None) -> tuple[list[Issue], list[Issue]]

Run all registered checks and return (errors, warnings).

Parameters

cfg : dict Configuration dictionary (or Config dataclass with to_dict). enabled : Iterable[str] | None If provided, only run checks whose names are in this set.

Returns

tuple[list[Issue], list[Issue]] (errors, warnings) collected from all executed checks.

format_report 

format_report(errors: list[Issue], warnings: list[Issue]) -> str

Format errors and warnings into a human-readable string.

get 

get(d: dict[str, Any], path: str, default: Any = None) -> Any

Retrieve a value from a nested dict using a dotted path.

Parameters

d : dict Nested dictionary to search. path : str Dot-separated key path, e.g. "lst.solver.type". default : Any Value returned when any segment is missing.

register_check 

register_check(name: str | None = None) -> Callable[[CheckFn], CheckFn]

Decorator that adds a check function to the module registry.

lst_tools.config.format_report 

format_report(errors: list[Issue], warnings: list[Issue]) -> str

Format errors and warnings into a human-readable string.