absfuyu 5.0.0__py3-none-any.whl → 6.1.2__py3-none-any.whl

absfuyu/util/performance.py

@@ -3,8 +3,8 @@ Absfuyu: Performance
 --------------------
 Performance Check
 
-Version: 5.0.0
-Date updated: 13/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/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

@@ -1,12 +1,16 @@
 """
 Absfuyu: Shorten number
 -----------------------
-Short number base on suffixes
+Short number base on suffixes (deprecated, use absfuyu.numbers instead)
 
-Version: 5.0.0
-Date updated: 18/02/2025 (dd/mm/yyyy)
+WILL BE REMOVED IN VERSION 7.0.0
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
+from __future__ import annotations
+
 # Module level
 # ---------------------------------------------------------------------------
 __all__ = [
@@ -14,6 +18,8 @@ __all__ = [
     "CommonUnitSuffixesFactory",
     "Decimal",
     "shorten_number",
+    "Duration",
+    "SupportDurationFormatPreset",
 ]
 
 
@@ -22,7 +28,7 @@ __all__ = [
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from functools import wraps
-from typing import Annotated, NamedTuple, ParamSpec, Self, TypeVar
+from typing import Annotated, NamedTuple, ParamSpec, Protocol, Self, TypeVar
 
 from absfuyu.core import versionadded
 
@@ -32,7 +38,7 @@ P = ParamSpec("P")  # Parameter type
 N = TypeVar("N", int, float)  # Number type
 
 
-# Class
+# Class - Decimal
 # ---------------------------------------------------------------------------
 @versionadded("4.1.0")
 class UnitSuffixFactory(NamedTuple):
@@ -156,11 +162,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 +196,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()
 
@@ -205,11 +229,7 @@ class Decimal:
     def _get_factory(self) -> None:
         if self.factory is not None:
             self.base = self.factory.base
-            self.suffixes = (
-                self.factory.full_name
-                if self.suffix_full_name
-                else self.factory.short_name
-            )
+            self.suffixes = self.factory.full_name if self.suffix_full_name else self.factory.short_name
 
     def _convert_decimal(self) -> tuple[float, str]:
         """Convert to smaller number"""
@@ -222,15 +242,25 @@ class Decimal:
         output = self.original_value / unit
         return output, suffix
 
-    def to_text(
-        self, decimal: int = 2, *, separator: str = " ", float_only: bool = True
-    ) -> str:
+    def to_text(self, decimal: int = 2, *, separator: str = " ", float_only: bool = True) -> str:
         """
         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:,}"
@@ -277,3 +307,196 @@ def shorten_number(f: Callable[P, N]) -> Callable[P, Decimal]:
         return value
 
     return wrapper
