danielutils 1.1.28__py3-none-any.whl

danielutils/date_time.py

@@ -0,0 +1,23 @@
+from datetime import datetime, timezone
+
+
+def get_datetime() -> datetime:
+    """return the current datetime
+
+    Returns:
+        datetime: current datetime
+    """
+    return datetime.now()
+
+def utc_now() -> datetime:
+    """return the current datetime in UTC
+
+    Returns:
+        datetime: current datetime in UTC
+    """
+    return datetime.now(timezone.utc)
+
+__all__ = [
+    "get_datetime",
+    "utc_now"
+]

danielutils/decorators/__init__.py

@@ -0,0 +1,18 @@
+from .validate import *
+from .atomic import *
+from .attach import *
+from .decorate_conditionally import *
+from .limit_recursion import *
+from .memo import *
+from .overload import *
+from .partially_implemented import *
+from .timeout import *
+from .chain_decorators import *
+from .threadify import *
+from .delay_call import *
+from .deprecate import *
+from .processify import *
+from .singleton import *
+from .total_ordering import *
+from .final import *
+from .normalize_decorator import *

danielutils/decorators/atomic.py

@@ -0,0 +1,45 @@
+import functools
+import logging
+from typing import Callable, Any, TypeVar
+import threading
+from .validate import validate
+from ..logging_.utils import get_logger
+logger = get_logger(__name__)
+
+from ..versioned_imports import ParamSpec
+
+T = TypeVar("T")
+P = ParamSpec("P")
+FuncT = Callable[P, T]  # type:ignore
+
+
+@validate  # type:ignore
+def atomic(func: FuncT) -> FuncT:
+    """will make function thread safe by making it
+    accessible for only one thread at one time
+
+    Args:
+        func (Callable): function to make thread safe
+
+    Returns:
+        Callable: the thread safe function
+    """
+    logger.debug("Making function %s atomic (thread-safe)", func.__name__)
+    lock = threading.Lock()
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs) -> Any:
+        logger.debug("Acquiring lock for atomic function %s", func.__name__)
+        with lock:
+            logger.debug("Executing atomic function %s", func.__name__)
+            result = func(*args, **kwargs)
+            logger.debug("Atomic function %s completed", func.__name__)
+            return result
+
+    logger.debug("Atomic decorator applied to %s", func.__name__)
+    return wrapper
+
+
+__all__ = [
+    "atomic"
+]

danielutils/decorators/attach.py

@@ -0,0 +1,61 @@
+import functools
+import logging
+from typing import Callable, Optional, TypeVar
+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(strict=False)  # type:ignore
+def attach(before: Optional[Callable] = None, after: Optional[Callable] = None) -> Callable[[FuncT], FuncT]:
+    """attaching functions to a function
+
+    Args:
+        before (Callable, optional): function to call before. Defaults to None.
+        after (Callable, optional): function to call after. Defaults to None.
+
+    Raises:
+        ValueError: if both before and after are none
+        ValueError: if the decorated object is not a Callable
+
+    Returns:
+        Callable: the decorated result
+    """
+    logger.debug("Creating attach decorator with before=%s, after=%s", before, after)
+    if before is None and after is None:
+        logger.error("Both before and after functions are None")
+        raise ValueError("You must supply at least one function")
+
+    def attach_deco(func: FuncT) -> FuncT:
+        logger.debug("Applying attach decorator to function %s", func.__name__)
+        if not callable(func):
+            logger.error("Object %s is not callable", func)
+            raise ValueError("attach must decorate a function")
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            logger.debug("Executing attached function %s", func.__name__)
+            if before is not None:
+                logger.debug("Calling before function: %s", before.__name__)
+                before()
+            res = func(*args, **kwargs)
+            if after is not None:
+                logger.debug("Calling after function: %s", after.__name__)
+                after()
+            logger.debug("Attached function %s completed", func.__name__)
+            return res
+
+        logger.debug("Attach decorator applied to %s", func.__name__)
+        return wrapper
+
+    return attach_deco
+
+
+__all__ = [
+    "attach"
+]

