plexus-python-common 1.1.87__py3-none-any.whl → 1.1.89__py3-none-any.whl

plexus/common/utils/funcutils.py

@@ -21,7 +21,8 @@ __all__ = [
 
 def const[T](value: T) -> Callable[..., T]:
     """
-    Returns a function that always returns the specified ``value``, regardless of the input arguments.
+    Returns a function that always returns the specified ``value``, regardless of the input
+    arguments.
 
     :param value: The constant value to return.
     :return: A function that takes any arguments and returns ``value``.
@@ -65,15 +66,17 @@ def second[V]() -> Callable[[tuple[Any, V]], V]:
 
 def packed[R](func: Callable[..., R]) -> Callable[[tuple[Any, ...]], R]:
     """
-    Wraps a function to accept its arguments as a single tuple, unpacking them when called. This is useful for
-    scenarios where arguments are naturally grouped in tuples, such as when working with data structures like maps or
-    lists of tuples, or when interfacing with APIs that provide arguments in tuple form.
+    Wraps a function to accept its arguments as a single tuple, unpacking them when called. This is
+    useful for scenarios where arguments are naturally grouped in tuples, such as when working with
+    data structures like maps or lists of tuples, or when interfacing with APIs that provide
+    arguments in tuple form.
 
     >>> data = [(1, 2), (3, 4), (5, 6)]
     >>> sums = map(packed(lambda x, y: x + y), data)
 
     :param func: The function to wrap.
-    :return: A function that takes a tuple of arguments and calls the original function with them unpacked.
+    :return: A function that takes a tuple of arguments and calls the original function with them
+             unpacked.
     """
 
     @functools.wraps(func)
@@ -85,7 +88,8 @@ def packed[R](func: Callable[..., R]) -> Callable[[tuple[Any, ...]], R]:
 
 def identity[T](instance: T) -> T:
     """
-    Returns the input ``instance`` unchanged. This is a utility function often used as a default or placeholder.
+    Returns the input ``instance`` unchanged. This is a utility function often used as a default or
+    placeholder.
 
     :param instance: The value to return.
     :return: The same value as provided in ``instance``.
@@ -130,9 +134,10 @@ def composable[T, R](func: Callable[[T], R]) -> Composable[T, R]:
     return func
 
 
-def singleton[R](tar: Callable[..., R] = None):
+def singleton[R](tar: Callable[..., R] | None = None):
     """
-    Decorator to ensure a function or class is only instantiated once. Subsequent calls return the same instance.
+    Decorator to ensure a function or class is only instantiated once. Subsequent calls return the
+    same instance.
 
     :param tar: The target callable to decorate.
     :return: The singleton instance of the callable.
@@ -155,9 +160,10 @@ def singleton[R](tar: Callable[..., R] = None):
     return decorator if tar is None else decorator(tar)
 
 
-def memorized[R](tar: Callable[..., R] = None, *, ordered: bool = False, typed: bool = False):
+def memorized[R](tar: Callable[..., R] | None = None, *, ordered: bool = False, typed: bool = False):
     """
-    Decorator to cache the results of a function based on its arguments. Supports options for argument order and type.
+    Decorator to cache the results of a function based on its arguments. Supports options for
+    argument order and type.
 
     :param tar: The target callable to decorate.
     :param ordered: If ``True``, keyword argument order is significant in the cache key.
@@ -198,7 +204,7 @@ def memorized[R](tar: Callable[..., R] = None, *, ordered: bool = False, typed:
     return decorator if tar is None else decorator(tar)
 
 
-def lazy[R](tar: Callable[..., R] = None):
+def lazy[R](tar: Callable[..., R] | None = None):
     """
     Decorator to defer the execution of a function until its result is explicitly requested.
 
@@ -219,10 +225,10 @@ def lazy[R](tar: Callable[..., R] = None):
     return decorator if tar is None else decorator(tar)
 
 
-def unique_returns[R](tar: Callable[..., R] = None, *, max_trials: int | None = None):
+def unique_returns[R](tar: Callable[..., R] | None = None, *, max_trials: int | None = None):
     """
-    Decorator to ensure a function produces unique return values. If no unique value is found within max_trials,
-    raises an error.
+    Decorator to ensure a function produces unique return values. If no unique value is found
+    within ``max_trials``, raises an error.
 
     :param tar: The target callable to decorate.
     :param max_trials: The maximum number of attempts to find a unique return value. If ``None``,
@@ -255,9 +261,9 @@ def unique_returns[R](tar: Callable[..., R] = None, *, max_trials: int | None =
 
 class ChainableResult[T, R]:
     """
-    A proxy object that holds a result of type R and delegates attribute access to a chained object of type C.
-    This is useful for chaining operations that produce intermediate results while still allowing access to the
-    original object.
+    A proxy object that holds a result of type ``R`` and delegates attribute access to a chained
+    object of type ``T``. This is useful for chaining operations that produce intermediate results
+    while still allowing access to the original object.
     """
 
     def __init__(self, target: T, result: R):

plexus/common/utils/logger.py

@@ -105,13 +105,14 @@ def __get_logger_caller_module_name() -> str:
 
     :return: The name of the caller's module, or an empty string if not found.
     """
-    frames = inspect.stack()
-    if len(frames) < 3:
-        return ""  # cause degeneration to root logger
-
-    # 0: this frame, 1: caller frame (logger), 2: caller's caller frame (logging function)
-    caller_frame = frames[2]
-    module = inspect.getmodule(caller_frame[0])
-    if module is None:
-        return ""
-    return module.__name__
+    frame = inspect.currentframe()
+    try:
+        # This helper -> public logging function -> caller.
+        caller_frame = frame.f_back.f_back if frame is not None and frame.f_back is not None else None
+        if caller_frame is None:
+            return ""  # cause degeneration to root logger
+        module = inspect.getmodule(caller_frame)
+        return "" if module is None else module.__name__
+    finally:
+        # Frame references can otherwise participate in reference cycles.
+        del frame

plexus/common/utils/retry.py

@@ -1,9 +1,9 @@
 import abc
+import functools
 import time
 from collections.abc import Callable
 from typing import Any
 
-from plexus.common.utils.dtutils import dt_utc_now
 from plexus.common.utils.randutils import randomizer
 
 __all__ = [
@@ -24,7 +24,7 @@ class Attempt(object):
         next_wait: int,
         start_ts: float,
         check_ts: float,
-        last_exception: Exception,
+        last_exception: Exception | None = None,
     ):
         """
         Represents an attempt in retrying.
@@ -87,10 +87,11 @@ class RetryWrapper(object):
     def __init__(
         self,
         target: Callable[..., Any] | Retry,
-        wait: int = None,
-        wait_func: Callable[[int], int] = None,
-        retrials: int = None,
-        timeout: int = None,
+        wait: int | None = None,
+        wait_func: Callable[[int], int] | None = None,
+        retrials: int | None = None,
+        timeout: int | None = None,
+        exceptions: type[Exception] | tuple[type[Exception], ...] = Exception,
     ):
         """
         Retry executor that wraps a callable or ``Retry`` instance, providing flexible retry strategies including fixed,
@@ -101,12 +102,27 @@ class RetryWrapper(object):
         :param wait_func: Function to determine wait time based on attempt number.
         :param retrials: Maximum number of retrials (``None`` for unlimited).
         :param timeout: Maximum total time (in seconds) allowed for all attempts (``None`` for unlimited).
+        :param exceptions: Exceptions to catch during retrials.
         """
+        if wait is not None and wait < 0:
+            raise ValueError("'wait' must be greater than or equal to zero")
+        if retrials is not None and retrials < 0:
+            raise ValueError("'retrials' must be greater than or equal to zero")
+        if timeout is not None and timeout < 0:
+            raise ValueError("'timeout' must be greater than or equal to zero")
+        if isinstance(exceptions, type):
+            exceptions = (exceptions,)
+        if not exceptions or not all(isinstance(exc, type) and issubclass(exc, Exception) for exc in exceptions):
+            raise TypeError("'exceptions' must contain 'Exception' subclasses")
+
         self.target = target
         self.wait = wait
         self.wait_func = wait_func
         self.retrials = retrials
         self.timeout = timeout
+        self.exceptions = exceptions
+        if not isinstance(target, Retry) and hasattr(target, "__name__"):
+            functools.update_wrapper(self, target)
 
     def __call__(self, *args, **kwargs):
         """
@@ -118,7 +134,7 @@ class RetryWrapper(object):
         """
         return self.run(*args, **kwargs)
 
-    def next_wait(self, attempt_number: int):
+    def next_wait(self, attempt_number: int) -> int:
         """
         Determines the wait time before the next retry attempt based on the configured strategy.
 
@@ -126,7 +142,7 @@ class RetryWrapper(object):
         :return: The wait time in seconds, or ``None`` if not applicable.
         """
         if attempt_number <= 0:
-            return None
+            return 0
         if self.wait is not None:
             return self.wait
         if self.wait_func is not None:
@@ -140,7 +156,7 @@ class RetryWrapper(object):
         :param start_ts: The start timestamp of the first attempt.
         :return: Tuple (``True`` if within timeout, current timestamp).
         """
-        current_ts = dt_utc_now().timestamp()
+        current_ts = time.monotonic()
         if self.timeout is None:
             return True, current_ts
         return current_ts < start_ts + self.timeout, current_ts
@@ -156,7 +172,7 @@ class RetryWrapper(object):
         :raises RuntimeError: If all attempts fail or timeout is reached.
         """
         attempt_number = 0
-        start_ts = dt_utc_now().timestamp()
+        start_ts = time.monotonic()
         last_exception = None
 
         while self.retrials is None or attempt_number <= self.retrials:
@@ -182,33 +198,55 @@ class RetryWrapper(object):
                     return result
                 else:
                     return self.target(*args, **kwargs)
-            except Exception as e:
+            except self.exceptions as e:
                 last_exception = e
                 if isinstance(self.target, Retry):
                     self.target.on_failure(attempt, e)
-                time.sleep(self.next_wait(attempt_number))
+                has_retrial = self.retrials is None or attempt_number <= self.retrials
+                if not has_retrial:
+                    break
+
+                wait = self.next_wait(attempt_number)
+                if self.timeout is not None:
+                    remaining = start_ts + self.timeout - time.monotonic()
+                    if remaining <= 0:
+                        break
+                    wait = min(wait, remaining)
+                time.sleep(wait)
 
         raise RuntimeError(
             f"failed to execute target '{self.target}' after {attempt_number} attempts") from last_exception
 
 
-def retry(wait: int = None, retrials: int = None, timeout: int = None):
+def retry(
+    wait: int | None = None,
+    retrials: int | None = None,
+    timeout: int | None = None,
+    exceptions: type[Exception] | tuple[type[Exception], ...] = Exception,
+):
     """
     Decorator to apply fixed wait retry logic to a function or callable.
 
     :param wait: Fixed wait time (in seconds) between retrials.
     :param retrials: Maximum number of retrials (``None`` for unlimited).
     :param timeout: Maximum total time (in seconds) allowed for all attempts (``None`` for unlimited).
+    :param exceptions: Exceptions to apply to retrials.
     :return: A decorated function with retry logic.
     """
 
     def wrapper(target):
-        return RetryWrapper(target, wait=wait, retrials=retrials, timeout=timeout)
+        return RetryWrapper(target, wait=wait, retrials=retrials, timeout=timeout, exceptions=exceptions)
 
     return wrapper
 
 
-def retry_exponent(wait_init: int, wait_max: int, retrials: int = None, timeout: int = None):
+def retry_exponent(
+    wait_init: int,
+    wait_max: int,
+    retrials: int | None = None,
+    timeout: int | None = None,
+    exceptions: type[Exception] | tuple[type[Exception], ...] = Exception,
+):
     """
     Decorator to apply exponential backoff retry logic to a function or callable.
 
@@ -216,21 +254,34 @@ def retry_exponent(wait_init: int, wait_max: int, retrials: int = None, timeout:
     :param wait_max: Maximum wait time for exponential backoff.
     :param retrials: Maximum number of retrials (``None`` for unlimited).
     :param timeout: Maximum total time (in seconds) allowed for all attempts (``None`` for unlimited).
+    :param exceptions: Exceptions to apply to retrials.
     :return: A decorated function with retry logic.
     """
 
+    if wait_init < 0 or wait_max < 0:
+        raise ValueError("'wait_init' and 'wait_max' must be greater than or equal to zero")
+    if wait_init > wait_max:
+        raise ValueError("'wait_init' must be less than or equal to 'wait_max'")
+
     def wrapper(target):
         return RetryWrapper(
             target,
             wait_func=lambda x: min(wait_init * (2 ** (x - 1)), wait_max),
             retrials=retrials,
             timeout=timeout,
+            exceptions=exceptions,
         )
 
     return wrapper
 
 
-def retry_random(wait_min: int, wait_max: int, retrials: int = None, timeout: int = None):
+def retry_random(
+    wait_min: int,
+    wait_max: int,
+    retrials: int | None = None,
+    timeout: int | None = None,
+    exceptions: type[Exception] | tuple[type[Exception], ...] = Exception,
+):
     """
     Decorator to apply random wait retry logic to a function or callable.
 
@@ -238,15 +289,22 @@ def retry_random(wait_min: int, wait_max: int, retrials: int = None, timeout: in
     :param wait_max: Maximum wait time for random backoff.
     :param retrials: Maximum number of retrials (``None`` for unlimited).
     :param timeout: Maximum total time (in seconds) allowed for all attempts (``None`` for unlimited).
+    :param exceptions: Exceptions to apply to retrials.
     :return: A decorated function with retry logic.
     """
 
+    if wait_min < 0 or wait_max < 0:
+        raise ValueError("'wait_min' and 'wait_max' must be greater than or equal to zero")
+    if wait_min > wait_max:
+        raise ValueError("'wait_min' must be less than or equal to 'wait_max'")
+
     def wrapper(target):
         return RetryWrapper(
             target,
             wait_func=lambda x: randomizer().next_int(wait_min, wait_max),
             retrials=retrials,
             timeout=timeout,
+            exceptions=exceptions,
         )
 
     return wrapper

plexus/common/utils/strutils.py

@@ -66,7 +66,7 @@ def parse_bool(v: Any) -> bool:
     elif isinstance(v, bool):
         return v
     else:
-        raise ValueError(f"type '{type(v)}' is not convertible to bool")
+        raise ValueError(f"type '{type(v)}' is not convertible to 'bool'")
 
 
 def parse_bool_or(v: Any, default: bool | None = False) -> bool | None:

plexus/common/utils/testutils.py

@@ -1,4 +1,5 @@
 import abc
+import datetime
 from decimal import Decimal
 from typing import Any, Protocol
 
@@ -69,7 +70,9 @@ def nested_approx(expected, rel: float = None, abs: float = None, nan_ok: bool =
         return ApproxNestedSequenceLike(expected, rel, abs, nan_ok)
     if isinstance(expected, Decimal):
         return ApproxDecimal(expected, to_decimal(rel), to_decimal(abs), nan_ok)
-    return pytest.approx(expected, rel, abs, nan_ok)
+    if isinstance(expected, (datetime.datetime, datetime.date, datetime.time, datetime.timedelta)):
+        return pytest.approx(expected, abs=datetime.timedelta(0))
+    return pytest.approx(expected, rel=rel, abs=abs, nan_ok=nan_ok)
 
 
 class MockedCallable(Protocol):

{plexus_python_common-1.1.87.dist-info → plexus_python_common-1.1.89.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python-common
-Version: 1.1.87
+Version: 1.1.89
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13

{plexus_python_common-1.1.87.dist-info → plexus_python_common-1.1.89.dist-info}/RECORD

@@ -5,19 +5,19 @@ plexus/common/utils/config.py,sha256=Hc35GzKWyKU4jyjsay5JtGhAtQ9GReNWKJEOskJVe3s
 plexus/common/utils/csvutils.py,sha256=quGN_F-WxtznhCLqst2coXaK-DVgxzwe2FA0qiiskf8,8344
 plexus/common/utils/dbutils.py,sha256=0GhnW1P1fJsqB4NjS4V6R-oV8d4R-ZZzi-IpiZCRjAs,16575
 plexus/common/utils/dtutils.py,sha256=A_upNJJJ3q6e3QZ2m5jXkDLwpAtUU9lEBY2MotAV5aY,12229
-plexus/common/utils/funcutils.py,sha256=5ciB_kiASUfQelRkKrtNkRru7E7835e5g-8j33Qb8V4,9789
+plexus/common/utils/funcutils.py,sha256=fdWmQ3GG0RjBwe2kgx4BIrsBUIs89saa60VN5lvZb4I,9862
 plexus/common/utils/iterutils.py,sha256=JL8j8plIoc2hF8D-BY6dOHEBoeoFZ1nLrhw4dFth_lA,30988
 plexus/common/utils/jsonutils.py,sha256=BDtqkvmWHiVFo4d5nGkmFtC00JQkGLC7ybchrpID5pU,18529
-plexus/common/utils/logger.py,sha256=FJaai6Sbchy4wKHcUMUCrrkBcXvIxq4qByERZ_TJBps,3881
+plexus/common/utils/logger.py,sha256=ce8B8CrxeoZnPIWNkNSL4JXFsK_3yXnBPDzxntUwG48,4046
 plexus/common/utils/numutils.py,sha256=p6Rz1qyCcUru3v1zDy2PM-nds2NWJdL5A_vLmG-kswk,4294
 plexus/common/utils/pathutils.py,sha256=vUuBZZShkK4oJN_GqWzMYeSGmnUFTcT8NoMgjh1YuUs,10201
 plexus/common/utils/randutils.py,sha256=Mkba-g2ZnasuhdtBWoVDsP_VuwKMJ8p2UCf6-GF4drg,12852
-plexus/common/utils/retry.py,sha256=u5t9Nl8GS8f6bRE3QbJFIfTcSIKXRQo03Psn61hk9AA,8981
+plexus/common/utils/retry.py,sha256=S_IfYrA30ci_sx6_ar0WUkNpKufoWi8xOSiWeYeAemA,11424
 plexus/common/utils/span.py,sha256=RqgUuupN01xCjm4l5uxrr8BFFrUrytRVGihmENUawpk,6839
-plexus/common/utils/strutils.py,sha256=PGOSYRgTnQcP0YXORzeTpiU9RweInxd5f6YcIHm6yiY,5096
-plexus/common/utils/testutils.py,sha256=D-EvK-Og8chyiks377PGDjqYid-l4F4Xfq9Q4yzrJtM,5441
+plexus/common/utils/strutils.py,sha256=uB46pPgaO_UMulwfW-hO7QOpCyhB9AdupeWSsJR3wGA,5098
+plexus/common/utils/testutils.py,sha256=AIuGok17mRackiSXO0ZiWXEwlna6Bv2J8ZFN48nypDY,5638
 plexus/common/utils/typeutils.py,sha256=RVkYkFRgDrx77OHFH7PavMV0AIB0S8ly40rs4g7JWE4,8220
-plexus_python_common-1.1.87.dist-info/METADATA,sha256=VBcicurcAqvKiH8HbY_b3ojdAE1kc20d0ChBz3FnvuM,871
-plexus_python_common-1.1.87.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-plexus_python_common-1.1.87.dist-info/top_level.txt,sha256=ug_g7CVwaMQuas5UzAXbHUrQvKGCn8ezc6ZNvvRlJOE,7
-plexus_python_common-1.1.87.dist-info/RECORD,,
+plexus_python_common-1.1.89.dist-info/METADATA,sha256=ak_tbOiy9nSsTLaWvmqwr6k9kfUxukLOIqbk4rk4nmo,871
+plexus_python_common-1.1.89.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+plexus_python_common-1.1.89.dist-info/top_level.txt,sha256=ug_g7CVwaMQuas5UzAXbHUrQvKGCn8ezc6ZNvvRlJOE,7
+plexus_python_common-1.1.89.dist-info/RECORD,,

{plexus_python_common-1.1.87.dist-info → plexus_python_common-1.1.89.dist-info}/WHEEL

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