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

absfuyu/core/baseclass2.py

@@ -3,8 +3,8 @@ Absfuyu: Core
 -------------
 Bases for other features (with library)
 
-Version: 5.0.0
-Date updated: 12/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -62,6 +62,47 @@ class ShowAllMethodsMixinInspectVer:
         return result
 
 
+class UniversalConfigMixin:
+    """
+    Universal config Mixin
+
+    This use these attributes:
+    - _instance_config
+    - config
+
+    Example:
+    --------
+    >>> class Test(UniversalConfigMixin):
+    >>>     DEFAULT_CONFIG = {"test": True}
+    >>> test = Test(config={"new_key": True})
+    >>> print(test.config)
+    {'test': True, 'new_key': True}
+    """
+
+    DEFAULT_CONFIG = {}
+
+    def __init__(self, **kwargs) -> None:
+        try:
+            super().__init__(**kwargs)
+        except TypeError:
+            pass
+        # instance override
+        self._instance_config = kwargs.get("config", {})
+
+    @property
+    def config(self):
+        # Priority: instance > class > default
+        merged = dict(self.DEFAULT_CONFIG)
+
+        try:
+            # merged.update(getattr(self, "CLASS_CONFIG", {}))
+            merged.update(self._instance_config)
+        except Exception:
+            pass
+
+        return merged
+
+
 # Metaclass
 # ---------------------------------------------------------------------------
 class PerformanceTrackingMeta(type):
@@ -71,7 +112,7 @@ class PerformanceTrackingMeta(type):
     Usage:
     ------
     >>> class Demo(metaclass=PerformanceTrackingMeta):
-    ...     def __init__(self):...
+    ...     def __init__(self): ...
     >>> Demo()
     --------------------------------------
     Class: Demo

absfuyu/core/decorator.py

@@ -3,20 +3,24 @@ Absfuyu: Core
 -------------
 Decorator
 
-Version: 5.0.0
-Date updated: 22/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/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: 13/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -28,9 +28,9 @@ from typing import ClassVar, ParamSpec, TypeVar, overload
 
 # Type
 # ---------------------------------------------------------------------------
-P = ParamSpec("P")  # Parameter type
-R = TypeVar("R")  # Return type - Can be anything
-T = TypeVar("T", bound=type)  # Type type - Can be any subtype of `type`
+_P = ParamSpec("_P")  # Parameter type
+_R = TypeVar("_R")  # Return type - Can be anything
+_T = TypeVar("_T", bound=type)  # Type type - Can be any subtype of `type`
 
 _SPHINX_DOCS_TEMPLATE = Template("$line_break*$mode in version $version$reason*")
 
@@ -46,6 +46,7 @@ class SphinxDocstringMode(Enum):
     ADDED = "Added"
     CHANGED = "Changed"
     DEPRECATED = "Deprecated"
+    PENDING_REMOVE = "Pending to remove"
 
 
 class SphinxDocstring:
@@ -53,6 +54,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 +94,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,35 +106,27 @@ class SphinxDocstring:
         self.reason = reason
         self.mode = mode
 
-    @overload
-    def __call__(self, obj: T) -> T: ...  # Class overload
-    @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]:
+    @overload  # Class overload
+    def __call__(self, obj: _T) -> _T: ...
+
+    @overload  # Function overload
+    def __call__(self, obj: Callable[_P, _R]) -> Callable[_P, _R]: ...
+
+    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:
+        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:
         """
@@ -127,19 +138,19 @@ class SphinxDocstring:
         if docs is None:
             return res
 
-        # # Index of the last whitespaces
-        # # https://stackoverflow.com/a/13649118
-        # res = next((i for i, c in enumerate(docs) if not c.isspace()), 0)
-        # return res if res % 2 == 0 else res - 1
-
-        # Alternative solution
-        for char in docs:
-            if char == " ":
-                res += 1
-            if char == "\t":
-                res += 4
-            if not char.isspace():
-                break
+        try:
+            # Replace tabs with space and split line
+            lines = docs.expandtabs(4).splitlines()
+        except UnicodeError:
+            return res
+        else:
+            # Get indentation of each line and unique it
+            indent_set = {len(line) - len(line.lstrip()) for line in lines[1:]}
+            # Drop 0
+            res_list = sorted([x for x in indent_set if x > 0])
+
+        if res_list:
+            return res_list[0]
         return res
 
     def _generate_version_note(self, num_of_white_spaces: int) -> str:
@@ -155,9 +166,21 @@ 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
 # ---------------------------------------------------------------------------
 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.0.0
-Date updated: 25/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+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.0.0
-Date updated: 14/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -12,6 +12,7 @@ Date updated: 14/02/2025 (dd/mm/yyyy)
 __all__ = [
     "tqdm",
     "unidecode",
+    "dummy_function",
 ]
 
 
@@ -23,8 +24,9 @@ from importlib import import_module
 # ---------------------------------------------------------------------------
 # tqdm wrapper
 try:
-    tqdm = import_module("tqdm").tqdm
-except ModuleNotFoundError:
+    _tqdm = import_module("tqdm")
+    tqdm = getattr(_tqdm, "tqdm")  # noqa
+except (ImportError, AttributeError):
 
     def tqdm(iterable, *args, **kwargs):
         """
@@ -36,8 +38,9 @@ except ModuleNotFoundError:
 
 # unidecode wrapper
 try:
-    unidecode = import_module("unidecode").unidecode
-except ModuleNotFoundError:
+    _unidecode = import_module("unidecode")
+    unidecode = getattr(_unidecode, "unidecode")  # noqa
+except (ImportError, AttributeError):
 
     def unidecode(*args, **kwargs):
         """
@@ -45,3 +48,13 @@ except ModuleNotFoundError:
         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: 11/01/2025 (dd/mm/yyyy)
+Version: 6.1.1
+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.1
+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