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

absfuyu/dxt/dictext.py

@@ -3,10 +3,12 @@ Absfuyu: Data Extension
 -----------------------
 dict extension
 
-Version: 5.0.0
-Date updated: 14/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
+from __future__ import annotations
+
 # Module Package
 # ---------------------------------------------------------------------------
 __all__ = ["DictExt", "DictAnalyzeResult"]
@@ -16,9 +18,20 @@ __all__ = ["DictExt", "DictAnalyzeResult"]
 # ---------------------------------------------------------------------------
 import operator
 from collections.abc import Callable
-from typing import Any, NamedTuple, Self
+from typing import Any, Literal, NamedTuple, Self, TypeVar, overload
+
+from absfuyu.core import GetClassMembersMixin, versionadded, versionchanged
+
+# from absfuyu.typings import KT as _KT
+# from absfuyu.typings import VT as _VT
 
-from absfuyu.core import ShowAllMethodsMixin, versionadded, versionchanged
+
+# Type
+# ---------------------------------------------------------------------------
+KT = TypeVar("KT")
+VT = TypeVar("VT")
+VT2 = TypeVar("VT2")
+R = TypeVar("R")  # Return type - Can be anything
 
 
 # Class
@@ -34,9 +47,12 @@ class DictAnalyzeResult(NamedTuple):
     min_list: list
 
 
-class DictExt(ShowAllMethodsMixin, dict):
+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()
     """
 
     @versionchanged("3.3.0", reason="Updated return type")
@@ -53,13 +69,7 @@ class DictExt(ShowAllMethodsMixin, dict):
 
         Example:
         --------
-        >>> test = DictExt({
-        ...     "abc": 9,
-        ...     "def": 9,
-        ...     "ghi": 8,
-        ...     "jkl": 1,
-        ...     "mno": 1
-        ... })
+        >>> 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)])
         """
@@ -101,9 +111,9 @@ class DictExt(ShowAllMethodsMixin, dict):
         {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, apply_to_value: bool = True) -> Self:
+    def apply(self, func: Callable[[Any], Any], apply_to_value: bool = True) -> Self:
         """
         Apply function to ``DictExt.keys()`` or ``DictExt.values()``
 
@@ -138,7 +148,7 @@ class DictExt(ShowAllMethodsMixin, dict):
     @versionadded("3.4.0")
     def aggregate(
         self,
-        other_dict: dict,
+        other_dict: dict[KT, VT],
         default_value: Any = 0,
         operator_func: Callable[[Any, Any], Any] = operator.add,  # operator add
     ) -> Self:
@@ -199,3 +209,181 @@ class DictExt(ShowAllMethodsMixin, dict):
                 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.0.0
-Date updated: 11/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+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.0.0
-Date updated: 11/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -15,10 +15,12 @@ __all__ = ["IntExt", "Pow"]
 # Library
 # ---------------------------------------------------------------------------
 import math
+from abc import ABC
 from collections import Counter
-from typing import Any, Self
+from typing import Any, Literal, Self, overload, override
 
-from absfuyu.core import ShowAllMethodsMixin, versionchanged
+from absfuyu.core.baseclass import GetClassMembersMixin
+from absfuyu.core.docstring import deprecated, versionadded, versionchanged
 from absfuyu.dxt.dxt_support import DictBoolTrue
 
 
@@ -32,20 +34,23 @@ class Pow:
         self.power_by = power_by
 
     def __str__(self) -> str:
+        return self.__repr__()
+
+    def __repr__(self) -> str:
         if self.power_by == 1:
             return str(self.number)
         else:
             return f"{self.number}^{self.power_by}"
         # return f"{self.__class__.__name__}({self.number}, {self.power_by})"
 
-    def __repr__(self) -> str:
-        return self.__str__()
-
     def to_list(self) -> list[int]:
         """
         Convert into list
 
-        :rtype: list[int | float]
+        Returns
+        -------
+        list[int | float]
+            list
         """
         return [self.number] * self.power_by  # type: ignore
 
@@ -53,18 +58,25 @@ class Pow:
         """
         Calculate the ``self.number`` to the power of ``self.power_by``
 
-        :rtype: float
+        Returns
+        -------
+        float
+            Result
         """
         # return self.number**self.power_by
         return math.pow(self.number, self.power_by)
 
 
-class IntExt(ShowAllMethodsMixin, int):
+class IntExt(GetClassMembersMixin, int):
     """
     ``int`` extension
+
+    >>> # For a list of new methods
+    >>> IntExt.show_all_methods()
     """
 
-    # convert stuff
+    # convert
+    @deprecated("5.4.0", reason="Use format(...) instead")
     def to_binary(self) -> str:
         """
         Convert to binary number
@@ -77,7 +89,7 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Example:
         --------
-        >>> test = IntNumber(10)
+        >>> test = IntExt(10)
         >>> test.to_binary()
         '1010'
         """
@@ -95,7 +107,7 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Example:
         --------
-        >>> test = IntNumber(10)
+        >>> test = IntExt(10)
         >>> test.to_celcius_degree()
         -12.222222222222221
         """
