config_editor module

class config_editor.YamlEditor(auto_load=True, show_load_buttons=True, config_path=None, parent_config_path=None)

Bases: QWidget

A QWidget-based YAML editor that loads, displays, and edits YAML configuration files.

The editor can merge an “override” configuration with a parent configuration, preserving comments and allowing for interactive editing using a tree view.

add_item_to_container(container)

Add a new key/value pair to a dictionary or a new item to a list container.

For dictionaries, prompts the user for a key and value. For lists, prompts for a new item. After adding the item, the tree view is repopulated.

Parameters:

container (dict or list) – The container to which a new entry will be added.

auto_load_defaults()

Automatically load default configuration files on startup. Loads ./src/configs/config.default.yaml as parent and ./src/configs/config.yaml as main config. Uses custom paths if provided during initialization.

convert_value(new_value, old_value)

Convert a new string value to the type of the old value, if possible.

Supports conversion to bool, int, or leaves as string if conversion fails.

Parameters:

• new_value (str) – The new value as a string.

• old_value (Any) – The original value whose type is to be preserved.

Returns:

The converted new value with an attempt to preserve the data type.

Return type:

Any

get_expanded_items(item=None)

Get a set of paths for all currently expanded items in the tree.

Parameters:

item – Starting tree item (None = root)

Returns:

Set of string paths like “key1.key2.[0]”

Return type:

set

get_inline_comment(data_dict, key)

Retrieve an inline comment for a given key from the YAML data if present.

Parameters:

• data_dict (CommentedMap) – The YAML data structure with comment attributes.

• key (str) – The key for which the inline comment is desired.

Returns:

The inline comment text if found, otherwise None.

Return type:

str or None

get_level_color(depth)

Get a color for text based on nesting depth. Uses distinct colors that alternate for better visual hierarchy.

Parameters:

depth (int) – The nesting level (0 = root)

Returns:

Color object for the depth level

Return type:

QColor

is_overridden(key_path)

Determine whether the effective value (after merging with a parent config) differs from the parent’s value.

Parameters:

key_path (list) – The path of keys in the YAML structure.

Returns:

True if the merged configuration differs from the parent’s configuration; otherwise, False.

Return type:

bool

load_config_files()

Load the configuration files based on current paths

make_editor_widget(value, inline_comment, set_value_callback, update_style_callback=None)

Create an editor widget (QComboBox or QLineEdit) for editing a YAML value.

The widget type is determined by the presence of selectable options in the inline comment. When updated, the widget calls set_value_callback (and optionally update_style_callback).

Parameters:

• value (Any) – The current value to display.

• inline_comment (str) – The inline comment that may include options.

• set_value_callback (callable) – Function to call with the new value.

• update_style_callback (callable, optional) – Function to call to update the style after editing. Defaults to None.

Returns:

The editor widget.

Return type:

QWidget

on_collapse_all()

Collapse all nodes in the tree widget.

on_config_selection_changed(index)

Handle config file selection change from dropdown

on_expand_all()

Expand all nodes in the tree widget.

on_load()

Load a YAML file and populate the tree view with its contents. Enables the save button when a file is successfully loaded.

on_load_parent()

Load a parent YAML configuration file, merge it with the current override, and update the tree view.

on_save()

Save the override YAML file by calculating the difference from the parent configuration, or saving the entire YAML data if no parent is set. Creates a backup of the existing file with timestamp before saving.

populate_tree(data, parent_item, path=None)

Recursively populate the QTreeWidget with YAML data.

The tree displays key names, values, and inline comments, and provides interactive widgets for editing and adding/removing items.

Parameters:

• data (dict or list) – The YAML data to display.

• parent_item (QTreeWidgetItem) – The parent widget item where data should be attached.

• path (list, optional) – The path to the current data element (used for tracking overrides). Defaults to [].

remove_index_from_list(lst, index)

Remove an item at a specific index from a list and update the tree view.

Parameters:

• lst (list) – The list from which the item will be removed.

• index (int) – The index of the item to remove.

remove_key_from_dict(dct, key)

Remove a key from a dictionary and update the tree view.

Parameters:

• dct (dict) – The dictionary from which the key will be removed.

• key (str) – The key to remove.

resizeEvent(event)

Handle resize events to adjust tree column widths proportionally

restore_expanded_items(expanded_paths, item=None)

