utils.py PySideAbdhUI — Resource Handling, Theme Management & Color Utilities

Retrieves the full filesystem path to a specified resource located within a given Python package. This is the foundational function upon which all other resource accessors depend. It uses importlib.resources.path() as a context manager to resolve the resource, which handles the complexity of different package installation formats transparently.

The function automatically appends the file extension to the resource name. If ext is provided (defaulting to 'svg'), the resource is looked up as f'{resource}.{ext}'. If ext is falsy (empty string or None), the extension is derived from the last segment of the package path — for example, a package path of 'PySideAbdhUI.resources.styles' would yield ext = 'styles', which is likely incorrect. This fallback behavior appears to be a design artifact rather than a useful feature.

If the resource cannot be located, a RuntimeError is raised with a descriptive message that includes both the resource name and the package path, and the original exception is chained via from e.

Convenience function that resolves the path to an SVG icon resource and returns it as a POSIX-style string. This is the primary function used by the framework's widgets to load icons — every QIcon(get_icon('icon-name')) call in the codebase goes through this function. The default package path points to the PySideAbdhUI.resources.icons.svg subpackage, where all SVG icons are expected to reside.

Convenience function that resolves the path to the QSS template file (qss-template.qss) within the styles package. The template contains CSS rules with placeholder tokens in the format --token-name-- that are replaced with actual color values during theme application. The template serves as the single source of truth for the application's stylesheet structure, while the color values come from the theme JSON file.

Convenience function that resolves the path to the color-roles JSON file (color-roles.json) within the styles package. This JSON file defines all available themes, their color categories and roles, and the currently active theme. The file is the persistence layer for the ThemeManager — it is read on initialization and written back when themes are switched or properties are modified.

Initializes the theme manager by resolving the paths to the color-roles JSON file and the QSS template, then loading the theme data. The constructor performs the following steps:

1. Calls get_color_roles() to resolve the path to color-roles.json.
2. Calls get_styles_template() to resolve the path to qss-template.qss.
3. Stores both paths as self.color_roles and self.template_path.
4. Calls self.load() to read and parse the JSON file into self.data.

Reads and parses the color-roles.json file, returning the resulting dictionary. The file is opened with UTF-8 encoding and parsed with json.load(). After reading, the file is explicitly closed with f.close() (though the with statement would handle this automatically).

If the file cannot be opened or parsed, the with block exits and the code after it (return {"active-theme": "", "themes": {}}) is reached. However, this fallback is unreachable because the return statement inside the with block always executes first if the file is successfully read, and an exception would propagate rather than falling through.

Writes the current self.data dictionary back to the color-roles.json file with 4-space indentation. The file is opened with UTF-8 encoding in write mode. Like load(), the file is explicitly closed with f.close() despite the with statement handling this automatically. This method is called by switch_theme() to persist the active theme name change.

Returns the name of the currently active theme. The name is stored under the "active-theme" key in the JSON data. If the key is missing, an empty string is returned.

Returns the full theme dictionary for the currently active theme. The theme dictionary is a nested structure organized by color categories and role names. For example, a theme might have categories like "surface", "text", "accent", each containing role entries with a "color" field. If the active theme name does not exist in the themes dictionary, an empty dict is returned.

Retrieves a specific color value from the current theme by navigating the nested dictionary structure: theme[role_category][role_name]["color"]. This provides a convenient lookup API that abstracts away the dictionary structure. If the category, role, or color key does not exist, None is returned due to the chained .get() calls.

Returns a list of all available theme names in the configuration. This is useful for populating a theme selector UI where the user can choose from the installed themes.

Switches the active theme to the specified theme name. The method first checks whether the requested theme exists in the "themes" dictionary. If it does, the "active-theme" key in self.data is updated and self.save() is called to persist the change to disk. If the theme name does not exist, the method returns False without making any changes.

The main entry point for applying a theme to the application. This method performs a complete theme application cycle:

1. Switch theme: Calls switch_theme(theme_name) to update the active theme in the JSON data and persist the change.
2. Load template: Reads the QSS template file from self.template_path into a string.
3. Replace placeholders: Iterates over the current theme's categories and roles, replacing each placeholder token --role_name-- in the QSS string with the corresponding color value. The iteration order ensures all nested categories and roles are covered.
4. Apply stylesheet: Calls app.setStyleSheet(qss) on the QApplication instance to apply the completed stylesheet.

If the QSS template file cannot be read, an error message is printed to the console and the method returns without applying any changes. The existing stylesheet remains in effect.

Adds or updates a CSS property within a specific widget's style block in the QSS template file. This method provides a programmatic way to customize the stylesheet without manually editing the template file. It uses regular expressions to locate and modify the target widget block.

The method performs the following steps:

1. Read template: Reads the entire QSS template file into a string.
2. Match widget block: Uses the regex widget_name\s*\{[^}]*\} to find the CSS block for the specified widget. This pattern matches the widget name followed by a brace-enclosed block of properties.
3. Check for existing property: Within the matched block, searches for property_name\s*:\s*[^;]+; to determine if the property already exists.
4. Update or insert: If the property exists, its value is replaced. If it does not exist, the new property is appended before the closing brace with proper indentation.
5. Write template: The modified QSS string is written back to the template file.

Generates a random hex color that is guaranteed to be readable against the given background color, meeting a specified minimum WCAG contrast ratio. The function uses the WCAG 2.0 relative luminance algorithm to compute perceptual brightness and the standard contrast ratio formula to ensure accessibility. The generated color is never extremely bright (no white or near-white) and tends toward bolder, more saturated colors due to the minimum saturation threshold.

The function supports two operating modes controlled by the theme parameter:

• "auto" (default): Automatically determines whether a light or dark foreground is needed based on the background's luminance. If the background luminance is below 0.5, a light foreground is generated; otherwise, a dark one.
• "dark" or "light": Forces the generation of a specific foreground type regardless of the background brightness. Use "dark" to generate light foreground colors (for dark backgrounds) and "light" for dark foreground colors (for light backgrounds).