bear-utils 0.7.20__py3-none-any.whl → 0.7.22__py3-none-any.whl

bear_utils/files/file_handlers/_base_file_handler.py

@@ -8,6 +8,12 @@ P = ParamSpec("P")
 R = TypeVar("R")
 
 
+def check_data_type(data: dict[str, Any] | str, valid_types: tuple[type, ...]) -> None:
+    """Check if the data is of a valid type for text files."""
+    if not isinstance(data, valid_types):
+        raise TypeError(f"Data must be one of {valid_types}, got {type(data)}")
+
+
 class FileHandler(ABC):
     """Abstract class for file handling with read, write, and present methods
 
@@ -19,6 +25,7 @@ class FileHandler(ABC):
     """
 
     valid_extensions: ClassVar[list[str]] = []
+    valid_types: ClassVar[tuple[type, ...]] = ()
 
     @classmethod
     def file_checker(cls, file_path: Path) -> bool:
@@ -33,7 +40,20 @@ class FileHandler(ABC):
         return file_path.suffix.lstrip(".") in cls.valid_extensions
 
     @classmethod
-    def ValidateFileType(cls, method: Callable[P, R]) -> Callable[P, R]:
+    def check_data_type(cls, data: Any) -> Any:
+        """Check if the data is of the correct type.
+
+        Args:
+            data: Data to check the type of
+
+        Returns:
+            bool: True if the data is of the correct type, False otherwise
+        """
+        if not isinstance(data, cls.valid_types):
+            raise TypeError(f"Data must be one of {cls.valid_types}, got {type(data)}")
+
+    @classmethod
+    def ValidateFileType(cls, method: Callable[P, R]) -> Callable[P, R]:  # noqa: N802 disable=invalid-name
         """Decorator to validate file type before executing a method.
 
         This decorator checks if the file is of the correct type before
@@ -50,9 +70,9 @@ class FileHandler(ABC):
         def wrapper(self: "FileHandler", file_path: Path, *args: Any, **kwargs: Any) -> R:
             if not self.file_checker(file_path):
                 raise ValueError(f"Invalid file type. Expected {self.valid_extensions}")
-            return method(self, file_path, *args, **kwargs)  # type: ignore
+            return method(self, file_path, *args, **kwargs)  # type: ignore[return-value]
 
-        return cast(Callable[P, R], wrapper)
+        return cast("Callable[P, R]", wrapper)
 
     @abstractmethod
     def read_file(self, file_path: Path) -> dict[str, Any] | str:

bear_utils/files/file_handlers/file_handler_factory.py

@@ -1,8 +1,15 @@
-import warnings
+"""Factory for creating and managing file handlers based on file types."""
+
 from pathlib import Path
 from typing import Any, cast
+import warnings
 
 from ._base_file_handler import FileHandler
+from .json_file_handler import JsonFileHandler
+from .log_file_handler import LogFileHandler
+from .toml_file_handler import TomlFileHandler
+from .txt_file_handler import TextFileHandler
+from .yaml_file_handler import YamlFileHandler
 
 
 class FileHandlerFactory:
@@ -44,20 +51,14 @@ class FileHandlerFactory:
         This method imports and registers all standard FileHandler implementations.
         """
         try:
-            from .json_file_handler import JsonFileHandler
-            from .log_file_handler import LogFileHandler
-            from .toml_file_handler import TomlFileHandler
-            from .txt_file_handler import TextFileHandler
-            from .yaml_file_handler import YamlFileHandler
-
-            self.register_handler(JsonFileHandler)
-            self.register_handler(TextFileHandler)
-            self.register_handler(YamlFileHandler)
-            self.register_handler(LogFileHandler)
-            self.register_handler(TomlFileHandler)
+            self.register_handler(handler_class=JsonFileHandler)
+            self.register_handler(handler_class=TextFileHandler)
+            self.register_handler(handler_class=YamlFileHandler)
+            self.register_handler(handler_class=LogFileHandler)
+            self.register_handler(handler_class=TomlFileHandler)
 
         except ImportError as e:
-            warnings.warn(f"Could not import all default handlers: {e}")
+            warnings.warn(f"Could not import all default handlers: {e}", UserWarning, stacklevel=2)
 
     def register_handler(self, handler_class: type[FileHandler]) -> None:
         """Register a handler class for its supported extensions.
@@ -91,25 +92,25 @@ class FileHandlerFactory:
         Raises:
             ValueError: If no file path is provided or stored, or if no handler exists for the file extension
         """