Restore expansion state for items based on their paths.

Parameters:

• expanded_paths – Set of string paths that should be expanded

• item – Starting tree item (None = root)

set_dict_value(data_dict, key, new_value)

Set a new value in a dictionary while preserving the data type.

Parameters:

• data_dict (dict) – The dictionary to update.

• key (str) – The key whose value is to be updated.

• new_value (Any) – The new value, as a string from the widget.

set_list_value(data_list, index, new_value)

Set a new value in a list while preserving the data type.

Parameters:

• data_list (list) – The list to update.

• index (int) – The index of the item to update.

• new_value (Any) – The new value, as a string from the widget.

set_override_value(key_path, new_value)

Update the override YAML configuration stored in self.yaml_data with a new value.

This function traverses (or creates) the nested dictionary structure given by key_path and sets the final key to the provided new_value. If self.yaml_data is not initialized, it is created as an empty dictionary.

Parameters:

• key_path (list) – The path of keys specifying the location in the YAML structure.

• new_value (Any) – The new value to set at the leaf of key_path.

staticMetaObject = PySide6.QtCore.QMetaObject("YamlEditor" inherits "QWidget": )

update_item_style(tree_item, key_path)

Update the visual style of a QTreeWidgetItem based on whether its value is overridden.

Parameters:

• tree_item (QTreeWidgetItem) – The tree widget item to update.

• key_path (list) – The path corresponding to the data item.

update_override(key_path, new_value)

Create or update the corresponding key in the override configuration (self.yaml_data) with new_value.

If necessary, nested dictionaries are created along the key_path.

Parameters:

• key_path (list) – The path of keys in the YAML structure.

• new_value (Any) – The new value to update in the configuration.

config_editor.calculate_diff(parent: dict, override)

Recursively compare two YAML data structures and return only the differences.

The function traverses both the parent and override data recursively. For dictionaries, it returns keys and subkeys that differ or do not exist in the parent. For lists, if they differ the entire override list is returned.

Parameters:

• parent (dict) – The parent YAML configuration.

• override (dict) – The override YAML configuration.

Returns:

The differences found in override compared to parent. Returns an empty dict/list if no differences exist.

Return type:

dict, list, or scalar

config_editor.get_expanded_paths(tree_widget)

Recursively record the unique paths of expanded items within a QTreeWidget.

Each item’s unique path is constructed from the root by joining the text in column 0 for each level of the item hierarchy.

Parameters:

tree_widget (QTreeWidget) – The tree widget whose expanded state is to be recorded.

Returns:

A set of string paths corresponding to the expanded items.

Return type:

set

config_editor.get_value(data, key_path)

Retrieve a value from a nested dictionary (or CommentedMap) given a key path list.

This function traverses the dictionary using the list of keys provided in key_path. If any of the keys in the path are missing, it returns None.

Parameters:

• data (dict or CommentedMap) – The nested dictionary to search within.

• key_path (list) – A list of keys that represent the path to the desired value.

Returns:

The value found at the end of the key_path, or None if any key is missing.

Return type:

Any

config_editor.main()

Entry point for running the YAML Editor application.

config_editor.merge_configs(parent, override)

Recursively merge two YAML configurations while preserving ruamel.yaml comment attributes.

If a key exists in both configurations:

• If both values are mappings, they are merged recursively.

• Otherwise, the override value is used while preserving parent comments if available.

For lists, the override list is returned directly.

Parameters:

• parent (CommentedMap) – The parent configuration.

• override (CommentedMap) – The override configuration with new or modified values.

Returns:

The merged configuration.

Return type:

CommentedMap or CommentedSeq or scalar

config_editor.parse_options_from_comment(comment: str)

Parse a comment string to extract options in the format “# Options: X, Y, Z” or “# Options: X or Y”.

Parameters:

comment (str) – The comment string that may include options.

Returns:

A list of options if found; otherwise, None.

Return type:

list or None

config_editor.restore_expanded_paths(tree_widget, expanded_paths)

Restore the expansion state of items in a QTreeWidget using a stored set of paths.

The function traverses the tree, and if an item’s constructed path is in the expanded_paths set, the item is set to expanded.

Parameters:

• tree_widget (QTreeWidget) – The tree widget to restore expansion state.

• expanded_paths (set) – A set of string paths indicating which items should be expanded.