danielutils/decorators/chain_decorators.py

@@ -0,0 +1,39 @@
+import functools
+import logging
+from typing import Callable
+from ..logging_.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def chain_decorators(*decorators, reverse_order: bool = False) -> Callable:
+    """will chain the given decorators in the order they appear
+
+    Args:
+        reverse_order (bool, optional): whether to reverse the order of decoration. Defaults to False.
+
+    Returns:
+        Callable: resulting multi-decorated function
+    """
+    logger.debug("Creating chain decorator with %s decorators, reverse_order=%s", len(decorators), reverse_order)
+    def decorators_deco(func):
+        logger.debug("Applying chain decorators to function %s", func.__name__)
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            logger.debug("Executing chained function %s", func.__name__)
+            return func(*args, **kwargs)
+        
+        decorator_order = decorators[::1 if reverse_order else -1]
+        logger.debug("Applying decorators in order: %s", [d.__name__ if hasattr(d, '__name__') else str(d) for d in decorator_order])
+        for i, deco in enumerate(decorator_order):
+            logger.debug("Applying decorator %s/%s: %s", i+1, len(decorator_order), deco.__name__ if hasattr(deco, '__name__') else str(deco))
+            wrapper = deco(wrapper)
+        
+        logger.debug("Chain decorators applied to %s", func.__name__)
+        return wrapper
+    return decorators_deco
+
+
+__all__ = [
+    "chain_decorators"
+]

danielutils/decorators/decorate_conditionally.py

@@ -0,0 +1,32 @@
+import functools
+from typing import Callable, Optional, Union
+from .validate import validate
+
+
+@validate(strict=False)  # type:ignore
+def decorate_conditionally(decorator: Callable, predicate: Union[bool, Callable[[], bool]], *,
+                           decorator_args: Optional[list] = None, decorator_kwargs: Optional[dict] = None):
+    """will decorate a function iff the predicate is True or returns True
+
+    Args:
+        decorator (Callable): the decorator to use
+        predicate (bool | Callable[[], bool]): the predicate
+    """
+
+    def deco(func):
+        if (predicate() if callable(predicate) else predicate):
+            nonlocal decorator_args, decorator_kwargs, decorator
+            if decorator_args is None:
+                decorator_args = []
+            if decorator_kwargs is None:
+                decorator_kwargs = {}
+            decorator = functools.wraps(func)(decorator)
+            return decorator(*decorator_args, **decorator_kwargs)(func)
+        return func
+
+    return deco
+
+
+__all__ = [
+    "decorate_conditionally"
+]

danielutils/decorators/delay_call.py

@@ -0,0 +1,47 @@
+import logging
+from typing import Callable, TypeVar, Union
+import time
+import functools
+from .decorate_conditionally import decorate_conditionally
+from .threadify import threadify
+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 delay_call(seconds: Union[float, int], blocking: bool = True) -> Callable[[FuncT], FuncT]:
+    """will delay the call to a function by the given amount of seconds
+
+    Args:
+        seconds (float | int): the amount of time to wait
+        blocking (bool, optional): whether to block the main thread
+        when waiting or to wait in a different thread. Defaults to True.
+    """
+    logger.debug("Creating delay_call decorator with %ss delay, blocking=%s", seconds, blocking)
+
+    def deco(func: FuncT) -> FuncT:
+        logger.debug("Applying delay_call decorator to function %s", func.__name__)
+        @decorate_conditionally(threadify, not blocking)
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            logger.debug("Delaying call to %s by %s seconds", func.__name__, seconds)
+            time.sleep(seconds)
+            logger.debug("Delay completed, calling %s", func.__name__)
+            result = func(*args, **kwargs)
+            logger.debug("Delayed function %s completed", func.__name__)
+            return result
+
+        logger.debug("Delay_call decorator applied to %s", func.__name__)
+        return wrapper
+
+    return deco
+
+
+__all__ = [
+    "delay_call"
+]

danielutils/decorators/deprecate.py

