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

absfuyu/core/decorator.py

@@ -3,20 +3,24 @@ Absfuyu: Core
 -------------
 Decorator
 
-Version: 5.0.0
-Date updated: 22/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 14/03/2025 (dd/mm/yyyy)
 """
 
 # Module Package
 # ---------------------------------------------------------------------------
-__all__ = ["dummy_decorator", "dummy_decorator_with_args"]
+__all__ = [
+    "dummy_decorator",
+    "dummy_decorator_with_args",
+    "add_subclass_methods_decorator",
+]
 
 
 # Library
 # ---------------------------------------------------------------------------
 from collections.abc import Callable
 from functools import wraps
-from typing import ParamSpec, TypeVar, overload
+from typing import ParamSpec, TypeVar, cast, overload
 
 # Type
 # ---------------------------------------------------------------------------
@@ -52,8 +56,10 @@ def dummy_decorator_with_args(*args, **kwargs):
 
     @overload
     def decorator(obj: T) -> T: ...
+
     @overload
     def decorator(obj: Callable[P, R]) -> Callable[P, R]: ...
+
     def decorator(obj: Callable[P, R] | T) -> Callable[P, R] | T:
         if isinstance(obj, type):
             return obj
@@ -65,3 +71,63 @@ def dummy_decorator_with_args(*args, **kwargs):
         return wrapper
 
     return decorator
+
+
+def add_subclass_methods_decorator(cls: T) -> T:
+    """
+    Class decorator replace the ``__init_subclass__`` method.
+
+    This method populates a dictionary with subclass names as keys
+    and their available methods as values.
+
+    - Create 2 class attributes: ``_METHOD_INCLUDE`` (bool) and ``SUBCLASS_METHODS`` (dict[str, list[str]])
+    - Automatically add subclass methods to class variable: ``SUBCLASS_METHODS``
+    - Set class attribute ``_METHOD_INCLUDE`` to ``False`` to exclude from ``SUBCLASS_METHODS``
+
+    Example:
+    --------
+    >>> # Normal behavior
+    >>> @add_subclass_methods_decorator
+    >>> class TestParent: ...
+    >>> class TestChild(TestParent):
+    ...     def method1(self): ...
+    >>> TestChild.SUBCLASS_METHODS
+    {'__main__.TestChild': ['method1']}
+
+    >>> # Hidden from ``SUBCLASS_METHODS``
+    >>> @add_subclass_methods_decorator
+    >>> class TestParent: ...
+    >>> class TestChildHidden(TestParent):
+    ...     _METHOD_INCLUDE = False
+    ...     def method1(self): ...
+    >>> TestChildHidden.SUBCLASS_METHODS
+    {}
+    """
+
+    # Check for class
+    if not isinstance(cls, type):
+        raise ValueError("Object is not a class")
+
+    class AutoSubclassMixin:
+        _METHOD_INCLUDE: bool = True  # Include in SUBCLASS_METHODS
+        SUBCLASS_METHODS: dict[str, list[str]] = {}
+
+        def __init_subclass__(cls, *args, **kwargs) -> None:
+            """
+            This create a dictionary with:
+            - key   (str)      : Subclass
+            - value (list[str]): List of available methods
+            """
+            super().__init_subclass__(*args, **kwargs)
+
+            if cls._METHOD_INCLUDE and not any(
+                [x.endswith(cls.__name__) for x in cls.SUBCLASS_METHODS.keys()]
+            ):
+                methods_list: list[str] = [
+                    k for k, v in cls.__dict__.items() if callable(v)
+                ]
+                if len(methods_list) > 0:
+                    name = f"{cls.__module__}.{cls.__name__}"
+                    cls.SUBCLASS_METHODS.update({name: sorted(methods_list)})
+
+    return cast(T, type("AutoSubclass", (AutoSubclassMixin, cls), {}))

absfuyu/core/docstring.py

@@ -3,8 +3,8 @@ Absfuyu: Core
 -------------
 Sphinx docstring decorator
 
-Version: 5.0.0
-Date updated: 23/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 14/03/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -53,6 +53,24 @@ class SphinxDocstring:
     A class-based decorator to add a 'Version added',
     'Version changed', or 'Deprecated' note to a function's docstring,
     formatted for Sphinx documentation.
+
+    Parameters
+    ----------
+    version : str
+        The version in which the function was added, changed, or deprecated.
+
+    reason : str | None, optional
+        An optional reason or description for the change
+        or deprecation, by default ``None``
+
+    mode : SphinxDocstringMode, optional
+        Specifies whether the function was 'added', 'changed', or 'deprecated',
+        by default SphinxDocstringMode.ADDED
+
+
+    Usage
+    -----
+    Use this as a decorator (``@SphinxDocstring(<parameters>)``)
     """
 
     _LINEBREAK: ClassVar[str] = "\n\n"  # Use ClassVar for constant
@@ -75,7 +93,7 @@ class SphinxDocstring:
             An optional reason or description for the change
             or deprecation, by default ``None``
 
-        mode : SphinxDocstringMode | int, optional
+        mode : SphinxDocstringMode, optional
             Specifies whether the function was 'added', 'changed', or 'deprecated',
             by default SphinxDocstringMode.ADDED
 
@@ -87,38 +105,27 @@ class SphinxDocstring:
         self.reason = reason
         self.mode = mode
 
-    @overload
-    def __call__(self, obj: _T) -> _T: ...  # Class overload
+    @overload  # Class overload
+    def __call__(self, obj: _T) -> _T: ...
+
+    @overload  # Function overload
+    def __call__(self, obj: Callable[_P, _R]) -> Callable[_P, _R]: ...
 
