absfuyu 5.0.1__py3-none-any.whl → 5.2.0__py3-none-any.whl

absfuyu/util/path.py

@@ -3,8 +3,8 @@ Absfuyu: Path
 -------------
 Path related
 
-Version: 5.0.0
-Date updated: 22/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 14/03/2025 (dd/mm/yyyy)
 
 Feature:
 --------
@@ -16,8 +16,15 @@ Feature:
 # ---------------------------------------------------------------------------
 __all__ = [
     # Main
+    "DirectoryBase",
     "Directory",
     "SaveFileAs",
+    # Mixin
+    "DirectoryInfoMixin",
+    "DirectoryBasicOperationMixin",
+    "DirectoryArchiverMixin",
+    "DirectoryOrganizerMixin",
+    "DirectoryTreeMixin",
     # Support
     "FileOrFolderWithModificationTime",
     "DirectoryInfo",
@@ -32,9 +39,11 @@ import shutil
 from datetime import datetime
 from functools import partial
 from pathlib import Path
-from typing import Any, Literal, NamedTuple
+from typing import Any, ClassVar, Literal, NamedTuple
 
-from absfuyu.core import versionadded
+from absfuyu.core.baseclass import BaseClass
+from absfuyu.core.decorator import add_subclass_methods_decorator
+from absfuyu.core.docstring import deprecated, versionadded, versionchanged
 from absfuyu.logger import logger
 
 
@@ -53,21 +62,40 @@ class FileOrFolderWithModificationTime(NamedTuple):
     modification_time: datetime
 
 
+@deprecated(
+    "5.1.0", reason="Support for ``DirectoryInfoMixin`` which is also deprecated"
+)
 @versionadded("3.3.0")
 class DirectoryInfo(NamedTuple):
     """
     Information of a directory
     """
 
-    files: int
-    folders: int
     creation_time: datetime
     modification_time: datetime
 
 
-# Class - Directory | version 3.4.0: Remake Directory into modular class
+# Class - Directory
 # ---------------------------------------------------------------------------
-class DirectoryBase:
+@add_subclass_methods_decorator
+class DirectoryBase(BaseClass):
+    """
+    Directory - Base
+
+    Parameters
+    ----------
+    source_path : str | Path
+        Source folder
+
+    create_if_not_exist : bool
+        Create directory when not exist,
+        by default ``False``
+    """
+
+    # Custom attribute
+    _METHOD_INCLUDE: ClassVar[bool] = True  # Include in DIR_METHODS
+    SUBCLASS_METHODS: ClassVar[dict[str, list[str]]] = {}
+
     def __init__(
         self,
         source_path: str | Path,
@@ -80,80 +108,53 @@ class DirectoryBase:
             Source folder
 
         create_if_not_exist : bool
-            Create directory when not exist
-            (Default: ``False``)
+            Create directory when not exist,
+            by default ``False``
         """
         self.source_path = Path(source_path)
-        if create_if_not_exist:
-            if not self.source_path.exists():
+        if not self.source_path.exists():
+            if create_if_not_exist:
                 self.source_path.mkdir(exist_ok=True, parents=True)
+            else:
+                raise FileNotFoundError("Directory not existed")
 
-    def __str__(self) -> str:
-        return self.source_path.__str__()
-
-    def __repr__(self) -> str:
-        return f"{self.__class__.__name__}({self.source_path})"
-
-    def __format__(self, __format_spec: str) -> str:
-        """
-        Change format of an object.
-        Avaiable option: ``info``
-
-        Usage
-        -----
-        >>> print(f"{<object>:<format_spec>}")
-        >>> print(<object>.__format__(<format_spec>))
-        >>> print(format(<object>, <format_spec>))
-        """
-        # Show quick info
-        if __format_spec.lower().startswith("info"):
-            return self.quick_info().__repr__()
-
-        # No format spec
-        return self.__repr__()
 
-    # Everything
-    @property
-    @versionadded("3.3.0")
-    def everything(self) -> list[Path]:
-        """
-        Every folders and files in this Directory
-        """
-        return list(x for x in self.source_path.glob("**/*"))
-
-    @versionadded("3.3.0")
-    def _every_folder(self) -> list[Path]:
-        """
-        Every folders in this Directory
-        """
-        return list(x for x in self.source_path.glob("**/*") if x.is_dir())
+class DirectoryInfoMixin(DirectoryBase):
+    """
+    Directory - Info
 
-    @versionadded("3.3.0")
-    def _every_file(self) -> list[Path]:
-        """
-        Every folders in this Directory
-        """
-        return list(x for x in self.source_path.glob("**/*") if x.is_file())
+    - Quick info
+    """
 
-    # Quick information
+    @deprecated("5.1.0", reason="Not efficient")
     @versionadded("3.3.0")
     def quick_info(self) -> DirectoryInfo:
         """
         Quick information about this Directory
 
-        :rtype: DirectoryInfo
+        Returns
+        -------
+        DirectoryInfo
+            DirectoryInfo
         """
         source_stat: os.stat_result = self.source_path.stat()
         out = DirectoryInfo(
-            files=len(self._every_file()),
-            folders=len(self._every_folder()),
             creation_time=datetime.fromtimestamp(source_stat.st_ctime),
             modification_time=datetime.fromtimestamp(source_stat.st_mtime),
         )
         return out
 
 
-class DirectoryBasicOperation(DirectoryBase):
+class DirectoryBasicOperationMixin(DirectoryBase):
+    """
+    Directory - Basic operation
+
+    - Rename
+    - Copy
+    - Move
+    - Delete
+    """
+
     # Rename
     def rename(self, new_name: str) -> None:
         """
@@ -214,7 +215,7 @@ class DirectoryBasicOperation(DirectoryBase):
                 shutil.move(self.source_path, Path(dst))
             logger.debug(f"Moving to {dst}...DONE")
 
-        except shutil.Error as e:  # File already exists
+        except OSError as e:  # File already exists
             logger.error(e)
             logger.debug("Overwriting file...")
             if content_only:
@@ -316,31 +317,54 @@ class DirectoryBasicOperation(DirectoryBase):
         except Exception as e:
             logger.error(f"Removing {self.source_path}...FAILED\n{e}")
 
-    # Zip
+
+class DirectoryArchiverMixin(DirectoryBase):
+    """
+    Directory - Archiver/Compress
+
+    - Compress
+    - Decompress
+    - Register extra zip format <staticmethod>
+    """
+
+    @versionchanged("5.1.0", reason="Update funcionality (new parameter)")
     def compress(
-        self, *, format: Literal["zip", "tar", "gztar", "bztar", "xztar"] = "zip"
+        self,
+        format: Literal["zip", "tar", "gztar", "bztar", "xztar"] = "zip",
+        delete_after_compress: bool = False,
+        move_inside: bool = True,
     ) -> Path | None:
         """
         Compress the directory (Default: Create ``.zip`` file)
 
         Parameters
         ----------
-        format : Literal["zip", "tar", "gztar", "bztar", "xztar"]
+        format : Literal["zip", "tar", "gztar", "bztar", "xztar"], optional
+            By default ``"zip"``
             - ``zip``: ZIP file (if the ``zlib`` module is available).
             - ``tar``: Uncompressed tar file. Uses POSIX.1-2001 pax format for new archives.
             - ``gztar``: gzip'ed tar-file (if the ``zlib`` module is available).
             - ``bztar``: bzip2'ed tar-file (if the ``bz2`` module is available).
             - ``xztar``: xz'ed tar-file (if the ``lzma`` module is available).
 
+        delete_after_compress : bool, optional
+            Delete directory after compress, by default ``False``
+
+        move_inside : bool, optional
+            Move the commpressed file inside the directory,
+            by default ``True``
+
         Returns
         -------
         Path
             Compressed path
+
         None
             When fail to compress
         """
         logger.debug(f"Zipping {self.source_path}...")
         try:
+            # Zip
             # zip_name = self.source_path.parent.joinpath(self.source_path.name).__str__()
             # shutil.make_archive(zip_name, format=format, root_dir=self.source_path)
             zip_path = shutil.make_archive(
@@ -348,26 +372,85 @@ class DirectoryBasicOperation(DirectoryBase):
             )
             logger.debug(f"Zipping {self.source_path}...DONE")
             logger.debug(f"Path: {zip_path}")
+
+            # Del
+            if delete_after_compress:
+                move_inside = False
+                shutil.rmtree(self.source_path)
+
+            # Move
+            if move_inside:
+                zf = Path(zip_path)
+                _move_path = self.source_path.joinpath(zf.name)
+                if _move_path.exists():
+                    _move_path.unlink(missing_ok=True)
+                _move = zf.rename(_move_path)
+                return _move
+
             return Path(zip_path)
-        except Exception as e:
+        except (FileExistsError, OSError) as e:
             logger.error(f"Zipping {self.source_path}...FAILED\n{e}")
             return None
 
+    @staticmethod
+    @versionadded("5.1.0")
+    def register_extra_zip_format() -> None:
+        """This register extra extension for zipfile"""
+        extra_extension = [".zip", ".cbz"]
+        shutil.unregister_unpack_format("zip")
+        shutil.register_unpack_format(
+            "zip",
+            extra_extension,
+            shutil._unpack_zipfile,  # type: ignore
+            description="ZIP file",
+        )
 
-class DirectoryTree(DirectoryBase):
-    pass
+    @versionadded("5.1.0")
+    def decompress(
+        self,
+        format: Literal["zip", "tar", "gztar", "bztar", "xztar"] | None = None,
+        delete_after_done: bool = False,
+    ) -> None:
+        """
+        Decompress compressed file in directory (first level only)
+
+        Parameters
+        ----------
+        format : Literal["zip", "tar", "gztar", "bztar", "xztar"] | None, optional
+            By default ``None``
+            - ``zip``: ZIP file (if the ``zlib`` module is available).
+            - ``tar``: Uncompressed tar file. Uses POSIX.1-2001 pax format for new archives.
+            - ``gztar``: gzip'ed tar-file (if the ``zlib`` module is available).
+            - ``bztar``: bzip2'ed tar-file (if the ``bz2`` module is available).
+            - ``xztar``: xz'ed tar-file (if the ``lzma`` module is available).
 
+        delete_after_done : bool, optional
+            Delete compressed file when extracted, by default ``False``
+        """
+        # Register extra extension
+        self.register_extra_zip_format()
+
+        # Decompress first level only
+        for path in self.source_path.glob("*"):
+            try:
+                shutil.unpack_archive(
+                    path, path.parent.joinpath(path.stem), format=format
+                )
+                if delete_after_done and path.is_file():
+                    path.unlink(missing_ok=True)
+            except OSError:
+                continue
 
-class Directory(DirectoryBasicOperation, DirectoryTree):
-    """
-    Some shortcuts for directory
 
-    - list_structure
-    - delete, rename, copy, move
-    - zip
-    - quick_info
+class DirectoryOrganizerMixin(DirectoryBase):
     """
+    Directory - File organizer - SOON
+    """
+
+    pass
 
+
+class DirectoryTreeMixin(DirectoryBase):
     # Directory structure
     def _list_dir(self, *ignore: str) -> list[Path]:
         """
@@ -504,10 +587,41 @@ class Directory(DirectoryBasicOperation, DirectoryTree):
         return self.list_structure("__pycache__", ".pyc")
 
 
+class Directory(
+    DirectoryTreeMixin,
+    DirectoryOrganizerMixin,
+    DirectoryArchiverMixin,
+    DirectoryBasicOperationMixin,
+    DirectoryInfoMixin,
+):
+    """
+    Some shortcuts for directory
+
+    Parameters
+    ----------
+    source_path : str | Path
+        Source folder
+
+    create_if_not_exist : bool
+        Create directory when not exist,
+        by default ``False``
+
+
+    Example:
+    --------
+    >>> # For a list of method
+    >>> Directory.SUBCLASS_METHODS
+    """
+
+    pass
+
+
 # Class - SaveFileAs
 # ---------------------------------------------------------------------------
 class SaveFileAs:
-    """File as multiple file type"""
+    """
+    File as multiple file type
+    """
 
     def __init__(self, data: Any, *, encoding: str | None = "utf-8") -> None:
         """
@@ -552,9 +666,3 @@ class SaveFileAs:
     #     from absfuyu.util.json_method import JsonFile
     #     temp = JsonFile(path, sort_keys=False)
     #     temp.save_json()
-
-
-# Dev and Test new feature before get added to the main class
-# ---------------------------------------------------------------------------
-class _NewDirFeature(Directory):
-    pass

absfuyu/util/performance.py

@@ -3,8 +3,8 @@ Absfuyu: Performance
 --------------------
 Performance Check
 
-Version: 5.0.0
-Date updated: 22/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 15/03/2025 (dd/mm/yyyy)
 
 Feature:
 --------
@@ -20,6 +20,7 @@ Feature:
 __all__ = [
     # Wrapper
     "function_debug",
+    "function_benchmark",
     "measure_performance",
     "retry",
     # Class
@@ -32,12 +33,12 @@ __all__ = [
 import time
 import tracemalloc
 from collections.abc import Callable
+from dataclasses import dataclass
 from functools import wraps
 from inspect import getsource
-from typing import Any, ParamSpec, TypeVar
+from typing import Any, Literal, ParamSpec, TypeVar, overload
 
-from absfuyu.core import versionadded, versionchanged
-from absfuyu.dxt import ListNoDunder
+from absfuyu.core import deprecated, versionadded, versionchanged
 
 # Type
 # ---------------------------------------------------------------------------
@@ -45,6 +46,30 @@ P = ParamSpec("P")  # Parameter type
 R = TypeVar("R")  # Return type
 
 
+# Support
+# ---------------------------------------------------------------------------
+@dataclass
+class BenchmarkResult:
+    """
+    Use ``format(BenchmarkResult(...), "seconds")`` to view result in seconds.
+    """
+
+    min_: float
+    max_: float
+    avg: float
+
+    def __format__(self, format_spec: str) -> str:
+        clsname = self.__class__.__name__
+        if format_spec.lower().strip().startswith("seconds"):
+            fields = [f"{x}={getattr(self, x):,.6f}s" for x in self._get_fields()]
+            return f"{clsname}({', '.join(fields)})"
+        return repr(self)
+
+    @classmethod
+    def _get_fields(cls) -> tuple[str, ...]:
+        return tuple(cls.__dataclass_fields__)
+
+
 # Function
 # ---------------------------------------------------------------------------
 @versionchanged("3.2.0", reason="Updated functionality")
@@ -108,6 +133,96 @@ def measure_performance(f: Callable[P, R]) -> Callable[P, R]:
     return wrapper
 
 
+@overload
+def function_benchmark(func: Callable[P, R], /) -> Callable[P, R]: ...
+@overload
+def function_benchmark(*, n: int = 1) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+@overload
+def function_benchmark(
+    *, n: int = 1, result_only: Literal[False] = False
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+@overload
+def function_benchmark(
+    *, n: int = 1, result_only: Literal[True] = ...
+) -> Callable[[Callable[P, R]], Callable[P, BenchmarkResult]]: ...
+
+
+@versionadded("5.2.0")
+def function_benchmark(
+    func: Callable[P, R] | None = None, /, *, n: int = 1, result_only: bool = False
+):
+    """
+    This run function for ``n`` times and calculate min, max, average runtime.
+
+    Parameters
+    ----------
+    func : Callable[P, R] | None, optional
+        Callable with parameter **P and returns R, by default ``None``
+
+    n : int, optional
+        Run how many times, by default ``1``
+
+    result_only : bool, optional
+        Returns BenchmarkResult instead of ``func`` result, by default ``False``
+
+
+    Usage
+    -----
+    Use this as a decorator (``@function_benchmark``)
+
+    Example:
+    --------
+    >>> @function_benchmark
+    >>> def test():
+    ...     return 1 + 1
+    >>> test()
+    BenchmarkResult(min_=0.000000s, max_=0.000000s, avg=0.000000s)
+    2
+
+    >>> @function_benchmark(n=1)
+    >>> def test():
+    ...     return 1 + 1
+    >>> test()
+    BenchmarkResult(min_=0.000000s, max_=0.000000s, avg=0.000000s)
+    2
+    """
+
+    times = max(n, 1)
+
+    def decorator(f: Callable[P, R]) -> Callable[P, R | BenchmarkResult]:
+        @wraps(f)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | BenchmarkResult:
+            output = f(*args, **kwargs)  # Run function and save result into a variable
+
+            def _run() -> float:
+                # Performance check
+                start_time = time.perf_counter()  # Start time measure
+                f(*args, **kwargs)
+                finish_time = time.perf_counter()  # Get finished time
+                return finish_time - start_time
+
+            # run = (_run() for _ in range(times))
+            run = [_run() for _ in range(times)]
+            try:
+                avg_runtime = sum(run) / len(run)
+            except ZeroDivisionError:
+                avg_runtime = min(run)
+            result = BenchmarkResult(min(run), max(run), avg_runtime)
+
+            if result_only:
+                return result
+
+            print(format(result, "seconds"))
+
+            return output
+
+        return wrapper
+
+    if func is None:
+        return decorator
+    return decorator(func)
+
+
 @versionadded("3.2.0")
 def function_debug(f: Callable[P, R]) -> Callable[P, R]:
     """
@@ -225,7 +340,7 @@ def retry(retries: int, delay: float = 1):
 
 # Class
 # ---------------------------------------------------------------------------
-# TODO: Rewrite this with inspect
+@deprecated("5.1.0", reason="Use `absfuyu.tools.inspector` instead")
 class Checker:
     """
     Check a variable
@@ -284,7 +399,7 @@ class Checker:
     def dir_(self) -> list[str]:
         """``dir()`` of variable"""
         # return self.item_to_check.__dir__()
-        return ListNoDunder(self.item_to_check.__dir__())
+        return [x for x in dir(self.item_to_check) if not x.startswith("__")]
 
     @property
     def source(self) -> str | None:

absfuyu/util/shorten_number.py

@@ -3,8 +3,8 @@ Absfuyu: Shorten number
 -----------------------
 Short number base on suffixes
 
-Version: 5.0.0
-Date updated: 24/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 10/03/2025 (dd/mm/yyyy)
 """
 
 # Module level
@@ -156,11 +156,28 @@ class Decimal:
     """
     Shorten large number
 
-    :param original_value: Value to shorten
-    :param base: Short by base (must be > 0)
-    :param suffixes: List of suffixes to use (ascending order)
-    :param factory: ``UnitSuffixFactory`` to use (will overwrite ``base`` and ``suffixes``)
-    :param suffix_full_name: Use suffix full name (default: False)
+    Parameters
+    ----------
+    original_value : int | float
+        Value to shorten
+
+    base : int
+        Short by base (must be > 0)
+
+    suffixes : list[str]
+        List of suffixes to use (ascending order)
+
+    factory : UnitSuffixFactory | None
+        ``UnitSuffixFactory`` to use
+        (will overwrite ``base`` and ``suffixes``)
+
+    suffix_full_name : bool
+        Use suffix full name (available with ``UnitSuffixFactory``), by default ``False``
+
+    Returns
+    -------
+    Decimal
+        Decimal instance
     """
 
     original_value: int | float = field(repr=False)
@@ -173,6 +190,7 @@ class Decimal:
     suffix: str = field(init=False)
 
     def __post_init__(self) -> None:
+        self.base = max(1, self.base)  # Make sure that base >= 1
         self._get_factory()
         self.value, self.suffix = self._convert_decimal()
 
@@ -228,9 +246,21 @@ class Decimal:
         """
         Convert to string
 
-        :param decimal: Round up to which decimal
-        :param separator: Character between value and suffix, default: ``" "``
-        :param float_only: Returns value as <float> instead of <int> when ``decimal = 0``
+        Parameters
+        ----------
+        decimal : int, optional
+            Round up to which decimal, by default ``2``
+
+        separator : str, optional
+            Character between value and suffix, by default ``" "``
+
+        float_only : bool, optional
+            Returns value as <float> instead of <int> when ``decimal = 0``, by default ``True``
+
+        Returns
+        -------
+        str
+            Decimal string
         """
         val = self.value.__round__(decimal)
         formatted_value = f"{val:,}"