dycw-utilities 0.125.23__tar.gz → 0.125.24__tar.gz

{dycw_utilities-0.125.23 → dycw_utilities-0.125.24}/PKG-INFO

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

{dycw_utilities-0.125.23 → dycw_utilities-0.125.24}/pyproject.toml

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

{dycw_utilities-0.125.23 → dycw_utilities-0.125.24}/src/tests/test_asyncio.py

@@ -56,6 +56,7 @@ from utilities.datetime import (
     datetime_duration_to_timedelta,
     get_now,
 )
+from utilities.functions import get_class_name
 from utilities.hypothesis import sentinels, text_ascii
 from utilities.iterables import one, unique_everseen
 from utilities.pytest import skipif_windows
@@ -882,7 +883,7 @@ class _ExampleLooperError(Exception): ...
 
 
 @dataclass(kw_only=True)
-class _ExampleLooper(Looper[Any]):
+class _ExampleCounterLooper(Looper[Any]):
     freq: Duration = field(default=10 * MILLISECOND, repr=False)
     backoff: Duration = field(default=100 * MILLISECOND, repr=False)
     _debug: bool = field(default=True, repr=False)
@@ -901,13 +902,13 @@ class _ExampleLooper(Looper[Any]):
 
 
 @dataclass(kw_only=True)
-class _ExampleOuterLooper(_ExampleLooper):
-    inner: _ExampleLooper = field(init=False, repr=False)
+class _ExampleOuterLooper(_ExampleCounterLooper):
+    inner: _ExampleCounterLooper = field(init=False, repr=False)
 
     @override
     def __post_init__(self) -> None:
         super().__post_init__()
