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

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

@@ -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 → dycw_utilities-0.117.0}/pyproject.toml

@@ -92,7 +92,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.116.6"
+version = "0.117.0"
 
 [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.0"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

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

@@ -48,11 +48,13 @@ from utilities.asyncio import (
     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, 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
@@ -951,6 +953,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.0}/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.0}/src/utilities/__init__.py

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

{dycw_utilities-0.116.6 → dycw_utilities-0.117.0}/src/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",
 ]

{dycw_utilities-0.116.6 → dycw_utilities-0.117.0}/src/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",
 ]

{dycw_utilities-0.116.6 → dycw_utilities-0.117.0}/src/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: