refactor(base): rename settings_manager utility

retspy_radar/base/utils/__init__.py

@@ -1,4 +1,4 @@
 from .console import console as console
 from .filesystem import filesystem as filesystem
-from .settings import settings as settings
+from .settings import settings_manager as settings_manager
 from .timing import timing as timing

retspy_radar/base/utils/settings.py

@@ -1,9 +1,44 @@
-from ..exceptions import InvalidConfigurationFileError, NotAFileError
+"""
+Módulo con funciones para cargar y guardar ajustes de configuración
+en un archivo.
+
+Las funciones de este módulo permiten cargar y guardar ajustes de
+configuración en un archivo JSON. Las funciones de carga y guardado
+de ajustes de configuración son `load` y `save`, respectivamente.
+
+La función `load` carga los ajustes de configuración desde un archivo
+JSON. Si el archivo no existe, se lanza una excepción. La función
+`save` guarda los ajustes de configuración en un archivo JSON.
+
+Las clases de este módulo son:
+
+    - `settings_manager`: Clase con utilidades para cargar y guardar
+        ajustes de configuración en un archivo.
+
+Las funciones de este módulo son:
+
+    - `load`: Carga los ajustes de configuración desde un archivo.
+    - `save`: Guarda los ajustes de configuración en un archivo.
+    - `_load_settings`: Carga los ajustes de configuración desde un
+        archivo.
+    - `_save_settings`: Guarda los ajustes de configuración en un
+        archivo.
+"""
+
+from ..exceptions import ConfigurationFileError, NotAFileError
 from ..settings import SettingsBasic
 from . import filesystem
 
+# Mensajes de error
+
+CONFIG_FILE_NOT_FOUND_ERROR = "No se encontró el archivo de configuración"
+CONFIG_FILE_OPEN_ERROR = "No se pudo abrir el archivo de configuración"
+CONFIG_FILE_PATH_ERROR = "La ruta del archivo de configuración no es válida"
+CONFIG_FILE_READ_ERROR = "No se pudo leer el archivo de configuración"
+CONFIG_FILE_WRITE_ERROR = "No se pudo escribir en el archivo de configuración"
 
-class settings:
+
+class settings_manager:  # pylint: disable=invalid-name
 
     @classmethod
     def load(
@@ -25,10 +60,9 @@ def load(
             Una instancia de la clase SettingsBasic con los ajustes
             cargados desde el archivo.
         """
-        if fail_if_not_exists:
-            return cls._load_settings(settings_path)
-
-        return cls._acquire_settings(settings_path)
+        return cls._load_settings(
+            settings_path, optional=not fail_if_not_exists
+        )
 
     @classmethod
     def save(cls, settings_path: str, settings: SettingsBasic) -> None:
@@ -46,111 +80,70 @@ def save(cls, settings_path: str, settings: SettingsBasic) -> None:
         cls._save_settings(settings_path, settings)
 
     @staticmethod
-    def _acquire_settings(settings_path: str) -> SettingsBasic:
+    def _load_settings(
+        settings_path: str, *, optional: bool = False
+    ) -> SettingsBasic:
         """
-        Carga los ajustes de configuración desde un archivo, si existe.
+        Carga los ajustes de configuración desde un archivo.
 
-        Intenta obtener los ajustes de configuración desde un archivo
-        JSON. Retorna un diccionario vacío si no se pudo acceder al
-        archivo o si el archivo no existe.
+        Obtiene los ajustes de configuración desde un archivo JSON.
+        Falla si no pudo acceder al archivo o si el archivo no tiene
+        formato JSON válido si `optional` es `False`. Si `optional` es
+        `True` y el archivo no existe, retorna un objeto vacío.
 
         Parameters
         ----------
         settings_path : str
             La ruta del archivo de configuración.
+        optional : bool, optional
+            Si se debe lanzar una excepción si el archivo no existe, por
+            defecto es `False`.
 
         Returns
         -------
         SettingsBasic
-            Una instancia de la clase SettingsBasic con los ajustes
-            cargados desde el archivo.
+            Una instancia de la clase `SettingsBasic` con los ajustes
+            cargados desde un archivo, o un objeto vacío si el archivo
+            no existe y `optional` es `True`.
 
         Raises
         ------
-        InvalidConfigurationFileError
+        ConfigurationFileError
             Si no se pudieron cargar los ajustes de configuración.
         """
         settings = SettingsBasic()
 
         try:
             # Verificar que la ruta del archivo de configuración sea
-            # válida: que sea un archivo legible si existiere
+            # válida: que la ruta exista y sea un archivo legible
+            # (optional=False) o que sea un archivo legible si existe
+            # (optional=True)
 
-            exists: bool = filesystem.ensure_optional_file(settings_path)
+            exists: bool = filesystem.ensure_readable_file(
+                settings_path, optional=optional
+            )
 
             if not exists:
                 return settings
 
             # Leer los ajustes de configuración del archivo JSON,
             # cargarlos en un diccionario y retornarlos
 
-            with open(settings_path, "r", encoding="utf-8") as file:
+            with open(
+                settings_path, "rt", encoding="utf-8", errors="strict"
+            ) as file:
                 settings.load(file)
 
             return settings
 
-        except (FileNotFoundError, NotAFileError) as exc:
-            raise InvalidConfigurationFileError(
-                f"La ruta del archivo de configuración no es válida: {exc}"
-            ) from exc
-
-        except (PermissionError, IOError) as exc:  # == OSError
-            raise InvalidConfigurationFileError(
-                "No se pudo acceder a la ruta del archivo de "
-                f"configuración: {exc}"
-            ) from exc
-
-    @staticmethod
-    def _load_settings(settings_path: str) -> SettingsBasic:
-        """
-        Carga los ajustes de configuración desde un archivo.
+        except FileNotFoundError as exc:
+            raise ConfigurationFileError(CONFIG_FILE_NOT_FOUND_ERROR) from exc
 
-        Intenta obtener los ajustes de configuración desde un archivo
-        JSON. Falla si no se puede acceder al archivo o si el archivo
-        no tiene formato JSON válido.
+        except (IsADirectoryError, NotAFileError) as exc:
+            raise ConfigurationFileError(CONFIG_FILE_OPEN_ERROR) from exc
 
-        Parameters
-        ----------
-        settings_path : str
-            La ruta del archivo de configuración.
-
-        Returns
-        -------
-        SettingsBasic
-            Una instancia de la clase SettingsBasic con los ajustes
-            cargados desde el archivo.
-
-        Raises
-        ------
-        InvalidConfigurationFileError
-            Si no se pudieron cargar los ajustes de configuración.
-        """
-        settings = SettingsBasic()
-
-        try:
-            # Verificar que la ruta del archivo de configuración sea
-            # válida: que la ruta exista y sea un archivo legible
-
-            filesystem.ensure_readable_file(settings_path)
-
-            # Leer los ajustes de configuración del archivo JSON,
-            # cargarlos en un diccionario y retornarlos
-
-            with open(settings_path, "r", encoding="utf-8") as file:
-                settings.load(file)
-
-            return settings
-
-        except (FileNotFoundError, NotAFileError) as exc:
-            raise InvalidConfigurationFileError(
-                f"La ruta del archivo de configuración no es válida: {exc}"
-            ) from exc
-
-        except (PermissionError, IOError) as exc:  # == OSError
-            raise InvalidConfigurationFileError(
-                "No se pudo acceder a la ruta del archivo de "
-                f"configuración: {exc}"
-            ) from exc
+        except (PermissionError, IOError) as exc:  # IOError == OSError
+            raise ConfigurationFileError(CONFIG_FILE_READ_ERROR) from exc
 
     @staticmethod
     def _save_settings(settings_path: str, settings: SettingsBasic) -> None:
@@ -169,7 +162,7 @@ def _save_settings(settings_path: str, settings: SettingsBasic) -> None:
 
         Raises
         ------
-        InvalidConfigurationFileError
+        ConfigurationFileError
             Si no se pudieron guardar las credenciales.
         """
         try:
@@ -181,21 +174,12 @@ def _save_settings(settings_path: str, settings: SettingsBasic) -> None:
             # Escribir el diccionario en un archivo de configuración
 
             with open(
-                settings_path, "w", encoding="utf-8", newline="\n"
+                settings_path, "wt", encoding="utf-8", newline="\n"
             ) as file:
                 settings.dump(file)
 
-        except TypeError:
-            raise InvalidConfigurationFileError(
-                "No se pudieron guardar las credenciales"
-            )
+        except (IsADirectoryError, NotAFileError) as exc:
+            raise ConfigurationFileError(CONFIG_FILE_PATH_ERROR) from exc
 
-        except (IsADirectoryError, NotAFileError):
-            raise InvalidConfigurationFileError(
-                "La ruta del archivo de credenciales no es válida"
-            )
-
-        except (PermissionError, IOError):  # == OSError
-            raise InvalidConfigurationFileError(
-                "No se pudo acceder al archivo de credenciales"
-            )
+        except (PermissionError, IOError) as exc:  # IOError == OSError
+            raise ConfigurationFileError(CONFIG_FILE_WRITE_ERROR) from exc