bear-utils 0.0.1__py3-none-any.whl

bear_utils/files/file_handlers/_base_file_handler.py

@@ -0,0 +1,107 @@
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from functools import wraps
+from pathlib import Path
+from typing import Any, ClassVar, ParamSpec, TypeVar, cast
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class FileHandler(ABC):
+    """Abstract class for file handling with read, write, and present methods
+
+    :attr ext str: File extension to check for.
+    :method file_checker: Class method to check if file is of correct type.
+    :method read_file: Read file method.
+    :method write_file: Write file method.
+    :method present_file: Present file method.
+    """
+
+    valid_extensions: ClassVar[list[str]] = []
+    valid_types: ClassVar[tuple[type, ...]] = ()
+
+    @classmethod
+    def file_checker(cls, file_path: Path) -> bool:
+        """Check if the file is of the correct type.
+
+        Args:
+            file_path: Path to the file
+
+        Returns:
+            bool: True if the file is of the correct type, False otherwise
+        """
+        return file_path.suffix.lstrip(".") in cls.valid_extensions
+
+    @classmethod
+    def check_data_type(cls, data: dict[str, Any] | str, valid_types: tuple[type, ...]) -> None:
+        """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, valid_types):
+            raise TypeError(f"Data must be one of {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
+        executing the method. If not, it raises a ValueError.
+
+        Args:
+            method: Method to decorate
+
+        Returns:
+            Decorated method
+        """
+
+        @wraps(method)
+        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-value]
+
+        return cast("Callable[P, R]", wrapper)
+
+    @abstractmethod
+    def read_file(self, file_path: Path) -> dict[str, Any] | str:
+        if not file_path.exists():
+            raise ValueError(f"File does not exist: {file_path}")
+
+    @abstractmethod
+    def write_file(self, file_path: Path, data: dict[str, Any] | str, **kwargs) -> None:
+        if not file_path.parent.exists():
+            if kwargs.get("mkdir", False):
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+            else:
+                raise ValueError(f"Directory does not exist: {file_path.parent}. Set mkdir=True to create it.")
+
+    @abstractmethod
+    def present_file(self, data: dict[str, Any] | str) -> str: ...
+
+    @staticmethod
+    def get_file_info(file_path: Path) -> dict[str, Any]:
+        """Get information about a file.
+
+        Args:
+            file_path: Path to the file
+
+        Returns:
+            Dictionary with file information
+        """
+        if not file_path.exists():
+            raise ValueError(f"File does not exist: {file_path}")
+
+        return {
+            "path": file_path,
+            "name": file_path.name,
+            "extension": file_path.suffix,
+            "size": file_path.stat().st_size if file_path.exists() else 0,
+            "is_file": file_path.is_file() if file_path.exists() else False,
+            "modified": file_path.stat().st_mtime if file_path.exists() else None,
+        }

bear_utils/files/file_handlers/file_handler_factory.py

