absfuyu 5.12.1__py3-none-any.whl → 5.13.0__py3-none-any.whl

absfuyu/extra/picture.py

@@ -0,0 +1,386 @@
+"""
+Absfuyu: Picture
+----------------
+Image converter
+
+
+Version: 5.13.0
+Date updated: 02/11/2025 (dd/mm/yyyy)
+"""
+
+# Module level
+# ---------------------------------------------------------------------------
+__all__ = ["ImgConverter"]
+
+
+# Library
+# ---------------------------------------------------------------------------
+import logging
+import shutil
+from functools import partial
+from pathlib import Path
+from typing import Any, Literal, Protocol
+
+from absfuyu.core.dummy_func import tqdm as tqdm_base
+from absfuyu.util.path import DirectorySelectMixin
+
+try:
+    from PIL import Image
+    from PIL.ImageFile import ImageFile
+except ImportError:
+    from subprocess import run
+
+    from absfuyu.config import ABSFUYU_CONFIG
+
+    if ABSFUYU_CONFIG._get_setting("auto-install-extra").value:  # type: ignore
+        cmd = "python -m pip install -U absfuyu[pic]".split()
+        run(cmd)
+    else:
+        raise SystemExit("This feature is in absfuyu[pic] package")  # noqa: B904
+
+try:
+    from pillow_heif import register_heif_opener  # type: ignore
+except ImportError:
+    from absfuyu.core.dummy_func import dummy_function as register_heif_opener
+register_heif_opener()
+
+
+# Setup
+# ---------------------------------------------------------------------------
+tqdm = partial(tqdm_base, unit_scale=True, dynamic_ncols=True)
+SupportedImageExtension = Literal[".jpg", ".jpeg", ".png", ".webp"]
+
+
+# Exporter/Converter
+# ---------------------------------------------------------------------------
+class SupportImageConverter(Protocol):
+    # Callable[[ImageFile, Path], None]
+    def __call__(self, image: ImageFile, path: Path, **params: Any) -> None: ...
+
+
+def _image_convert_default(image: ImageFile, path: Path, **params: Any) -> None:
+    """
+    Default convert image function
+
+    Parameters
+    ----------
+    image : ImageFile
+        Image file
+
+    path : Path
+        Path to export
+    """
+    image.save(path, **params)
+
+
+def _image_convert_webp(image: ImageFile, path: Path, **params: Any) -> None:
+    """
+    Convert image to .webp format (with custom settings)
+
+    Parameters
+    ----------
+    image : ImageFile
+        Image file
+
+    path : Path
+        Path to export
+    """
+    image.save(
+        path,
+        format="WEBP",
+        lossless=True,
+        quality=100,
+        alpha_quality=100,
+        method=4,
+        exact=False,  # If true, preserve the transparent RGB values. Otherwise, discard invisible RGB values for better compression. Defaults to false.
+        **params,
+    )
+
+
+def _image_convert_png(image: ImageFile, path: Path, **params: Any) -> None:
+    """
+    Convert image to .png format (with custom settings)
+
+    Parameters
+    ----------
+    image : ImageFile
+        Image file
+
+    path : Path
+        Path to export
+    """
+    image.save(
+        path,
+        format="PNG",
+        # optimize=True,
+        compress_level=6,
+        **params,
+    )
+
+
+def _image_convert_jpg(image: ImageFile, path: Path, **params: Any) -> None:
+    """
+    Convert image to .jpg format (with custom settings)
+
+    Parameters
+    ----------
+    image : ImageFile
+        Image file
+
+    path : Path
+        Path to export
+    """
+    image.convert("RGB")
+    image.save(
+        path,
+        format="JPG",
+        optimize=True,
+        keep_rgb=True,
+        **params,
+    )
+
+
+# Class
+# ---------------------------------------------------------------------------
+class ImgConverter(DirectorySelectMixin):
+    _IMAGE_CONVERTER: dict[str, SupportImageConverter] = {
+        "default": _image_convert_default,
+        ".webp": _image_convert_webp,
+        ".png": _image_convert_png,
+        ".jpg": _image_convert_jpg,
+        ".jpeg": _image_convert_jpg,
+    }
+
+    def __init__(
+        self,
+        source_path: str | Path,
+        create_if_not_exist: bool = False,
+        backup_dir_name: str | None = None,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        super().__init__(source_path, create_if_not_exist)
+
+        # Supported image extension
+        self._supported_image_format = [".png", ".jpeg", ".jpg", ".webp"]
+        self._register_heif_format()
+
+        # Backup
+        if backup_dir_name is None:
+            backup_dir_name = "ZZZ_Backup"
+        self.backup_path = self.source_path.joinpath(backup_dir_name)
+
+        # Not available yet
+        self.logger = logger
+
+    # Extra format
+    @classmethod
+    def install_all_extension(cls) -> None:
+        """
+        Install all extra package to unlock all features
+        """
+        extra = [
+            "pillow_heif",  # heic support
+            "defusedxml",  # xmp
+            "olefile",
+        ]
+        base = ["pip", "install", "-U"]
+        base.extend(extra)
+
+        import subprocess
+
+        subprocess.run(base)
+
+    def _register_heif_format(self) -> None:
+        """
+        Try to register .heif format
+
+        ``pillow_heif`` package required
+        """
+        try:
+            from pillow_heif import register_heif_opener  # type: ignore
+
+            self._supported_image_format.append(".heic")
+            self._supported_image_format.append(".heif")
+        except ImportError:
+            pass
+
+    @property
+    def supported_image_format(self) -> list[str]:
+        """
+        Supported image format
+
+        Returns
+        -------
+        list[str]
+            Supported image format
+        """
+        return self._supported_image_format
+
+    @classmethod
+    def add_converter(cls, format_name: str, converter_func: SupportImageConverter) -> None:
+        """
+        Add image converter function to a format
+
+        Parameters
+        ----------
+        format_name : str
+            Image format name
+
+        converter_func : SupportImageConverter
+            Converter function
+
+
+        Example:
+        --------
+        >>> ImgConverter.add_converter(".png", convert_to_png)
+        """
+        cls._IMAGE_CONVERTER[format_name] = converter_func
+
+    # Support
+    def _make_suffix_selection(self, exclude_suffix: str) -> tuple[str, ...]:
+        """
+        Make suffix selection (exclude the image with converted to suffix)
+
+        Parameters
+        ----------
+        exclude_suffix : str
+            Converted to suffix
+
+        Returns
+        -------
+        tuple[str, ...]
+            Suffix selection
+        """
+        out = []
+        for x in self._supported_image_format:
+            if x.lower() == exclude_suffix.lower():
+                continue
+            out.append(x.lower())
+            out.append(x.upper())
+        return tuple(out)
+
+    def _make_backup(self, src_file: Path) -> None:
+        dest = self.backup_path.joinpath(src_file.name)
+        shutil.move(src_file, dest)
+
+    # Convert
+    def _image_convert_legacy(
+        self,
+        path: Path,
+        to_extension: SupportedImageExtension | None = None,
+        lossless: bool = True,
+        compression_level: int | None = None,
+    ) -> None:
+        """
+        Convert image to other format (settings are mostly for .webp format)
+
+        Parameters
+        ----------
+        path : Path
+            Path to image
+
+        to_extension : SupportedImageExtension | None, optional
+            New image format, by default None
+
+        lossless : bool, optional
+            Lossless compression, by default True
+
+        compression_level : int | None, optional
+            Compression level, by default None
+        """
+        # Load image
+        new_suffix = path.suffix if to_extension is None else to_extension
+        image = Image.open(path)
+
+        # Extract metadata
+        # exif = image.info.get("exif")
+        # xmp = image.getxmp()
+        # icc_profile = image.info.get("icc_profile")
+        xmp = image.info.get("xmp")
+        exif = image.getexif()
+        icc_profile = image.info.get("icc_profile")
+        # print(image.info.keys())
+
+        # Save
+        image.save(
+            path.with_suffix(new_suffix),
+            format=new_suffix[1:].upper(),
+            lossless=lossless,
+            quality=100,
+            alpha_quality=100,
+            method=(4 if compression_level is None else compression_level),
+            exact=False,  # If true, preserve the transparent RGB values. Otherwise, discard invisible RGB values for better compression. Defaults to false.
+            exif=exif,
+            icc_profile=icc_profile,
+            xmp=xmp,
+        )
+
+    def _image_convert(
+        self,
+        path: Path,
+        to_extension: str | None = None,
+    ) -> None:
+        """
+        Convert image to other format
+
+        Parameters
+        ----------
+        path : Path
+            Path to image
+
+        to_extension : SupportedImageExtension | None, optional
+            New image format, by default None
+        """
+        # Load image
+        new_suffix = path.suffix if to_extension is None else to_extension
+        image = Image.open(path)
+
+        # Extract metadata
+        xmp = image.info.get("xmp")
+        exif = image.getexif()
+        icc_profile = image.info.get("icc_profile")
+
+        # Save
+        convert_func = self._IMAGE_CONVERTER.get(new_suffix, _image_convert_default)
+        # self.logger.debug(f"Using {convert_func}")
+        convert_func(
+            image,
+            path.with_suffix(new_suffix),
+            exif=exif,
+            icc_profile=icc_profile,
+            xmp=xmp,
+        )
+
+    def img_convert(self, to_extension: SupportedImageExtension | str, backup: bool = True) -> None:
+        """
+        Convert images in directory to desire format
+
+        Parameters
+        ----------
+        to_extension : SupportedImageExtension
+            Format to convert
+
+        backup : bool
+            Move pictures to a backup folder
+
+        Raises
+        ------
+        NotImplementedError
+            Not supported image format
+        """
+        if to_extension not in self._supported_image_format:
+            raise NotImplementedError("Format not supported")
+
+        imgs = self.select_all(*self._make_suffix_selection(to_extension))
+
+        for x in tqdm(imgs, desc=f"Converting to {to_extension}"):
+            try:
+                self._image_convert(x, to_extension=to_extension)
+
+                if backup:
+                    self.backup_path.mkdir(parents=True, exist_ok=True)
+                    self._make_backup(x)
+            except TypeError as err:
+                print(f" TYPE ERROR: {x} - {err}")
+            except Exception as err:
+                print(f" ERROR: {x} - {err}")

absfuyu/extra/rclone.py

@@ -3,7 +3,7 @@ Absfuyu: Rclone decrypt
 -----------------------
 Rclone decryptor
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/extra/xml.py

@@ -3,7 +3,7 @@ Absfuyu: XML
 ------------
 XML Tool [W.I.P]
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/fun/__init__.py

@@ -3,7 +3,7 @@ Absfuyu: Fun
 ------------
 Some fun or weird stuff
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/fun/rubik.py

@@ -3,7 +3,7 @@ Absfuyu: Fun
 ------------
 Rubik
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 
 

absfuyu/fun/tarot.py

@@ -4,7 +4,7 @@ Absfuyu: Tarot
 Tarot stuff
 
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 
 Usage:

absfuyu/game/__init__.py

@@ -3,7 +3,7 @@ Absfuyu: Game
 -------------
 Contain some game that can be played on terminal
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/game/game_stat.py

@@ -1,7 +1,7 @@
 """
 Game: Game Stat
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/game/schulte.py

@@ -2,7 +2,7 @@
 Game: Schulte
 -------------
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/game/sudoku.py

@@ -3,7 +3,7 @@ Game: Sudoku
 ------------
 Sudoku 9x9 Solver
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 
 Credit:

absfuyu/game/tictactoe.py

@@ -2,7 +2,7 @@
 Game: Tic Tac Toe
 -----------------
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/game/wordle.py

@@ -2,7 +2,7 @@
 Game: Wordle Solver
 -------------------
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 
 Usage:

absfuyu/general/__init__.py

@@ -3,7 +3,7 @@ Absfuyu: General
 ----------------
 Collection of useful classes
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 
 Features:

absfuyu/general/content.py

@@ -3,7 +3,7 @@ Absfuyu: Content
 ----------------
 Handle .txt file
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 
 Usage:

absfuyu/general/human.py

@@ -3,7 +3,7 @@ Absfuyu: Human
 --------------
 Human related stuff
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/general/shape.py

@@ -3,7 +3,7 @@ Absfuyu: Shape
 --------------
 Shapes
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/general/tax.py

@@ -3,7 +3,7 @@ Absfuyu: Tax calculator
 -----------------------
 Tax calculator
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/logger.py

@@ -3,7 +3,7 @@ Absfuyu: Logger
 ---------------
 Custom Logger Module
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 
 Usage:

absfuyu/pkg_data/__init__.py

@@ -3,7 +3,7 @@ Absfuyu: Package data
 ---------------------
 Load package data
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/pkg_data/deprecated.py

@@ -3,7 +3,7 @@ Absfuyu: Package data
 ---------------------
 Deprecated (but might have some use)
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/pkg_data/logo.py

@@ -3,7 +3,7 @@ Absfuyu: Logo
 -------------
 Absfuyu logo in base64 string for easy access
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/sort.py

@@ -3,7 +3,7 @@ Absfuyu: Sort
 -------------
 Sort Module
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/tools/__init__.py

@@ -3,7 +3,7 @@ Absfuyu: Tools
 --------------
 Some useful tools
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/tools/checksum.py

@@ -3,7 +3,7 @@ Absufyu: Checksum
 -----------------
 Check MD5, SHA256, ...
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 """
 

absfuyu/tools/converter.py

@@ -3,7 +3,7 @@ Absufyu: Converter
 ------------------
 Convert stuff
 
-Version: 5.12.0
+Version: 5.13.0
 Date updated: 17/10/2025 (dd/mm/yyyy)
 
 Feature:

absfuyu/tools/generator.py

@@ -3,8 +3,8 @@ Absfuyu: Generator
 ------------------
 This generate stuff (Not python's ``generator``)
 
-Version: 5.12.0
-Date updated: 17/10/2025 (dd/mm/yyyy)
+Version: 5.13.0
+Date updated: 28/10/2025 (dd/mm/yyyy)
 
 Features:
 ---------
@@ -25,7 +25,7 @@ import string
 from collections.abc import Collection, Sequence
 from itertools import chain, combinations
 from random import choice
-from typing import TypeVar, cast, overload
+from typing import Literal, TypeVar, cast, overload
 
 from absfuyu.core.baseclass import GetClassMembersMixin
 from absfuyu.core.docstring import deprecated
@@ -78,6 +78,25 @@ class Generator(GetClassMembersMixin):
     """
 
     # Generate string
+    @overload
+    @staticmethod
+    def generate_string(  # type: ignore
+        charset: str = Charset.DEFAULT,
+        size: int = 8,
+        times: int = 1,
+        unique: bool = False,
+    ) -> list[str]: ...
+
+    @overload
+    @staticmethod
+    def generate_string(
+        charset: str = Charset.DEFAULT,
+        size: int = 8,
+        times: int = 1,
+        unique: bool = False,
+        string_type_if_1: Literal[True] = ...,
+    ) -> str: ...
+
     @staticmethod
     @deprecated("5.2.0", reason="Use generate_string2() instead.")
     def generate_string(
@@ -86,7 +105,7 @@ class Generator(GetClassMembersMixin):
         times: int = 1,
         unique: bool = False,
         string_type_if_1: bool = False,
-    ):
+    ) -> str | list[str]:
         """
         Generate a list of random string from character set (Random string generator).
         Deprecated
@@ -394,9 +413,7 @@ class Generator(GetClassMembersMixin):
 
     @overload
     @staticmethod
-    def combinations_range(
-        collection: Collection[T], *, min_len: int = 1, max_len: int = 0
-    ) -> list[tuple[T, ...]]: ...
+    def combinations_range(collection: Collection[T], *, min_len: int = 1, max_len: int = 0) -> list[tuple[T, ...]]: ...
 
     @staticmethod
     def combinations_range(