@@ -114,7 +126,7 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Example:
         --------
-        >>> test = IntNumber(10)
+        >>> test = IntExt(10)
         >>> test.to_fahrenheit_degree()
         50.0
         """
@@ -127,13 +139,13 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Returns
         -------
-        IntNumber
-            Reversed number
+        Self
+            Reversed number.
 
 
         Example:
         --------
-        >>> test = IntNumber(102)
+        >>> test = IntExt(102)
         >>> test.reverse()
         201
         """
@@ -381,13 +393,13 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Returns
         -------
-        IntNumber
-            Least common multiple
+        Self
+            Least common multiple.
 
 
         Example:
         --------
-        >>> test = IntNumber(102)
+        >>> test = IntExt(102)
         >>> test.lcm(5)
         510
         """
@@ -405,13 +417,13 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Returns
         -------
-        IntNumber
-            Greatest common divisor
+        Self
+            Greatest common divisor.
 
 
         Example:
         --------
-        >>> test = IntNumber(1024)
+        >>> test = IntExt(1024)
         >>> test.gcd(8)
         8
         """
@@ -430,28 +442,31 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Returns
         -------
-        IntNumber
-            IntNumber
+        Self
+            IntExt
 
 
         Example:
         --------
-        >>> test = IntNumber(119)
+        >>> test = IntExt(119)
         >>> test.add_to_one_digit()
         2
 
-        >>> test = IntNumber(119)
+        >>> test = IntExt(119)
         >>> test.add_to_one_digit(master_number=True)
         11
         """
+
         number = int(self)
-        if number < 0:
+        if number < 0:  # Convert positive
             number *= -1
+
         while len(str(number)) != 1:
             number = sum(map(int, str(number)))
             if master_number:
                 if number == 22 or number == 11:
                     break  # Master number
+
         return self.__class__(number)
 
     @versionchanged("5.0.0", reason="Removed ``short_form`` parameter")
@@ -467,7 +482,7 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Example:
         --------
-        >>> test = IntNumber(1024)
+        >>> test = IntExt(1024)
         >>> test.divisible_list()
         [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024]
         """
@@ -478,6 +493,12 @@ class IntExt(ShowAllMethodsMixin, int):
 
         return divi_list
 
+    @overload
+    def prime_factor(self) -> list[Pow]: ...  # type: ignore
+
+    @overload
+    def prime_factor(self, short_form: Literal[False] = ...) -> list[int]: ...
+
     def prime_factor(self, short_form: bool = True) -> list[int] | list[Pow]:
         """
         Prime factor
@@ -500,14 +521,15 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Example:
         --------
-        >>> test = IntNumber(1024)
+        >>> test = IntExt(1024)
         >>> test.prime_factor()
         [2^10]
 
-        >>> test = IntNumber(1024)
+        >>> test = IntExt(1024)
         >>> test.prime_factor(short_form=False)
         [2, 2, 2, 2, 2, 2, 2, 2, 2, 2]
         """
+
         # Generate list
         factors = []
         divisor = 2
@@ -530,7 +552,7 @@ class IntExt(ShowAllMethodsMixin, int):
     # analyze
     def analyze(self, short_form: bool = True) -> dict[str, dict[str, Any]]:
         """
-        Analyze the number with almost all ``IntNumber`` method
+        Analyze the number with almost all ``IntExt`` method
 
         Parameters
         ----------
@@ -546,7 +568,7 @@ class IntExt(ShowAllMethodsMixin, int):
 
         Example:
         --------
-        >>> test = IntNumber(1024)
+        >>> test = IntExt(1024)
         >>> test.analyze()
         {
             'summary': {'number': 1024, 'length': 4, 'even': True, 'prime factor': [2^10], 'divisible': [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024]},
@@ -559,7 +581,7 @@ class IntExt(ShowAllMethodsMixin, int):
                 "number": self,
                 "length": len(str(self)),
                 "even": self.is_even(),
-                "prime factor": self.prime_factor(short_form=short_form),
+                "prime factor": self.prime_factor(short_form=short_form),  # type: ignore[call-overload]
                 "divisible": self.divisible_list(),
             },
             "convert": {
@@ -584,3 +606,98 @@ class IntExt(ShowAllMethodsMixin, int):
 
         output["characteristic"] = characteristic
         return output  # type: ignore
+
+    @versionadded("5.1.0")
+    def split(self, parts: int) -> list[int]:
+        """
+        Evenly split the number into ``parts`` parts
+
+        Parameters
+        ----------
+        parts : int
+            Split by how many parts
+
+        Returns
+        -------
+        list[int]
+            List of evenly splitted numbers
+
+
+        Example:
+        --------
+        >>> IntExt(10).split(4)
+        [2, 2, 3, 3]
+        """
+        p = max(1, parts)
+        if p == 1:
+            return [int(self)]
+
+        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