@@ -0,0 +1,280 @@
+"""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:
+    """Factory class to create and manage FileHandler instances based on file types.
+
+    This factory maintains state about the current file path and can create appropriate
+    handlers for different file types.
+    """
+
+    def __init__(self, file_path: Path | None = None) -> None:
+        """Initialize the factory with an optional file path.
+
+        Args:
+            file_path: Optional Path to the file to handle
+        """
+        self._file_path: Path | None = file_path
+        self._handler_registry: dict[str, type[FileHandler]] = {}
+        self._handler_instance: FileHandler | None = None
+        self._register_default_handlers()
+
+    @property
+    def file_path(self) -> Path | None:
+        """Get the current file path."""
+        return self._file_path
+
+    @file_path.setter
+    def file_path(self, path: Path) -> None:
+        """Set the current file path and reset the handler instance.
+
+        Args:
+            path: New file path to set
+        """
+        self._file_path = path
+        self._handler_instance = None
+
+    def _register_default_handlers(self) -> None:
+        """Register all default handlers from the package.
+
+        This method imports and registers all standard FileHandler implementations.
+        """
+        try:
+            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}", UserWarning, stacklevel=2)
+
+    def register_handler(self, handler_class: type[FileHandler]) -> None:
+        """Register a handler class for its supported extensions.
+
+        Args:
+            handler_class: The FileHandler class to register
+        """
+        for ext in handler_class.valid_extensions:
+            self._handler_registry[ext] = handler_class
+
+    def get_handler_class(self, extension: str) -> type[FileHandler] | None:
+        """Get the handler class for a specific extension.
+
+        Args:
+            extension: File extension (without the dot)
+
+        Returns:
+            FileHandler class for the extension or None if not found
+        """
+        return self._handler_registry.get(extension)
+
+    def get_handler_for_path(self, file_path: Path | None = None) -> FileHandler:
+        """Get or create a handler instance for the given path or the current path.
+
+        Args:
+            file_path: Path to get handler for (uses stored path if None)
+
+        Returns:
+            Appropriate FileHandler instance
+
+        Raises:
+            ValueError: If no file path is provided or stored, or if no handler exists for the file extension
+        """
+        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 is not None:
+            self._file_path = file_path
+            self._handler_instance = None
+
+        if self._handler_instance and file_path is None:
+            return self._handler_instance
+
+        extension: str = path.suffix.lstrip(".")
+        handler_class: type[FileHandler] | None = self.get_handler_class(extension)
+
+        if handler_class is None:
+            raise ValueError(f"No handler registered for extension: {extension}")
+
+        handler = handler_class()
+        if file_path is None:
+            self._handler_instance = handler
+
+        return handler
+
+    def handle_file(self, operation: str, file_path: Path | None = None, data: Any = None, **kwargs) -> Any:
+        """Handle file operations using the appropriate handler.
+
+        Args:
+            operation: Operation to perform ('read', 'write', 'present', 'info')
+            file_path: Path to the file (uses stored path if None)
+            data: Data for write operations
+            **kwargs: Additional arguments for the operation
+
+        Returns:
+            Result of the operation
+
+        Raises:
+            ValueError: If an invalid operation is specified
+        """
+        path: Path | None = file_path or self._file_path
+        if not path and operation != "present":
+            raise ValueError("File path required for this operation")
+
+        match operation:
+            case "read":
+                handler = self.get_handler_for_path(path)
+                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)
+            case "present":
+                if data is None:
+                    raise ValueError("Data required for present operation")
+                if path:
+                    handler: FileHandler = self.get_handler_for_path(path)
+                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("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))
+            case _:
+                raise ValueError(f"Invalid operation: {operation}")
+
+    def read(self, file_path: Path | None = None, **kwargs) -> Any:
+        """Read a file using the appropriate handler.
+
+        Args:
+            file_path: Path to read (uses stored path if None)
+            **kwargs: Additional arguments for read_file
+
+        Returns:
+            File contents
+        """
+        return self.handle_file("read", file_path, **kwargs)
+
+    def write(self, data: dict | str, file_path: Path | None = None, **kwargs) -> None:
+        """Write to a file using the appropriate handler.
+
+        Args:
+            data: Data to write
+            file_path: Path to write to (uses stored path if None)
+            **kwargs: Additional arguments for write_file
+        """
+        return self.handle_file("write", file_path, data, **kwargs)
+
+    def present(self, data: dict | str, file_path: Path | None = None) -> str:
+        """Present data using the appropriate handler.
+
+        Args:
+            data: Data to present
+            file_path: Optional path to determine format (uses stored path if None)
+
+        Returns:
+            String representation of the data
+        """
+        return self.handle_file("present", file_path, data)
+
+    def get_info(self, file_path: Path | None = None) -> dict[str, Any]:
+        """Get information about a file.
+
+        Args:
+            file_path: Path to get info for (uses stored path if None)
+
+        Returns:
+            Dictionary with file information
+        """
+        return self.handle_file("info", file_path)
+
+    def convert(self, source_path: Path, target_path: Path, **kwargs) -> None:
+        """Convert a file from one format to another.
+
+        Args:
+            source_path: Path to the source file
+            target_path: Path to the target file
+            **kwargs: Additional arguments for read_file and write_file
+        """
+        source_handler = self.get_handler_for_path(source_path)
+        data = source_handler.read_file(source_path, **kwargs)
+
+        target_handler = self.get_handler_for_path(target_path)
+        target_handler.write_file(target_path, data, **kwargs)
+
+
+_default_factory = FileHandlerFactory()
+
+
+def get_handler_for_file(file_path: Path) -> FileHandler:
+    """Get a handler for the given file path.
+
+    Args:
+        file_path: Path to the file
+
+    Returns:
+        Appropriate FileHandler instance
+    """
+    return _default_factory.get_handler_for_path(file_path)
+
+
+def read_file(file_path: Path, **kwargs) -> Any:
+    """Read a file using the appropriate handler.
+
+    Args:
+        file_path: Path to the file
+        **kwargs: Additional arguments for read_file
+
+    Returns:
+        File contents
+    """
+    return _default_factory.read(file_path, **kwargs)
+
+
+def write_file(file_path: Path, data: Any, **kwargs) -> None:
+    """Write to a file using the appropriate handler.
+
+    Args:
+        file_path: Path to the file
+        data: Data to write
+        **kwargs: Additional arguments for write_file
+    """
+    return _default_factory.write(data, file_path, **kwargs)
+
+
+def convert_file(source_path: Path, target_path: Path, **kwargs) -> None:
+    """Convert a file from one format to another.
+
+    Args:
+        source_path: Path to the source file
+        target_path: Path to the target file
+        **kwargs: Additional arguments for read_file and write_file
+    """
+    return _default_factory.convert(source_path, target_path, **kwargs)

bear_utils/files/file_handlers/json_file_handler.py

@@ -0,0 +1,71 @@
+"""JsonFileHandler: A class for handling JSON files in Bear Utils."""
+
+import json
+from pathlib import Path
+from typing import Any, ClassVar, overload
+
+from ._base_file_handler import FileHandler
+
+
+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=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}") 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,
+        indent: int = 2,
+        sort_keys: bool = False,
+        **_,
+    ) -> None:
+        """Write data to a JSON file."""
+        try:
+            super().write_file(file_path=file_path, data=data)
+            self.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}") 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, indent: int = 2, sort_keys: bool = False, **_) -> str:
+        """Present data as a JSON string."""
+        try:
+            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}") from e

bear_utils/files/file_handlers/log_file_handler.py

@@ -0,0 +1,40 @@
+"""Log File Handler Module"""
+
+from pathlib import Path
+from typing import Any, ClassVar, cast
+
+from ._base_file_handler import FileHandler
+
+
+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, encoding="utf-8") as file:
+                return file.read()
+        except Exception as e:
+            raise ValueError(f"Error reading file: {e}") from e
+
+    @FileHandler.ValidateFileType
+    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=file_path, data=data)
+            self.check_data_type(data=data, valid_types=self.valid_types)
+            with open(file_path, "w", encoding="utf-8") as file:
+                file.write(cast("str", data))
+        except Exception as e:
+            raise ValueError(f"Error writing file: {e}") from e
+
+    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

@@ -0,0 +1,76 @@
+"""TOML File Handler Module"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+import toml
+
+from ._base_file_handler import FileHandler
+
+
+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}") 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=file_path, data=data)
+            self.check_data_type(data=data, valid_types=self.valid_types)
+            with open(file_path, "w", encoding="utf-8") as file:
+                if isinstance(data, dict):
+                    toml.dump(data, file, **kwargs)
+                else:
+                    file.write(data)
+        except Exception as e:
+            raise ValueError(f"Error writing file: {e}") from e
+
+    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
+class PyProjectToml:
+    """Dataclass for handling pyproject.toml files"""
+
+    name: str
+    version: str
+    description: str | None = None
+    author_name: str | None = None
+    author_email: str | None = None
+    dependencies: list[str] | None = None
+
+    def __post_init__(self):
+        if self.dependencies:
+            self.dependencies = [dep.split(" ")[0] for dep in self.dependencies if isinstance(dep, str)]
+            self.dependencies = [dep.split(">=")[0] for dep in self.dependencies]
+
+    @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(
+            name=data.get("name", ""),
+            version=data.get("version", ""),
+            description=data.get("description"),
+            author_name=authors.get("name") if authors else None,
+            author_email=authors.get("email") if authors else None,
+            dependencies=data.get("dependencies", []),
+        )

bear_utils/files/file_handlers/txt_file_handler.py

@@ -0,0 +1,76 @@
+"""Text File Handler Module for .txt files"""
+
+import json
+from pathlib import Path
+from typing import Any, ClassVar, overload
+
+from ._base_file_handler import FileHandler
+
+
+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, encoding="utf-8") as file:
+                return file.read()
+        except Exception as 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,
+        indent: int = 2,
+        sort_keys: bool = False,
+        **_,
+    ) -> None:
+        """Write data to a text file."""
+        try:
+            super().write_file(file_path=file_path, data=data)
+            self.check_data_type(data=data, valid_types=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}") 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")
+
+        return str(converted_data if isinstance(data, dict | list) else data)