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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.116.6
+Version: 0.117.0
 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.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
-utilities/__init__.py,sha256=SnbbEgMhiQnik2PTXQdCVRriOVeUKTr4S6_qZSLJwj0,60
+utilities/__init__.py,sha256=P9EtLQQfrOCDM1TAOhodQ4gfhNisheGhmugAZrQJYYc,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=HqPgdti3ZJPH7uHJkvmZ2weIVKYEpB6FKh6FBriMAPU,24287
 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.0.dist-info/METADATA,sha256=OB8XvTMe2rLu98khXHV7Y43VtZl_4iotbtejKesZsZg,12943
+dycw_utilities-0.117.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.117.0.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.117.0.dist-info/RECORD,,

utilities/__init__.py

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

utilities/asyncio.py

@@ -41,7 +41,14 @@ 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,
+    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
@@ -55,6 +62,7 @@ from utilities.types import (
 )
 
 if TYPE_CHECKING:
+    import datetime as dt
     from asyncio import _CoroutineLike
     from asyncio.subprocess import Process
     from collections.abc import AsyncIterator, Sequence
@@ -686,6 +694,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 +797,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: