dycw-utilities 0.129.1__tar.gz → 0.129.3__tar.gz

{dycw_utilities-0.129.1 → dycw_utilities-0.129.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.129.1
+Version: 0.129.3
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.129.1 → dycw_utilities-0.129.3}/pyproject.toml

@@ -94,7 +94,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.129.1"
+version = "0.129.3"
 
 [project.optional-dependencies]
 test = [
@@ -334,7 +334,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.129.1"
+current_version = "0.129.3"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.129.1 → dycw_utilities-0.129.3}/src/tests/test_asyncio.py

@@ -21,7 +21,10 @@ from hypothesis.strategies import (
 )
 from pytest import LogCaptureFixture, approx, mark, param, raises
 
+from tests.conftest import IS_CI
 from tests.test_asyncio_classes.loopers import (
+    _BACKOFF,
+    _FREQ,
     _REL,
     CountingLooper,
     CountingLooperError,
@@ -63,6 +66,7 @@ from utilities.sentinel import Sentinel, sentinel
 from utilities.timer import Timer
 
 if TYPE_CHECKING:
+    import datetime as dt
     from collections.abc import AsyncIterator
 
     from utilities.types import Duration, MaybeCallableEvent
@@ -255,9 +259,15 @@ class TestGetItems:
 
 
 class TestLooper:
-    sleep_if_failure_cases: ClassVar[list[Any]] = [
-        param(True, "; sleeping for .*"),
-        param(False, ""),
+    _restart_min_elapsed: ClassVar[dt.timedelta] = datetime_duration_to_timedelta(
+        (0.8 if IS_CI else 1.0) * _BACKOFF
+    )
+    _restart_max_elapsed: ClassVar[dt.timedelta] = datetime_duration_to_timedelta(
+        (1.2 if IS_CI else 1.0) * _FREQ
+    )
+    skip_sleep_if_failure_cases: ClassVar[list[Any]] = [
+        param(True, ""),
+        param(False, "; sleeping for .*"),
     ]
 
     async def test_main_with_nothing(self) -> None:
@@ -330,16 +340,16 @@ class TestLooper:
             @override
             async def _initialize_core(self) -> None:
                 if self._initialization_attempts == 1:
-                    _ = await super().initialize(sleep_if_failure=False)
+                    _ = await super().initialize()
                 await super()._initialize_core()
 
         looper = Example()
-        _ = await looper.initialize(sleep_if_failure=False)
+        _ = await looper.initialize()
         _ = one(m for m in caplog.messages if search(": already initializing$", m))
 
-    @mark.parametrize(("sleep_if_failure", "extra"), sleep_if_failure_cases)
+    @mark.parametrize(("skip_sleep_if_failure", "extra"), skip_sleep_if_failure_cases)
     async def test_initialize_failure(
-        self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
+        self, *, skip_sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
     ) -> None:
         class Example(CountingLooper):
             @override
@@ -349,7 +359,7 @@ class TestLooper:
                 await super()._initialize_core()
 
         looper = Example()
-        _ = await looper.initialize(sleep_if_failure=sleep_if_failure)
+        _ = await looper.initialize(skip_sleep_if_failure=skip_sleep_if_failure)
         pattern = rf": encountered {get_class_name(CountingLooperError)}\(\) whilst initializing{extra}$"
         _ = one(m for m in caplog.messages if search(pattern, m))
 
@@ -443,6 +453,40 @@ class TestLooper:
         looper = CountingLooper().replace(freq=10.0)
         assert looper.freq == 10.0
 
+    async def test_request_back_off(self) -> None:
+        class Example(CountingLooper):
+            @override
+            async def core(self) -> None:
+                await super().core()
+                if (self._initialization_attempts >= 2) and (
+                    self.count >= (self.max_count / 2)
+                ):
+                    self.request_back_off()
+
+        looper = Example(auto_start=True, timeout=1.0)
+        async with looper:
+            ...
+        assert_looper_stats(
+            looper,
+            entries=1,
+            core_successes=23,
+            core_failures=2,
+            initialization_successes=3,
+            tear_down_successes=2,
+            restart_successes=2,
+            stops=1,
+        )
+
+    async def test_request_back_off_already_requested(
+        self, *, caplog: LogCaptureFixture
+    ) -> None:
+        looper = CountingLooper()
+        for _ in range(2):
+            looper.request_back_off()
+        _ = one(
+            m for m in caplog.messages if search(r": already requested back off$", m)
+        )
+
     async def test_request_restart(self) -> None:
         class Example(CountingLooper):
             @override
@@ -459,11 +503,11 @@ class TestLooper:
         assert_looper_stats(
             looper,
             entries=1,
-            core_successes=79,
+            core_successes=35,
             core_failures=1,
-            initialization_successes=16,
-            tear_down_successes=15,
-            restart_successes=15,
+            initialization_successes=7,
+            tear_down_successes=6,
+            restart_successes=6,
             stops=1,
         )
 
@@ -553,9 +597,8 @@ class TestLooper:
             if search(r": already requested stop when empty$", m)
         )
 
-    @mark.parametrize(("sleep_if_failure", "extra"), sleep_if_failure_cases)
     async def test_restart_failure_during_initialization(
-        self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
+        self, *, caplog: LogCaptureFixture
     ) -> None:
         class Example(CountingLooper):
             @override
@@ -565,13 +608,14 @@ class TestLooper:
                 await super()._initialize_core()
 
         looper = Example()
-        await looper.restart(sleep_if_failure=sleep_if_failure)
-        pattern = rf": encountered {get_class_name(CountingLooperError)}\(\) whilst restarting \(initialize\){extra}$"
+        with Timer() as timer:
+            await looper.restart()
+        assert timer.timedelta >= self._restart_min_elapsed
+        pattern = rf": encountered {get_class_name(CountingLooperError)}\(\) whilst restarting \(initialize\); sleeping for .*\.\.\.$"
         _ = one(m for m in caplog.messages if search(pattern, m))
 
-    @mark.parametrize(("sleep_if_failure", "extra"), sleep_if_failure_cases)
     async def test_restart_failure_during_tear_down(
-        self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
+        self, *, caplog: LogCaptureFixture
     ) -> None:
         class Example(CountingLooper):
             @override
@@ -581,13 +625,14 @@ class TestLooper:
                 await super()._tear_down_core()
 
         looper = Example()
-        await looper.restart(sleep_if_failure=sleep_if_failure)
-        pattern = rf": encountered {get_class_name(CountingLooperError)}\(\) whilst restarting \(tear down\){extra}$"
+        with Timer() as timer:
+            await looper.restart()
+        assert timer.timedelta >= self._restart_min_elapsed
+        pattern = rf": encountered {get_class_name(CountingLooperError)}\(\) whilst restarting \(tear down\); sleeping for .*\.\.\.$"
         _ = one(m for m in caplog.messages if search(pattern, m))
 
-    @mark.parametrize(("sleep_if_failure", "extra"), sleep_if_failure_cases)
     async def test_restart_failure_during_tear_down_and_initialization(
-        self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
+        self, *, caplog: LogCaptureFixture
     ) -> None:
         class Example(CountingLooper):
             @override
@@ -603,8 +648,18 @@ class TestLooper:
                 await super()._tear_down_core()
 
         looper = Example()
-        await looper.restart(sleep_if_failure=sleep_if_failure)
-        pattern = rf": encountered {get_class_name(CountingLooperError)}\(\) \(tear down\) and then {get_class_name(CountingLooperError)}\(\) \(initialization\) whilst restarting{extra}$"
+        with Timer() as timer:
+            await looper.restart()
+        assert timer.timedelta >= self._restart_min_elapsed
+        pattern = rf": encountered {get_class_name(CountingLooperError)}\(\) \(tear down\) and then {get_class_name(CountingLooperError)}\(\) \(initialization\) whilst restarting; sleeping for .*\.\.\.$"
+        _ = one(m for m in caplog.messages if search(pattern, m))
+
+    async def test_restart_success(self, *, caplog: LogCaptureFixture) -> None:
+        looper = CountingLooper()
+        with Timer() as timer:
+            await looper.restart()
+        assert timer.timedelta <= self._restart_max_elapsed
+        pattern = r": finished restarting$"
         _ = one(m for m in caplog.messages if search(pattern, m))
 
     @mark.parametrize("n", [param(0), param(1), param(2)])
@@ -698,16 +753,16 @@ class TestLooper:
             @override
             async def _tear_down_core(self) -> None:
                 if self._tear_down_attempts == 1:
-                    _ = await super().tear_down(sleep_if_failure=False)
+                    _ = await super().tear_down()
                 await super()._tear_down_core()
 
         looper = Example()
-        _ = await looper.tear_down(sleep_if_failure=False)
+        _ = await looper.tear_down()
         _ = one(m for m in caplog.messages if search(": already tearing down$", m))
 
-    @mark.parametrize(("sleep_if_failure", "extra"), sleep_if_failure_cases)
+    @mark.parametrize(("skip_sleep_if_failure", "extra"), skip_sleep_if_failure_cases)
     async def test_tear_down_failure(
-        self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
+        self, *, skip_sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
     ) -> None:
         class Example(CountingLooper):
             @override
@@ -717,7 +772,7 @@ class TestLooper:
                 await super()._tear_down_core()
 
         looper = Example()
-        _ = await looper.tear_down(sleep_if_failure=sleep_if_failure)
+        _ = await looper.tear_down(skip_sleep_if_failure=skip_sleep_if_failure)
         pattern = rf": encountered {get_class_name(CountingLooperError)}\(\) whilst tearing down{extra}$"
         _ = one(m for m in caplog.messages if search(pattern, m))
 
@@ -751,7 +806,7 @@ class TestLooper:
         assert_looper_stats(
             looper,
             entries=1,
-            core_successes=45,
+            core_successes=47,
             core_failures=5,
             initialization_successes=6,
             tear_down_successes=5,
@@ -767,10 +822,10 @@ class TestLooper:
             looper,
             entries=1,
             core_successes=56,
-            core_failures=13,
-            initialization_successes=14,
-            tear_down_successes=13,
-            restart_successes=13,
+            core_failures=14,
+            initialization_successes=15,
+            tear_down_successes=14,
+            restart_successes=14,
             stops=stops,
             rel=rel,
         )
@@ -781,7 +836,7 @@ class TestLooper:
         assert_looper_stats(
             looper,
             entries=1,
-            core_successes=49,
+            core_successes=48,
             core_failures=24,
             initialization_successes=25,
             tear_down_successes=24,
@@ -798,9 +853,9 @@ class TestLooper:
             entries=1,
             core_successes=35,
             core_failures=35,
-            initialization_successes=35,
-            tear_down_successes=34,
-            restart_successes=34,
+            initialization_successes=36,
+            tear_down_successes=35,
+            restart_successes=35,
             stops=stops,
             rel=rel,
         )

{dycw_utilities-0.129.1 → dycw_utilities-0.129.3}/src/tests/test_sqlalchemy.py

@@ -1332,6 +1332,7 @@ class TestUpsertItems:
         await upsert_items(engine, item)
 
     @given(data=data(), triples=_upsert_lists(nullable=True, min_size=1))
+    @mark.flaky
     @settings_with_reduced_examples(phases={Phase.generate})
     async def test_multiple_elements_with_the_same_primary_key(
         self, *, data: DataObject, triples: list[tuple[int, bool, bool | None]]

{dycw_utilities-0.129.1 → dycw_utilities-0.129.3}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.129.1"
+__version__ = "0.129.3"

{dycw_utilities-0.129.1 → dycw_utilities-0.129.3}/src/utilities/asyncio.py

@@ -353,6 +353,7 @@ class Looper(Generic[_T]):
     _is_entered: Event = field(default_factory=Event, init=False, repr=False)
     _is_initialized: Event = field(default_factory=Event, init=False, repr=False)
     _is_initializing: Event = field(default_factory=Event, init=False, repr=False)
+    _is_pending_back_off: Event = field(default_factory=Event, init=False, repr=False)
     _is_pending_restart: Event = field(default_factory=Event, init=False, repr=False)
     _is_pending_stop: Event = field(default_factory=Event, init=False, repr=False)
     _is_pending_stop_when_empty: Event = field(
@@ -439,6 +440,11 @@ class Looper(Generic[_T]):
     def __len__(self) -> int:
         return self._queue.qsize()
 
+    async def _apply_back_off(self) -> None:
+        """Apply a back off period."""
+        await sleep(self._backoff)
+        self._is_pending_back_off.clear()
+
     async def core(self) -> None:
         """Core part of running the looper."""
 
@@ -458,7 +464,9 @@ class Looper(Generic[_T]):
         """Remove and return an item from the end of the queue without blocking."""
         return self._queue.get_right_nowait()
 
-    async def initialize(self, *, sleep_if_failure: bool) -> Exception | None:
+    async def initialize(
+        self, *, skip_sleep_if_failure: bool = False
+    ) -> Exception | None:
         """Initialize the looper."""
         match self._is_initializing.is_set():
             case True:
@@ -476,21 +484,21 @@ class Looper(Generic[_T]):
                     async with self._lock:
                         self._initialization_failures += 1
                     ret = error
-                    match sleep_if_failure:
+                    match skip_sleep_if_failure:
                         case True:
                             _ = self._logger.warning(
-                                "%s: encountered %s whilst initializing; sleeping for %s...",
+                                "%s: encountered %s whilst initializing",
                                 self,
                                 repr_error(error),
-                                self.backoff,
                             )
-                            await sleep(self._backoff)
                         case False:
                             _ = self._logger.warning(
-                                "%s: encountered %s whilst initializing",
+                                "%s: encountered %s whilst initializing; sleeping for %s...",
                                 self,
                                 repr_error(error),
+                                self.backoff,
                             )
+                            await self._apply_back_off()
                         case _ as never:
                             assert_never(never)
                 else:
@@ -547,6 +555,21 @@ class Looper(Generic[_T]):
             **kwargs,
         )
 
+    def request_back_off(self) -> None:
+        """Request the looper to back off."""
+        match self._is_pending_back_off.is_set():
+            case True:
+                _ = self._debug and self._logger.debug(
+                    "%s: already requested back off", self
+                )
+            case False:
+                _ = self._debug and self._logger.debug(
+                    "%s: requesting back off...", self
+                )
+                self._is_pending_back_off.set()
+            case _ as never:
+                assert_never(never)
+
     def request_restart(self) -> None:
         """Request the looper to restart."""
         match self._is_pending_restart.is_set():
@@ -561,6 +584,7 @@ class Looper(Generic[_T]):
                 self._is_pending_restart.set()
             case _ as never:
                 assert_never(never)
+        self.request_back_off()
 
     def request_stop(self) -> None:
         """Request the looper to stop."""
@@ -590,20 +614,20 @@ class Looper(Generic[_T]):
             case _ as never:
                 assert_never(never)
 
-    async def restart(self, *, sleep_if_failure: bool) -> None:
+    async def restart(self) -> None:
         """Restart the looper."""
         _ = self._debug and self._logger.debug("%s: restarting...", self)
         self._is_pending_restart.clear()
         async with self._lock:
             self._restart_attempts += 1
-        tear_down = await self.tear_down(sleep_if_failure=False)
-        initialization = await self.initialize(sleep_if_failure=False)
-        match tear_down, initialization, sleep_if_failure:
-            case None, None, bool():
+        tear_down = await self.tear_down(skip_sleep_if_failure=True)
+        initialization = await self.initialize(skip_sleep_if_failure=True)
+        match tear_down, initialization:
+            case None, None:
                 _ = self._debug and self._logger.debug("%s: finished restarting", self)
                 async with self._lock:
                     self._restart_successes += 1
-            case Exception(), None, True:
+            case Exception(), None:
                 async with self._lock:
                     self._restart_failures += 1
                 _ = self._logger.warning(
@@ -612,16 +636,8 @@ class Looper(Generic[_T]):
                     repr_error(tear_down),
                     self.backoff,
                 )
-                await sleep(self._backoff)
-            case Exception(), None, False:
-                async with self._lock:
-                    self._restart_failures += 1
-                _ = self._logger.warning(
-                    "%s: encountered %s whilst restarting (tear down)",
-                    self,
-                    repr_error(tear_down),
-                )
-            case None, Exception(), True:
+                await self._apply_back_off()
+            case None, Exception():
                 async with self._lock:
                     self._restart_failures += 1
                 _ = self._logger.warning(
@@ -630,16 +646,8 @@ class Looper(Generic[_T]):
                     repr_error(initialization),
                     self.backoff,
                 )
-                await sleep(self._backoff)
-            case None, Exception(), False:
-                async with self._lock:
-                    self._restart_failures += 1
-                _ = self._logger.warning(
-                    "%s: encountered %s whilst restarting (initialize)",
-                    self,
-                    repr_error(initialization),
-                )
-            case Exception(), Exception(), True:
+                await self._apply_back_off()
+            case Exception(), Exception():
                 async with self._lock:
                     self._restart_failures += 1
                 _ = self._logger.warning(
@@ -649,16 +657,7 @@ class Looper(Generic[_T]):
                     repr_error(initialization),
                     self.backoff,
                 )
-                await sleep(self._backoff)
-            case Exception(), Exception(), False:
-                async with self._lock:
-                    self._restart_failures += 1
-                _ = self._logger.warning(
-                    "%s: encountered %s (tear down) and then %s (initialization) whilst restarting",
-                    self,
-                    repr_error(tear_down),
-                    repr_error(initialization),
-                )
+                await self._apply_back_off()
             case _ as never:
                 assert_never(never)
 
@@ -674,10 +673,12 @@ class Looper(Generic[_T]):
                         self._is_pending_stop_when_empty.is_set() and self.empty()
                     ):
                         await self.stop()
+                    elif self._is_pending_back_off.is_set():
+                        await self._apply_back_off()
                     elif self._is_pending_restart.is_set():
-                        await self.restart(sleep_if_failure=True)
+                        await self.restart()
                     elif not self._is_initialized.is_set():
-                        _ = await self.initialize(sleep_if_failure=True)
+                        _ = await self.initialize()
                     else:
                         _ = self._debug and self._logger.debug(
                             "%s: running core...", self
@@ -695,7 +696,6 @@ class Looper(Generic[_T]):
                             async with self._lock:
                                 self._core_failures += 1
                             self.request_restart()
-                            await sleep(self._backoff)
                         else:
                             async with self._lock:
                                 self._core_successes += 1
@@ -749,7 +749,9 @@ class Looper(Generic[_T]):
             case _ as never:
                 assert_never(never)
 
-    async def tear_down(self, *, sleep_if_failure: bool) -> Exception | None:
+    async def tear_down(
+        self, *, skip_sleep_if_failure: bool = False
+    ) -> Exception | None:
         """Tear down the looper."""
         match self._is_tearing_down.is_set():
             case True:
@@ -766,21 +768,21 @@ class Looper(Generic[_T]):
                     async with self._lock:
                         self._tear_down_failures += 1
                     ret = error
-                    match sleep_if_failure:
+                    match skip_sleep_if_failure:
                         case True:
                             _ = self._logger.warning(
-                                "%s: encountered %s whilst tearing down; sleeping for %s...",
+                                "%s: encountered %s whilst tearing down",
                                 self,
                                 repr_error(error),
-                                self.backoff,
                             )
-                            await sleep(self._backoff)
                         case False:
                             _ = self._logger.warning(
-                                "%s: encountered %s whilst tearing down",
+                                "%s: encountered %s whilst tearing down; sleeping for %s...",
                                 self,
                                 repr_error(error),
+                                self.backoff,
                             )
+                            await self._apply_back_off()
                         case _ as never:
                             assert_never(never)
                 else: