dycw-utilities 0.116.6__tar.gz → 0.117.1__tar.gz

{dycw_utilities-0.116.6 → dycw_utilities-0.117.1}/PKG-INFO

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

{dycw_utilities-0.116.6 → dycw_utilities-0.117.1}/pyproject.toml

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

{dycw_utilities-0.116.6 → dycw_utilities-0.117.1}/src/tests/test_asyncio.py

@@ -17,7 +17,7 @@ from itertools import chain, count
 from re import search
 from typing import TYPE_CHECKING, Self, override
 
-from hypothesis import Phase, given, settings
+from hypothesis import HealthCheck, Phase, given, settings
 from hypothesis.strategies import (
     DataObject,
     data,
@@ -28,7 +28,7 @@ from hypothesis.strategies import (
     permutations,
     sampled_from,
 )
-from pytest import approx, mark, param, raises
+from pytest import LogCaptureFixture, approx, mark, param, raises
 
 from utilities.asyncio import (
     AsyncLoopingService,
@@ -42,17 +42,25 @@ from utilities.asyncio import (
     QueueProcessor,
     UniquePriorityQueue,
     UniqueQueue,
+    _DurationOrEvery,
     get_event,
     get_items,
     get_items_nowait,
     put_items,
     put_items_nowait,
     sleep_dur,
+    sleep_until,
+    sleep_until_rounded,
     stream_command,
     timeout_dur,
 )
 from utilities.dataclasses import replace_non_sentinel
-from utilities.datetime import MILLISECOND, datetime_duration_to_timedelta
+from utilities.datetime import (
+    MILLISECOND,
+    MINUTE,
+    datetime_duration_to_timedelta,
+    get_now,
+)
 from utilities.hypothesis import sentinels, text_ascii
 from utilities.iterables import one, unique_everseen
 from utilities.pytest import skipif_windows
@@ -341,8 +349,8 @@ class TestGetEvent:
 
 
 class TestInfiniteLooper:
-    @given(n=integers(10, 11))
-    async def test_main(self, *, n: int) -> None:
+    @given(n=integers(10, 11), sleep_core=sampled_from([0.1, ("every", 0.1)]))
+    async def test_main(self, *, n: int, sleep_core: _DurationOrEvery) -> None:
         class TrueError(BaseException): ...
 
         class FalseError(BaseException): ...
@@ -368,7 +376,7 @@ class TestInfiniteLooper:
                 yield (True, TrueError)
                 yield (False, FalseError)
 
-        looper = Example(sleep_core=0.1)
+        looper = Example(sleep_core=sleep_core)
         match n % 2 == 0:
             case True:
                 with raises(TrueError):
@@ -520,7 +528,24 @@ class TestInfiniteLooper:
         assert 1 <= looper.counter <= 6
 
     @given(logger=just("logger") | none())
-    async def test_error_upon_initialize(self, *, logger: str | None) -> None:
+    @mark.parametrize(
+        ("sleep_restart", "desc"),
+        [
+            (60.0, "for 0:01:00"),
+            (MINUTE, "for 0:01:00"),
+            (("every", 60), "until next 0:01:00"),
+            (("every", MINUTE), "until next 0:01:00"),
+        ],
+    )
+    @settings(suppress_health_check={HealthCheck.function_scoped_fixture})
+    async def test_error_upon_initialize(
+        self,
+        *,
+        sleep_restart: _DurationOrEvery,
+        desc: str,
+        logger: str | None,
+        caplog: LogCaptureFixture,
+    ) -> None:
         class CustomError(Exception): ...
 
         @dataclass(kw_only=True)
@@ -533,13 +558,34 @@ class TestInfiniteLooper:
             async def _core(self) -> None:
                 raise NotImplementedError
 
-        looper = Example(sleep_core=0.1, logger=logger)
+        looper = Example(sleep_core=0.1, sleep_restart=sleep_restart, logger=logger)
         with raises(TimeoutError):
             async with timeout_dur(duration=0.5):
                 _ = await looper()
+        if logger is not None:
+            message = caplog.messages[0]
+            expected = f"'Example' encountered 'CustomError()' whilst initializing; sleeping {desc}..."
+            assert message == expected
 
     @given(logger=just("logger") | none())
-    async def test_error_group_upon_coroutines(self, *, logger: str | None) -> None:
+    @mark.parametrize(
+        ("sleep_restart", "desc"),
+        [
+            (60.0, "for 0:01:00"),
+            (MINUTE, "for 0:01:00"),
+            (("every", 60), "until next 0:01:00"),
+            (("every", MINUTE), "until next 0:01:00"),
+        ],
+    )
+    @settings(suppress_health_check={HealthCheck.function_scoped_fixture})
+    async def test_error_group_upon_coroutines(
+        self,
+        *,
+        sleep_restart: _DurationOrEvery,
+        desc: str,
+        logger: str | None,
+        caplog: LogCaptureFixture,
+    ) -> None:
         class CustomError(Exception): ...
 
         @dataclass(kw_only=True)
@@ -554,10 +600,14 @@ class TestInfiniteLooper:
             ) -> Iterator[tuple[None, MaybeType[BaseException]]]:
                 yield (None, CustomError)
 
-        looper = Example(sleep_core=0.1, logger=logger)
+        looper = Example(sleep_core=0.1, sleep_restart=sleep_restart, logger=logger)
         with raises(TimeoutError):
             async with timeout_dur(duration=0.5):
                 _ = await looper()
+        if logger is not None:
+            message = caplog.messages[0]
+            expected = f"'Example' encountered 'CustomError()'; sleeping {desc}..."
+            assert message == expected
 
     async def test_error_no_event_found(self) -> None:
         @dataclass(kw_only=True)
@@ -951,6 +1001,19 @@ class TestSleepDur:
         assert timer <= 0.01
 
 
+class TestSleepUntil:
+    async def test_main(self) -> None:
+        now = get_now()
+        with Timer() as timer:
+            await sleep_until(now + 10 * MILLISECOND)
+        assert timer >= datetime_duration_to_timedelta(5 * MILLISECOND)
+
+
+class TestSleepUntilRounded:
+    async def test_main(self) -> None:
+        await sleep_until_rounded(10 * MILLISECOND)
+
+
 class TestStreamCommand:
     @skipif_windows
     async def test_main(self) -> None:

{dycw_utilities-0.116.6 → dycw_utilities-0.117.1}/src/tests/test_datetime.py

@@ -88,6 +88,8 @@ from utilities.datetime import (
     date_to_datetime,
     date_to_month,
     datetime_duration_to_float,
+    datetime_duration_to_microseconds,
+    datetime_duration_to_milliseconds,
     datetime_duration_to_timedelta,
     datetime_utc,
     days_since_epoch,
@@ -128,8 +130,6 @@ from utilities.datetime import (
     serialize_month,
     sub_duration,
     timedelta_since_epoch,
-    timedelta_to_microseconds,
-    timedelta_to_milliseconds,
     yield_days,
     yield_weekdays,
 )
@@ -520,6 +520,60 @@ class TestDateTimeDurationToFloat:
         assert result == timedelta.total_seconds()
 
 
+class TestDateTimeDurationToMicrosecondsOrMilliseconds:
+    @given(timedelta=timedeltas())
+    def test_timedelta_to_microseconds(self, *, timedelta: dt.timedelta) -> None:
+        microseconds = datetime_duration_to_microseconds(timedelta)
+        result = microseconds_to_timedelta(microseconds)
+        assert result == timedelta
+
+    @given(microseconds=integers())
+    def test_microseconds_to_timedelta(self, *, microseconds: int) -> None:
+        with assume_does_not_raise(OverflowError):
+            timedelta = microseconds_to_timedelta(microseconds)
+        result = datetime_duration_to_microseconds(timedelta)
+        assert result == microseconds
+
+    @given(timedelta=timedeltas(), strict=booleans())
+    @settings(suppress_health_check={HealthCheck.filter_too_much})
+    def test_timedelta_to_milliseconds_exact(
+        self, *, timedelta: dt.timedelta, strict: bool
+    ) -> None:
+        _, remainder = divmod(timedelta.microseconds, _MICROSECONDS_PER_MILLISECOND)
+        _ = assume(remainder == 0)
+        milliseconds = datetime_duration_to_milliseconds(timedelta, strict=strict)
+        assert isinstance(milliseconds, int)
+        result = milliseconds_to_timedelta(milliseconds)
+        assert result == timedelta
+
+    @given(timedelta=timedeltas())
+    def test_timedelta_to_milliseconds_inexact(
+        self, *, timedelta: dt.timedelta
+    ) -> None:
+        _, remainder = divmod(timedelta.microseconds, _MICROSECONDS_PER_MILLISECOND)
+        _ = assume(remainder != 0)
+        milliseconds = datetime_duration_to_milliseconds(timedelta)
+        result = milliseconds_to_timedelta(round(milliseconds))
+        assert abs(result - timedelta) <= SECOND
+
+    @given(timedelta=timedeltas())
+    def test_timedelta_to_milliseconds_error(self, *, timedelta: dt.timedelta) -> None:
+        _, microseconds = divmod(timedelta.microseconds, _MICROSECONDS_PER_MILLISECOND)
+        _ = assume(microseconds != 0)
+        with raises(
+            TimedeltaToMillisecondsError,
+            match=r"Unable to convert .* to milliseconds; got .* microsecond\(s\)",
+        ):
+            _ = datetime_duration_to_milliseconds(timedelta, strict=True)
+
+    @given(milliseconds=int32s())
+    def test_milliseconds_to_timedelta(self, *, milliseconds: int) -> None:
+        with assume_does_not_raise(OverflowError):
+            timedelta = milliseconds_to_timedelta(milliseconds)
+        result = datetime_duration_to_milliseconds(timedelta)
+        assert result == milliseconds
+
+
 class TestDateTimeDurationToTimeDelta:
     @given(n=int32s())
     def test_int(self, *, n: int) -> None:
@@ -1205,60 +1259,6 @@ class TestTimedeltaSinceEpoch:
         assert result1 == result2
 
 
-class TestTimedeltaToMicrosecondsOrMilliseconds:
-    @given(timedelta=timedeltas())
-    def test_timedelta_to_microseconds(self, *, timedelta: dt.timedelta) -> None:
-        microseconds = timedelta_to_microseconds(timedelta)
-        result = microseconds_to_timedelta(microseconds)
-        assert result == timedelta
-
-    @given(microseconds=integers())
-    def test_microseconds_to_timedelta(self, *, microseconds: int) -> None:
-        with assume_does_not_raise(OverflowError):
-            timedelta = microseconds_to_timedelta(microseconds)
-        result = timedelta_to_microseconds(timedelta)
-        assert result == microseconds
-
-    @given(timedelta=timedeltas(), strict=booleans())
-    @settings(suppress_health_check={HealthCheck.filter_too_much})
-    def test_timedelta_to_milliseconds_exact(
-        self, *, timedelta: dt.timedelta, strict: bool
-    ) -> None:
-        _, remainder = divmod(timedelta.microseconds, _MICROSECONDS_PER_MILLISECOND)
-        _ = assume(remainder == 0)
-        milliseconds = timedelta_to_milliseconds(timedelta, strict=strict)
-        assert isinstance(milliseconds, int)
-        result = milliseconds_to_timedelta(milliseconds)
-        assert result == timedelta
-
-    @given(timedelta=timedeltas())
-    def test_timedelta_to_milliseconds_inexact(
-        self, *, timedelta: dt.timedelta
-    ) -> None:
-        _, remainder = divmod(timedelta.microseconds, _MICROSECONDS_PER_MILLISECOND)
-        _ = assume(remainder != 0)
-        milliseconds = timedelta_to_milliseconds(timedelta)
-        result = milliseconds_to_timedelta(round(milliseconds))
-        assert abs(result - timedelta) <= SECOND
-
-    @given(timedelta=timedeltas())
-    def test_timedelta_to_milliseconds_error(self, *, timedelta: dt.timedelta) -> None:
-        _, microseconds = divmod(timedelta.microseconds, _MICROSECONDS_PER_MILLISECOND)
-        _ = assume(microseconds != 0)
-        with raises(
-            TimedeltaToMillisecondsError,
-            match=r"Unable to convert .* to milliseconds; got .* microsecond\(s\)",
-        ):
-            _ = timedelta_to_milliseconds(timedelta, strict=True)
-
-    @given(milliseconds=int32s())
-    def test_milliseconds_to_timedelta(self, *, milliseconds: int) -> None:
-        with assume_does_not_raise(OverflowError):
-            timedelta = milliseconds_to_timedelta(milliseconds)
-        result = timedelta_to_milliseconds(timedelta)
-        assert result == milliseconds
-
-
 class TestTimedeltas:
     @mark.parametrize(
         "timedelta",

{dycw_utilities-0.116.6 → dycw_utilities-0.117.1}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.116.6"
+__version__ = "0.117.1"

{dycw_utilities-0.116.6 → dycw_utilities-0.117.1}/src/utilities/asyncio.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import datetime as dt
 from abc import ABC, abstractmethod
 from asyncio import (
     CancelledError,
@@ -32,6 +33,7 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Generic,
+    Literal,
     NoReturn,
     Self,
     TextIO,
@@ -41,7 +43,15 @@ from typing import (
     override,
 )
 
-from utilities.datetime import MILLISECOND, MINUTE, SECOND, datetime_duration_to_float
+from utilities.datetime import (
+    MILLISECOND,
+    MINUTE,
+    SECOND,
+    datetime_duration_to_float,
+    datetime_duration_to_timedelta,
+    get_now,
+    round_datetime,
+)
 from utilities.errors import ImpossibleCaseError, repr_error
 from utilities.functions import ensure_int, ensure_not_none, get_class_name
 from utilities.reprlib import get_repr
@@ -329,12 +339,15 @@ class ExceptionProcessor(QueueProcessor[Exception | type[Exception]]):
 ##
 
 
+type _DurationOrEvery = Duration | tuple[Literal["every"], Duration]
+
+
 @dataclass(kw_only=True, unsafe_hash=True)
 class InfiniteLooper(ABC, Generic[THashable]):
     """An infinite loop which can throw exceptions by setting events."""
 
-    sleep_core: Duration = SECOND
-    sleep_restart: Duration = MINUTE
+    sleep_core: _DurationOrEvery = SECOND
+    sleep_restart: _DurationOrEvery = MINUTE
     logger: str | None = None
     _events: Mapping[THashable, Event] = field(
         default_factory=dict, init=False, repr=False, hash=False
@@ -361,7 +374,7 @@ class InfiniteLooper(ABC, Generic[THashable]):
                     await self._initialize()
                 except Exception as error:  # noqa: BLE001
                     self._error_upon_initialize(error)
-                    await sleep_dur(duration=self.sleep_restart)
+                    await self._run_sleep(self.sleep_restart)
                 else:
                     while True:
                         try:
@@ -372,14 +385,14 @@ class InfiniteLooper(ABC, Generic[THashable]):
                             )
                         except StopIteration:
                             await self._core()
-                            await sleep_dur(duration=self.sleep_core)
+                            await self._run_sleep(self.sleep_core)
                         else:
                             self._raise_error(event)
             except InfiniteLooperError:
                 raise
             except Exception as error:  # noqa: BLE001
                 self._error_upon_core(error)
-                await sleep_dur(duration=self.sleep_restart)
+                await self._run_sleep(self.sleep_restart)
 
     async def _run_looper_with_coroutines(
         self, *coroutines: Callable[[], Coroutine1[None]]
@@ -393,7 +406,7 @@ class InfiniteLooper(ABC, Generic[THashable]):
                     _ = [tg.create_task(c()) for c in coroutines]
             except ExceptionGroup as error:
                 self._error_group_upon_coroutines(error)
-                await sleep_dur(duration=self.sleep_restart)
+                await self._run_sleep(self.sleep_restart)
 
     async def _initialize(self) -> None:
         """Initialize the loop."""
@@ -405,20 +418,20 @@ class InfiniteLooper(ABC, Generic[THashable]):
         """Handle any errors upon initializing the looper."""
         if self.logger is not None:
             getLogger(name=self.logger).error(
-                "%r encountered %r whilst initializing; sleeping for %s...",
+                "%r encountered %r whilst initializing; sleeping %s...",
                 get_class_name(self),
                 repr_error(error),
-                self.sleep_restart,
+                self._sleep_restart_desc,
             )
 
     def _error_upon_core(self, error: Exception, /) -> None:
         """Handle any errors upon running the core function."""
         if self.logger is not None:
             getLogger(name=self.logger).error(
-                "%r encountered %r; sleeping for %s...",
+                "%r encountered %r; sleeping %s...",
                 get_class_name(self),
                 repr_error(error),
-                self.sleep_restart,
+                self._sleep_restart_desc,
             )
 
     def _error_group_upon_coroutines(self, group: ExceptionGroup, /) -> None:
@@ -431,7 +444,7 @@ class InfiniteLooper(ABC, Generic[THashable]):
                 f"- Error #{i}/{n}: {repr_error(e)}"
                 for i, e in enumerate(errors, start=1)
             )
-            msgs.append(f"Sleeping for {self.sleep_restart}...")
+            msgs.append(f"Sleeping {self._sleep_restart_desc}...")
             getLogger(name=self.logger).error("\n".join(msgs))
 
     def _raise_error(self, event: THashable, /) -> NoReturn:
@@ -446,6 +459,29 @@ class InfiniteLooper(ABC, Generic[THashable]):
             event: Event() for event, _ in self._yield_events_and_exceptions()
         }
 
+    async def _run_sleep(self, sleep: _DurationOrEvery, /) -> None:
+        """Sleep until the next part of the loop."""
+        match sleep:
+            case int() | float() | dt.timedelta() as duration:
+                await sleep_dur(duration=duration)
+            case "every", (int() | float() | dt.timedelta()) as duration:
+                await sleep_until_rounded(duration)
+            case _ as never:
+                assert_never(never)
+
+    @property
+    def _sleep_restart_desc(self) -> str:
+        """Get a description of the sleep until restart."""
+        match self.sleep_restart:
+            case int() | float() | dt.timedelta() as duration:
+                timedelta = datetime_duration_to_timedelta(duration)
+                return f"for {timedelta}"
+            case "every", (int() | float() | dt.timedelta()) as duration:
+                timedelta = datetime_duration_to_timedelta(duration)
+                return f"until next {timedelta}"
+            case _ as never:
+                assert_never(never)
+
     def _set_event(self, event: THashable, /) -> None:
         """Set the given event."""
         try:
@@ -686,6 +722,27 @@ async def sleep_dur(*, duration: Duration | None = None) -> None:
 ##
 
 
+async def sleep_until(datetime: dt.datetime, /) -> None:
+    """Sleep until a given time."""
+    await sleep_dur(duration=datetime - get_now())
+
+
+##
+
+
+async def sleep_until_rounded(
+    duration: Duration, /, *, rel_tol: float | None = None, abs_tol: float | None = None
+) -> None:
+    """Sleep until a rounded time; accepts durations."""
+    datetime = round_datetime(
+        get_now(), duration, mode="ceil", rel_tol=rel_tol, abs_tol=abs_tol
+    )
+    await sleep_until(datetime)
+
+
+##
+
+
 @dataclass(kw_only=True, slots=True)
 class StreamCommandOutput:
     process: Process
@@ -768,6 +825,8 @@ __all__ = [
     "put_items",
     "put_items_nowait",
     "sleep_dur",
+    "sleep_until",
+    "sleep_until_rounded",
     "stream_command",
     "timeout_dur",
 ]