-        path = file_path or self._file_path
-        if not path:
+        path: Path | None = file_path or self._file_path
+        if path is None:
             raise ValueError("No file path provided or stored in factory")
 
-        if file_path:
+        if file_path is not None:
             self._file_path = file_path
             self._handler_instance = None
 
-        if self._handler_instance and not file_path:
+        if self._handler_instance and file_path is None:
             return self._handler_instance
 
-        extension = path.suffix.lstrip(".")
-        handler_class = self.get_handler_class(extension)
+        extension: str = path.suffix.lstrip(".")
+        handler_class: type[FileHandler] | None = self.get_handler_class(extension)
 
-        if not handler_class:
+        if handler_class is None:
             raise ValueError(f"No handler registered for extension: {extension}")
 
         handler = handler_class()
-        if not file_path:  # Only cache if using the stored path
+        if file_path is None:
             self._handler_instance = handler
 
         return handler
@@ -136,37 +137,36 @@ class FileHandlerFactory:
         match operation:
             case "read":
                 handler = self.get_handler_for_path(path)
-                return handler.read_file(cast(Path, path), **kwargs)
+                return handler.read_file(cast("Path", path), **kwargs)
             case "write":
                 if data is None:
                     raise ValueError("Data required for write operation")
                 handler = self.get_handler_for_path(path)
-                return handler.write_file(cast(Path, path), data, **kwargs)
+                return handler.write_file(cast("Path", path), data, **kwargs)
             case "present":
                 if data is None:
                     raise ValueError("Data required for present operation")
                 if path:
                     handler: FileHandler = self.get_handler_for_path(path)
-                else:
-                    if isinstance(data, dict):
-                        yaml_class = self.get_handler_class("yaml")
-                        if yaml_class:
-                            handler = yaml_class()
-                        else:
-                            raise ValueError("No handler available for dict data")
-                    elif isinstance(data, str):
-                        text_class = self.get_handler_class("txt")
-                        if text_class:
-                            handler = text_class()
-                        else:
-                            raise ValueError("No handler available for string data")
+                elif isinstance(data, dict):
+                    yaml_class = self.get_handler_class("yaml")
+                    if yaml_class:
+                        handler = yaml_class()
+                    else:
+                        raise ValueError("No handler available for dict data")
+                elif isinstance(data, str):
+                    text_class = self.get_handler_class("txt")
+                    if text_class:
+                        handler = text_class()
                     else:
-                        raise ValueError(f"Cannot determine handler for data type: {type(data)}")
+                        raise ValueError("No handler available for string data")
+                else:
+                    raise ValueError(f"Cannot determine handler for data type: {type(data)}")
                 return handler.present_file(data)
 
             case "info":
                 handler = self.get_handler_for_path(path)
-                return handler.get_file_info(cast(Path, path))
+                return handler.get_file_info(cast("Path", path))
             case _:
                 raise ValueError(f"Invalid operation: {operation}")
 

bear_utils/files/file_handlers/json_file_handler.py

@@ -1,44 +1,71 @@
+"""JsonFileHandler: A class for handling JSON files in Bear Utils."""
+
 import json
 from pathlib import Path
-from typing import Any, ClassVar
+from typing import Any, ClassVar, overload
 
-from ._base_file_handler import FileHandler
+from ._base_file_handler import FileHandler, check_data_type
 
 
 class JsonFileHandler(FileHandler):
     """Class for handling JSON files with read, write, and present methods"""
 
     valid_extensions: ClassVar[list[str]] = ["json"]
+    valid_types: ClassVar[tuple[type, ...]] = (dict, list, str)
 
     @FileHandler.ValidateFileType
     def read_file(self, file_path: Path, **kwargs) -> dict[str, Any]:
+        """Read a JSON file and return its content as a dictionary."""
         try:
-            super().read_file(file_path)
-            with open(file_path, "r", encoding="utf-8") as file:
+            super().read_file(file_path=file_path)
+            with open(file_path, encoding="utf-8") as file:
                 return json.load(file, **kwargs)
         except Exception as e:
