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

absfuyu/core/baseclass.py

@@ -0,0 +1,299 @@
+"""
+Absfuyu: Core
+-------------
+Bases for other features
+
+Version: 5.0.0
+Date updated: 12/02/2025 (dd/mm/yyyy)
+"""
+
+# Module Package
+# ---------------------------------------------------------------------------
+__all__ = [
+    # Color
+    "CLITextColor",
+    # Mixins
+    "ShowAllMethodsMixin",
+    "AutoREPRMixin",
+    # Class
+    "BaseClass",
+    # Metaclass
+    "PositiveInitArgsMeta",
+]
+
+
+# Color
+# ---------------------------------------------------------------------------
+class CLITextColor:
+    """Color code for text in terminal"""
+
+    WHITE = "\x1b[37m"
+    BLACK = "\x1b[30m"
+    BLUE = "\x1b[34m"
+    GRAY = "\x1b[90m"
+    GREEN = "\x1b[32m"
+    RED = "\x1b[91m"
+    DARK_RED = "\x1b[31m"
+    MAGENTA = "\x1b[35m"
+    YELLOW = "\x1b[33m"
+    RESET = "\x1b[39m"
+
+
+# Mixins
+# ---------------------------------------------------------------------------
+class ShowAllMethodsMixin:
+    """
+    Show all methods of the class and its parent class minus ``object`` class
+
+    *This class is meant to be used with other class*
+    """
+
+    @classmethod
+    def show_all_methods(
+        cls,
+        include_classmethod: bool = True,
+        classmethod_indicator: str = "<classmethod>",
+        include_staticmethod: bool = True,
+        staticmethod_indicator: str = "<staticmethod>",
+        include_private_method: bool = False,
+        print_result: bool = False,
+    ) -> dict[str, list[str]]:
+        """
+        Class method to display all methods of the class and its parent classes,
+        including the class in which they are defined in alphabetical order.
+
+        Parameters
+        ----------
+        include_classmethod : bool, optional
+            Whether to include classmethod in the output, by default ``True``
+
+        classmethod_indicator : str, optional
+            A string used to mark classmethod in the output. This string is appended
+            to the name of each classmethod to visually differentiate it from regular
+            instance methods, by default ``"<classmethod>"``
+
+        include_staticmethod : bool, optional
+            Whether to include staticmethod in the output, by default ``True``
+
+        staticmethod_indicator : str, optional
+            A string used to mark staticmethod in the output. This string is appended
+            to the name of each staticmethod to visually differentiate it from regular
+            instance methods, by default ``"<staticmethod>"``
+
+        include_private_method : bool, optional
+            Whether to include private method in the output, by default ``False``
+
+        print_result : bool, optional
+            Beautifully print the output, by default ``False``
+
+        Returns
+        -------
+        dict[str, list[str]]
+            A dictionary where keys are class names and values are lists of method names.
+        """
+        classes = cls.__mro__[::-1][1:]  # MRO in reverse order
+        result = {}
+        for base in classes:
+            methods = []
+            for name, attr in base.__dict__.items():
+                # Skip private attribute
+                if name.startswith("__"):
+                    continue
+
+                # Skip private Callable
+                if base.__name__ in name and not include_private_method:
+                    continue
+
+                # Function
+                if callable(attr):
+                    if isinstance(attr, staticmethod):
+                        if include_staticmethod:
+                            methods.append(f"{name} {staticmethod_indicator}")
+                    else:
+                        methods.append(name)
+                if isinstance(attr, classmethod) and include_classmethod:
+                    methods.append(f"{name} {classmethod_indicator}")
+
+            if methods:
+                result[base.__name__] = sorted(methods)
+
+        if print_result:
+            cls.__print_show_all_result(result)
+
+        return result
+
+    @classmethod
+    def show_all_properties(cls, print_result: bool = False) -> dict[str, list[str]]:
+        """
+        Class method to display all properties of the class and its parent classes,
+        including the class in which they are defined in alphabetical order.
+
+        Parameters
+        ----------
+        print_result : bool, optional
+            Beautifully print the output, by default ``False``
+
+        Returns
+        -------
+        dict[str, list[str]]
+            A dictionary where keys are class names and values are lists of property names.
+        """
+        classes = cls.__mro__[::-1][1:]  # MRO in reverse order
+        result = {}
+        for base in classes:
+            properties = []
+            for name, attr in base.__dict__.items():
+                # Skip private attribute
+                if name.startswith("__"):
+                    continue
+
+                if isinstance(attr, property):
+                    properties.append(name)
+
+            if properties:
+                result[base.__name__] = sorted(properties)
+
+        if print_result:
+            cls.__print_show_all_result(result)
+
+        return result
+
+    @staticmethod
+    def __print_show_all_result(result: dict[str, list[str]]) -> None:
+        """
+        Pretty print the result of ``ShowAllMethodsMixin.show_all_methods()``
+
+        Parameters
+        ----------
+        result : dict[str, list[str]]
+            Result of ``ShowAllMethodsMixin.show_all_methods()``
+        """
+        print_func = print  # Can be extended with function parameter
+
+        # Loop through each class base
+        for order, (class_base, methods) in enumerate(result.items(), start=1):
+            mlen = len(methods)  # How many methods in that class
+            print_func(f"{order:02}. <{class_base}> | len: {mlen:02}")
+
+            # Modify methods list
+            max_method_name_len = max([len(x) for x in methods])
+            if mlen % 2 == 0:
+                p1, p2 = methods[: int(mlen / 2)], methods[int(mlen / 2) :]
+            else:
+                p1, p2 = methods[: int(mlen / 2) + 1], methods[int(mlen / 2) + 1 :]
+                p2.append("")
+            new_methods = list(zip(p1, p2))
+
+            # This print 2 methods in 1 line
+            for x1, x2 in new_methods:
+                if x2 == "":
+                    print_func(f"    - {x1.ljust(max_method_name_len)}")
+                else:
+                    print_func(
+                        f"    - {x1.ljust(max_method_name_len)}    - {x2.ljust(max_method_name_len)}"
+                    )
+
+            # This print 1 method in one line
+            # for name in methods:
+            #     print(f"    - {name.ljust(max_method_name_len)}")
+
+            print_func("".ljust(88, "-"))
+
+
+class AutoREPRMixin:
+    """
+    Generate ``repr()`` output as ``<class(param1=any, param2=any, ...)>``
+
+    *This class is meant to be used with other class*
+
+
+    Example:
+    --------
+    >>> class Test(AutoREPRMixin):
+    ...     def __init__(self, param):
+    ...         self.param = param
+    >>> print(repr(Test(1)))
+    Test(param=1)
+    """
+
+    def __repr__(self) -> str:
+        """
+        Generate a string representation of the instance's attributes.
+
+        This function retrieves attributes from either the ``__dict__`` or
+        ``__slots__`` of the instance, excluding private attributes (those
+        starting with an underscore). The attributes are returned as a
+        formatted string, with each attribute represented as ``"key=value"``.
+
+        Convert ``self.__dict__`` from ``{"a": "b"}`` to ``a=repr(b)``
+        or ``self.__slots__`` from ``("a",)`` to ``a=repr(self.a)``
+        (excluding private attributes)
+        """
+        # Default output
+        out = []
+        sep = ", "  # Separator
+
+        # Get attributes
+        cls_dict = getattr(self, "__dict__", None)
+        cls_slots = getattr(self, "__slots__", None)
+
+        # Check if __dict__ exist and len(__dict__) > 0
+        if cls_dict is not None and len(cls_dict) > 0:
+            out = [
+                f"{k}={repr(v)}"
+                for k, v in self.__dict__.items()
+                if not k.startswith("_")
+            ]
+
+        # Check if __slots__ exist and len(__slots__) > 0
+        elif cls_slots is not None and len(cls_slots) > 0:
+            out = [
+                f"{x}={repr(getattr(self, x))}"
+                for x in self.__slots__  # type: ignore
+                if not x.startswith("_")
+            ]
+
+        # Return out
+        return f"{self.__class__.__name__}({sep.join(out)})"
+
+
+# Class
+# ---------------------------------------------------------------------------
+class BaseClass(ShowAllMethodsMixin, AutoREPRMixin):
+    """Base class"""
+
+    def __str__(self) -> str:
+        return repr(self)
+
+    def __format__(self, format_spec: str) -> str:
+        """
+        Formats the object according to the specified format.
+        If no format_spec is provided, returns the object's string representation.
+        (Currently a dummy function)
+
+        Usage
+        -----
+        >>> print(f"{<object>:<format_spec>}")
+        >>> print(<object>.__format__(<format_spec>))
+        >>> print(format(<object>, <format_spec>))
+        """
+
+        return self.__str__()
+
+
+# Metaclass
+# ---------------------------------------------------------------------------
+class PositiveInitArgsMeta(type):
+    """Make sure that every args in a class __init__ is positive"""
+
+    def __call__(cls, *args, **kwargs):
+        # Check if all positional and keyword arguments are positive
+        for arg in args:
+            if isinstance(arg, (int, float)) and arg < 0:
+                raise ValueError(f"Argument {arg} must be positive")
+        for key, value in kwargs.items():
+            if isinstance(value, (int, float)) and value < 0:
+                raise ValueError(f"Argument {key}={value} must be positive")
+
+        # Call the original __init__ method
+        return super().__call__(*args, **kwargs)

