Application layer

Application orchestration components: main window, app services, and bootstrap flow.

📦 EzQt_App

EzQt_App

EzQt_App()

Bases: QMainWindow

Main EzQt_App application.

This class represents the main application window with all its components (menu, pages, settings, etc.).

Initialize the EzQt_App application.

no_menu

no_menu() -> EzQt_App

Disable the left menu for this application instance.

Returns:

Name	Type	Description
EzQt_App	EzQt_App	Self instance for chaining.

no_settings_panel

no_settings_panel() -> EzQt_App

Disable the settings slide-in panel for this application instance.

Returns:

Name	Type	Description
EzQt_App	EzQt_App	Self instance for chaining.

build

build() -> EzQt_App

Explicitly build the UI layout.

Automatically called on first show() if not called.

Returns:

Name	Type	Description
EzQt_App	EzQt_App	Self instance for chaining.

showEvent

showEvent(event: QShowEvent) -> None

Ensure UI is built before showing the window.

Parameters:

Name	Type	Description	Default
event	QShowEvent	The QShowEvent instance.	required

set_app_theme

set_app_theme() -> None

Update and apply the application theme based on current settings.

The theme was already persisted and applied to SettingsService by _on_theme_selector_changed before this slot fires. We only need to trigger a full UI refresh here.

update_ui

update_ui() -> None

Force a full UI refresh including themes, icons, and styles.

refresh_theme

refresh_theme() -> EzQt_App

Re-apply the theme stylesheet and polish all widgets.