-    @overload
-    def __call__(
-        self, obj: Callable[_P, _R]
-    ) -> Callable[_P, _R]: ...  # Function overload
     def __call__(self, obj: _T | Callable[_P, _R]) -> _T | Callable[_P, _R]:
+        """
+        Decorator for class and callable
+        """
+
         # Class wrapper
         if isinstance(obj, type):  # if inspect.isclass(obj):
-            obj.__doc__ = (obj.__doc__ or "") + self._generate_version_note(
-                num_of_white_spaces=self._calculate_white_space(obj.__doc__)
-            )
-            return obj
+            return self._update_doc(obj)
 
         # Function wrapper
         @wraps(obj)
         def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
             return obj(*args, **kwargs)
 
-        # Add docstring
-        # version_note = self._generate_version_note()
-        # if wrapper.__doc__ is None:
-        #     wrapper.__doc__ = version_note
-        # else:
-        #     wrapper.__doc__ += version_note
-
-        wrapper.__doc__ = (wrapper.__doc__ or "") + self._generate_version_note(
-            num_of_white_spaces=self._calculate_white_space(wrapper.__doc__)
-        )
-
-        return wrapper
+        return self._update_doc(wrapper)
 
     def _calculate_white_space(self, docs: str | None) -> int:
         """
@@ -158,6 +165,17 @@ class SphinxDocstring:
             reason=reason_str,
         )
 
+    @overload
+    def _update_doc(self, obj: _T) -> _T: ...
+    @overload
+    def _update_doc(self, obj: Callable[_P, _R]) -> Callable[_P, _R]: ...
+    def _update_doc(self, obj: _T | Callable[_P, _R]) -> _T | Callable[_P, _R]:
+        """Update docstring for an object"""
+        obj.__doc__ = (obj.__doc__ or "") + self._generate_version_note(
+            num_of_white_spaces=self._calculate_white_space(obj.__doc__)
+        )
+        return obj
+
 
 # Partial
 # ---------------------------------------------------------------------------

absfuyu/core/dummy_cli.py

@@ -3,8 +3,8 @@ Absfuyu: Core
 -------------
 Dummy cli
 
-Version: 5.0.0
-Date updated: 25/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 10/03/2025 (dd/mm/yyyy)
 """
 
 # Module Package

absfuyu/core/dummy_func.py

@@ -3,8 +3,8 @@ Absfuyu: Core
 -------------
 Dummy functions when other libraries are unvailable
 
-Version: 5.0.0
-Date updated: 22/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 13/03/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -12,6 +12,7 @@ Date updated: 22/02/2025 (dd/mm/yyyy)
 __all__ = [
     "tqdm",
     "unidecode",
+    "dummy_function",
 ]
 
 
@@ -25,7 +26,7 @@ from importlib import import_module
 try:
     _tqdm = import_module("tqdm")
     tqdm = getattr(_tqdm, "tqdm")  # noqa
-except (ModuleNotFoundError, AttributeError):
+except (ImportError, AttributeError):
 
     def tqdm(iterable, *args, **kwargs):
         """
@@ -39,7 +40,7 @@ except (ModuleNotFoundError, AttributeError):
 try:
     _unidecode = import_module("unidecode")
     unidecode = getattr(_unidecode, "unidecode")  # noqa
-except (ModuleNotFoundError, AttributeError):
+except (ImportError, AttributeError):
 
     def unidecode(*args, **kwargs):
         """
@@ -47,3 +48,13 @@ except (ModuleNotFoundError, AttributeError):
         install package ``unidecode`` to fully use this feature
         """
         return args[0]
+
+
+# dummy
+def dummy_function(*args, **kwargs):
+    """This is a dummy function"""
+    if args:
+        return args[0]
+    if kwargs:
+        return kwargs[list(kwargs)[0]]
+    return None

absfuyu/dxt/__init__.py

@@ -3,8 +3,8 @@ Absfuyu: Data Extension
 -----------------------
 Extension for data type such as ``list``, ``str``, ``dict``, ...
 
-Version: 5.0.0
-Date updated: 22/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 10/03/2025 (dd/mm/yyyy)
 
 Features:
 ---------

absfuyu/dxt/dictext.py

@@ -3,8 +3,8 @@ Absfuyu: Data Extension
 -----------------------
 dict extension
 
-Version: 5.0.0
-Date updated: 25/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 12/03/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -37,6 +37,9 @@ class DictAnalyzeResult(NamedTuple):
 class DictExt(ShowAllMethodsMixin, dict):
     """
     ``dict`` extension
+
+    >>> # For a list of new methods
+    >>> DictExt.show_all_methods()
     """
 
     @versionchanged("3.3.0", reason="Updated return type")

absfuyu/dxt/dxt_support.py

@@ -3,8 +3,8 @@ Absfuyu: Data Extension
 -----------------------
 Support classes
 
-Version: 5.0.0
-Date updated: 22/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 10/03/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: 25/02/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 12/03/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -18,7 +18,7 @@ import math
 from collections import Counter
 from typing import Any, Self
 
-from absfuyu.core import ShowAllMethodsMixin, versionchanged
+from absfuyu.core import ShowAllMethodsMixin, versionadded, versionchanged
 from absfuyu.dxt.dxt_support import DictBoolTrue
 
 
@@ -62,6 +62,9 @@ class Pow:
 class IntExt(ShowAllMethodsMixin, int):
     """
     ``int`` extension
+
+    >>> # For a list of new methods
+    >>> IntExt.show_all_methods()
     """
 
     # convert stuff
@@ -584,3 +587,31 @@ 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)]