@@ -0,0 +1,46 @@
+from typing import Callable, TypeVar
+from ..colors import warning, ColoredText
+from ..versioned_imports import ParamSpec
+
+T = TypeVar("T")
+P = ParamSpec("P")
+FuncT = Callable[P, T]  # type:ignore
+
+
+def deprecate_with(replacement_func) -> Callable[[FuncT], FuncT]:
+    """will replace a deprecated function with the replacement func and will print a warning"""
+
+    def deco(func: FuncT) -> FuncT:
+        warning(f"{func.__module__}.{func.__qualname__} is deprecated,"
+                f" using {replacement_func.__module__}.{replacement_func.__qualname__} instead")
+
+        def wrapper(*args, **kwargs):
+            return replacement_func(*args, **kwargs)
+
+        return wrapper
+
+    return deco
+
+
+def deprecate(deprecation_message: str) -> Callable[[FuncT], FuncT]:
+    """A decorator to print a deprecation message when using a deprecated function
+
+    Args:
+        deprecation_message (str): deprecation message
+    """
+
+    def deco(func: FuncT) -> FuncT:
+        def wrapper(*args, **kwargs):
+            print(ColoredText.orange("Deprecation Warning") +
+                  ":", deprecation_message)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return deco
+
+
+__all__ = [
+    "deprecate_with",
+    "deprecate"
+]

danielutils/decorators/final.py

@@ -0,0 +1,39 @@
+def final(cls: type) -> type:
+    """
+    A class Decorator to mark a class as final and add expected behavior
+    Args:
+        cls: the class to mark
+
+    Returns:
+        marked class
+    """
+
+    def __init__subclass__(*args, **kwargs):
+        raise TypeError(f"'{cls.__qualname__}' is final. Can't create subclasses")
+
+    setattr(cls, "__init_subclass__", __init__subclass__)
+    return cls
+
+
+class Final:
+    """
+    A parent class to make direct child a Final class. will add expected behaviour.
+    """
+
+    def __new__(cls, *args, **kwargs):
+        if cls is Final:
+            raise TypeError("Can't instantiate 'Final'")
+        return super().__new__(cls, *args, **kwargs)
+
+    @classmethod
+    def __init_subclass__(cls, **kwargs):
+        def __init__subclass__(*args, **kwargs):
+            raise TypeError(f"'{cls.__qualname__}' is final. Can't create subclasses")
+
+        setattr(cls, "__init_subclass__", __init__subclass__)
+
+
+__all__ = [
+    "final",
+    "Final"
+]

danielutils/decorators/limit_recursion.py

@@ -0,0 +1,63 @@
+import functools
+import re
+import traceback
+import logging
+from typing import Any, Callable, TypeVar
+from .validate import validate
+from ..colors import warning
+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 limit_recursion(max_depth: int, return_value: Any = None, quiet: bool = True) -> Callable[[FuncT], FuncT]:
+    """decorator to limit recursion of functions
+
+    Args:
+        max_depth (int): max recursion depth which is allowed for this function
+        return_value (Any, optional): The value to return when the limit is reached. Defaults to None.
+            if is None, will return the last a tuple for the last args, kwargs given
+        quiet (bool, optional): whether to print a warning message. Defaults to True.
+    """
+    logger.debug("Creating limit_recursion decorator with max_depth=%s, quiet=%s", max_depth, quiet)
+
+    def deco(func: FuncT) -> FuncT:
+        logger.debug("Applying limit_recursion decorator to function %s", func.__name__)
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            depth = functools.reduce(
+                lambda count, line:
+                count + 1 if re.search(rf"{func.__name__}\(.*\)$", line)
+                else count,
+                traceback.format_stack(), 0
+            )
+            logger.debug("Function %s called at recursion depth %s/%s", func.__name__, depth, max_depth)
+            if depth >= max_depth:
+                logger.warning("Recursion limit reached for %s at depth %s", func.__name__, depth)
+                if not quiet:
+                    warning(
+                        "limit_recursion has limited the number of calls for "
+                        f"{func.__module__}.{func.__qualname__} to {max_depth}")
+                if return_value:
+                    logger.debug("Returning specified return_value: %s", return_value)
+                    return return_value
+                logger.debug("Returning args and kwargs: %s, %s", args, kwargs)
+                return args, kwargs
+            logger.debug("Recursion depth %s is within limit, calling function", depth)
+            return func(*args, **kwargs)
+
+        logger.debug("Limit_recursion decorator applied to %s", func.__name__)
+        return wrapper
+
+    return deco
+
+
+__all__ = [
+    "limit_recursion"
+]

