danielutils 1.1.28__py3-none-any.whl

danielutils/decorators/overload.py

@@ -0,0 +1,204 @@
+import logging
+from typing import Callable, cast, Any, TypeVar, Dict, List
+import inspect
+import functools
+from ..reflection import is_function_annotated_properly
+from ..functions import isoftype, isoneof, isoneof_strict
+from ..exceptions import OverloadDuplication, OverloadNotFound
+from .deprecate import deprecate
+from ..versioned_imports import ParamSpec
+from ..logging_.utils import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+P = ParamSpec("P")
+FuncT = Callable[P, T]  # type:ignore
+T2 = TypeVar("T2")
+P2 = ParamSpec("P2")
+FuncT2 = Callable[P2, T2]  # type:ignore
+
+__overload_dict: Dict[str, Dict[tuple, Callable]] = {}
+
+
+@deprecate("'explicit_global_overload' is a legacy decorator please use 'overload' instead")
+def explicit_global_overload(*types) -> Callable:
+    """decorator for overloading functions\n
+    Usage\n-------\n
+    @overload(str,str)\n
+    def print_info(name,color):
+        ...\n\n
+    @overload(str,[int,float]))\n
+    def print_info(name,age):
+        ...\n\n
+
+    * use None to skip argument
+    * use no arguments to mark as default function
+    * you should overload in decreasing order of specificity! e.g
+    @overload(int) should appear in the code before @overload(Any)
+
+    \n\n\n
+    \nRaises:
+        OverloadDuplication: if a functions is overloaded twice (or more)
+        with same argument types
+        OverloadNotFound: if an overloaded function is called with
+        types that has no variant of the function
+
+    \nNotice:
+        The function's __doc__ will hold the value of the last variant only
+    """
+    # make sure to use unique global dictionary
+    if len(types) == 1 and type(types[0]).__name__ == "function":
+        raise ValueError("can't create an overload without defining types")
+    global __overload_dict
+    types = cast(tuple, types)
+    # allow input of both tuples and lists for flexibly
+    if len(types) > 0:
+        types_as_list = list(types)
+        for i, maybe_list_of_types in enumerate(types):
+            if isoneof(maybe_list_of_types, [list, tuple]):
+                types_as_list[i] = tuple(sorted(list(maybe_list_of_types),
+                                                key=lambda sub_type: sub_type.__name__))
+        types = tuple(types_as_list)
+
+    def deco(func: Callable) -> Callable:
+        if not callable(func):
+            raise TypeError("overload decorator must be used on a callable")
+
+        # assign current overload to overload dictionary
+        name = f"{func.__module__}.{func.__qualname__}"
+
+        if name not in __overload_dict:
+            __overload_dict[name] = {}
+
+        if types in __overload_dict[name]:
+            # raise if current overload already exists for current function
+            raise OverloadDuplication(
+                f"{name} has duplicate overloading for type(s): {types}")
+
+        __overload_dict[name][types] = func
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            default_func = None
+            # select correct overload
+            for variable_types, curr_func in __overload_dict[f"{func.__module__}.{func.__qualname__}"].items():
+                if len(variable_types) == 0:
+                    if default_func is None:
+                        default_func = curr_func
+                        continue
+                    # will not reach here because of duplicate overloading so this is redundant
+                    raise ValueError("Can't have two default functions")
+
+                if len(variable_types) != len(args):
+                    continue
+
+                for i, variable_type in enumerate(variable_types):
+                    if variable_type is not None:
+                        if isoneof(variable_type, [list, tuple]):
+                            if not isoneof_strict(args[i], variable_type):
+                                break
+                        else:
+                            if not isoftype(args[i], variable_type):
+                                break
+                else:
+                    return curr_func(*args, **kwargs)
+
+            if default_func is not None:
+                return default_func(*args, **kwargs)
+            # or raise exception if no overload exists for current arguments
+            raise OverloadNotFound(
+                f"function {func.__module__}.{func.__qualname__} is not overloaded with {[type(v) for v in args]}")
+
+        return wrapper
+
+    return deco
+
+
+class overload:
+    """this class create an object to manage the overloads for a given function.\n
+    will only match a specific resolution and won't infer best guess for types
+    """
+
+    __SKIP_SET = {"self", "cls", "args", "kwargs"}
+
+    def __init__(self, func: FuncT):
+        overload._validate(func)
+        self._qualname = func.__qualname__
+        self._moudle = func.__module__
+        self._functions: Dict[int, List[Callable]] = {}
+        self._functions[overload._get_key(func)] = [func]
+        functools.wraps(func)(self)
+
+    @staticmethod
+    def _get_key(func: Callable):
+        return len(inspect.signature(func).parameters)
+
+    @staticmethod
+    def _validate(func: Callable):
+        if not callable(func):
+            raise ValueError("Can only overload functions")
+        if not is_function_annotated_properly(func):
+            raise ValueError(
+                f"{func.__module__}.{func.__qualname__} is not properly annotated."
+                "\nFunction must be fully annotated to be overloaded")
+
+    def overload(self, func: FuncT2) -> "overload":
+        """will add another function to the list of available options
+
+        Args:
+            func (Callable): a new alternative function
+
+        Returns:
+            overload2: returns the overload object
+        """
+        self._validate(func)
+        k = overload._get_key(func)
+        if k not in self._functions:
+            self._functions[k] = []
+        self._functions[k].append(func)
+        return self
+
+    def __call__(self, *args, **kwargs):
+        num_args = len(args) + len(kwargs.keys())
+        if num_args not in self._functions:
+            raise AttributeError(
+                f"No overload with {num_args} argument found for {self._moudle}.{self._qualname}")
+
+        if num_args == 0:
+            return self._functions[num_args][0](*args, **kwargs)
+
+        max_score = 0
+        winner = self._functions[num_args][0]
+        EXACT_MATCH = 1 / num_args
+        SUBCLASS = 1 / num_args
+        for func in self._functions[num_args]:
+            score = 0
+            signature = inspect.signature(func)
+            for i, tup in enumerate(signature.parameters.items()):
+                param_name, param_type = tup
+                if param_name in overload.__SKIP_SET:
+                    continue
+
+                if type(args[i]) == param_type.annotation:  # pylint :disable=unidiomatic-typecheck
+                    score += EXACT_MATCH  # type:ignore
+
+                elif isoftype(args[i], param_type.annotation):
+                    score += SUBCLASS # type:ignore
+                else:
+                    break
+
+            else:
+                # reaching here means current function matches perfectly the annotation
+                if score > max_score:
+                    max_score = score
+                    winner = func
+        # raise AttributeError("No overload found")
+
+        return winner(*args, **kwargs)
+
+
+__all__ = [
+    "explicit_global_overload",
+    "overload"
+]

