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

absfuyu/core/baseclass2.py

@@ -0,0 +1,165 @@
+"""
+Absfuyu: Core
+-------------
+Bases for other features (with library)
+
+Version: 5.0.0
+Date updated: 25/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,166 @@
+"""
+Absfuyu: Core
+-------------
+Sphinx docstring decorator
+
+Version: 5.0.0
+Date updated: 23/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
+
+        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:
+        """
+        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)

absfuyu/core/dummy_cli.py

@@ -0,0 +1,67 @@
+"""
+Absfuyu: Core
+-------------
+Dummy cli
+
+Version: 5.0.0
+Date updated: 25/02/2025 (dd/mm/yyyy)
+"""
+
+# Module Package
+# ---------------------------------------------------------------------------
+__all__ = ["cli"]
+
+
+# Library
+# ---------------------------------------------------------------------------
+import sys
+from argparse import ArgumentDefaultsHelpFormatter, ArgumentParser
+
+from absfuyu import __title__, __version__
+
+
+# Function
+# ---------------------------------------------------------------------------
+def get_parser(
+    name: str | None = None,
+    description: str | None = None,
+    epilog: str | None = None,
+    *,
+    version: str = "",
+    add_help: bool = True,
+    add_logging: bool = True,
+) -> ArgumentParser:
+    arg_parser = ArgumentParser(
+        prog=name,
+        description=description,
+        epilog=epilog,
+        add_help=add_help,
+        formatter_class=ArgumentDefaultsHelpFormatter,
+        # allow_abbrev=False, # Disable long options recognize
+        # exit_on_error=True
+    )
+    arg_parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {version}"
+    )
+    if add_logging:
+        _ll_val = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        arg_parser.add_argument(
+            "--log-level",
+            metavar="LOG_LEVEL",
+            dest="log_level",
+            choices=_ll_val,
+            default="INFO",
+            help=f"Log level: {_ll_val}",
+        )
+    return arg_parser
+
+
+def cli() -> None:
+    desc = "This is a dummy cli, please install <click> and <colorama> package to use this feature"
+    arg_parser = get_parser(
+        name=__title__,
+        description=desc,
+        version=__version__,
+        add_logging=False,
+    )
+    args = arg_parser.parse_args(args=None if sys.argv[1:] else ["--help"])  # noqa

absfuyu/core/dummy_func.py

@@ -0,0 +1,49 @@
+"""
+Absfuyu: Core
+-------------
+Dummy functions when other libraries are unvailable
+
+Version: 5.0.0
+Date updated: 22/02/2025 (dd/mm/yyyy)
+"""
+
+# Module Package
+# ---------------------------------------------------------------------------
+__all__ = [
+    "tqdm",
+    "unidecode",
+]
+
+
+# Library
+# ---------------------------------------------------------------------------
+from importlib import import_module
+
+# Wrapper
+# ---------------------------------------------------------------------------
+# tqdm wrapper
+try:
+    _tqdm = import_module("tqdm")
+    tqdm = getattr(_tqdm, "tqdm")  # noqa
+except (ModuleNotFoundError, AttributeError):
+
+    def tqdm(iterable, *args, **kwargs):
+        """
+        Dummy tqdm function,
+        install package ``tqdm`` to fully use this feature
+        """
+        return iterable
+
+
+# unidecode wrapper
+try:
+    _unidecode = import_module("unidecode")
+    unidecode = getattr(_unidecode, "unidecode")  # noqa
+except (ModuleNotFoundError, AttributeError):
+
+    def unidecode(*args, **kwargs):
+        """
+        Dummy unidecode function,
+        install package ``unidecode`` to fully use this feature
+        """
+        return args[0]

absfuyu/dxt/__init__.py

@@ -0,0 +1,42 @@
+"""
+Absfuyu: Data Extension
+-----------------------
+Extension for data type such as ``list``, ``str``, ``dict``, ...
+
+Version: 5.0.0
+Date updated: 22/02/2025 (dd/mm/yyyy)
+
+Features:
+---------
+- DictExt
+- IntExt
+- ListExt
+- Text
+"""
+
+# Module Package
+# ---------------------------------------------------------------------------
+__all__ = [
+    # Main
+    "DictExt",
+    "IntExt",
+    "ListExt",
+    "Text",
+    # Support
+    "DictAnalyzeResult",
+    "DictBoolFalse",
+    "DictBoolTrue",
+    "ListNoDunder",
+    "ListREPR",
+    "Pow",
+    "TextAnalyzeDictFormat",
+]
+
+
+# Library
+# ---------------------------------------------------------------------------
+from absfuyu.dxt.dictext import DictAnalyzeResult, DictExt
+from absfuyu.dxt.dxt_support import DictBoolFalse, DictBoolTrue, ListNoDunder, ListREPR
+from absfuyu.dxt.intext import IntExt, Pow
+from absfuyu.dxt.listext import ListExt
+from absfuyu.dxt.strext import Text, TextAnalyzeDictFormat