absfuyu/core/baseclass2.py

@@ -0,0 +1,165 @@
+"""
+Absfuyu: Core
+-------------
+Bases for other features (with library)
+
+Version: 5.0.0
+Date updated: 12/02/2025 (dd/mm/yyyy)
+"""
+
+# Module Package
+# ---------------------------------------------------------------------------
+__all__ = [
+    # Class
+    "ShowAllMethodsMixinInspectVer",
+    # Metaclass
+    "PerformanceTrackingMeta",
+    # Class decorator
+    "positive_class_init_args",
+]
+
+
+# Library
+# ---------------------------------------------------------------------------
+import time
+import tracemalloc
+from collections.abc import Callable
+from functools import wraps
+from inspect import getmro, isfunction
+from types import MethodType
+from typing import Any, ParamSpec, TypeVar
+
+# Type
+# ---------------------------------------------------------------------------
+P = ParamSpec("P")  # Parameter type
+T = TypeVar("T", bound=type)  # Type type - Can be any subtype of `type`
+# R = TypeVar("R")  # Return type
+
+
+# Class
+# ---------------------------------------------------------------------------
+class ShowAllMethodsMixinInspectVer:
+    @classmethod
+    def show_all_methods(
+        cls,
+        include_classmethod: bool = True,
+        classmethod_indicator: str = "<classmethod>",
+    ) -> dict[str, list[str]]:
+        result = {}
+        for base in getmro(cls)[::-1]:
+            methods = []
+            # for name, attr in inspect.getmembers(base, predicate=callable):
+            for name, attr in base.__dict__.items():
+                if name.startswith("__"):
+                    continue
+                if isfunction(attr):
+                    methods.append(name)
+                # if inspect.ismethod(attr):
+                if isinstance(attr, (classmethod, MethodType)) and include_classmethod:
+                    methods.append(f"{name} {classmethod_indicator}")
+            if methods:
+                result[base.__name__] = sorted(methods)
+        return result
+
+
+# Metaclass
+# ---------------------------------------------------------------------------
+class PerformanceTrackingMeta(type):
+    """
+    A metaclass that tracks the instantiation time of classes.
+
+    Usage:
+    ------
+    >>> class Demo(metaclass=PerformanceTrackingMeta):
+    ...     def __init__(self):...
+    >>> Demo()
+    --------------------------------------
+    Class: Demo
+    Memory usage:            0.000000 MB
+    Peak memory usage:       0.000008 MB
+    Time elapsed:            0.000001 s
+    --------------------------------------
+    """
+
+    def __new__(mcs, name: str, bases: tuple, attrs: dict[str, Any]):
+        """
+        Intercepts class creation to wrap the ``__init__`` method.
+
+        Parameters
+        ----------
+        mcs
+            The metaclass
+
+        name : str
+            The class name
+
+        bases : tuple
+            Tuple of base classes
+
+        attrs : dict[str, Any]
+            Dictionary of attributes
+        """
+        if "__init__" in attrs:
+            original_init = attrs["__init__"]
+
+            @wraps(original_init)
+            def wrapped_init(self, *args, **kwargs):
+                # Performance check
+                tracemalloc.start()
+                start_time = time.perf_counter()
+
+                # Run __init__()
+                original_init(self, *args, **kwargs)
+
+                # Performance stop
+                current, peak = tracemalloc.get_traced_memory()
+                end_time = time.perf_counter()
+                tracemalloc.stop()
+                creation_time = end_time - start_time
+
+                # Print output
+                print(
+                    f"{''.ljust(38, '-')}\n"
+                    f"Class: {name}\n"
+                    f"Memory usage:\t\t {current / 10**6:,.6f} MB\n"
+                    f"Peak memory usage:\t {peak / 10**6:,.6f} MB\n"
+                    f"Time elapsed:\t\t {creation_time:,.6f} s\n"
+                    f"{''.ljust(38, '-')}"
+                )
+
+            attrs["__init__"] = wrapped_init
+        return super().__new__(mcs, name, bases, attrs)
+
+
+# Decorator
+# ---------------------------------------------------------------------------
+def positive_class_init_args(cls: T):
+    """
+    A class decorator that ensures all arguments in the ``__init__()`` method are positive.
+    """
+    # original_init: Callable[P, None] | None = getattr(cls, "__init__", None)
+    # if original_init is None:
+    #     return cls
+    try:
+        original_init: Callable[P, None] = cls.__init__  # type: ignore
+    except AttributeError:
+        return cls
+
+    @wraps(original_init)
+    def new_init(self, *args: P.args, **kwargs: P.kwargs):
+        # Check if all positional arguments are positive
+        for arg in args:
+            if isinstance(arg, (int, float)) and arg < 0:
+                raise ValueError(f"Argument {arg} must be positive")
+
+        # Check if all keyword arguments are positive
+        for key, value in kwargs.items():
+            if isinstance(value, (int, float)) and value < 0:
+                raise ValueError(f"Argument {key}={value} must be positive")
+
+        # Call the original __init__ method
+        original_init(self, *args, **kwargs)
+
+    # setattr(cls, "__init__", new_init)
+    cls.__init__ = new_init  # type: ignore
+    return cls

