absfuyu 5.6.1__py3-none-any.whl → 6.1.3__py3-none-any.whl

absfuyu/core/docstring.py

@@ -3,8 +3,8 @@ Absfuyu: Core
 -------------
 Sphinx docstring decorator
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -46,6 +46,7 @@ class SphinxDocstringMode(Enum):
     ADDED = "Added"
     CHANGED = "Changed"
     DEPRECATED = "Deprecated"
+    PENDING_REMOVE = "Pending to remove"
 
 
 class SphinxDocstring:
@@ -182,3 +183,4 @@ class SphinxDocstring:
 versionadded = partial(SphinxDocstring, mode=SphinxDocstringMode.ADDED)
 versionchanged = partial(SphinxDocstring, mode=SphinxDocstringMode.CHANGED)
 deprecated = partial(SphinxDocstring, mode=SphinxDocstringMode.DEPRECATED)
+pendingremove = partial(SphinxDocstring, mode=SphinxDocstringMode.PENDING_REMOVE)

absfuyu/core/dummy_cli.py

@@ -3,8 +3,8 @@ Absfuyu: Core
 -------------
 Dummy cli
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -57,7 +57,7 @@ def get_parser(
 
 
 def cli() -> None:
-    desc = "This is a dummy cli, please install <click> and <colorama> package to use this feature"
+    desc = "This is a dummy cli, install <click> and <colorama> package to use this feature"
     arg_parser = get_parser(
         name=__title__,
         description=desc,

absfuyu/core/dummy_func.py

@@ -3,8 +3,8 @@ Absfuyu: Core
 -------------
 Dummy functions when other libraries are unvailable
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package

absfuyu/dxt/__init__.py

@@ -3,8 +3,8 @@ Absfuyu: Data Extension
 -----------------------
 Extension for data type such as ``list``, ``str``, ``dict``, ...
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
 
 Features:
 ---------

absfuyu/dxt/base_type.py

@@ -0,0 +1,93 @@
+"""
+Absfuyu: Data Extension
+-----------------------
+Base type expansion
+
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
+"""
+
+# from __future__ import annotations
+
+# Module Package
+# ---------------------------------------------------------------------------
+__all__ = []
+
+
+# Library
+# ---------------------------------------------------------------------------
+from abc import ABC
+from typing import Generic, Self, TypeVar
+
+# Class
+# ---------------------------------------------------------------------------
+T = TypeVar("T")
+
+
+class BaseType(Generic[T], ABC):
+    """
+    A universal base class for creating custom immutable type wrappers.
+
+    Features:
+    ----------
+    - Works with any immutable type (int, str, float, etc.)
+    - Provides validation hook via `_validate`
+    - Automatically infers the base type from generic argument
+
+
+    Example:
+    --------
+    >>> class NonNegativeInt(BaseType[int], int):
+    >>>     @classmethod
+    >>>     def _validate(cls, value: int) -> None:
+    >>>         if value < 0:
+    >>>             raise ValueError("Value must be non-negative")
+    """
+
+    # Automatically infer `_base_type` when subclassed
+    def __init_subclass__(cls, *args, **kwargs) -> None:
+        super().__init_subclass__(*args, **kwargs)
+
+        # print(getattr(cls, "__orig_bases__", []))
+        for base in getattr(cls, "__orig_bases__", []):
+            if hasattr(base, "__args__") and base.__args__:
+                cls._base_type: type[T] = base.__args__[0]
+                break
+        else:
+            raise TypeError(f"{cls.__name__} must specify a generic base type, e.g. BaseType[int]")
+
+    def __new__(cls, value: T) -> Self:
+        base_type = cls._base_type
+        if not isinstance(value, base_type):
+            raise TypeError(f"{cls.__name__} must be initialized with {base_type.__name__}, got {type(value).__name__}")
+        cls._validate(value)
+        return base_type.__new__(cls, value)  # type: ignore
+
+    @classmethod
+    def _validate(cls, value: T) -> None:
+        """Override this in subclasses to add custom validation."""
+        pass
+
+    def __repr__(self) -> str:
+        # base_name = self._base_type.__name__
+        # return f"{self.__class__.__name__}({base_name}={self._base_type(self)!r})"  # type: ignore
+        return f"{self.__class__.__name__}({self._base_type(self)!r})"  # type: ignore
+
+
+class IntBase(BaseType[int], int):
+    """
+    A base class for creating custom integer-like types.
+    Provides a hook for validation and extension.
+
+    Parameters
+    ----------
+    value : int
+        Int value
+
+
+    Usage:
+    ------
+    Use ``_validate(cls, value: int) -> None:`` classmethod to create custom validator
+    """
+
+    pass

absfuyu/dxt/dictext.py

@@ -3,10 +3,12 @@ Absfuyu: Data Extension
 -----------------------
 dict extension
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
+from __future__ import annotations
+
 # Module Package
 # ---------------------------------------------------------------------------
 __all__ = ["DictExt", "DictAnalyzeResult"]
@@ -16,7 +18,7 @@ __all__ = ["DictExt", "DictAnalyzeResult"]
 # ---------------------------------------------------------------------------
 import operator
 from collections.abc import Callable
-from typing import Any, NamedTuple, Self, TypeVar
+from typing import Any, Literal, NamedTuple, Self, TypeVar, overload
 
 from absfuyu.core import GetClassMembersMixin, versionadded, versionchanged
 
@@ -28,6 +30,8 @@ from absfuyu.core import GetClassMembersMixin, versionadded, versionchanged
 # ---------------------------------------------------------------------------
 KT = TypeVar("KT")
 VT = TypeVar("VT")
+VT2 = TypeVar("VT2")
+R = TypeVar("R")  # Return type - Can be anything
 
 
 # Class
@@ -43,9 +47,9 @@ class DictAnalyzeResult(NamedTuple):
     min_list: list
 
 
-class DictExt(GetClassMembersMixin, dict[KT, VT]):
+class DictExtLegacy(GetClassMembersMixin, dict[KT, VT]):
     """
-    ``dict`` extension
+    ``dict`` extension (with no generic type-hints)
 
     >>> # For a list of new methods
     >>> DictExt.show_all_methods()
@@ -107,7 +111,7 @@ class DictExt(GetClassMembersMixin, dict[KT, VT]):
         {9: 'abc'}
         """
         # return self.__class__(zip(self.values(), self.keys()))
-        return self.__class__({v: k for k, v in self.items()})
+        return self.__class__({v: k for k, v in self.items()})  # type: ignore
 
     def apply(self, func: Callable[[Any], Any], apply_to_value: bool = True) -> Self:
         """
@@ -205,3 +209,181 @@ class DictExt(GetClassMembersMixin, dict[KT, VT]):
                 merged_output[k] = [value_self, value_other]
 
         return self.__class__(merged_output)
+
+
+# Type-hints are hard coded, no work around Self[KT, VT] yet
+class DictExt(GetClassMembersMixin, dict[KT, VT]):
+    """
+    ``dict`` extension
+
+    >>> # For a list of new methods
+    >>> DictExt.show_all_methods()
+    """
+
+    # Analyze
+    @versionchanged("3.3.0", reason="Updated return type")
+    def analyze(self) -> DictAnalyzeResult:
+        """
+        Analyze all the key values (``int``, ``float``)
+        in ``dict`` then return highest/lowest index
+
+        Returns
+        -------
+        dict
+            Analyzed data
+
+
+        Example:
+        --------
+        >>> test = DictExt({"abc": 9, "def": 9, "ghi": 8, "jkl": 1, "mno": 1})
+        >>> test.analyze()
+        DictAnalyzeResult(max_value=9, min_value=1, max_list=[('abc', 9), ('def', 9)], min_list=[('jkl', 1), ('mno', 1)])
+        """
+        try:
+            dct: dict = self.copy()
+
+            max_val: int | float = max(list(dct.values()))
+            min_val: int | float = min(list(dct.values()))
+            max_list = []
+            min_list = []
+
+            for k, v in dct.items():
+                if v == max_val:
+                    max_list.append((k, v))
+                if v == min_val:
+                    min_list.append((k, v))
+
+            return DictAnalyzeResult(max_val, min_val, max_list, min_list)
+
+        except TypeError:
+            err_msg = "Value must be int or float"
+            # logger.error(err_msg)
+            raise ValueError(err_msg)  # noqa: B904
+
+    # Swap
+    def swap_items(self) -> DictExt[VT, KT]:
+        """
+        Swap ``dict.keys()`` with ``dict.values()``
+
+        Returns
+        -------
+        DictExt
+            Swapped dict
+
+
+        Example:
+        --------
+        >>> test = DictExt({"abc": 9})
+        >>> test.swap_items()
+        {9: 'abc'}
+        """
+        # return self.__class__(zip(self.values(), self.keys()))
+        out: dict[VT, KT] = {v: k for k, v in self.items()}
+        # return self.__class__({v: k for k, v in self.items()})  # type: ignore
+        return self.__class__(out)  # type: ignore
+
+    # Apply
+    @overload
+    def apply(self, func: Callable[[VT], R]) -> DictExt[KT, R]: ...
+
+    @overload
+    def apply(self, func: Callable[[KT], R], apply_to_value: Literal[False] = ...) -> DictExt[R, VT]: ...
+
+    def apply(self, func: Callable[[KT | VT], R], apply_to_value: bool = True) -> DictExt[KT | R, VT | R]:  # type: ignore
+        """
+        Apply function to ``DictExt.keys()`` or ``DictExt.values()``
+
+        Parameters
+        ----------
+        func : Callable
+            Callable function
+
+        apply_to_value : bool
+            | ``True``: Apply ``func`` to ``DictExt.values()``
+            | ``False``: Apply ``func`` to ``DictExt.keys()``
+
+        Returns
+        -------
+        DictExt
+            DictExt
+
+
+        Example:
+        --------
+        >>> test = DictExt({"abc": 9})
+        >>> test.apply(str)
+        {'abc': '9'}
+        """
+        if apply_to_value:
+            new_dict_v: dict[KT, R] = {k: func(v) for k, v in self.items()}
+            return self.__class__(new_dict_v)  # type: ignore
+        else:
+            new_dict_k: dict[R, VT] = {func(k): v for k, v in self.items()}
+            return self.__class__(new_dict_k)  # type: ignore
+
+    # Aggregate
+    @versionchanged("5.0.0", reason="Updated to handle more types and operator")
+    @versionadded("3.4.0")
+    def aggregate(
+        self,
+        other_dict: dict[KT, VT | VT2],
+        default_value: Any = 0,
+        operator_func: Callable[[Any, Any], R] = operator.add,  # operator add
+    ):
+        """
+        Aggregates the values of the current dictionary with another dictionary.
+
+        For each unique key, this method applies the specified operator to the values
+        from both dictionaries. If a key exists in only one dictionary, its value is used.
+        If an error occurs during aggregation (e.g., incompatible types), the values
+        from both dictionaries are returned as a list.
+
+        Parameters
+        ----------
+        other_dict : dict
+            The dictionary to aggregate with.
+
+        default_value : Any, optional
+            The value to use for missing keys, by default ``0``
+
+
+        operator_func : Callable[[Any, Any], Any], optional
+            A function that takes two arguments and returns a single value,
+            by default ``operator.add``
+
+        Returns
+        -------
+        Self
+            A new instance of the aggregated dictionary.
+
+
+        Example:
+        --------
+        >>> test = DictExt({"test": 5, "test2": 9})
+        >>> agg = {"test1": 10, "test2": 1}
+        >>> print(test.aggregate(agg))
+        {'test1': 10, 'test': 5, 'test2': 10}
+
+        >>> test = DictExt({"test": 5, "test2": 9})
+        >>> agg = {"test1": 10, "test2": "1"}
+        >>> print(test.aggregate(agg))
+        {'test1': 10, 'test': 5, 'test2': [9, '1']}
+        """
+        merged_output: dict[KT, VT | R | list[VT | VT2]] = {}
+
+        # Create a set of all unique keys from both dictionaries
+        all_keys = set(self) | set(other_dict)
+
+        for k in all_keys:
+            # Retrieve values with default fallback
+            value_self = self.get(k, default_value)
+            value_other = other_dict.get(k, default_value)
+
+            try:
+                # Attempt to apply the operator for existing keys
+                merged_output[k] = operator_func(value_self, value_other)
+            except TypeError:
+                # If a TypeError occurs (e.g., if values are not compatible), store values as a list
+                merged_output[k] = [value_self, value_other]  # type: ignore
+
+        return self.__class__(merged_output)  # type: ignore

absfuyu/dxt/dxt_support.py

@@ -3,8 +3,8 @@ Absfuyu: Data Extension
 -----------------------
 Support classes
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package

absfuyu/dxt/intext.py

@@ -3,8 +3,8 @@ Absfuyu: Data Extension
 -----------------------
 int extension
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -15,8 +15,9 @@ __all__ = ["IntExt", "Pow"]
 # Library
 # ---------------------------------------------------------------------------
 import math
+from abc import ABC
 from collections import Counter
-from typing import Any, Literal, Self, overload
+from typing import Any, Literal, Self, overload, override
 
 from absfuyu.core.baseclass import GetClassMembersMixin
 from absfuyu.core.docstring import deprecated, versionadded, versionchanged
@@ -493,7 +494,7 @@ class IntExt(GetClassMembersMixin, int):
         return divi_list
 
     @overload
-    def prime_factor(self) -> list[Pow]: ...
+    def prime_factor(self) -> list[Pow]: ...  # type: ignore
 
     @overload
     def prime_factor(self, short_form: Literal[False] = ...) -> list[int]: ...
@@ -633,3 +634,70 @@ class IntExt(GetClassMembersMixin, int):
 
         quotient, remainder = divmod(self, p)
         return [quotient + (i >= (p - remainder)) for i in range(p)]
+
+
+# Class
+# ---------------------------------------------------------------------------
+class IntBase(int, ABC):
+    """
+    A base class for creating custom integer-like types.
+    Provides a hook for validation and extension.
+
+    Usage:
+    ------
+    Use ``_validate(cls, value: int) -> None:`` classmethod to create custom validator
+    """
+
+    def __new__(cls, value: int = 0) -> Self:
+        # Ensure the value is an integer
+        if not isinstance(value, int):
+            raise TypeError(f"{cls.__name__} must be initialized with an int, got {type(value).__name__}")
+        # Optional validation hook
+        cls._validate(value)
+        return int.__new__(cls, value)
+
+    @classmethod
+    def _validate(cls, value: int) -> None:
+        """Override in subclasses to add custom validation."""
+        pass
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({int(self)})"
+
+
+class PositiveInt(IntBase):
+    """Only allows positive int"""
+
+    @classmethod
+    @override
+    def _validate(cls, value: int) -> None:
+        if value < 0:
+            raise ValueError(f"{cls.__name__} must be non-negative")
+
+
+class NegativeInt(IntBase):
+    """Only allows negative int"""
+
+    @classmethod
+    @override
+    def _validate(cls, value: int) -> None:
+        if value >= 0:
+            raise ValueError(f"{cls.__name__} must be non-positive")
+
+
+class IntWithNote(IntBase):
+    """Int with additional note"""
+
+    def __new__(cls, value: int = 0) -> Self:
+        ins = super().__new__(cls, value)
+        ins.note = ""
+        return ins
+
+    def __repr__(self) -> str:
+        if self.note == "":
+            return f"{int(self)}"
+            # return super().__repr__()
+        return f"{self.__class__.__name__}({int(self)}, note={repr(self.note)})"
+
+    def add_note(self, note: str) -> None:
+        self.note = note