dycw-utilities 0.116.6__py3-none-any.whl → 0.117.1__py3-none-any.whl

{dycw_utilities-0.116.6.dist-info → dycw_utilities-0.117.1.dist-info}/METADATA

@@ -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.dist-info → dycw_utilities-0.117.1.dist-info}/RECORD

@@ -1,7 +1,7 @@
-utilities/__init__.py,sha256=SnbbEgMhiQnik2PTXQdCVRriOVeUKTr4S6_qZSLJwj0,60
+utilities/__init__.py,sha256=3AZFp33-B-_k917jGyOdDiXXC3IjJevPa1TRWy9GCgs,60
 utilities/altair.py,sha256=Gpja-flOo-Db0PIPJLJsgzAlXWoKUjPU1qY-DQ829ek,9156
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
-utilities/asyncio.py,sha256=HX5iRmQCbipkbeUgT9Y47KxYvzdqJogysjWygMe5saA,23671
+utilities/asyncio.py,sha256=R_UJvKhbhjUKxzotJUoFiE05pVy5Y6rQqwJodAjFMHY,25443
 utilities/atomicwrites.py,sha256=geFjn9Pwn-tTrtoGjDDxWli9NqbYfy3gGL6ZBctiqSo,5393
 utilities/atools.py,sha256=IYMuFSFGSKyuQmqD6v5IUtDlz8PPw0Sr87Cub_gRU3M,1168
 utilities/cachetools.py,sha256=C1zqOg7BYz0IfQFK8e3qaDDgEZxDpo47F15RTfJM37Q,2910
@@ -12,7 +12,7 @@ utilities/contextvars.py,sha256=RsSGGrbQqqZ67rOydnM7WWIsM2lIE31UHJLejnHJPWY,505
 utilities/cryptography.py,sha256=_CiK_K6c_-uQuUhsUNjNjTL-nqxAh4_1zTfS11Xe120,972
 utilities/cvxpy.py,sha256=Rv1-fD-XYerosCavRF8Pohop2DBkU3AlFaGTfD8AEAA,13776
 utilities/dataclasses.py,sha256=iiC1wpGXWhaocIikzwBt8bbLWyImoUlOlcDZJGejaIg,33011
-utilities/datetime.py,sha256=PcN-4_sSPX1zbpdzBQRdo08pubCuGHyigxkV6SUnvlo,38733
+utilities/datetime.py,sha256=VOwjPibw63Myv-CRYhT2eEHpz277GqUiEDEaI7p-nQw,38985
 utilities/enum.py,sha256=HoRwVCWzsnH0vpO9ZEcAAIZLMv0Sn2vJxxA4sYMQgDs,5793
 utilities/errors.py,sha256=gxsaa7eq7jbYl41Of40-ivjXqJB5gt4QAcJ0smZZMJE,829
 utilities/eventkit.py,sha256=6M5Xu1SzN-juk9PqBHwy5dS-ta7T0qA6SMpDsakOJ0E,13039
@@ -85,10 +85,10 @@ utilities/tzlocal.py,sha256=3upDNFBvGh1l9njmLR2z2S6K6VxQSb7QizYGUbAH3JU,960
 utilities/uuid.py,sha256=jJTFxz-CWgltqNuzmythB7iEQ-Q1mCwPevUfKthZT3c,611
 utilities/version.py,sha256=QFuyEeQA6jI0ruBEcmhqG36f-etg1AEiD1drBBqhQrs,5358
 utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
-utilities/whenever.py,sha256=iLRP_-8CZtBpHKbGZGu-kjSMg1ZubJ-VSmgSy7Eudxw,17787
+utilities/whenever.py,sha256=fC0ZtnO0AyFHsxP4SWj0POI1bf4BIL3Hh4rR51BHfaw,17803
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-Xm57PMMwDTYpxJdkiJG13wnbwK--I7XItBh5WVhD-o,1874
-dycw_utilities-0.116.6.dist-info/METADATA,sha256=8P0vlfhUa8DiK1Pnx0T7YwYBvFO5S7xgFgV7PK6CqM0,12943
-dycw_utilities-0.116.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.116.6.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.116.6.dist-info/RECORD,,
+dycw_utilities-0.117.1.dist-info/METADATA,sha256=jFmm81hWyjNuttvOK52BPLHNdskY53ciWAA7CLMYy_I,12943
+dycw_utilities-0.117.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.117.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.117.1.dist-info/RECORD,,