absfuyu/core/decorator.py

@@ -0,0 +1,67 @@
+"""
+Absfuyu: Core
+-------------
+Decorator
+
+Version: 5.0.0
+Date updated: 22/02/2025 (dd/mm/yyyy)
+"""
+
+# Module Package
+# ---------------------------------------------------------------------------
+__all__ = ["dummy_decorator", "dummy_decorator_with_args"]
+
+
+# Library
+# ---------------------------------------------------------------------------
+from collections.abc import Callable
+from functools import wraps
+from typing import 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`
+
+
+# Decorator
+# ---------------------------------------------------------------------------
+@overload
+def dummy_decorator(obj: T) -> T: ...
+@overload
+def dummy_decorator(obj: Callable[P, R]) -> Callable[P, R]: ...
+def dummy_decorator(obj: Callable[P, R] | T) -> Callable[P, R] | T:
+    """
+    This is a decorator that does nothing. Normally used as a placeholder
+    """
+    if isinstance(obj, type):
+        return obj
+
+    @wraps(obj)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return obj(*args, **kwargs)
+
+    return wrapper
+
+
+def dummy_decorator_with_args(*args, **kwargs):
+    """
+    This is a decorator with args and kwargs that does nothing. Normally used as a placeholder
+    """
+
+    @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
+
+        @wraps(obj)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            return obj(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

absfuyu/core/docstring.py

@@ -0,0 +1,163 @@
+"""
+Absfuyu: Core
+-------------
+Sphinx docstring decorator
+
+Version: 5.0.0
+Date updated: 13/02/2025 (dd/mm/yyyy)
+"""
+
+# Module Package
+# ---------------------------------------------------------------------------
+__all__ = [
+    "SphinxDocstring",
+    "SphinxDocstringMode",
+    "versionadded",
+    "versionchanged",
+    "deprecated",
+]
+
+
+# Library
+# ---------------------------------------------------------------------------
+from collections.abc import Callable
+from enum import Enum
+from functools import partial, wraps
+from string import Template
+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`
+
+_SPHINX_DOCS_TEMPLATE = Template("$line_break*$mode in version $version$reason*")
+
+
+# Class
+# ---------------------------------------------------------------------------
+class SphinxDocstringMode(Enum):
+    """
+    Enum representing the mode of the version change
+    (added, changed, or deprecated)
+    """
+
+    ADDED = "Added"
+    CHANGED = "Changed"
+    DEPRECATED = "Deprecated"
+
+
+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.
+    """
+
+    _LINEBREAK: ClassVar[str] = "\n\n"  # Use ClassVar for constant
+
+    def __init__(
+        self,
+        version: str,
+        reason: str | None = None,
+        mode: SphinxDocstringMode = SphinxDocstringMode.ADDED,
+    ) -> None:
+        """
+        Initializes the SphinxDocstring decorator.
+
+        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 | int, optional
+            Specifies whether the function was 'added', 'changed', or 'deprecated',
+            by default SphinxDocstringMode.ADDED
+
+        Usage
+        -----
+        Use this as a decorator (``@SphinxDocstring(<parameters>)``)
+        """
+        self.version = version
+        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]:
+        # 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
+
+        # 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
+
+    def _calculate_white_space(self, docs: str | None) -> int:
+        """
+        Calculates the number of leading white spaces
+        in __doc__ of original function
+        """
+
+        res = 0
+        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
+        return res
+
+    def _generate_version_note(self, num_of_white_spaces: int) -> str:
+        """
+        Generates the version note string based on the mode
+        """
+        reason_str = f": {self.reason}" if self.reason else ""
+        # return f"{self._LINEBREAK}*{self.mode.value} in version {self.version}{reason_str}*"
+        return _SPHINX_DOCS_TEMPLATE.substitute(
+            line_break=self._LINEBREAK + " " * num_of_white_spaces,
+            mode=self.mode.value,
+            version=self.version,
+            reason=reason_str,
+        )
+
+
+# Partial
+# ---------------------------------------------------------------------------
+versionadded = partial(SphinxDocstring, mode=SphinxDocstringMode.ADDED)
+versionchanged = partial(SphinxDocstring, mode=SphinxDocstringMode.CHANGED)
+deprecated = partial(SphinxDocstring, mode=SphinxDocstringMode.DEPRECATED)