shared.user_settings

Generic class to store and retrieve user preferences.

This module provides the UserSettings class for managing user configuration settings and a generic SettingsManager for handling application-specific defaults.

Attributes

LOG

Classes

SettingsManager	Manager class for user-configured settings.
UserSettings	Generic Settings class to hold, read, and compare dictionary data.

Module Contents

class SettingsManager(settings_file_name: str, defaults: Dict[str, Any])

Manager class for user-configured settings.

get(key: str, default_override: Any = None) → Any

Get a setting value.

Uses defaults as the ultimate fallback.

Args:

key: Setting key to retrieve. default_override: Override default value if provided.

Returns:

Any: The setting value.

get_all_settings() → Dict[str, Any]

Return all current setting data.

Returns:

dict: Dictionary of all settings.

is_changed() → bool

Check if current settings differ from the last saved state.

Returns:

bool: True if settings have changed, False otherwise.

reset() → None

Reset settings to their last saved state.

reset_to_factory_defaults() → None

Reset the values to the defaults.

save() → bool

Save any pending changes to the settings file.

Returns:

bool: True if file was written, False otherwise.

set(key: str, value: Any) → None

Edit a setting.

Does not save immediately.

Args:

key: Setting key to set. value: New value for the setting.

class UserSettings(file_name: str | pathlib.Path)

Generic Settings class to hold, read, and compare dictionary data.

add_property(key: str, val: Any, force: bool = True) → bool

Create a property key with given value.

Args:

key: Name of the property. val: Value for the property. Must be JSON-serializable. force: If False, existing keys will not be overwritten.

Returns:

True if property was changed/created, False otherwise.

apply_settings(force: bool = False) → bool

Apply the changed settings and write them to file.

Args:

force: If True, force writing even if settings did not change.

Returns:

True if the file has been written, False otherwise.

delete_property(key: str) → None

Delete the given property key.

Args:

key: Name of the key to be deleted.

edit_property(key: str, val: Any) → None

Update the property key with given value.

Args:

key: Property name. val: New value for the property.

edit_sub_property(sub_keys: Iterable[str], new_val: Any) → None

Edit nested properties.

Args:

sub_keys: Iterable of sub-keys. Each item must be the parent

of the next item in the hierarchy.

new_val: Value of the resolved key.

get(key: str, default: Any = None) → Any

Dict-style alias for get_property.

get_data() → Dict[str, Any]

Return the whole current data.

Returns:

dict: Complete current data dictionary.

get_property(key: str, default: Any = None) → Any

Return the value of the property key.

Args:

key: Name of the property to query. default: Default value if key is missing.

Returns:

Dictionary value of the property.

get_sub_property(sub_keys: Iterable[str]) → Any

Return the value of a nested property.

Args:

sub_keys: Iterable of nested keys.

Returns:

Any: Dictionary value of the nested property.

initialize(data: MutableMapping[str, Any] | None) → None

Initialize the settings data.

Args:

data: Dictionary data to feed into the class.

is_settings_changed() → bool

Check if the settings changed since initialization.

Returns:

bool: True if settings have changed, False otherwise.

reset_settings() → None

Revert unsaved changes to the original state.

set_data(data: Dict[str, Any]) → None

Feed the raw data directly.

Args:

data: Dictionary that will be fed into the class directly.

Must have JSON-serializable values.

set_fallback(file_path: str | pathlib.Path) → None

Use this file in case the main file is not found.

Args:

file_path: Path to a json file location.

update(data: MutableMapping[str, Any] | UserSettings, add_missing_keys: bool = False) → None

Update the settings data.

Args:

data: Dictionary (or another UserSettings) to update the existing

data.

add_missing_keys: If True, all missing keys will be added.

Otherwise only existing keys will be updated.

use_fallback() → None

Use the fallback file.

property keys: List[str]

Return all keys in the current data.

Returns:

list: List of all keys.

property properties: Dict[str, Any]

Return the current dictionary data.

Returns:

dict: Dictionary of all properties.

property values: List[Any]

Return all values in the current data.

Returns:

list: List of all values.

LOG