Merge pull request #11 from thewebscraping/feat/improve-image-optimizer

feat: improve image optimizer class, unittests

Author: thewebscraping

README.md

@@ -8,7 +8,7 @@ Features
 ----------
 - Multiple file uploads.
 - Drag and Drop UI.
-- MD5 checksum file.
+- MD5 checksum file: check, validate, handle duplicate files.
 - Chunked uploads: optimizing large file transfers.
 - Prevent uploading existing files with MD5 checksum.
 - Easy to use any models.
@@ -57,27 +57,26 @@ Change default config: `settings.py`
 
 ```python
 DJANGO_CHUNK_FILE_UPLOAD = {
-    "chunk_size": 1024 * 1024 * 2,  # # custom chunk size upload (default: 2MB).
-    "upload_to": "custom_folder/%Y/%m/%d",  # custom upload folder.
-    "is_metadata_storage": True,  # save file metadata,
+    "chunk_size": 1024 * 1024 * 2,  # # Custom chunk size upload (default: 2MB).
+    "upload_to": "uploads/%Y/%m/%d",  # Custom upload folder.
+    "is_metadata_storage": True,  # Save file metadata,
     "remove_file_on_update": True,
     "optimize": True,
-    "js": (
-        "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js",
-        "https://cdnjs.cloudflare.com/ajax/libs/spark-md5/3.0.2/spark-md5.min.js",
-        "https://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/toastr.min.js",
-    ),  # use cdn.
-    "css": (
-        "custom.css"
-     ),  # custom css path.
     "image_optimizer": {
         "quality": 82,
         "compress_level": 9,
         "max_width": 1024,
         "max_height": 720,
-        "to_webp": True,  # focus convert image to webp type.
+        "to_webp": True,  # Force convert image to webp type.
+        "remove_origin": True,  # Force to delete original image after optimization.
     },
-    "permission_classes": ("django_chunk_file_upload.permissions.AllowAny",)  # default: IsAuthenticated
+    "permission_classes": ("django_chunk_file_upload.permissions.AllowAny",),  # default: IsAuthenticated
+    # "js": (
+    #     "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js",
+    #     "https://cdnjs.cloudflare.com/ajax/libs/spark-md5/3.0.2/spark-md5.min.js",
+    #     "https://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/toastr.min.js",
+    # ),  # custom js, use cdn.
+    # "css": ("custom.css",),  # custom your css path.
 }
 
 ```
@@ -129,13 +128,13 @@ class CustomChunkedUploadView(ChunkedUploadView):
     form_class = YourForm
     permission_classes = (IsAuthenticated,)
 
-    # file_class = File  # file class
+    # file_class = File  # File handle class
     # file_status = app_settings.status  # default: PENDING (Used when using background task, you can change it to COMPLETED.)
     # optimize = True  # default: True
-    # remove_file_on_update = True  # update image on admin page.
-    # chunk_size = 1024 * 1024 * 2  # custom chunk size upload (default: 2MB).
-    # upload_to = "custom_folder/%Y/%m/%d"  # custom upload folder.
-    # template_name = "custom_template.html"  # custom template
+    # remove_file_on_update = True  # Update image on admin page.
+    # chunk_size = 1024 * 1024 * 2  # Custom chunk size upload (default: 2MB).
+    # upload_to = "custom_folder/%Y/%m/%d"  # Custom upload folder.
+    # template_name = "custom_template.html"  # Custom template
 
     # # Run background task like celery when upload is complete
     # def background_task(self, instance):
