Skip to content

Configuration and runtime

Configuration and runtime state services for project setup and UI behavior.

⚠️ Strict validation contracts

ConfigService.save_config() now validates known payloads in strict mode before writing files:

Config file Validated sections
app.config.yaml app, settings_panel
translation.config.yaml translation, language_detection, supported_languages
theme.config.yaml palette

Unknown keys in validated sections are rejected (strict schema mode). When validation fails, the file is not written.

🎨 Theme default source

The default/active theme is read from settings_panel.theme.default in app.config.yaml.

app.theme is no longer part of the configuration contract.

📦 ConfigService

ConfigService 

ConfigService()

Bases: ConfigServiceProtocol

Modular configuration service for EzQt_App.

set_project_root 

set_project_root(project_root: Path | str) -> None

Set the active project root directory.

load_config 

load_config(config_name: str, force_reload: bool = False) -> dict[str, Any]

Load a named configuration from the first matching path.

Parameters

config_name: Configuration file name (without extension, e.g. "app"). force_reload: Bypass cache and reload from disk.

Returns

dict[str, Any] Loaded configuration data, or empty dict on failure.

get_config_value 

get_config_value(config_name: str, key_path: str, default: Any = None) -> Any

Read a specific value from a configuration using dot-notation key path.

Parameters

config_name: Configuration file name. key_path: Dot-separated path (e.g. "app.name" or "palette.dark"). default: Value returned when key is absent.

save_config 

save_config(config_name: str, config_data: dict[str, Any]) -> bool

Persist a named configuration to the project directory.

Writes use ruamel.yaml round-trip mode to preserve existing comments, key ordering, and formatting whenever the target file already exists. Configuration reads stay on PyYAML for the current typed read path.

Parameters

config_name: Configuration file name. config_data: Data to serialise as YAML.

Returns

bool True if the write succeeded.

get_config_paths 

get_config_paths(config_name: str) -> list[Path]

Return candidate paths for config_name in priority order.

Parameters

config_name: Logical configuration name (e.g. "app", "languages", "theme"). Files are resolved as <name>.config.yaml.

copy_package_configs_to_project 

copy_package_configs_to_project() -> bool

Copy package configuration files into the child project.

Returns

bool True if the operation succeeded.

clear_cache 

clear_cache() -> None

Invalidate the in-memory configuration cache.

get_loaded_configs 

get_loaded_configs() -> dict[str, Path]

Return a snapshot of currently cached configuration paths.

📦 SettingsService

SettingsService 

SettingsService()

Bases: SettingsServiceProtocol

Service managing mutable application settings state.

Initialize settings state container.

app property 

app: AppSettingsModel

Return mutable application settings.

gui property 

gui: GuiSettingsModel

Return mutable GUI settings.

set_app_name 

set_app_name(name: str) -> None

Set application name.

set_app_description 

set_app_description(description: str) -> None

Set application description.

set_custom_title_bar_enabled 

set_custom_title_bar_enabled(enabled: bool) -> None

Enable or disable custom title bar.

set_app_min_size 

set_app_min_size(width: int, height: int) -> None

Set minimum window size.

set_app_min_size_qsize 

set_app_min_size_qsize(size: QSize) -> None

Set minimum window size from QSize (convenience, not part of the port).

set_app_dimensions 

set_app_dimensions(width: int, height: int) -> None

Set default window dimensions.

set_debug_enabled 

set_debug_enabled(enabled: bool) -> None

Enable or disable debug console output.

set_theme 

set_theme(theme: str) -> None

Set active theme.

Accepts either a 'preset:variant' string (e.g. 'blue_gray:dark') or a bare variant (e.g. 'dark', 'light') for backward compat. A bare variant keeps the current THEME_PRESET unchanged.

set_menu_widths 

set_menu_widths(shrinked: int, extended: int) -> None

Set menu panel widths.

set_settings_panel_width 

set_settings_panel_width(width: int) -> None

Set settings panel width.

set_time_animation 

set_time_animation(duration: int) -> None

Set animation duration in milliseconds.

📦 RuntimeStateService

RuntimeStateService 

RuntimeStateService()

Bases: RuntimeStateServiceProtocol

Service managing runtime flags and legacy global UI state.

Initialize runtime state.

  • ezqt_app.domain.ports.config_service.ConfigServiceProtocol
  • ezqt_app.domain.ports.settings_service.SettingsServiceProtocol
  • ezqt_app.domain.ports.runtime_state_service.RuntimeStateServiceProtocol