Upload file_manager.py

storage/files/file_manager.py

@@ -0,0 +1,152 @@
+"""
+file_manager.py
+
+This module provides the FileManager class, a high-level interface for managing
+files and directories inside a specified media folder. It centralizes common
+operations such as reading, writing, listing, copying, moving, and deleting files,
+ensuring that all actions are safely constrained within the defined root directory.
+The class is designed to simplify file handling logic in larger applications by
+offering a consistent, validated, and extensible API for filesystem interactions.
+"""
+
+from pathlib import Path
+
+class FileManager:
+    """
+    FileManager is a utility class that encapsulates common filesystem operations
+    within a defined media directory. It ensures that all file manipulations remain
+    inside the configured root folder and provides helper methods to interact with
+    files and subdirectories in a structured, safe, and predictable manner.
+
+    Typical use cases include managing uploaded media, performing batch operations
+    on directory contents, and abstracting filesystem complexity behind a clean API.
+    """
+
+    def __init__(self, media_folder: Path):
+        """
+        Initialize the FileManager with a specific root directory for all file
+        operations.
+
+        Parameters
+        ----------
+        media_folder : Path
+            The base directory where all file and folder operations will be performed.
+            It must be a valid filesystem path. If the directory does not exist, the
+            instance will attempt to create it automatically.
+
+        Raises
+        ------
+        ValueError
+            If the provided media_folder path is not a valid directory or cannot be
+            created.
+        """
+        self.media_folder = Path(media_folder)
+
+        if not self.media_folder.exists():
+            try:
+                self.media_folder.mkdir(parents=True)
+            except Exception as exc:
+                raise ValueError(
+                    f"Unable to create media folder at: {self.media_folder}"
+                ) from exc
+
+        if not self.media_folder.is_dir():
+            raise ValueError(f"Media folder is not a directory: {self.media_folder}")
+    
+
+    def upload_file(self, file_handler, destination: Path):
+        """
+        Upload a file to a target destination inside the media folder.
+
+        This method takes a file-like object and writes its contents to the
+        specified destination within the media folder. The method ensures the path
+        remains inside the media folder and creates necessary directories. It
+        returns a structured response indicating whether the operation succeeded
+        or failed, along with any relevant error message.
+
+        Parameters
+        ----------
+        file_handler : file-like object
+            A file-like object opened in binary mode that provides a `.read()` method.
+        destination : Path
+            The relative or absolute path (within the media folder) where the file
+            should be saved.
+
+        Returns
+        -------
+        dict
+            A dictionary with:
+            - "operation_success" (bool): True if the file was saved successfully.
+            - "error" (str): An empty string on success, or the error message on failure.
+
+        Raises
+        ------
+        None
+            Any exceptions are captured and returned inside the result dictionary.
+        """
+        try:
+            destination = self.media_folder / destination
+            destination = destination.resolve()
+
+            # Ensure the destination lies inside the media folder
+            if self.media_folder not in destination.parents:
+                return {
+                    "operation_success": False,
+                    "error": "Destination path is outside the media folder."
+                }
+
+            # Create parent directories if needed
+            destination.parent.mkdir(parents=True, exist_ok=True)
+
+            with open(destination, "wb") as f:
+                f.write(file_handler.read())
+
+            return {"operation_success": True, "error": ""}
+
+        except Exception as exc:
+            return {
+                "operation_success": False,
+                "error": str(exc)
+            }
+
+    def get_file(self, file_path: Path):
+        """
+        Retrieve a file inside the media folder and return an open file handler.
+
+        This method receives a path pointing to a file expected to be located
+        inside the media folder. If the file exists and is valid, the method
+        returns a file handler opened in binary read mode. If the file does not
+        exist or the resolved path escapes the media folder, the method returns
+        None.
+
+        Parameters
+        ----------
+        file_path : Path
+            The relative or absolute path to the file within the media folder.
+
+        Returns
+        -------
+        file object or None
+            A file handler opened in 'rb' mode if the file exists and is accessible.
+            Returns None if the file does not exist or the path is invalid.
+
+        Raises
+        ------
+        None
+            All exceptions are handled internally and result in returning None.
+        """
+        try:
+            target = self.media_folder / file_path
+            target = target.resolve()
+
+            # Ensure the resolved path is inside the media folder
+            if self.media_folder not in target.parents:
+                return None
+
+            if not target.exists() or not target.is_file():
+                return None
+
+            return open(target, "rb")
+
+        except Exception:
+            return None