-        self.inner = _ExampleLooper(
+        self.inner = _ExampleCounterLooper(
             freq=self.freq / 2,
             backoff=self.backoff / 2,
             logger=self.logger,
@@ -921,6 +922,15 @@ class _ExampleOuterLooper(_ExampleLooper):
         yield self.inner
 
 
+@dataclass(kw_only=True)
+class _ExampleQueueLooper(Looper[int]):
+    @override
+    async def core(self) -> None:
+        await super().core()
+        if not self.empty():
+            _ = self.get_left_nowait()
+
+
 class TestLooper:
     sleep_if_failure_cases: ClassVar[list[Any]] = [
         param(True, "; sleeping for .*"),
@@ -928,61 +938,60 @@ class TestLooper:
     ]
 
     async def test_main_with_nothing(self) -> None:
-        looper = _ExampleLooper()
+        looper = _ExampleCounterLooper()
         async with looper:
             ...
         assert looper.stats == _LooperStats(entries=1, stops=1)
 
-    @mark.flaky
-    async def test_main_with_explicit_start(self) -> None:
-        looper = _ExampleLooper()
-        with raises(TimeoutError):
-            async with timeout(1.0), looper:
-                await looper
-        self._assert_stats(looper, stops=1)
-
-    async def test_main_with_auto_start(self) -> None:
-        looper = _ExampleLooper(auto_start=True)
+    async def test_auto_start(self) -> None:
+        looper = _ExampleCounterLooper(auto_start=True)
         with raises(TimeoutError):
             async with timeout(1.0), looper:
                 ...
         self._assert_stats(looper)
 
-    @mark.flaky
-    async def test_main_with_timeout(self) -> None:
-        looper = _ExampleLooper(timeout=SECOND)
-        async with looper:
-            with raises(LooperTimeoutError, match="Timeout"):
-                await looper
-        self._assert_stats(looper, stops=1)
-
-    async def test_main_with_auto_start_and_timeout(self) -> None:
-        looper = _ExampleLooper(auto_start=True, timeout=SECOND)
+    async def test_auto_start_and_timeout(self) -> None:
+        looper = _ExampleCounterLooper(auto_start=True, timeout=1.0)
         async with looper:
             ...
         self._assert_stats(looper, stops=1)
 
     async def test_await_without_task(self) -> None:
-        looper = _ExampleLooper()
+        looper = _ExampleCounterLooper()
         with raises(_LooperNoTaskError, match=".* has no running task"):
             await looper
 
     async def test_context_manager_already_entered(
         self, *, caplog: LogCaptureFixture
     ) -> None:
-        looper = _ExampleLooper(auto_start=True, timeout=SECOND)
+        looper = _ExampleCounterLooper(auto_start=True, timeout=SECOND)
         async with looper, looper:
             ...
         _ = one(m for m in caplog.messages if search(": already entered$", m))
 
     def test_empty(self) -> None:
-        looper = _ExampleLooper()
+        looper = _ExampleCounterLooper()
         assert looper.empty()
         looper.put_left_nowait(None)
         assert not looper.empty()
 
+    async def test_empty_upon_exit(self) -> None:
+        looper = _ExampleQueueLooper(freq=0.05, empty_upon_exit=True)
+        looper.put_right_nowait(0)
+        assert not looper.empty()
+        async with timeout(1.0), looper:
+            ...
+        assert looper.empty()
+
+    async def test_explicit_start(self) -> None:
+        looper = _ExampleCounterLooper()
+        with raises(TimeoutError):
+            async with timeout(1.0), looper:
+                await looper
+        self._assert_stats(looper, stops=1)
+
     def test_get_all_nowait(self) -> None:
-        looper = _ExampleLooper()
+        looper = _ExampleCounterLooper()
         looper.put_left_nowait(None)
         items = looper.get_all_nowait()
         assert items == [None]
@@ -990,7 +999,7 @@ class TestLooper:
     async def test_initialize_already_initializing(
         self, *, caplog: LogCaptureFixture
     ) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def _initialize_core(self) -> None:
                 if self._initialization_attempts == 1:
@@ -1005,7 +1014,7 @@ class TestLooper:
     async def test_initialize_failure(
         self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
     ) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def _initialize_core(self) -> None:
                 if self._initialization_attempts == 1:
@@ -1018,17 +1027,17 @@ class TestLooper:
         _ = one(m for m in caplog.messages if search(pattern, m))
 
     def test_len_and_qsize(self) -> None:
-        looper = _ExampleLooper()
+        looper = _ExampleCounterLooper()
         assert len(looper) == looper.qsize() == 0
         looper.put_left_nowait(None)
         assert len(looper) == looper.qsize() == 1
 
     def test_replace(self) -> None:
-        looper = _ExampleLooper().replace(freq=SECOND)
-        assert looper.freq == SECOND
+        looper = _ExampleCounterLooper().replace(freq=10.0)
+        assert looper.freq == 10.0
 
     async def test_request_restart(self) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def core(self) -> None:
                 await super().core()
@@ -1037,7 +1046,7 @@ class TestLooper:
                 ):
                     self.request_restart()
 
-        looper = Example(auto_start=True, timeout=SECOND)
+        looper = Example(auto_start=True, timeout=1.0)
         async with looper:
             ...
         self._assert_stats(
@@ -1053,7 +1062,7 @@ class TestLooper:
     def test_request_restart_already_requested(
         self, *, caplog: LogCaptureFixture
     ) -> None:
-        looper = _ExampleLooper()
+        looper = _ExampleCounterLooper()
         for _ in range(2):
             looper.request_restart()
         _ = one(
@@ -1061,7 +1070,7 @@ class TestLooper:
         )
 
     async def test_request_stop(self) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def core(self) -> None:
                 await super().core()
@@ -1070,7 +1079,7 @@ class TestLooper:
                 ):
                     self.request_stop()
 
-        looper = Example(auto_start=True, timeout=SECOND)
+        looper = Example(auto_start=True, timeout=1.0)
         async with looper:
             ...
         self._assert_stats(
@@ -1084,13 +1093,13 @@ class TestLooper:
         )
 
     def test_request_stop_already_requested(self, *, caplog: LogCaptureFixture) -> None:
-        looper = _ExampleLooper()
+        looper = _ExampleCounterLooper()
         for _ in range(2):
             looper.request_stop()
         _ = one(m for m in caplog.messages if search(r": already requested stop$", m))
 
     async def test_request_stop_when_empty(self) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def core(self) -> None:
                 await super().core()
@@ -1103,7 +1112,7 @@ class TestLooper:
                         _ = self.get_right_nowait()
                 self.request_stop_when_empty()
 
-        looper = Example(auto_start=True, timeout=SECOND)
+        looper = Example(auto_start=True, timeout=1.0)
         for i in range(25):
             match i % 2 == 0:
                 case True:
@@ -1125,7 +1134,7 @@ class TestLooper:
     def test_request_stop_when_empty_already_requested(
         self, *, caplog: LogCaptureFixture
     ) -> None:
-        looper = _ExampleLooper()
+        looper = _ExampleCounterLooper()
         for _ in range(2):
             looper.request_stop_when_empty()
         _ = one(
@@ -1138,7 +1147,7 @@ class TestLooper:
     async def test_restart_failure_during_initialization(
         self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
     ) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def _initialize_core(self) -> None:
                 if self._initialization_attempts == 1:
@@ -1154,7 +1163,7 @@ class TestLooper:
     async def test_restart_failure_during_tear_down(
         self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
     ) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def _tear_down_core(self) -> None:
                 if self._tear_down_attempts == 1:
@@ -1170,7 +1179,7 @@ class TestLooper:
     async def test_restart_failure_during_tear_down_and_initialization(
         self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
     ) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def _initialize_core(self) -> None:
                 if self._initialization_attempts == 1:
@@ -1188,11 +1197,19 @@ class TestLooper:
         pattern = rf": encountered _ExampleLooperError\(\) \(tear down\) and then _ExampleLooperError\(\) \(initialization\) whilst restarting{extra}$"
         _ = one(m for m in caplog.messages if search(pattern, m))
 
+    @mark.parametrize("n", [param(0), param(1), param(2)])
+    async def test_run_until_empty(self, *, n: int) -> None:
+        looper = _ExampleQueueLooper(freq=0.05)
+        looper.put_right_nowait(*range(n))
+        async with timeout(1.0), looper:
+            await looper.run_until_empty()
+        assert looper.empty()
+
     @mark.parametrize("auto_start", [param(True), param(False)])
     async def test_sub_looper_one(
         self, *, auto_start: bool, caplog: LogCaptureFixture
     ) -> None:
-        looper = _ExampleOuterLooper(auto_start=True, timeout=SECOND)
+        looper = _ExampleOuterLooper(auto_start=True, timeout=1.0)
         looper.inner.auto_start = auto_start
         async with looper:
             ...
@@ -1206,7 +1223,7 @@ class TestLooper:
             restart_successes=13,
             stops=1,
         )
-        pattern = r": changing sub-looper _ExampleLooper\(.*?\) to auto-start\.\.\.$"
+        pattern = rf": changing sub-looper {get_class_name(_ExampleCounterLooper)}\(.*?\) to auto-start\.\.\.$"
         matches = [m for m in caplog.messages if bool(search(pattern, m))]
         if auto_start:
             assert len(matches) == 0
@@ -1215,14 +1232,14 @@ class TestLooper:
 
     async def test_sub_loopers_multiple(self) -> None:
         @dataclass(kw_only=True)
-        class Example(_ExampleLooper):
-            inner1: _ExampleLooper = field(init=False, repr=False)
-            inner2: _ExampleLooper = field(init=False, repr=False)
+        class Example(_ExampleCounterLooper):
+            inner1: _ExampleCounterLooper = field(init=False, repr=False)
+            inner2: _ExampleCounterLooper = field(init=False, repr=False)
 
             @override
             def __post_init__(self) -> None:
                 super().__post_init__()
-                self.inner1 = _ExampleLooper(
+                self.inner1 = _ExampleCounterLooper(
                     freq=self.freq / 2,
                     backoff=self.backoff / 2,
                     logger=self.logger,
@@ -1230,7 +1247,7 @@ class TestLooper:
                     timeout_error=self.timeout_error,
                     max_count=round(self.max_count / 2),
                 )
-                self.inner2 = _ExampleLooper(
+                self.inner2 = _ExampleCounterLooper(
                     freq=self.freq / 2,
                     backoff=self.backoff / 2,
                     logger=self.logger,
@@ -1244,7 +1261,7 @@ class TestLooper:
                 yield self.inner1
                 yield self.inner2
 
-        looper = Example(auto_start=True, timeout=SECOND)
+        looper = Example(auto_start=True, timeout=1.0)
         async with looper:
             ...
         self._assert_stats(looper, stops=1)
@@ -1261,7 +1278,7 @@ class TestLooper:
 
     async def test_sub_loopers_nested(self) -> None:
         @dataclass(kw_only=True)
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             middle: _ExampleOuterLooper = field(init=False, repr=False)
 
             @override
@@ -1280,7 +1297,7 @@ class TestLooper:
             def _yield_sub_loopers(self) -> Iterator[Looper]:
                 yield self.middle
 
-        looper = Example(auto_start=True, timeout=SECOND)
+        looper = Example(auto_start=True, timeout=1.0)
         async with looper:
             ...
         self._assert_stats(looper, stops=1)
@@ -1306,7 +1323,7 @@ class TestLooper:
     async def test_tear_down_already_tearing_down(
         self, *, caplog: LogCaptureFixture
     ) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def _tear_down_core(self) -> None:
                 if self._tear_down_attempts == 1:
@@ -1321,7 +1338,7 @@ class TestLooper:
     async def test_tear_down_failure(
         self, *, sleep_if_failure: bool, extra: str, caplog: LogCaptureFixture
     ) -> None:
-        class Example(_ExampleLooper):
+        class Example(_ExampleCounterLooper):
             @override
             async def _tear_down_core(self) -> None:
                 if self._tear_down_attempts == 1:
@@ -1333,14 +1350,21 @@ class TestLooper:
         pattern = rf": encountered _ExampleLooperError\(\) whilst tearing down{extra}$"
         _ = one(m for m in caplog.messages if search(pattern, m))
 
+    async def test_timeout(self) -> None:
+        looper = _ExampleCounterLooper(timeout=1.0)
+        async with looper:
+            with raises(LooperTimeoutError, match="Timeout"):
+                await looper
+        self._assert_stats(looper, stops=1)
+
     def test_with_auto_start(self) -> None:
-        looper = _ExampleLooper()
+        looper = _ExampleCounterLooper()
         assert not looper.auto_start
         assert looper.with_auto_start.auto_start
 
     def _assert_stats(
         self,
-        looper: _ExampleLooper,
+        looper: _ExampleCounterLooper,
         /,
         *,
         entries: int = 1,

{dycw_utilities-0.125.23 → dycw_utilities-0.125.24}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.125.23"
+__version__ = "0.125.24"

{dycw_utilities-0.125.23 → dycw_utilities-0.125.24}/src/utilities/asyncio.py

@@ -688,6 +688,7 @@ class Looper(Generic[_T]):
     auto_start: bool = field(default=False, repr=False)
     freq: Duration = field(default=SECOND, repr=False)
     backoff: Duration = field(default=10 * SECOND, repr=False)
+    empty_upon_exit: bool = field(default=False, repr=False)
     logger: str | None = field(default=None, repr=False)
     timeout: Duration | None = field(default=None, repr=False)
     timeout_error: type[Exception] = field(default=LooperTimeoutError, repr=False)
@@ -791,6 +792,8 @@ class Looper(Generic[_T]):
                     )
                 _ = await self._stack.__aexit__(exc_type, exc_value, traceback)
                 await self.stop()
+                if self.empty_upon_exit:
+                    await self.run_until_empty()
             case False:
                 _ = self._debug and self._logger.debug("%s: already exited", self)
             case _ as never:
@@ -891,6 +894,7 @@ class Looper(Generic[_T]):
         self,
         *,
         auto_start: bool | Sentinel = sentinel,
+        empty_upon_exit: bool | Sentinel = sentinel,
         freq: Duration | Sentinel = sentinel,
         backoff: Duration | Sentinel = sentinel,
         logger: str | None | Sentinel = sentinel,
@@ -902,6 +906,7 @@ class Looper(Generic[_T]):
         return replace_non_sentinel(
             self,
             auto_start=auto_start,
+            empty_upon_exit=empty_upon_exit,
             freq=freq,
             backoff=backoff,
             logger=logger,
@@ -1061,6 +1066,13 @@ class Looper(Generic[_T]):
                             self._core_successes += 1
                         await sleep(self._freq)
 
+    async def run_until_empty(self) -> None:
+        """Run until the queue is empty."""
+        while not self.empty():
+            await self.core()
+            if not self.empty():
+                await sleep(self._freq)
+
     @property
     def stats(self) -> _LooperStats:
         """Return the statistics."""