+
+
+# Class - Duration
+# ---------------------------------------------------------------------------
+# Format preset
+class SupportDurationFormatPreset(Protocol):
+    def __call__(self, duration: Duration, /) -> str: ...
+
+
+@dataclass
+@versionadded("5.16.0")
+class Duration:
+    """
+    Convert duration in seconds to a more readable form. Eg: 3 mins 2 secs
+
+    Parameters
+    ----------
+    total_seconds : int | float
+        Seconds to convert to
+    """
+
+    total_seconds: int | float
+
+    years: int = field(init=False)
+    months: int = field(init=False)
+    days: int = field(init=False)
+    hours: int = field(init=False)
+    minutes: int = field(init=False)
+    seconds: int = field(init=False)
+
+    _formats: dict[str, SupportDurationFormatPreset] = field(init=False)
+
+    # Calculate duration
+    def _calculate_duration(self) -> None:
+        SEC_PER_MIN = 60
+        SEC_PER_HOUR = 3600
+        SEC_PER_DAY = 86400
+        SEC_PER_MONTH = 30 * SEC_PER_DAY
+        SEC_PER_YEAR = 365 * SEC_PER_DAY
+
+        secs = self.total_seconds
+
+        self.years, secs = divmod(secs, SEC_PER_YEAR)
+        self.months, secs = divmod(secs, SEC_PER_MONTH)
+        self.days, secs = divmod(secs, SEC_PER_DAY)
+        self.hours, secs = divmod(secs, SEC_PER_HOUR)
+        self.minutes, self.seconds = divmod(secs, SEC_PER_MIN)
+
+    # Format handling
+    def _init_format(self) -> None:
+
+        def duration_compact_preset(duration: Self, /) -> str:
+            """
+            Example: "1y 2m 3d 4h 5m 6s"
+            (fields = hidden when = 0).
+            """
+            parts = []
+            if duration.years:
+                parts.append(f"{duration.years}y")
+            if duration.months:
+                parts.append(f"{duration.months}m")
+            if duration.days:
+                parts.append(f"{duration.days}d")
+            if duration.hours:
+                parts.append(f"{duration.hours}h")
+            if duration.minutes:
+                parts.append(f"{duration.minutes}m")
+            if duration.seconds:
+                parts.append(f"{duration.seconds}s")
+            return " ".join(parts) if parts else "0s"
+
+        def duration_HMS_only_preset(duration: Self, /) -> str:
+            """
+            Example: "02:15:09" (HH:MM:SS only).
+            """
+            total = duration.total_seconds
+            h, m = divmod(total, 3600)
+            m, s = divmod(m, 60)
+            return f"{h:02d}:{m:02d}:{s:02d}"
+
+        def duration_digital_preset(duration: Self, /) -> str:
+            """
+            Examples:
+            - If >= 1 day: "1d 02:03:04"
+            - else: "02:03:04"
+            """
+            total = duration.total_seconds
+            days, sec = divmod(total, 86400)
+            h, sec = divmod(sec, 3600)
+            m, s = divmod(sec, 60)
+
+            if days:
+                return f"{days}d {h:02d}:{m:02d}:{s:02d}"
+            return f"{h:02d}:{m:02d}:{s:02d}"
+
+        self._formats = {
+            "compact": duration_compact_preset,
+            "hms": duration_HMS_only_preset,
+            "digital": duration_digital_preset,
+        }
+
+    @versionadded("5.17.0")
+    def add_format(self, name: str, format_func: SupportDurationFormatPreset) -> None:
+        """
+        Add format style to Duration
+
+        Parameters
+        ----------
+        name : str
+            Name of the style (name will be lowercased)
+
+        format_func : SupportDurationFormatPreset
+            Format function
+        """
+        self._formats[name.lower().strip()] = format_func
+
+    @property
+    def available_formats(self) -> list[str]:
+        """
+        Available style format
+
+        Returns
+        -------
+        list[str]
+            All available style formats
+        """
+        return list(self._formats)
+
+    def __format__(self, format_spec: str) -> str:
+        """
+        Change format of an object.
+
+        Usage
+        -----
+        >>> print(f"{<object>:<format_spec>}")
+        >>> print(<object>.__format__(<format_spec>))
+        >>> print(format(<object>, <format_spec>))
+        """
+
+        func = self._formats.get(format_spec.lower().strip(), None)
+
+        if func is None:
+            return self.__str__()
+        else:
+            return func(self)
+
+    # POST INIT
+    def __post_init__(self) -> None:
+        if not isinstance(self.total_seconds, (int, float)) or self.total_seconds < 0:
+            raise ValueError("seconds must be a non-negative number")
+        self._calculate_duration()
+        self._init_format()
+
+    def __str__(self) -> str:
+
+        def _plural(n: int | float, word: str):
+            return f"{n} {word}{'s' if n != 1 else ''}"
+
+        parts = []
+        if self.years:
+            parts.append(_plural(self.years, "year"))
+        if self.months:
+            parts.append(_plural(self.months, "month"))
+        if self.days:
+            parts.append(_plural(self.days, "day"))
+        if self.hours:
+            parts.append(_plural(self.hours, "hour"))
+        if self.minutes:
+            parts.append(_plural(self.minutes, "minute"))
+        if self.seconds:
+            parts.append(_plural(self.seconds, "second"))
+        return " ".join(parts) if parts else "0 second"
+
+    # From other type of duration
+    @classmethod
+    def from_minute(cls, minutes: int | float) -> Self:
+        return cls(minutes * 60)
+
+    @classmethod
+    def from_hour(cls, hours: int | float) -> Self:
+        return cls(hours * 3600)
+
+    @classmethod
+    def from_day(cls, days: int | float) -> Self:
+        return cls(days * 86400)
+
+    @classmethod
+    def from_month(cls, months: int | float) -> Self:
+        return cls(months * 86400 * 30)
+
+    @classmethod
+    def from_year(cls, years: int | float) -> Self:
+        return cls(years * 86400 * 365)