utilities/__init__.py

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

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",
 ]

utilities/datetime.py

@@ -334,6 +334,52 @@ def datetime_duration_to_float(duration: Duration, /) -> float:
             assert_never(never)
 
 
+def datetime_duration_to_microseconds(duration: Duration, /) -> int:
+    """Compute the number of microseconds in a datetime duration."""
+    timedelta = datetime_duration_to_timedelta(duration)
+    return (
+        _MICROSECONDS_PER_DAY * timedelta.days
+        + _MICROSECONDS_PER_SECOND * timedelta.seconds
+        + timedelta.microseconds
+    )
+
+
+@overload
+def datetime_duration_to_milliseconds(
+    duration: Duration, /, *, strict: Literal[True]
+) -> int: ...
+@overload
+def datetime_duration_to_milliseconds(
+    duration: Duration, /, *, strict: bool = False
+) -> float: ...
+def datetime_duration_to_milliseconds(
+    duration: Duration, /, *, strict: bool = False
+) -> int | float:
+    """Compute the number of milliseconds in a datetime duration."""
+    timedelta = datetime_duration_to_timedelta(duration)
+    microseconds = datetime_duration_to_microseconds(timedelta)
+    milliseconds, remainder = divmod(microseconds, _MICROSECONDS_PER_MILLISECOND)
+    match remainder, strict:
+        case 0, _:
+            return milliseconds
+        case _, True:
+            raise TimedeltaToMillisecondsError(duration=duration, remainder=remainder)
+        case _, False:
+            return milliseconds + remainder / _MICROSECONDS_PER_MILLISECOND
+        case _ as never:
+            assert_never(never)
+
+
+@dataclass(kw_only=True, slots=True)
+class TimedeltaToMillisecondsError(Exception):
+    duration: Duration
+    remainder: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to convert {self.duration} to milliseconds; got {self.remainder} microsecond(s)"
+
+
 def datetime_duration_to_timedelta(duration: Duration, /) -> dt.timedelta:
     """Ensure a datetime duration is a timedelta."""
     match duration:
@@ -651,8 +697,9 @@ YEAR = get_years(n=1)
 ##
 
 
-def is_integral_timedelta(timedelta: dt.timedelta, /) -> bool:
-    """Check if a timedelta is integral."""
+def is_integral_timedelta(duration: Duration, /) -> bool:
+    """Check if a duration is integral."""
+    timedelta = datetime_duration_to_timedelta(duration)
     return (timedelta.seconds == 0) and (timedelta.microseconds == 0)
 
 
@@ -679,9 +726,9 @@ def is_weekday(date: dt.date, /) -> bool:
 ##
 
 
-def is_zero_time(timedelta: dt.timedelta, /) -> bool:
+def is_zero_time(duration: Duration, /) -> bool:
     """Check if a timedelta is 0."""
-    return timedelta == ZERO_TIME
+    return datetime_duration_to_timedelta(duration) == ZERO_TIME
 
 
 ##