-            raise ValueError(f"Error reading file: {e}")
+            raise ValueError(f"Error reading file: {e}") from e
+
+    @overload
+    def write_file(self, file_path: Path, data: str) -> None: ...
+
+    @overload
+    def write_file(self, file_path: Path, data: list[str]) -> None: ...
+
+    @overload
+    def write_file(self, file_path: Path, data: dict[str, Any], indent: int = 2, sort_keys: bool = False) -> None: ...
 
     @FileHandler.ValidateFileType
-    def write_file(self, file_path: Path, data: dict[str, Any] | str, **kwargs) -> None:
+    def write_file(
+        self,
+        file_path: Path,
+        data: dict[str, Any] | str,
+        indent: int = 2,
+        sort_keys: bool = False,
+        **_,
+    ) -> None:
+        """Write data to a JSON file."""
         try:
-            super().write_file(file_path, data)
-            with open(file_path, "w", encoding="utf-8") as file:
-                json.dump(
-                    data,
-                    file,
-                    indent=kwargs.pop("indent", 4),
-                    **kwargs,
-                )
+            super().write_file(file_path=file_path, data=data)
+            check_data_type(data=data, valid_types=self.valid_types)
+            data = self.present_file(data, indent=indent, sort_keys=sort_keys)
+            file_path.write_text(data=data, encoding="utf-8")
         except Exception as e:
-            raise ValueError(f"Error writing file: {e}")
+            raise ValueError(f"Error writing file: {e}") from e
+
+    @overload
+    def present_file(self, data: dict[str, Any], indent: int = 2, sort_keys: bool = False) -> str: ...
+
+    @overload
+    def present_file(self, data: str, **kwargs) -> str: ...
 
-    def present_file(self, data: dict[str, Any] | str, **kwargs) -> str:
+    def present_file(self, data: dict[str, Any] | str, indent: int = 2, sort_keys: bool = False, **_) -> str:
+        """Present data as a JSON string."""
         try:
-            return json.dumps(
-                data,
-                indent=kwargs.pop("indent", 4),
-                **kwargs,
-            )
+            if isinstance(data, list):
+                data = {"data": data}
+            elif isinstance(data, str):
+                try:
+                    data = json.loads(data)
+                except json.JSONDecodeError as e:
+                    raise ValueError(f"Invalid JSON string: {e}") from e
+            return json.dumps(data, indent=indent, sort_keys=sort_keys)
         except Exception as e:
-            raise ValueError(f"Error presenting file: {e}")
+            raise ValueError(f"Error presenting file: {e}") from e

bear_utils/files/file_handlers/log_file_handler.py

@@ -1,33 +1,40 @@
+"""Log File Handler Module"""
+
 from pathlib import Path
-from typing import Any, ClassVar
+from typing import Any, ClassVar, cast
 
-from ._base_file_handler import FileHandler
+from ._base_file_handler import FileHandler, check_data_type
 
 
 class LogFileHandler(FileHandler):
     """Class for handling .log files with read, write, and present methods"""
 
     valid_extensions: ClassVar[list[str]] = ["log"]
+    valid_types: ClassVar[tuple[type, ...]] = (str,)
 
     @FileHandler.ValidateFileType
     def read_file(self, file_path: Path) -> str:
+        """Read a log file and return its content as a string."""
         try:
             super().read_file(file_path)
-            with open(file_path, "r", encoding="utf-8") as file:
+            with open(file_path, encoding="utf-8") as file:
                 return file.read()
         except Exception as e:
-            raise ValueError(f"Error reading file: {e}")
+            raise ValueError(f"Error reading file: {e}") from e
 
     @FileHandler.ValidateFileType
-    def write_file(self, file_path: Path, data: dict[str, Any] | str, **kwargs) -> None:
+    def write_file(self, file_path: Path, data: dict[str, Any] | str, **_) -> None:
+        """Write data to a log file."""
         try:
-            super().write_file(file_path, data)
-            if not isinstance(data, str):
-                raise ValueError("Data must be a string for log files")
+            super().write_file(file_path=file_path, data=data)
+            check_data_type(data=data, valid_types=self.valid_types)
             with open(file_path, "w", encoding="utf-8") as file:
-                file.write(data)
+                file.write(cast("str", data))
         except Exception as e:
-            raise ValueError(f"Error writing file: {e}")
+            raise ValueError(f"Error writing file: {e}") from e
 
-    def present_file(self, data: dict[str, Any] | str, **kwargs) -> str:
-        raise NotImplementedError("Presenting log files is not implemented. Not needed.")
+    def present_file(self, data: dict[str, Any] | list[str] | str, **_) -> str:
+        """Present data as a string."""
+        if isinstance(data, dict):
+            data = "\n".join(f"{key}: {value}" for key, value in data.items())
+        return str(data)