@@ -189,4 +188,33 @@ from django_chunk_file_upload.typed import (
 )
 ```
 
-This package is under development, only supports create view. There are also no features related to image optimization. Use at your own risk.
+### Image Optimizer
+Use image Optimizer feature for other modules
+
+```python
+from django_chunk_file_upload.optimize import ImageOptimizer
+from django_chunk_file_upload.app_settings import app_settings
+
+# Image optimize method: resize, crop, delete, convert and optimize
+# This method calls two other methods:
+#   ImageOptimizer.resize: resize image
+#   ImageOptimizer.crop: example get parameters from Cropperjs (https://github.com/fengyuanchen/cropperjs).
+image, path = ImageOptimizer.optimize(
+    fp='path/image.png',
+    filename=None,  # Rename the original file.
+    upload_to=None,  # Upload dir.
+    box=None,  # The crop rectangle, as a (left, upper, right, lower)-tuple to crop the image.
+    max_width =app_settings.image_optimizer.max_width,  # Max width of the image to resize.
+    max_height=app_settings.image_optimizer.max_height,  # Max height of the image to resize.
+    to_webp=True,  # Force convert image to webp type.
+    remove_origin =app_settings.image_optimizer.remove_origin,  # Force to delete original image after optimization.
+)
+```
+
+### UnitTests
+
+```shell
+python runtests.py
+```
+
+Note: This package is under development, only supports create view. There are also no features related to image optimization. Use at your own risk.

django_chunk_file_upload/__init__.py

@@ -1,5 +1,5 @@
 __title__ = "django-chunk-file-upload"
-__version__ = "1.0.2"
+__version__ = "1.0.3"
 __author__ = "Tu Pham"
 __license__ = "MIT"
 __copyright__ = "Copyright 2024 Tu Pham and contributors"

django_chunk_file_upload/app_settings.py

@@ -29,6 +29,7 @@ class _ImageSettings(_Settings):
     max_width: int = 1280
     max_height: int = 720
     to_webp: bool = True
+    remove_origin: bool = True
 
 
 @dataclass(kw_only=True)

django_chunk_file_upload/optimize.py

@@ -1,29 +1,81 @@
+from __future__ import annotations
+
+from io import BufferedReader, BytesIO
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from django.core.files.uploadedfile import (
+    InMemoryUploadedFile,
+    TemporaryUploadedFile,
+)
+from django.db.models.fields.files import FieldFile, ImageFieldFile
+
 from PIL import Image, UnidentifiedImageError
 from PIL.JpegImagePlugin import JpegImageFile
 from PIL.PngImagePlugin import PngImageFile
 from PIL.WebPImagePlugin import WebPImageFile
 
 from .app_settings import app_settings
 from .constants import TypeChoices
-from .utils import get_file_path
+from .utils import get_md5_checksum, get_paths, safe_remove_file
+
+
+if TYPE_CHECKING:
+    from .models import FileManager
+    from .typed import File
 
 
 class BaseOptimizer:
     """Base Optimizer"""
 
-    def __init__(self, instance, file, *args, **kwargs):
+    def __init__(self, instance: FileManager, file: File, *args, **kwargs):
         self._instance = instance
         self._file = file
 
     @property
-    def instance(self):
+    def instance(self) -> FileManager:
         return self._instance
 
     @property
-    def file(self):
+    def file(self) -> File:
         return self._file
 
-    def optimize(self):
+    @classmethod
+    def open(
+        cls, fp: str | bytes | BytesIO | BufferedReader | FieldFile | ImageFieldFile
+    ) -> None | BufferedReader | BytesIO:
+        return cls._open(fp)
+
+    @classmethod
+    def _open(
+        cls, fp: str | bytes | BytesIO | BufferedReader | FieldFile | ImageFieldFile
+    ) -> None | BufferedReader | BytesIO:
+        if isinstance(fp, str):
+            return open(fp, "rb")
+        if isinstance(fp, bytes):
+            fp = BytesIO(fp)
+        if isinstance(fp, (BytesIO, BufferedReader)):
+            return fp
+        if isinstance(fp, (FieldFile, ImageFieldFile)):
+            return fp.file.file
+
+    @classmethod
+    def close(cls, fp: BufferedReader | BytesIO | FieldFile | ImageFieldFile) -> None:
+        if isinstance(fp, (FieldFile, ImageFieldFile)):
+            fp.close()
+        else:
+            if fp and bool(getattr(fp, "closed", None) is False):
+                fp.close()
+
+    @classmethod
+    def checksum(cls, fp: str | bytes | InMemoryUploadedFile | TemporaryUploadedFile):
+        return get_md5_checksum(fp)
+
+    @classmethod
+    def get_identifier(cls, fp: str | bytes) -> UUID:
+        return UUID(hex=cls.checksum(fp))
+
+    def run(self):
         pass
 
 
@@ -41,68 +93,154 @@ def __init__(
     ):
         super().__init__(instance, file, *args, **kwargs)
 
-    def open(self) -> Image.Image | None:
+    def run(self):
+        image, path = self.optimize(self.file.save_path, upload_to=self.file._upload_to)
+        self.file.path = path
+        self.close(image)
+
+    @classmethod
+    def open(
+        cls, fp: str | bytes | BytesIO | BufferedReader | FieldFile | ImageFieldFile
+    ) -> None | Image.Image:
         try:
-            image = Image.open(self.file.file)
+            image = Image.open(cls._open(fp))
             return image
-        except UnidentifiedImageError:
+        except (UnidentifiedImageError, FileNotFoundError):
             pass
 
-    def close(self, image: Image.Image) -> None:
-        if isinstance(image, Image.Image):
-            image.close()
-
-    def optimize(self) -> None:
-        resized_img = self.open()
-        if not resized_img:
+    @classmethod
+    def close(
+        cls, fp: BufferedReader | BytesIO | Image.Image | FieldFile | ImageFieldFile
+    ) -> None:
+        if isinstance(fp, (Image.Image, FieldFile, ImageFieldFile)):
+            fp.close()
+        else:
+            super().close(fp)
+
+    @classmethod
+    def optimize(
+        cls,
+        fp: str | bytes | BytesIO | BufferedReader | FieldFile | ImageFieldFile,
+        *,
+        filename: str = None,
+        upload_to: str = None,
+        box: tuple[int, int, int, int] = None,
+        max_width: int = app_settings.image_optimizer.max_width,
+        max_height: int = app_settings.image_optimizer.max_height,
+        to_webp: bool = app_settings.image_optimizer.to_webp,
+        remove_origin: bool = app_settings.image_optimizer.remove_origin,
+    ) -> tuple[Image.Image, str]:
+        """Optimize the Image File
+
+        Args:
+          fp: File path or file object.
+          filename: Rename the original file.
+          upload_to: Upload dir.
+          box: The crop rectangle, as a (left, upper, right, lower)-tuple to crop the image.
+          max_width: Max width of the image to resize.
+          max_height: Max height of the image to resize.
+          to_webp: Force convert image to webp type.
+          remove_origin: Force to delete original image after optimization.
+
+        Returns:
+          The Tuple: PIL Image, Image file path location. If the file is not in the correct format, a tuple with the value (None, None) can be returned.
+        """
+
+        image = cls.open(fp)
+        path = None
+        if not isinstance(image, Image.Image):
             return
 
         fm, ext = None, None
-        if isinstance(resized_img, PngImageFile):
+        if isinstance(image, PngImageFile):
             fm, ext = "PNG", ".png"
-            resized_img = resized_img.convert("P", palette=Image.ADAPTIVE)
-        elif isinstance(resized_img, JpegImageFile):
+            image = image.convert("P", palette=Image.ADAPTIVE)
+        elif isinstance(image, JpegImageFile):
             fm, ext = "JPEG", ".jpg"
-        elif isinstance(resized_img, WebPImageFile):
+        elif isinstance(image, WebPImageFile):
             fm, ext = "WEBP", ".webp"
 
         if app_settings.image_optimizer.to_webp:
             fm, ext = "WEBP", ".webp"
 
-        if str(ext) in self._supported_file_types:
-            resized_img = self.resize(resized_img)
-            orig_save_path = self.file.save_path
-            filename = self.file.repl_filename + ext
-            self.file.path = get_file_path(filename, self.file._upload_to)
-            resized_img.save(
-                self.file.save_path,
+        if str(ext) in cls._supported_file_types:
+            image = cls.crop(image, box=box)
+            image = cls.resize(image, max_width, max_height)
+            if not filename and not isinstance(filename, str):
+                filename = str(cls.get_identifier(fp))
+
+            filename = filename + ext
+            save_path, path = get_paths(filename, upload_to=upload_to)
+            image.save(
+                save_path,
                 fm,
                 optimize=True,
                 quality=app_settings.image_optimizer.quality,
                 compress_level=app_settings.image_optimizer.compress_level,
             )
-            if orig_save_path != self.file.save_path:
-                self.instance.file.delete()
-                self.file.extension = ext
 
-        self.close(resized_img)
+            if remove_origin:
+                if isinstance(fp, (FieldFile, ImageFieldFile)):
+                    fp.delete(save=False)
+                else:
+                    origin_fp = (
+                        getattr(fp, "name", None)
+                        if isinstance(fp, (BytesIO, BufferedReader))
+                        else fp
+                    )
+                    if (
+                        origin_fp
+                        and isinstance(origin_fp, str)
+                        and path not in origin_fp
+                    ):
+                        safe_remove_file(origin_fp)
+        return image, path
+
+    @classmethod
+    def crop(
+        cls, image: Image.Image, box: tuple[int, int, int, int] = None
+    ) -> Image.Image:
+        """Crop an image
+
+        Args:
+          image: PIL image object.
+          box: The crop rectangle, as a (left, upper, right, lower)-tuple.
+
+        Returns:
+          Returns a rectangular region from this PIL image.
+        """
+        if image and box is not None:
+            return image.crop(box)
+        return image
+
+    @classmethod
+    def resize(
+        cls,
+        image: Image.Image,
+        width: int = app_settings.image_optimizer.max_width,
+        height: int = app_settings.image_optimizer.max_height,
+    ) -> Image.Image:
+        """Resize image to fit with Width and Height
+
+        Args:
+          image: PIL image object.
+          width: Max width to resize.
+          height: Max height to resize.
 
-    def resize(self, image: Image.Image) -> Image.Image:
-        """Resize image to fit with max width and max height"""
+        Returns:
+          PIL image after resizing
+        """
 
         w, h = image.size
         aspect_ratio = w / h
 
-        if (
-            w > app_settings.image_optimizer.max_width
-            or h > app_settings.image_optimizer.max_height
-        ):
+        if w > width or h > height:
             if aspect_ratio > 1:
-                nw = app_settings.image_optimizer.max_width
-                nh = int(app_settings.image_optimizer.max_width / aspect_ratio)
+                nw = width
+                nh = int(width / aspect_ratio)
             else:
-                nh = app_settings.image_optimizer.max_height
-                nw = int(app_settings.image_optimizer.max_height * aspect_ratio)
+                nh = height
+                nw = int(height * aspect_ratio)
 
             return image.resize((nw, nh), Image.LANCZOS)
         return image