shared.user_settings
====================

.. py:module:: shared.user_settings

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   shared.user_settings.LOG


Classes
-------

.. autoapisummary::

   shared.user_settings.SettingsManager
   shared.user_settings.UserSettings


Module Contents
---------------

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

   Manager class for user-configured settings.


   .. py:method:: 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.



   .. py:method:: get_all_settings() -> Dict[str, Any]

      Return all current setting data.

      Returns:
          dict: Dictionary of all settings.



   .. py:method:: is_changed() -> bool

      Check if current settings differ from the last saved state.

      Returns:
          bool: True if settings have changed, False otherwise.



   .. py:method:: reset() -> None

      Reset settings to their last saved state.



   .. py:method:: reset_to_factory_defaults() -> None

      Reset the values to the defaults.



   .. py:method:: save() -> bool

      Save any pending changes to the settings file.

      Returns:
          bool: True if file was written, False otherwise.



   .. py:method:: 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.



.. py:class:: UserSettings(file_name: Union[str, pathlib.Path])

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


   .. py:method:: 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.



   .. py:method:: 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.



   .. py:method:: delete_property(key: str) -> None

      Delete the given property key.

      Args:
          key: Name of the key to be deleted.



   .. py:method:: edit_property(key: str, val: Any) -> None

      Update the property key with given value.

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



   .. py:method:: 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.



   .. py:method:: get(key: str, default: Any = None) -> Any

      Dict-style alias for get_property.



   .. py:method:: get_data() -> Dict[str, Any]

      Return the whole current data.

      Returns:
          dict: Complete current data dictionary.



   .. py:method:: 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.



   .. py:method:: 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.



   .. py:method:: initialize(data: Optional[MutableMapping[str, Any]]) -> None

      Initialize the settings data.

      Args:
          data: Dictionary data to feed into the class.



   .. py:method:: is_settings_changed() -> bool

      Check if the settings changed since initialization.

      Returns:
          bool: True if settings have changed, False otherwise.



   .. py:method:: reset_settings() -> None

      Revert unsaved changes to the original state.



   .. py:method:: 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.



   .. py:method:: set_fallback(file_path: Union[str, pathlib.Path]) -> None

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

      Args:
          file_path: Path to a json file location.



   .. py:method:: update(data: Union[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.



   .. py:method:: use_fallback() -> None

      Use the fallback file.



   .. py:property:: keys
      :type: List[str]


      Return all keys in the current data.

      Returns:
          list: List of all keys.



   .. py:property:: properties
      :type: Dict[str, Any]


      Return the current dictionary data.

      Returns:
          dict: Dictionary of all properties.



   .. py:property:: values
      :type: List[Any]


      Return all values in the current data.

      Returns:
          list: List of all values.



.. py:data:: LOG