bear_utils/files/file_handlers/toml_file_handler.py

@@ -1,3 +1,5 @@
+"""TOML File Handler Module"""
+
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, ClassVar
@@ -11,20 +13,23 @@ class TomlFileHandler(FileHandler):
     """Class for handling .toml files with read, write, and present methods"""
 
     valid_extensions: ClassVar[list[str]] = ["toml"]
+    valid_types: ClassVar[tuple[type, ...]] = (dict, str)
 
     @FileHandler.ValidateFileType
     def read_file(self, file_path: Path) -> dict:
+        """Read a TOML file and return its content as a dictionary."""
         try:
             super().read_file(file_path)
 
             return toml.load(file_path)
         except Exception as e:
-            raise ValueError(f"Error reading file: {e}")
+            raise ValueError(f"Error reading file: {e}") from e
 
     @FileHandler.ValidateFileType
     def write_file(self, file_path: Path, data: dict[str, Any] | str, **kwargs) -> None:
+        """Write data to a TOML file."""
         try:
-            super().write_file(file_path, data)
+            super().write_file(file_path=file_path, data=data)
 
             with open(file_path, "w", encoding="utf-8") as file:
                 if isinstance(data, dict):
@@ -32,10 +37,12 @@ class TomlFileHandler(FileHandler):
                 else:
                     file.write(data)
         except Exception as e:
-            raise ValueError(f"Error writing file: {e}")
+            raise ValueError(f"Error writing file: {e}") from e
 
-    def present_file(self, data: dict[str, Any] | str, **kwargs) -> str:
-        raise NotImplementedError("Presenting TOML files is not implemented. Not needed.")
+    def present_file(self, data: dict[str, Any] | str, **_) -> str:
+        """Present data as a string."""
+        # TODO: Actually implement this method to format TOML data nicely
+        return str(data)
 
 
 @dataclass
