From e81add491de63651242297e5cbba903c377f8499 Mon Sep 17 00:00:00 2001 From: "Nicklas H." Date: Mon, 19 Aug 2024 14:59:06 +0200 Subject: [PATCH] Begin adding detailed docstrings with doctests --- settings/base.py | 29 +++++++++++++++ settings/settings_manager.py | 72 ++++++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+) diff --git a/settings/base.py b/settings/base.py index 69184ec..84aa256 100644 --- a/settings/base.py +++ b/settings/base.py @@ -39,6 +39,35 @@ class SettingsManagerBase(ABC, Generic[T]): + """ + Base class for managing settings. + + This class provides functionality for managing settings data, including loading, saving, and sanitizing settings. + Supports type parameterization to help IDEs and type checkers infer which settings object is being used and how it can be used. + + args: + path (Optional[str]): The path to the settings file. Defaults to None. + autosave (bool): Flag indicating whether to automatically save the settings after any changes. Defaults to False. + auto_sanitize (bool): Flag indicating whether to automatically sanitize the settings after loading or saving. Defaults to False. + config_format (Optional[str]): The format of the settings file. Defaults to None. + default_settings (T): The default settings data. Must be provided. + read_path (Optional[str]): The path to read the settings file from. Defaults to None. + write_path (Optional[str]): The path to write the settings file to. Defaults to None. + autosave_on_exit (bool): Flag indicating whether to automatically save the settings when the program exits. Defaults to False. + auto_sanitize_on_load (bool): Flag indicating whether to automatically sanitize the settings after loading. Defaults to False. + auto_sanitize_on_save (bool): Flag indicating whether to automatically sanitize the settings before saving. Defaults to False. + ValueError: If default_settings is not provided. + + Attributes: + settings (T): The current settings data. + + Methods: + save(): Save the settings data to a file. + autosave(): A context manager that allows you to save the settings data to a file within a context block. + load(): Load the settings from the specified file into the internal data attribute. + sanitize_settings(): Sanitizes the settings data by applying the default settings and removing any invalid or unnecessary values. + """ + def __init__( self, path: Optional[str] = None, diff --git a/settings/settings_manager.py b/settings/settings_manager.py index f09b35f..185f175 100644 --- a/settings/settings_manager.py +++ b/settings/settings_manager.py @@ -23,6 +23,78 @@ def __init__(self, dict: dict) -> None: class SettingsManagerWithDataclass(SettingsManagerBase[T]): + """ + SettingsManager variant which uses a dataclass to store settings. + + This class provides functionality for managing settings data, including loading, saving, and sanitizing settings. + Supports type parameterization to help IDEs and type checkers infer which settings object is being used and how it can be used. + Refer to the Examples section for more information on how to use this class. + + args: + path (Optional[str]): The path to the settings file. Defaults to None. + autosave (bool): Flag indicating whether to automatically save the settings after any changes. Defaults to False. + auto_sanitize (bool): Flag indicating whether to automatically sanitize the settings after loading or saving. Defaults to False. + config_format (Optional[str]): The format of the settings file. Defaults to None. + default_settings (T): The default settings data. Must be provided. + read_path (Optional[str]): The path to read the settings file from. Defaults to None. + write_path (Optional[str]): The path to write the settings file to. Defaults to None. + autosave_on_exit (bool): Flag indicating whether to automatically save the settings when the program exits. Defaults to False. + auto_sanitize_on_load (bool): Flag indicating whether to automatically sanitize the settings after loading. Defaults to False. + auto_sanitize_on_save (bool): Flag indicating whether to automatically sanitize the settings before saving. Defaults to False. + ValueError: If default_settings is not provided. + + Attributes: + settings (T): The current settings data. + + Methods: + save(): Save the settings data to a file. + autosave(): A context manager that allows you to save the settings data to a file within a context block. + load(): Load the settings from the specified file into the internal data attribute. + sanitize_settings(): Sanitizes the settings data by applying the default settings and removing any invalid or unnecessary values. + + Examples: + ``` + >>> from dataclasses import dataclass, field + + >>> @dataclass + ... class MySection: + ... section_key: str = field(default="section_value") + + >>> @dataclass + ... class MySettings: + ... key: str = field(default="value") + ... section: MySection = field(default_factory=MySection) + + >>> settings_manager: SettingsManagerWithDataclass[MySettings] = SettingsManagerWithDataclass( + ... path="settings.json", + ... default_settings=MySettings() + ... ) + + # The class already automatically loads the settings data from the file, but it can be done manually as well: + >>> settings_manager.load() + + # Access the settings data directly: + >>> print(settings_manager.settings.key) + value + + >>> print(settings_manager.settings.section.section_key) + section_value + + # Modify the settings data: + >>> settings_manager.settings.key = "new_value" + >>> settings_manager.settings.section.section_key = "new_section_value" + + # Save the modified settings data to the file: + >>> settings_manager.save() + + # Using the autosave context manager, you can mimic the behavior of autosaving after any changes: + >>> with settings_manager.autosave(): + ... settings_manager.settings.key = "new_value" + ... settings_manager.settings.section.section_key = "new_section_value" + + ``` + """ + def _to_dict(self, obj: "DataclassInstance") -> Dict[str, Any]: """ Converts the settings object to a dictionary using dataclasses.asdict.