decorator-toolkit 0.1.0__py3-none-any.whl

decorator_toolkit/__init__.py

@@ -0,0 +1,10 @@
+"""Init file."""
+
+from .decorator_tools import log, timeit, memoize, validate
+
+__all__ = [
+    "log",
+    "timeit",
+    "memoize",
+    "validate"
+]

decorator_toolkit/decorator_tools.py

@@ -0,0 +1,205 @@
+"""Decorator tools."""
+
+import functools
+import logging
+from datetime import datetime
+from typing import TypeVar, ParamSpec, Callable
+
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def log(msg: str | None = None, success_msg: str | None = None, failed_msg: str | None = None) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Log the execution of a function.
+
+    The decorator logs an optional base message when the function is called.
+    If the wrapped function returns a truthy value, `success_msg` is logged.
+    If it returns a falsy value, `failed_msg` is logged.
+
+    Messages are only logged if provided. Exceptions raised by the wrapped
+    function are not suppressed.
+
+    Parameters
+    ----------
+    msg : str | None
+        Message logged every time the function is called.
+    success_msg : str | None
+        Message logged when the wrapped function returns a truthy value.
+    failed_msg : str | None
+        Message logged when the wrapped function returns a falsy value.
+    
+    Example
+    -------
+    >>> import logging
+    >>> logging.basicConfig(level=logging.INFO)
+    >>>
+    >>> @log(msg="Running check", success_msg="Passed", failed_msg="Failed")
+    ... def is_even(x: int) -> bool:
+    ...     return x % 2 == 0
+    >>>
+    >>> is_even(4)
+
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        logger = logging.getLogger(func.__module__)
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            logger.debug(f"Called {func.__name__} with args={args} & kwargs={kwargs}")
+            result = func(*args, **kwargs)
+            logger.debug(f"{func.__name__} returned {result} ({type(result)})")
+            if msg is not None:
+                logger.info(msg)
+            if isinstance(result, bool):
+                if result and success_msg:
+                    logger.info(success_msg)
+                elif not result and failed_msg:
+                    logger.info(failed_msg)
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def timeit(func: Callable[P, R]) -> Callable[P, R]:
+    """Measure execution time of a function.
+
+    The decorator records how long the wrapped function takes to execute
+    and reports the duration. The original return value of the function
+    is preserved.
+
+    The timing mechanism measures total runtime from function entry to exit.
+    Exceptions raised by the wrapped function are not suppressed.
+
+    Parameters
+    ----------
+    func : Callable[P, R]
+        The function whose execution time will be measured.
+
+    Returns
+    -------
+    Callable[P, R]
+        A wrapped function with identical signature and return value.
+
+    Example
+    -------
+    >>> @timeit
+    ... def slow_operation() -> None:
+    ...     import time
+    ...     time.sleep(1)
+    ...
+    >>> slow_operation()
+
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        start = datetime.now()
+        result = func(*args, **kwargs)
+        time_taken = datetime.now() - start
+        milliseconds = time_taken.total_seconds() * 1000
+        print(f"'{func.__name__}' took {round(milliseconds, 2)} milliseconds to run.")
+        return result
+
+    return wrapper
+
+
+def memoize(func: Callable[P, R]) -> Callable[P, R]:
+    """Cache function results based on input arguments.
+
+    The decorator stores results from previous calls and returns the cached
+    value when the function is called again with the same arguments.
+    This avoids repeated computation for identical inputs.
+
+    Cached values persist for the lifetime of the program unless explicitly
+    cleared by the implementation.
+
+    Parameters
+    ----------
+    func : Callable[P, R]
+        The function whose results will be cached.
+
+    Returns
+    -------
+    Callable[P, R]
+        A wrapped function with identical signature and return value.
+
+    Example
+    -------
+    >>> @memoize
+    ... def fibonacci(n: int) -> int:
+    ...     if n < 2:
+    ...         return n
+    ...     return fibonacci(n - 1) + fibonacci(n - 2)
+    ...
+    >>> fibonacci(30)
+
+    """
+    cache: dict[tuple[tuple[object, ...], frozenset[tuple[str, object]]], R] = {}
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        key = (args, frozenset(kwargs.items()))
+        if key in cache:
+            return cache[key]
+
+        result = func(*args, **kwargs)
+        cache[key] = result
+        return result
+
+    return wrapper
+
+
+def validate(
+    condition: Callable[..., bool],
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Enforce a validation condition before function execution.
+
+    The decorator factory accepts a condition function that is evaluated
+    using the same arguments passed to the wrapped function. If the condition
+    evaluates to True, the function executes normally. If it evaluates to
+    False, execution is prevented and an exception is raised.
+
+    The wrapped function’s signature and return value are preserved.
+
+    Parameters
+    ----------
+    condition : Callable[..., bool]
+        A callable that receives the same arguments as the wrapped function
+        and returns True if execution is allowed, or False otherwise.
+
+    Returns
+    -------
+    Callable[[Callable[P, R]], Callable[P, R]]
+        A decorator that applies the validation check.
+
+    Example
+    -------
+    >>> def not_negative(x: float) -> bool:
+    ...     if x >= 0:
+    ...         return True
+    ...     else:
+    ...         return False
+    ...
+    >>> @validate(not_negative)
+    ... def sqrt(x: float) -> float:
+    ...     return x ** 0.5
+    ...
+    >>> sqrt(9)
+    >>> sqrt(-1)  # validation fails
+
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            if not condition(*args, **kwargs):
+                logging.error("Validation failed.")
+                raise ValueError("Validation failed")
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

decorator_toolkit/decorator_tools.pyi

@@ -0,0 +1,9 @@
+from typing import Callable, TypeVar, ParamSpec
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+def log(msg: str | None = None, success_msg: str | None = None, failed_msg: str | None = None) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+def timeit(func: Callable[P, R]) -> Callable[P, R]: ...
+def memoize(func: Callable[P, R]) -> Callable[P, R]: ...
+def validate(condition: Callable[..., bool],) -> Callable[[Callable[P, R]], Callable[P, R]]: ...

decorator_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: decorator_toolkit
+Version: 0.1.0
+Summary: Type-safe decorators for logging, timing, retry, memoization, and validation.
+Author: Adam Worsnip
+Requires-Python: >=3.10
+License-File: LICENSE
+Dynamic: license-file

decorator_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+decorator_toolkit/__init__.py,sha256=ezV_a0ycTT_WXN2OYT9hPWIqBz2nVcpOvdxq0QPbSok,147
+decorator_toolkit/decorator_tools.py,sha256=PPv0XRx_R_FAC9_PJDbq5m37k6afWdfDy0WJBxnOue8,6093
+decorator_toolkit/decorator_tools.pyi,sha256=aWlPrBzDAHJKgU9YUSerJxQdhov97ToqVndxmMFqn1Y,441
+decorator_toolkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+decorator_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=-IhJmeRD2I8HlDFbm8DV6lfe4H3Xn1ruehUwegt44uQ,1069
+decorator_toolkit-0.1.0.dist-info/METADATA,sha256=-Vp6R5kRkaqyvhT7mb9O88th60KIviDZVoL6Z5-jeIQ,237
+decorator_toolkit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+decorator_toolkit-0.1.0.dist-info/top_level.txt,sha256=PBh3JT8TjriU_SE-hX5QIPhIQBzovIuphhAa-s17gZs,18
+decorator_toolkit-0.1.0.dist-info/RECORD,,

decorator_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

decorator_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Worsnip
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

decorator_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+decorator_toolkit