danielutils/decorators/partially_implemented.py

@@ -0,0 +1,32 @@
+from typing import Callable, Any, TypeVar
+import functools
+from .validate import validate
+from ..colors import warning
+from ..versioned_imports import ParamSpec
+
+T = TypeVar("T")
+P = ParamSpec("P")
+FuncT = Callable[P, T]  # type:ignore
+
+
+@validate  # type:ignore
+def PartiallyImplemented(func: FuncT) -> FuncT:
+    """decorator to mark function as not fully implemented for development purposes
+
+    Args:
+        func (Callable): the function to decorate
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs) -> Any:
+        warning(
+            f"As marked by the developer, {func.__module__}.{func.__qualname__} "
+            "may not be fully implemented and might not work properly.")
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+__all__ = [
+    "PartiallyImplemented"
+]

danielutils/decorators/processify.py

@@ -0,0 +1,74 @@
+import inspect
+import functools
+import multiprocessing
+import logging
+from typing import Any, Dict
+
+from ..reflection import get_prev_frame
+from ..abstractions.multiprogramming import process_id
+from ..logging_.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def processify(func):
+    """Modifies the function so that when calling it, a new process
+    will start to run it with provided arguments. Note that no return
+    value will be given.
+
+    Args:
+        func (Callable): the function to make a process
+
+    Returns:
+        Callable: the modified function
+    """
+    logger.debug("Creating processify decorator for function %s", func.__name__)
+    multiprocessing.freeze_support()
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        main_pid = kwargs.get("__main_pid", process_id())
+        current_pid = process_id()
+        logger.debug("Processify wrapper called for %s, main_pid=%s, current_pid=%s", func.__name__, main_pid, current_pid)
+        
+        if current_pid == main_pid:
+            logger.info("Starting new process for function %s", func.__name__)
+            frame = get_prev_frame(2)  # type:ignore
+            dct = {k: v for k, v in frame.f_globals.items() if type(v) != type(inspect)}   # type:ignore
+            logger.debug("Process context prepared with %s global variables", len(dct))
+            p = multiprocessing.Process(target=_run_func, args=(main_pid, dct, func.__name__, args, kwargs))
+            p.start()
+            logger.debug("Process started for %s, PID: %s", func.__name__, p.pid)
+            p.join()  # Optionally wait for the process to finish
+            logger.info("Process completed for %s", func.__name__)
+        else:
+            logger.debug("Executing %s in child process", func.__name__)
+            del kwargs["__main_pid"]
+            return func(*args, **kwargs)
+
+    logger.debug("Processify decorator applied to %s", func.__name__)
+    return wrapper
+
+
+def _run_func(main_pid: int, dct: dict, func_name: str, args, kwargs) -> None:
+    logger.debug("Running function %s in child process", func_name)
+    return dct[func_name](*args, __main_pid=main_pid, **kwargs)
+
+
+def debug_info(include_builtins: bool = False) -> Dict[str, Any]:
+    f = get_prev_frame(2)
+    if f is None:
+        raise RuntimeError("Failed to get frame")
+    g = {k: v for k, v in f.f_globals.items() if k != "__builtins__"} if not include_builtins else dict(f.f_globals)
+    return {
+        "file": f.f_code.co_filename,
+        "function": f.f_code.co_qualname,  # type:ignore
+        "line": f.f_lineno,
+        "globals": g,
+        "locals": dict(f.f_locals)
+    }
+
+
+__all__ = [
+    "processify"
+]

danielutils/decorators/property.py

@@ -0,0 +1,42 @@
+from typing import Any, Union
+
+
+class property2:
+    """my partial implementation to @property
+    """
+
+    def __init__(self, func):
+        self.gfunc = func
+        self.sfunc = None
+        self.dfunc = None
+
+    def setter(self, func):
+        """setter function
+        """
+        self.sfunc = func
+        return self
+
+    def deleter(self, func):
+        """deleter function"""
+        self.dfunc = func
+        return self
+
+    def __get__(self, instance: Any, owner: Union[type, None] = None) -> Any:
+        if callable(self.gfunc):
+            return self.gfunc(instance)
+        raise ValueError("Can't use unset getter function")
+
+    def __set__(self,  instance: Any, value: Any) -> None:
+        if callable(self.sfunc):
+            return self.sfunc(instance)
+        raise ValueError("Can't use unset getter function")
+
+    def __delete__(self, instance: Any) -> None:
+        if callable(self.dfunc):
+            return self.dfunc(instance)
+        raise ValueError("Can't use unset getter function")
+
+
+__all__ = [
+    "property2"
+]

danielutils/decorators/singleton.py

@@ -0,0 +1,59 @@
+import logging
+from ..logging_.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def singleton(og_class):
+    """Decorator that ensures a class has only one instance (Singleton pattern)."""
+    instance = None
+    original_new = getattr(og_class, '__new__')
+    original_init = getattr(og_class, '__init__')
+
+    def __new__(cls, *args, **kwargs):
+        nonlocal instance
+        if instance is None:
+            logger.debug("Creating singleton instance for %s", og_class.__name__)
+            # index 0 is the current class.
+            # in the minimal case index 1 has 'object' class
+            # otherwise the immediate parent of current class
+            cls_index, og_index = 0, list(cls.__mro__).index(og_class)
+            blacklist = {*cls.__mro__[:og_index + 1]}
+            for candidate in cls.__mro__[og_index + 1:]:
+                if candidate not in blacklist:
+                    try:
+                        instance = candidate.__new__(cls, *args, **kwargs)
+                        logger.debug("Successfully created singleton instance using %s", candidate.__name__)
+                        break
+                    except Exception as e:
+                        logger.debug("Failed to create instance using %s: %s", candidate.__name__, e)
+                        pass
+            else:
+                instance = object.__new__(cls)
+                logger.debug("Created singleton instance using object.__new__")
+        else:
+            logger.debug("Returning existing singleton instance for %s", og_class.__name__)
+        return instance
+
+    is_init: bool = False
+
+    def __init__(self, *args, **kwargs) -> None:
+        nonlocal is_init
+        if not is_init:
+            logger.debug("Initializing singleton instance for %s", og_class.__name__)
+            original_init(self, *args, **kwargs)
+            is_init = True
+            logger.info("Singleton instance initialized for %s", og_class.__name__)
+        else:
+            logger.debug("Singleton instance already initialized for %s", og_class.__name__)
+
+    setattr(og_class, "__new__", __new__)
+    setattr(og_class, "__init__", __init__)
+    setattr(og_class, "instance", lambda: instance)
+    logger.debug("Applied singleton decorator to %s", og_class.__name__)
+    return og_class
+
+
+__all__ = [
+    "singleton"
+]

danielutils/decorators/threadify.py

@@ -0,0 +1,40 @@
+import logging
+from typing import Callable, TypeVar
+import functools
+import threading
+from ..versioned_imports import ParamSpec
+from ..logging_.utils import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+P = ParamSpec("P")
+FuncT = Callable[P, T]  # type:ignore
+
+
+def threadify(func: FuncT) -> FuncT:
+    """will modify the function that when calling it a new thread
+    will start to run it with provided arguments.\nnote that no return value will be given
+
+    Args:
+        func (Callable): the function to make a thread
+
+    Returns:
+        Callable: the modified function
+    """
+    logger.debug("Creating threadify decorator for function %s", func.__name__)
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        logger.debug("Starting thread for function %s", func.__name__)
+        thread = threading.Thread(target=func, args=args, kwargs=kwargs)
+        thread.start()
+        logger.debug("Thread started for %s, thread_id=%s", func.__name__, thread.ident)
+
+    logger.debug("Threadify decorator applied to %s", func.__name__)
+    return wrapper
+
+
+__all__ = [
+    "threadify"
+]

danielutils/decorators/timeout.py

@@ -0,0 +1,82 @@
+import threading
+import functools
+import logging
+from typing import Callable, TypeVar, Union
+from .validate import validate
+from ..versioned_imports import ParamSpec
+from ..logging_.utils import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+P = ParamSpec("P")
+FuncT = Callable[P, T]  # type:ignore
+
+
+@validate  # type:ignore
+def timeout(duration: Union[int, float], silent: bool = False) -> Callable[[FuncT], FuncT]:
+    """A decorator to limit runtime for a function
+
+    Args:
+        duration (Union[int, float]): allowed runtime duration
+        silent (bool, optional): keyword only argument whether
+        to pass the exception up the call stack. Defaults to False.
+
+    Raises:
+        ValueError: if a function is not provided to be decorated
+        Exception: any exception from within the function
+
+    Returns:
+        Callable: the result decorated function
+    """
+    logger.debug("Creating timeout decorator with duration=%ss, silent=%s", duration, silent)
+
+    # https://stackoverflow.com/a/21861599/6416556
+    def timeout_deco(func: FuncT) -> FuncT:
+        logger.debug("Applying timeout decorator to function %s", func.__name__)
+        if not callable(func):
+            logger.error("Object %s is not callable", func)
+            raise ValueError("timeout must decorate a function")
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            logger.debug("Executing function %s with timeout %ss", func.__name__, duration)
+            res: list = [
+                TimeoutError(f'{func.__module__}.{func.__qualname__} timed out after {duration} seconds!')]
+
+            def timeout_wrapper() -> None:
+                try:
+                    logger.debug("Starting timeout thread for %s", func.__name__)
+                    res[0] = func(*args, **kwargs)
+                    logger.debug("Function %s completed successfully in timeout thread", func.__name__)
+                except Exception as function_error:  # pylint : disable=broad-exception-caught
+                    logger.warning("Function %s raised exception in timeout thread: %s: %s", func.__name__, type(function_error).__name__, function_error)
+                    res[0] = function_error
+
+            t = threading.Thread(target=timeout_wrapper, daemon=True)
+            try:
+                logger.debug("Starting timeout thread for %s", func.__name__)
+                t.start()
+                t.join(duration)
+                logger.debug("Timeout thread for %s completed or timed out", func.__name__)
+            except Exception as thread_error:
+                logger.error("Thread error for %s: %s: %s", func.__name__, type(thread_error).__name__, thread_error)
+                raise thread_error
+            if isinstance(res[0], BaseException):
+                if not silent:
+                    logger.warning("Function %s timed out or raised exception: %s", func.__name__, type(res[0]).__name__)
+                    raise res[0]
+                logger.debug("Function %s timed out but silent mode enabled", func.__name__)
+                return None
+            logger.debug("Function %s completed successfully within timeout", func.__name__)
+            return res[0]
+
+        logger.debug("Timeout decorator applied to %s", func.__name__)
+        return wrapper
+
+    return timeout_deco
+
+
+__all__ = [
+    "timeout"
+]

danielutils/decorators/total_ordering.py

@@ -0,0 +1,82 @@
+from typing import Callable, Any, Dict, List, Tuple
+
+
+def is_default_implementation(func: Callable) -> bool:
+    return type(func).__qualname__ == "wrapper_descriptor"
+
+
+def usable(func: Callable) -> bool:
+    return func is not None and not is_default_implementation(func)
+
+
+def total_ordering(cls: type) -> type:
+    funcs: Dict[str, Callable[[Any, Any], Any]] = {
+        '__eq__': getattr(cls, '__eq__'),
+        '__ne__': getattr(cls, '__ne__'),
+        '__gt__': getattr(cls, '__gt__'),
+        '__ge__': getattr(cls, '__ge__'),
+        '__lt__': getattr(cls, '__lt__'),
+        '__le__': getattr(cls, '__le__'),
+    }
+    g1: List[Callable[[Any, Any], Any]] = [funcs["__eq__"], funcs["__ne__"]]
+    u1 = any(map(usable, g1))
+    g2: List[Callable[[Any, Any], Any]] = [funcs["__ge__"], funcs["__gt__"]]
+    u2 = any(map(usable, g2))
+    g3: List[Callable[[Any, Any], Any]] = [funcs["__lt__"], funcs["__le__"]]
+    u3 = any(map(usable, g3))
+    if sum(map(int, [u1, u2, u3])) < 2:
+        raise ValueError("There are not enough functions from different groups implemented")
+    mapping: Dict[str, Dict[Tuple, Callable]] = {
+        '__eq__': {
+            # a==b <=> not a!=b
+            ('__ne__',): lambda self, other: not funcs['__eq__'](self, other),
+            # a==b <=> a<=b and b<=a
+            ('__le__',): lambda self, other: funcs['__le__'](self, other) and funcs['__le__'](other, self),
+            # a==b <=> a>=b and b>=a
+            # a==b <=> not a<b and not b<a
+            # a==b <=> not a>b and not b>a
+            # a==b <=> a<=b and not a<b
+            ('__le__', '__lt__'): lambda self, other: funcs['__le__'](self, other) and not funcs['__lt__'](self, other),
+            # a==b <=> a>=b and not a>b
+            ('__ge__', '__ge__'): lambda self, other: funcs['__ge__'](self, other) and not funcs['__gt__'](self, other),
+            # a==b <=> a<=b and not a>=b
+            ('__le__', '__ge__'): lambda self, other: funcs['__ge__'](self, other) and funcs['__le__'](self, other),
+            # not a<b and not b>a
+            ('__lt__', '__gt__'): lambda self, other: not funcs['__lt__'](self, other) and not funcs['__gt__'](other,
+                                                                                                               self),
+        },
+        '__ne__': {
+            ('__eq__',): lambda self, other: not funcs['__eq__'](self, other),
+        },
+        '__lt__': {
+            ('__ge__',): lambda self, other: not funcs['__ge__'](self, other),
+            ('__eq__', '__le__'): lambda self, other: funcs['__le__'](self, other) and not funcs['__eq__'](self, other),
+        },
+        '__le__': {
+            ('__gt__',): lambda self, other: not funcs['__gt__'](self, other),
+            ('__eq__', '__lt__'): lambda self, other: funcs['__lt__'](self, other) or funcs['__eq__'](self, other),
+        },
+        '__gt__': {
+            ('__le__',): lambda self, other: not funcs['__le__'](self, other),
+            ('__eq__', '__ge__'): lambda self, other: funcs['__ge__'](self, other) and not funcs['__eq__'](self, other),
+        },
+        '__ge__': {
+            ('__lt__',): lambda self, other: not funcs['__lt__'](self, other),
+            ('__eq__', '__gt__'): lambda self, other: funcs['__gt__'](self, other) or funcs['__eq__'](self, other),
+        },
+    }
+    for name, f in funcs.items():
+        if usable(f):
+            continue
+        for option, implementation in mapping[name].items():
+            if all(map(usable, (funcs[dep] for dep in option))):
+                funcs[name] = implementation
+                break
+    for name, f in funcs.items():
+        setattr(cls, name, f)
+    return cls
+
+
+__all__ = [
+    "total_ordering"
+]