danielutils/decorators/memo.py

@@ -0,0 +1,68 @@
+import functools
+import logging
+from typing import Callable, Any, TypeVar, Dict, Generator, List, Set, Optional
+from copy import deepcopy
+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 memo(func: FuncT) -> FuncT:
+    """decorator to memorize function calls in order to improve performance by using more memory
+
+    Args:
+        func (Callable): function to memorize
+    """
+    logger.debug("Creating memo decorator for function %s", func.__name__)
+    cache: Dict[tuple, Any] = {}
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        cache_key = (args, *kwargs.items())
+        if cache_key not in cache:
+            logger.debug("Cache miss for %s, computing result", func.__name__)
+            cache[cache_key] = func(*args, **kwargs)
+            logger.debug("Result cached for %s", func.__name__)
+        else:
+            logger.debug("Cache hit for %s, returning cached result", func.__name__)
+        return deepcopy(cache[cache_key])
+
+    logger.debug("Memo decorator applied to %s", func.__name__)
+    return wrapper
+
+
+def memo_generator(func: Callable[P, Generator]) -> Callable[P, Generator]:
+    logger.debug("Creating memo_generator decorator for function %s", func.__name__)
+    cache: Dict[tuple, Any] = {}
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> Generator:
+        args = tuple(args)
+        cache_key = (args, *kwargs.items())
+        if cache_key not in cache:
+            logger.debug("Cache miss for generator %s, computing and caching result", func.__name__)
+            lst = []
+            for v in func(*args, **kwargs):
+                lst.append(v)
+                yield v
+            cache[cache_key] = lst
+            logger.debug("Generator result cached for %s", func.__name__)
+        else:
+            logger.debug("Cache hit for generator %s, yielding from cache", func.__name__)
+            yield from cache[cache_key]
+
+    logger.debug("Memo_generator decorator applied to %s", func.__name__)
+    return wrapper
+
+
+__all__ = [
+    "memo",
+    "memo_generator"
+]

danielutils/decorators/normalize_decorator.py

@@ -0,0 +1,55 @@
+import functools
+from typing import Callable, Any
+
+
+def normalize_decorator(decorator: Callable[..., Any]) -> Callable[..., Any]:
+    """
+
+    Args:
+        decorator: a function that is used as a decorator and you want to be used with "normalized" arguments
+
+    Returns:
+        object: 
+        The normalized version of the decorator
+
+    Example:
+
+        Do
+        ```python
+        @normalize_decorator
+        def validate(func, strict:bool = False):
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                # do stuff
+                return func(*args, **kwargs)
+            return wrapper
+        ```
+
+        instead of
+        ```python
+        def validate(strict_or_func: Optional[Union[bool,Callable]] = None):
+            strict = False # default value
+            def deco(func):
+                @functools.wraps(func)
+                def wrapper(*args, **kwargs):
+                    # do stuff
+                    return func(*args, **kwargs)
+                return wrapper
+            if isinstance(strict_or_func, bool):
+                strict = strict_or_func
+                return deco
+            return deco(strict_or_func)
+    """
+    @functools.wraps(decorator)
+    def wrapper(*args, **kwargs):
+        if args and callable(args[0]):
+            return decorator(args[0], *args[1:], **kwargs)
+        else:
+            return lambda func: decorator(func, *args, **kwargs)
+
+    return wrapper
+
+
+__all__ = [
+    "normalize_decorator",
+]