@@ -56,6 +63,7 @@ class PyProjectToml:
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "PyProjectToml":
+        """Create a PyProjectToml instance from a dictionary."""
         data = data.get("project", {})
         authors: dict = data.get("authors", {})[0]
         return cls(

bear_utils/files/file_handlers/txt_file_handler.py

@@ -1,34 +1,76 @@
+"""Text File Handler Module for .txt files"""
+
+import json
 from pathlib import Path
-from typing import Any, ClassVar
+from typing import Any, ClassVar, overload
 
-from ._base_file_handler import FileHandler
+from ._base_file_handler import FileHandler, check_data_type
 
 
 class TextFileHandler(FileHandler):
     """Class for handling .txt files with read, write, and present methods"""
 
     valid_extensions: ClassVar[list[str]] = ["txt"]
+    valid_types: ClassVar[tuple[type, ...]] = (str, dict, list)
 
     @FileHandler.ValidateFileType
     def read_file(self, file_path: Path) -> str:
+        """Read a text file and return its content as a string."""
         try:
             super().read_file(file_path)
-            with open(file_path, "r", encoding="utf-8") as file:
+            with open(file_path, encoding="utf-8") as file:
                 return file.read()
         except Exception as e:
-            raise ValueError(f"Error reading file: {e}")
+            raise ValueError(f"Error reading file: {e}") from e
+
+    @overload
+    def write_file(self, file_path: Path, data: str) -> None: ...
+
+    @overload
+    def write_file(self, file_path: Path, data: list[str]) -> None: ...
+
+    @overload
+    def write_file(self, file_path: Path, data: dict[str, Any], indent: int = 2, sort_keys: bool = False) -> None: ...
 
     @FileHandler.ValidateFileType
-    def write_file(self, file_path: Path, data: dict[str, Any] | str, **kwargs) -> None:
+    def write_file(
+        self,
+        file_path: Path,
+        data: dict[str, Any] | str,
+        indent: int = 2,
+        sort_keys: bool = False,
+        **_,
+    ) -> None:
+        """Write data to a text file."""
         try:
-            super().write_file(file_path, data)
-            if not isinstance(data, str):
-                raise ValueError("Data must be a string for text files")
-
-            with open(file_path, "w", encoding="utf-8") as file:
-                file.write(data)
+            super().write_file(file_path=file_path, data=data)
+            check_data_type(data, self.valid_types)
+            if isinstance(data, dict):
+                data = json.dumps(data, indent=indent, sort_keys=sort_keys)
+            elif isinstance(data, list):
+                data = "\n".join(data)
+            file_path.write_text(data=data, encoding="utf-8")
         except Exception as e:
-            raise ValueError(f"Error writing file: {e}")
+            raise ValueError(f"Error writing file: {e}") from e
+
+    def present_file(self, data: dict[str, Any] | list[str] | Any, **kwargs) -> str:
+        """Present data as a string.
+
+        This method converts the data to a string representation if it is a dictionary,
+
+        Args:
+            data (dict[str, Any] | str): Data to present
+        Returns:
+            str: String representation of the data
+        """
+        converted_data: str | None = None
+        if data is None:
+            raise ValueError("No data to present")
+        if isinstance(data, dict):
+            converted_data = json.dumps(data, indent=kwargs.get("indent", 2), sort_keys=kwargs.get("sort", False))
+        elif isinstance(data, list):
+            converted_data = "\n".join(data)
+        elif not isinstance(data, str):
+            raise TypeError("Data must be a string for text files")
 
-    def present_file(self, data: dict[str, Any] | str, **kwargs) -> str:
-        raise NotImplementedError("Presenting text files is not implemented. Not needed.")
+        return str(converted_data if isinstance(data, dict | list) else data)

bear_utils/files/file_handlers/yaml_file_handler.py

@@ -1,3 +1,5 @@
+"""YamlFileHandler class for handling YAML files."""
+
 from pathlib import Path
 from typing import Any, ClassVar
 
@@ -10,6 +12,7 @@ class YamlFileHandler(FileHandler):
     """Class for handling .yaml/.yml files with read, write, and present methods"""
 
     valid_extensions: ClassVar[list[str]] = ["yaml", "yml"]
+    valid_types: ClassVar[tuple[type, ...]] = (dict, str)
 
     @FileHandler.ValidateFileType
     def unsafe_read_file(self, file_path: Path, **kwargs) -> dict[str, Any]:
@@ -26,32 +29,35 @@ class YamlFileHandler(FileHandler):
             Dictionary containing the parsed YAML data
         """
         try:
-            super().read_file(file_path)
-            with open(file_path, "r", encoding="utf-8") as file:
-                return yaml.load(file, **kwargs)
+            super().read_file(file_path=file_path)
+            with open(file=file_path, encoding="utf-8") as file:
+                return yaml.load(stream=file, **kwargs)  # noqa: S506 # Using unsafe loader intentionally
         except Exception as e:
-            raise ValueError(f"Error reading file: {e}")
+            raise ValueError(f"Error reading file: {e}") from e
 
     @FileHandler.ValidateFileType
     def read_file(self, file_path: Path) -> dict[str, Any]:
+        """Read YAML file safely."""
         try:
-            super().read_file(file_path)
-            with open(file_path, "r", encoding="utf-8") as file:
-                return yaml.safe_load(file)
+            super().read_file(file_path=file_path)
+            with open(file=file_path, encoding="utf-8") as file:
+                return yaml.safe_load(stream=file)
         except Exception as e:
-            raise ValueError(f"Error reading file: {e}")
+            raise ValueError(f"Error reading file: {e}") from e
 
     @FileHandler.ValidateFileType
     def write_file(self, file_path: Path, data: dict[str, Any] | str, **kwargs) -> None:
+        """Write data to a YAML file."""
         try:
-            super().write_file(file_path, data)
-            with open(file_path, "w", encoding="utf-8") as file:
-                yaml.dump(data, file, default_flow_style=False, sort_keys=False, **kwargs)
+            super().write_file(file_path=file_path, data=data)
+            with open(file=file_path, mode="w", encoding="utf-8") as file:
+                yaml.dump(data, stream=file, default_flow_style=False, sort_keys=False, **kwargs)
         except Exception as e:
-            raise ValueError(f"Error writing file: {e}")
+            raise ValueError(f"Error writing file: {e}") from e
 
     def present_file(self, data: dict[str, Any] | str, **kwargs) -> str:
+        """Present data as a YAML string."""
         try:
             return yaml.dump(data, default_flow_style=False, sort_keys=False, **kwargs)
         except Exception as e:
-            raise ValueError(f"Error presenting file: {e}")
+            raise ValueError(f"Error presenting file: {e}") from e