Call this after adding custom widgets to the application to ensure that QSS rules (especially #objectName selectors) are correctly evaluated against the newly added widgets. Also refreshes all ThemeIcon instances so that icons added after build() (e.g. via add_menu()) are correctly coloured for the current theme.

Returns:

Name	Type	Description
self	EzQt_App	Allows method chaining.

Example::

window = EzQt_App().build()
window.show()
add_things_to_my_app(window, Icons)
window.refresh_theme()

set_app_icon

set_app_icon(icon: str | QPixmap, y_shrink: int = 0, y_offset: int = 0) -> None

Set the application logo in the header.

Parameters:

Name	Type	Description	Default
icon	str | QPixmap	Path to icon or QPixmap object.	required
y_shrink	int	Vertical shrink factor.	0
y_offset	int	Vertical offset adjustment.	0

add_menu

add_menu(name: str, icon: str) -> QWidget

Add a new menu item and corresponding page.

Parameters:

Name	Type	Description	Default
name	str	Label for the menu and page.	required
icon	str	Icon name or path.	required

Returns:

Name	Type	Description
QWidget	QWidget	The created page widget.

switch_menu

switch_menu() -> None

Update active state of menu buttons based on sender.

resizeEvent

resizeEvent(_event: QResizeEvent) -> None

Handle window resize events to update UI components.

Parameters:

Name	Type	Description	Default
_event	QResizeEvent	The QResizeEvent instance (unused).	required

mousePressEvent

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events for window dragging and diagnostics.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The QMouseEvent instance.	required

set_credits

set_credits(credits: Any) -> None

Set credit text in the bottom bar.

Parameters:

Name	Type	Description	Default
credits	Any	Text or object to display as credits.	required

set_version

set_version(version: str) -> None

Set version text in the bottom bar.

Parameters:

Name	Type	Description	Default
version	str	Version string to display.	required

get_translation_stats

get_translation_stats() -> dict[str, Any]

Retrieve current translation statistics.

Returns:

Name	Type	Description
dict	dict[str, Any]	Statistics about translated and missing strings.

enable_auto_translation

enable_auto_translation(enabled: bool = True) -> None

Enable or disable automatic translation collection.

Parameters:

Name	Type	Description	Default
enabled	bool	Whether to enable auto-translation.	True

clear_translation_cache

clear_translation_cache() -> None

Clear the automatic translation cache.

collect_strings_for_translation

collect_strings_for_translation(widget: QWidget | None = None, recursive: bool = True) -> dict[str, Any]

Scan widgets for translatable strings and add them to the collector.

Parameters:

Name	Type	Description	Default
widget	QWidget | None	Root widget to start scanning from (default: self).	None
recursive	bool	Whether to scan child widgets recursively.	True

Returns:

Name	Type	Description
dict	dict[str, Any]	Summary of the collection process.

get_new_strings

get_new_strings() -> set[str]

Get all newly discovered strings since last save.

Returns:

Type	Description
set[str]	set[str]: Set of new translatable strings.

get_string_collector_stats

get_string_collector_stats() -> dict[str, Any]

Get statistics from the string collector.

Returns:

Name	Type	Description
dict	dict[str, Any]	Collector statistics.

📦 AppService

AppService

Central orchestration service for application lifecycle.

Aggregates config, asset, resource and settings operations into a single cohesive snake_case API used by widgets, CLI and bootstrap.

check_assets_requirements staticmethod

check_assets_requirements(base_path: Path | None = None, bin_path: Path | None = None, overwrite_policy: str = 'ask') -> None

Generate asset binaries, QRC and RC files at APP_PATH.

Parameters:

Name	Type	Description	Default
base_path	Path | None	Optional base path for assets.	None
bin_path	Path | None	Optional binary path.	None
overwrite_policy	str	Policy for overwriting existing files (default: "ask").	'ask'

make_required_files staticmethod

make_required_files(mk_theme: bool = True, mk_config: bool = True, mk_translations: bool = True, base_path: Path | None = None, bin_path: Path | None = None, overwrite_policy: str = 'ask') -> None

Copy YAML, QSS theme and translation files into project directories.

Parameters:

Name	Type	Description	Default
mk_theme	bool	When True also copies the QSS theme file.	True
mk_config	bool	When True copies configuration files.	True
mk_translations	bool	When True copies translation files.	True
base_path	Path | None	Optional base path.	None
bin_path	Path | None	Optional binary path.	None
overwrite_policy	str	Policy for overwriting (default: "ask").	'ask'

set_project_root staticmethod

set_project_root(project_root: Path) -> None

Set the project root directory used by the config service.

Parameters:

Name	Type	Description	Default
project_root	Path	The Path to the project root.	required

load_config staticmethod

load_config(config_name: str) -> dict[str, Any]

Load a named configuration from its YAML file.

Parameters:

Name	Type	Description	Default
config_name	str	Logical name of the configuration (e.g. "app").	required

Returns:

Name	Type	Description
dict	dict[str, Any]	The loaded configuration data.

get_config_value staticmethod

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

Get a value from a named configuration using dot-separated path.

Parameters:

Name	Type	Description	Default
config_name	str	Logical name of the configuration.	required
key_path	str	Dot-separated key path, e.g. "app.name".	required
default	Any	Value returned when the path is absent.	None

Returns:

Name	Type	Description
Any	Any	The configuration value or default.

save_config staticmethod

save_config(config_name: str, data: dict[str, Any]) -> None

Persist a named configuration to its YAML file.

Parameters:

Name	Type	Description	Default
config_name	str	Logical name of the configuration.	required
data	dict[str, Any]	Full configuration dict to write.	required

write_yaml_config staticmethod

write_yaml_config(keys: list[str], val: Any) -> None

Write a single value into a YAML config using a key list immediately.

Parameters:

Name	Type	Description	Default
keys	list[str]	List where keys[0] is config name and keys[1:] is the path.	required
val	Any	Value to assign at the leaf key.	required

stage_config_value staticmethod

stage_config_value(keys: list[str], val: Any) -> None

Mutate a config value in the shared cache and mark it dirty for flush.

Parameters:

Name	Type	Description	Default
keys	list[str]	List where keys[0] is config name and keys[1:] is the path.	required
val	Any	Value to assign at the leaf key.	required

flush_all staticmethod

flush_all() -> None

Write all dirty configs to disk and clear the dirty set.

copy_package_configs_to_project staticmethod

copy_package_configs_to_project() -> None

Copy package default configs into the child project directory.

get_package_resource staticmethod

get_package_resource(resource_path: str) -> Path

Return a Path to an installed package resource.

Parameters:

Name	Type	Description	Default
resource_path	str	Relative path inside the package.	required

Returns:

Name	Type	Description
Path	Path	Absolute path to the resource.

get_package_resource_content staticmethod

get_package_resource_content(resource_path: str) -> str

Return the text content of an installed package resource.

Parameters:

Name	Type	Description	Default
resource_path	str	Relative path inside the package.	required

Returns:

Name	Type	Description
str	str	Content of the resource.

load_fonts_resources staticmethod

load_fonts_resources(app: bool = False) -> None

Load .ttf font files into Qt's font database.

Parameters:

Name	Type	Description	Default
app	bool	Whether to also load fonts from the bin/fonts/ directory.	False

load_app_settings staticmethod

load_app_settings() -> dict[str, Any]

Load app settings from YAML and apply to SettingsService.

Returns:

Name	Type	Description
dict	dict[str, Any]	Loaded settings.

📦 InitService

InitService

InitService()

Coordinates initialization with a single options object.

run

run(options: InitOptions | None = None) -> InitResult

Run initialization sequence with normalized options.

is_initialized

is_initialized() -> bool

Return True if initialization has completed successfully.

reset

reset() -> None

Reset initialization state.

📦 InitOptions

InitOptions dataclass

InitOptions(project_root: Path | None = None, bin_path: Path | None = None, mk_theme: bool = True, mk_config: bool = True, mk_translations: bool = True, build_resources: bool = True, generate_main: bool = False, verbose: bool = True, overwrite_policy: OverwritePolicy = ASK)

Options driving initialization behavior across API and CLI.

Attributes:

Name	Type	Description
project_root	Path | None	Absolute path to the project root directory. When None, defaults to Path.cwd() at resolve time.
bin_path	Path | None	Directory where generated assets (resources_rc.py, app_icons.py, app_images.py, themes) are written. When None, defaults to <project_root>/bin. A relative value is resolved against project_root; an absolute value is used as-is.
mk_theme	bool	Generate QSS theme files under bin_path/themes/.
mk_config	bool	Generate the config/ YAML files.
mk_translations	bool	Generate the translations/ TS source files.
build_resources	bool	Compile the QRC file with pyside6-rcc and write resources_rc.py, app_icons.py, and app_images.py into bin_path. Raises ResourceCompilationError if pyside6-rcc is not found on PATH.
generate_main	bool	Write a main.py entrypoint in the project root.
verbose	bool	Print step-by-step progress to stdout.
overwrite_policy	OverwritePolicy	Controls behavior when generated files already exist. See :class:OverwritePolicy.

resolve

resolve() -> InitOptions

Return a copy with normalized paths and defaults resolved.

📦 InitializationSequence

InitializationSequence

InitializationSequence(options: InitOptions | None = None)

Orchestrates the ordered initialization steps for EzQt_App.

Each step is registered with a name, description, callable and a required flag. If a required step fails the sequence stops immediately; non-required steps are allowed to fail silently.

add_step

add_step(name: str, description: str, function: Callable[[], None], required: bool = True) -> None

Append a new step to the sequence.

execute

execute(verbose: bool = True) -> InitResult

Run all registered steps in order.

Returns

InitResult Typed aggregate result with step-level execution details.

📦 StartupConfig

StartupConfig

StartupConfig()

Manages system-level startup configuration.

Handles encoding, locale, environment variables and project root detection. Idempotent: subsequent calls to :meth:configure are no-ops once the instance is configured.

configure

configure(project_root: Path | None = None) -> None

Run all startup configuration steps (idempotent).