@@ -763,7 +810,7 @@ def mean_timedelta(
         case 1:
             return one(timedeltas)
         case _:
-            microseconds = list(map(timedelta_to_microseconds, timedeltas))
+            microseconds = list(map(datetime_duration_to_microseconds, timedeltas))
             mean_float = fmean(microseconds, weights=weights)
             mean_int = round_(mean_float, mode=mode, rel_tol=rel_tol, abs_tol=abs_tol)
             return microseconds_to_timedelta(mean_int)
@@ -781,7 +828,7 @@ class MeanTimeDeltaError(Exception):
 
 def microseconds_since_epoch(datetime: dt.datetime, /) -> int:
     """Compute the number of microseconds since the epoch."""
-    return timedelta_to_microseconds(timedelta_since_epoch(datetime))
+    return datetime_duration_to_microseconds(timedelta_since_epoch(datetime))
 
 
 def microseconds_to_timedelta(microseconds: int, /) -> dt.timedelta:
@@ -980,7 +1027,7 @@ class _ParseTwoDigitYearInvalidStringError(Exception):
 
 def round_datetime(
     datetime: dt.datetime,
-    timedelta: dt.timedelta,
+    duration: Duration,
     /,
     *,
     mode: RoundMode = "standard",
@@ -990,7 +1037,7 @@ def round_datetime(
     """Round a datetime to a timedelta."""
     if datetime.tzinfo is None:
         dividend = microseconds_since_epoch(datetime)
-        divisor = timedelta_to_microseconds(timedelta)
+        divisor = datetime_duration_to_microseconds(duration)
         quotient, remainder = divmod(dividend, divisor)
         rnd_remainder = round_(
             remainder / divisor, mode=mode, rel_tol=rel_tol, abs_tol=abs_tol
@@ -1000,7 +1047,7 @@ def round_datetime(
         return microseconds_since_epoch_to_datetime(microseconds)
     local = datetime.replace(tzinfo=None)
     rounded = round_datetime(
-        local, timedelta, mode=mode, rel_tol=rel_tol, abs_tol=abs_tol
+        local, duration, mode=mode, rel_tol=rel_tol, abs_tol=abs_tol
     )
     return rounded.replace(tzinfo=datetime.tzinfo)
 
@@ -1175,50 +1222,6 @@ def timedelta_since_epoch(date_or_datetime: DateOrDateTime, /) -> dt.timedelta:
             assert_never(never)
 
 
-def timedelta_to_microseconds(timedelta: dt.timedelta, /) -> int:
-    """Compute the number of microseconds in a timedelta."""
-    return (
-        _MICROSECONDS_PER_DAY * timedelta.days
-        + _MICROSECONDS_PER_SECOND * timedelta.seconds
-        + timedelta.microseconds
-    )
-
-
-@overload
-def timedelta_to_milliseconds(
-    timedelta: dt.timedelta, /, *, strict: Literal[True]
-) -> int: ...
-@overload
-def timedelta_to_milliseconds(
-    timedelta: dt.timedelta, /, *, strict: bool = False
-) -> float: ...
-def timedelta_to_milliseconds(
-    timedelta: dt.timedelta, /, *, strict: bool = False
-) -> int | float:
-    """Compute the number of milliseconds in a timedelta."""
-    microseconds = timedelta_to_microseconds(timedelta)
-    milliseconds, remainder = divmod(microseconds, _MICROSECONDS_PER_MILLISECOND)
-    match remainder, strict:
-        case 0, _:
-            return milliseconds
-        case _, True:
-            raise TimedeltaToMillisecondsError(timedelta=timedelta, remainder=remainder)
-        case _, False:
-            return milliseconds + remainder / _MICROSECONDS_PER_MILLISECOND
-        case _ as never:
-            assert_never(never)
-
-
-@dataclass(kw_only=True, slots=True)
-class TimedeltaToMillisecondsError(Exception):
-    timedelta: dt.timedelta
-    remainder: int
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to convert {self.timedelta} to milliseconds; got {self.remainder} microsecond(s)"
-
-
 ##
 
 
@@ -1367,6 +1370,8 @@ __all__ = [
     "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",
@@ -1407,8 +1412,6 @@ __all__ = [
     "serialize_month",
     "sub_duration",
     "timedelta_since_epoch",
-    "timedelta_to_microseconds",
-    "timedelta_to_milliseconds",
     "yield_days",
     "yield_weekdays",
 ]

utilities/whenever.py

@@ -14,8 +14,8 @@ from utilities.datetime import (
     _MICROSECONDS_PER_SECOND,
     ZERO_TIME,
     check_date_not_datetime,
+    datetime_duration_to_microseconds,
     parse_two_digit_year,
-    timedelta_to_microseconds,
 )
 from utilities.math import ParseNumberError, parse_number
 from utilities.re import (
@@ -601,7 +601,7 @@ class SerializeZonedDateTimeError(Exception):
 
 def _to_datetime_delta(timedelta: dt.timedelta, /) -> DateTimeDelta:
     """Serialize a timedelta."""
-    total_microseconds = timedelta_to_microseconds(timedelta)
+    total_microseconds = datetime_duration_to_microseconds(timedelta)
     if total_microseconds == 0:
         return DateTimeDelta()
     if total_microseconds >= 1: