sdsstools 1.9.4__py3-none-any.whl → 1.9.6__py3-none-any.whl

sdsstools/__init__.py

@@ -22,6 +22,7 @@ from ._vendor import color_print, toml, yanny
 from .configuration import *
 from .logger import *
 from .metadata import *
+from .retrier import *
 from .time import get_sjd
 from .utils import *
 

sdsstools/daemonizer.py

@@ -23,7 +23,19 @@ from click.decorators import pass_context
 from daemonocle import Daemon
 
 
-__all__ = ["cli_coro", "DaemonGroup"]
+__all__ = ["cli_coro", "DaemonGroup", "get_event_loop", "daemonize"]
+
+
+def get_event_loop() -> asyncio.AbstractEventLoop:
+    """Gets the current event loop, or creates a new one if none exists."""
+
+    try:
+        return asyncio.get_event_loop()
+    except RuntimeError:
+        # "There is no current event loop in thread %r"
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        return loop
 
 
 def cli_coro(
@@ -35,7 +47,7 @@ def cli_coro(
     def decorator_cli_coro(f):
         @wraps(f)
         def wrapper(*args, **kwargs):
-            loop = asyncio.get_event_loop()
+            loop = get_event_loop()
             if shutdown_func:
                 for ss in signals:
                     loop.add_signal_handler(ss, shutdown_func, ss, loop)

sdsstools/retrier.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# @Author: José Sánchez-Gallego (gallegoj@uw.edu)
+# @Date: 2024-01-02
+# @Filename: retrier.py
+# @License: BSD 3-clause (http://www.opensource.org/licenses/BSD-3-Clause)
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+import warnings
+from dataclasses import dataclass, field
+from functools import wraps
+
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    TypeVar,
+    overload,
+)
+
+from typing_extensions import ParamSpec, Self
+
+
+__all__ = ["Retrier"]
+
+
+T = TypeVar("T", bound=Any)
+P = ParamSpec("P")
+
+
+@dataclass
+class Retrier:
+    """A class that implements a retry mechanism.
+
+    The object returned by this class can be used to wrap a function that
+    will be retried ``max_attempts`` times if it fails::
+
+        def test_function():
+            ...
+
+        retrier = Retrier(max_attempts=5)
+        retrier(test_function)()
+
+    where the wrapped function can be a coroutine, in which case the wrapped function
+    will also be a coroutine.
+
+    Most frequently this class will be used as a decorator::
+
+        @Retrier(max_attempts=4, delay=0.1)
+        async def test_function(x, y):
+            ...
+
+        await test_function(1, 2)
+
+    Parameters
+    ----------
+    max_attempts
+        The maximum number of attempts before giving up.
+    delay
+        The delay between attempts, in seconds.
+    use_exponential_backoff
+        Whether to use exponential backoff for the delay between attempts. If
+        :obj:`True`, the delay will be
+        ``delay * exponential_backoff_base ** (attempt - 1) + random_ms`` where
+        ``random_ms`` is a random number between 0 and 100 ms used to avoid
+        synchronisation issues.
+    exponential_backoff_base
+        The base for the exponential backoff.
+    max_delay
+        The maximum delay between attempts when using exponential backoff.
+    on_retry
+        A function that will be called when a retry is attempted. The function
+        should accept an exception as its only argument.
+    raise_on_exception_class
+        A list of exception classes that will cause an exception to be raised
+        without retrying.
+    timeout
+        If defined, each attempt can take at most this amount of time. If the
+        attempt times out, an :obj:`asyncio.TimeoutError` will be raised.
+        This only works if the wrapped function is a coroutine.
+
+    """
+
+    max_attempts: int = 3
+    delay: float = 1
+    use_exponential_backoff: bool = True
+    exponential_backoff_base: float = 2
+    max_delay: float = 32.0
+    on_retry: Callable[[Exception], None] | None = None
+    raise_on_exception_class: list[type[Exception]] = field(default_factory=list)
+    timeout: float | None = None
+
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculates the delay for a given attempt."""
+
+        # Random number between 0 and 100 ms to avoid synchronisation issues.
+        random_ms = 0.1 * (time.time() % 1)
+
+        if self.use_exponential_backoff:
+            return min(
+                self.delay * self.exponential_backoff_base ** (attempt - 1) + random_ms,
+                self.max_delay,
+            )
+        else:
+            return self.delay
+
+    @overload
+    def __call__(
+        self: Self,
+        func: Callable[P, T],
+    ) -> Callable[P, T]: ...
+
+    @overload
+    def __call__(
+        self: Self,
+        func: Callable[P, Awaitable[T]],
+    ) -> Callable[P, Awaitable[T]]: ...
+
+    def __call__(
+        self,
+        func: Callable[P, T] | Callable[P, Awaitable[T]],
+    ) -> Callable[P, T] | Callable[P, Awaitable[T]]:
+        """Wraps a function to retry it if it fails."""
+
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs):
+                attempt = 0
+                while True:
+                    try:
+                        return await asyncio.wait_for(
+                            func(*args, **kwargs),
+                            timeout=self.timeout,
+                        )
+                    except Exception as ee:
+                        attempt += 1
+                        if attempt >= self.max_attempts:
+                            raise ee
+                        elif isinstance(ee, tuple(self.raise_on_exception_class)):
+                            raise ee
+                        else:
+                            if self.on_retry:
+                                self.on_retry(ee)
+                            await asyncio.sleep(self.calculate_delay(attempt))
+
+            return async_wrapper
+
+        else:
+
+            @wraps(func)
+            def wrapper(*args: P.args, **kwargs: P.kwargs):
+                attempt = 0
+                while True:
+                    try:
+                        if self.timeout is not None:
+                            warnings.warn(
+                                "The wrapped function is not a coroutine. "
+                                "The timeout parameter will be ignored.",
+                                RuntimeWarning,
+                            )
+                        return func(*args, **kwargs)
+                    except Exception as ee:
+                        attempt += 1
+                        if attempt >= self.max_attempts:
+                            raise ee
+                        elif isinstance(ee, tuple(self.raise_on_exception_class)):
+                            raise ee
+                        else:
+                            if self.on_retry:
+                                self.on_retry(ee)
+                            time.sleep(self.calculate_delay(attempt))
+
+            return wrapper

{sdsstools-1.9.4.dist-info → sdsstools-1.9.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdsstools
-Version: 1.9.4
+Version: 1.9.6
 Summary: Small tools for SDSS products
 Project-URL: Homepage, https://github.com/sdss/sdsstools
 Project-URL: Repository, https://github.com/sdss/sdsstools
@@ -284,6 +284,32 @@ To stop the daemon do `daemonize stop NAME`. See `daemonize --help` for more opt
 
 The function `sdsstools.time.get_sjd()` returns the integer with the SDSS-style Modified Julian Day. The function accepts an observatory (`'APO'` or `'LCO'`) but otherwise will try to determine the current location from environment variables or the fully qualified domain name.
 
+## Retrier
+
+The `Retrier` class provides a simple way to add retry logic to functions that may fail intermittently. It can be used to wrap both synchronous and asynchronous functions. `Retrier` produces a callable that can be used as a decorator or called directly. For example:
+
+```python
+from sdsstools.retrier import Retrier
+
+@Retrier(max_attempts=5, delay=2.0)
+async def my_function(param1, param2):
+    ...
+
+await my_function(1, 2)
+```
+
+or
+
+```python
+def my_function(param1, param2):
+    ...
+
+retrier = Retrier(max_attempts=5, delay=2.0)
+retrier(my_function)(1, 2)
+```
+
+By default `Retrier` will try three times with a one second delay between attempts. An exponential backoff is used by default. If the function keeps failing after the maximum number of attempts, the last exception is raised. It is possible to stop the retry process early if a certain type of exception is raised by passing a list of such exception classes to `raise_on_exception_class`.
+
 ## Bundled packages
 
 For convenience, `sdsstools` bundles the following products:

{sdsstools-1.9.4.dist-info → sdsstools-1.9.6.dist-info}/RECORD

@@ -1,10 +1,11 @@
-sdsstools/__init__.py,sha256=G8u94gRu4THFJvptEITykK0Q_3jHqhQY9p01j9QCQH4,744
+sdsstools/__init__.py,sha256=K1wL8SmTcCdutb-Nd_P1dCesoRJPJfOpJI7bcjR8gL0,767
 sdsstools/_tasks.py,sha256=U7fvxk9IExzE6voNjio2QqRTw-H9Upu1d0zKQlQFs5I,4263
 sdsstools/cli.py,sha256=e4BS4b1cJThCj5tytajr_VMUvmVP1xYq_r90EtEscg8,1348
 sdsstools/configuration.py,sha256=y_nmF_TN_o68ib2YIpdypHfwggvBpjz_dwKjNd0jzc8,14673
-sdsstools/daemonizer.py,sha256=TMzq3RgD0KqY6jmeeJASlCsw7CjDpLmF8QrENaxCHBU,7796
+sdsstools/daemonizer.py,sha256=Yd06BTwcAjQ9hIC3O-pQhqE5daHK-ECPZ17FzZPe3xM,8176
 sdsstools/logger.py,sha256=nGAC_hDK0dWVMAS-a-vBsw0oSCxAwx-ZsJUE5GMzILs,18382
 sdsstools/metadata.py,sha256=LZWO0KI-gVvzdJNIaVlIn4bBBHxbglU8BLW-MdlxOFA,3268
+sdsstools/retrier.py,sha256=inKy3dqe4RWNTdGGUHi2PwJqtbx8E5OmwLqpOmNnm1Y,5690
 sdsstools/time.py,sha256=cqLrch0ZUCt3ShagN1v-5GhgLyNjzPXgaQRem4j7vAk,4606
 sdsstools/utils.py,sha256=kl3FtvJdw3uEZye7gcBI9Ksvd1rk0EwkriiDkuyvlrU,5077
 sdsstools/_vendor/__init__.py,sha256=sy3LqhCDgkFjMQY7mLQolVOgvD7y9LM6DuWp2ylG0vc,282
@@ -15,8 +16,8 @@ sdsstools/_vendor/toml/decoder.py,sha256=hWUJ3UQ43MGVER35rSUUj7Hdh85Vat8Od_B4HeF
 sdsstools/_vendor/toml/encoder.py,sha256=OBRwH2tRUhRI8nJgKBwKbkyQnBAuhcUf60r3wykjPco,9989
 sdsstools/_vendor/toml/ordered.py,sha256=aW5woa5xOqR4BjIz9t10_lghxyhF54KQ7FqUNVv7WJ0,334
 sdsstools/_vendor/toml/tz.py,sha256=8TAiXrTqU08sE0ruz2TXH_pFY2rlwNKE47MSE4rDo8Y,618
-sdsstools-1.9.4.dist-info/METADATA,sha256=MXPK8lZT3NZeTdKjO10nznLWlh0ZPqPtlZG3J3wE9hU,15701
-sdsstools-1.9.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sdsstools-1.9.4.dist-info/entry_points.txt,sha256=H1UefQFMHyzmGcdNib_qxiOfFSx3351wr4c2ax0PJbQ,87
-sdsstools-1.9.4.dist-info/licenses/LICENSE.md,sha256=_7dAUQQ5Ph_x1hcFXhi9aHBcqq9H11zco12eO4B3Cyg,1504
-sdsstools-1.9.4.dist-info/RECORD,,
+sdsstools-1.9.6.dist-info/METADATA,sha256=9dtTD1rOuRKeJZiJ2niBhYgKa9WU5zbzxdbuGnRc8x0,16665
+sdsstools-1.9.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sdsstools-1.9.6.dist-info/entry_points.txt,sha256=H1UefQFMHyzmGcdNib_qxiOfFSx3351wr4c2ax0PJbQ,87
+sdsstools-1.9.6.dist-info/licenses/LICENSE.md,sha256=_7dAUQQ5Ph_x1hcFXhi9aHBcqq9H11zco12eO4B3Cyg,1504
+sdsstools-1.9.6.dist-info/RECORD,,