dycw-utilities 0.166.1__tar.gz → 0.166.3__tar.gz

{dycw_utilities-0.166.1 → dycw_utilities-0.166.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.166.1
+Version: 0.166.3
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -12,7 +12,7 @@ Provides-Extra: logging
 Requires-Dist: coloredlogs<15.1,>=15.0.1; extra == 'logging'
 Provides-Extra: test
 Requires-Dist: dycw-pytest-only<2.2,>=2.1.1; extra == 'test'
-Requires-Dist: hypothesis<6.139,>=6.138.2; extra == 'test'
+Requires-Dist: hypothesis<6.139,>=6.138.3; extra == 'test'
 Requires-Dist: pytest-asyncio<1.2,>=1.1.0; extra == 'test'
 Requires-Dist: pytest-cov<6.3,>=6.2.1; extra == 'test'
 Requires-Dist: pytest-instafail<0.6,>=0.5.0; extra == 'test'

{dycw_utilities-0.166.1 → dycw_utilities-0.166.3}/pyproject.toml

@@ -37,7 +37,7 @@ cryptography = [
   "cryptography >=45.0.4, <45.1",
 ]
 cvxpy = [
-  "cvxpy >=1.7.1, <1.8",
+  "cvxpy >=1.7.2, <1.8",
 ]
 dataclasses-test = [
   "orjson",
@@ -68,7 +68,7 @@ http-test = [
   "orjson",
 ]
 hypothesis = [
-  "hypothesis >=6.138.2, <6.139",
+  "hypothesis >=6.138.3, <6.139",
 ]
 hypothesis-test = [
   "libcst",
@@ -233,7 +233,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.166.1"
+version = "0.166.3"
 
 [project.entry-points.pytest11]
 pytest-randomly = "utilities.pytest_plugins.pytest_randomly"
@@ -245,7 +245,7 @@ logging = [
 ]
 test = [
   "dycw-pytest-only >=2.1.1, <2.2",
-  "hypothesis >=6.138.2, <6.139",
+  "hypothesis >=6.138.3, <6.139",
   "pytest >=8.4.1, <8.5",
   "pytest-asyncio >=1.1.0, <1.2",
   "pytest-cov >=6.2.1, <6.3",
@@ -266,7 +266,7 @@ test = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.166.1"
+current_version = "0.166.3"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.166.1 → dycw_utilities-0.166.3}/src/tests/test_whenever.py

@@ -40,7 +40,7 @@ from utilities.hypothesis import (
     zoned_date_times_2000,
 )
 from utilities.sentinel import Sentinel, sentinel
-from utilities.types import TIME_ZONES
+from utilities.types import TIME_ZONES, MaybeCallableTimeLike
 from utilities.tzdata import HongKong, Tokyo, USCentral, USEastern
 from utilities.tzlocal import LOCAL_TIME_ZONE_NAME
 from utilities.whenever import (
@@ -63,6 +63,8 @@ from utilities.whenever import (
     SECOND,
     TIME_DELTA_MAX,
     TIME_DELTA_MIN,
+    TIME_LOCAL,
+    TIME_UTC,
     TODAY_LOCAL,
     TODAY_UTC,
     ZERO_DAYS,
@@ -72,7 +74,6 @@ from utilities.whenever import (
     DatePeriodError,
     MeanDateTimeError,
     MinMaxDateError,
-    PeriodDict,
     TimePeriod,
     ToMonthsAndDaysError,
     ToNanosecondsError,
@@ -120,6 +121,8 @@ from utilities.whenever import (
     get_now_local,
     get_now_local_plain,
     get_now_plain,
+    get_time,
+    get_time_local,
     get_today,
     get_today_local,
     mean_datetime,
@@ -139,6 +142,7 @@ from utilities.whenever import (
     to_py_date_or_date_time,
     to_py_time_delta,
     to_seconds,
+    to_time,
     to_time_delta,
     to_weeks,
     to_years,
@@ -280,13 +284,8 @@ class TestDatePeriod:
 
     @given(data=data(), period=date_periods())
     def test_to_and_from_dict(self, *, data: DataObject, period: DatePeriod) -> None:
-        dict1 = period.to_dict()
-        dstart, dend = dict1["start"], dict1["end"]
-        dict2 = PeriodDict(
-            start=data.draw(sampled_from([dstart, dstart.py_date()])),
-            end=data.draw(sampled_from([dend, dend.py_date()])),
-        )
-        result = DatePeriod.from_dict(dict2)
+        dict_ = data.draw(sampled_from([period.to_dict(), period.to_py_dict()]))
+        result = DatePeriod.from_dict(dict_)
         assert result == period
 
     @given(dates=pairs(dates(), unique=True, sorted=True))
@@ -471,6 +470,25 @@ class TestGetNowPlain:
         assert isinstance(NOW_PLAIN, PlainDateTime)
 
 
+class TestGetTime:
+    @given(time_zone=zone_infos())
+    def test_function(self, *, time_zone: ZoneInfo) -> None:
+        now = get_time(time_zone)
+        assert isinstance(now, Time)
+
+    def test_constant(self) -> None:
+        assert isinstance(TIME_UTC, Time)
+
+
+class TestGetTimeLocal:
+    def test_function(self) -> None:
+        now = get_time_local()
+        assert isinstance(now, Time)
+
+    def test_constant(self) -> None:
+        assert isinstance(TIME_LOCAL, Time)
+
+
 class TestGetToday:
     def test_function(self) -> None:
         today = get_today()
@@ -853,14 +871,11 @@ class TestTimePeriod:
         )
 
     @given(data=data(), period=time_periods())
-    def test_to_and_from_dict(self, *, data: DataObject, period: TimePeriod) -> None:
-        dict1 = period.to_dict()
-        dstart, dend = dict1["start"], dict1["end"]
-        dict2 = PeriodDict(
-            start=data.draw(sampled_from([dstart, dstart.py_time()])),
-            end=data.draw(sampled_from([dend, dend.py_time()])),
-        )
-        result = TimePeriod.from_dict(dict2)
+    def test_to_dict_and_from_dict(
+        self, *, data: DataObject, period: TimePeriod
+    ) -> None:
+        dict_ = data.draw(sampled_from([period.to_dict(), period.to_py_dict()]))
+        result = TimePeriod.from_dict(dict_)
         assert result == period
 
 
@@ -1319,6 +1334,55 @@ class TestToSeconds:
             _ = to_seconds(delta)
 
 
+class TestToTime:
+    def test_default(self) -> None:
+        first = get_today().at(to_time()).assume_tz(UTC.key)
+        second = get_today().at(to_time()).assume_tz(UTC.key)
+        assert abs(first - second) <= SECOND
+
+    @given(time=times())
+    def test_time(self, *, time: Time) -> None:
+        assert to_time(time) == time
+
+    @given(time=times())
+    def test_str(self, *, time: Time) -> None:
+        assert to_time(time.format_common_iso()) == time
+
+    @given(time=times())
+    def test_py_time(self, *, time: Time) -> None:
+        assert to_time(time.py_time()) == time
+
+    @given(time=times())
+    def test_callable(self, *, time: Time) -> None:
+        assert to_time(lambda: time) == time
+
+    def test_none(self) -> None:
+        first = get_today().at(to_time(None)).assume_tz(UTC.key)
+        second = get_today().at(get_time()).assume_tz(UTC.key)
+        assert abs(first - second) <= SECOND
+
+    def test_sentinel(self) -> None:
+        assert to_time(sentinel) is sentinel
+
+    @given(times=pairs(times()))
+    def test_replace_non_sentinel(self, *, times: tuple[Time, Time]) -> None:
+        time1, time2 = times
+
+        @dataclass(kw_only=True, slots=True)
+        class Example:
+            time: Time = field(default_factory=get_time)
+
+            def replace(
+                self, *, time: MaybeCallableTimeLike | Sentinel = sentinel
+            ) -> Self:
+                return replace_non_sentinel(self, time=to_time(time))
+
+        obj = Example(time=time1)
+        assert obj.time == time1
+        assert obj.replace().time == time1
+        assert obj.replace(time=time2).time == time2
+
+
 class TestToWeeks:
     @given(cls=sampled_from([DateDelta, DateTimeDelta]), weeks=integers())
     def test_date_or_date_time_delta(
@@ -1695,13 +1759,8 @@ class TestZonedDateTimePeriod:
     ) -> None:
         start, end = datetimes
         period = ZonedDateTimePeriod(start, end)
-        dict1 = period.to_dict()
-        dstart, dend = dict1["start"], dict1["end"]
-        dict2 = PeriodDict(
-            start=data.draw(sampled_from([dstart, dstart.py_datetime()])),
-            end=data.draw(sampled_from([dend, dend.py_datetime()])),
-        )
-        result = ZonedDateTimePeriod.from_dict(dict2)
+        dict_ = data.draw(sampled_from([period.to_dict(), period.to_py_dict()]))
+        result = ZonedDateTimePeriod.from_dict(dict_)
         assert result == period
 
     @given(period=zoned_date_time_periods())

{dycw_utilities-0.166.1 → dycw_utilities-0.166.3}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.166.1"
+__version__ = "0.166.3"

{dycw_utilities-0.166.1 → dycw_utilities-0.166.3}/src/utilities/types.py

@@ -255,6 +255,7 @@ type DateTimeRoundMode = Literal[
 ]
 type Delta = DateDelta | TimeDelta | DateTimeDelta
 type MaybeCallableDateLike = MaybeCallable[DateLike]
+type MaybeCallableTimeLike = MaybeCallable[TimeLike]
 type MaybeCallableZonedDateTimeLike = MaybeCallable[ZonedDateTimeLike]
 type MonthDayLike = MaybeStr[MonthDay]
 type PlainDateTimeLike = MaybeStr[PlainDateTime]
@@ -308,6 +309,7 @@ __all__ = [
     "MaybeCallableDateLike",
     "MaybeCallablePathLike",
     "MaybeCallableStr",
+    "MaybeCallableTimeLike",
     "MaybeCallableUUIDLike",
     "MaybeCallableZonedDateTimeLike",
     "MaybeCollection",

{dycw_utilities-0.166.1 → dycw_utilities-0.166.3}/src/utilities/whenever.py

@@ -13,7 +13,6 @@ from typing import (
     Self,
     SupportsFloat,
     TypedDict,
-    TypeVar,
     assert_never,
     cast,
     overload,
@@ -47,6 +46,7 @@ if TYPE_CHECKING:
         DateTimeRoundMode,
         Delta,
         MaybeCallableDateLike,
+        MaybeCallableTimeLike,
         MaybeCallableZonedDateTimeLike,
         TimeOrDateTimeDelta,
         TimeZoneLike,
@@ -146,9 +146,6 @@ def sub_year_month(x: YearMonth, /, *, years: int = 0, months: int = 0) -> YearM
 ##
 
 
-_TDate_co = TypeVar("_TDate_co", bound=Date | dt.date, covariant=True)
-
-
 @dataclass(repr=False, order=True, unsafe_hash=True, kw_only=False)
 class DatePeriod:
     """A period of dates."""
@@ -210,7 +207,7 @@ class DatePeriod:
         return f"{fc(start)}-{fc(end)}"
 
     @classmethod
-    def from_dict(cls, mapping: PeriodDict[_TDate_co], /) -> Self:
+    def from_dict(cls, mapping: PeriodDict[Date] | PeriodDict[dt.date], /) -> Self:
         """Convert the dictionary to a period."""
         match mapping["start"]:
             case Date() as start:
@@ -238,6 +235,10 @@ class DatePeriod:
         """Convert the period to a dictionary."""
         return PeriodDict(start=self.start, end=self.end)
 
+    def to_py_dict(self) -> PeriodDict[dt.date]:
+        """Convert the period to a dictionary."""
+        return PeriodDict(start=self.start.py_date(), end=self.end.py_date())
+
 
 @dataclass(kw_only=True, slots=True)
 class DatePeriodError(Exception):
@@ -368,7 +369,7 @@ NOW_UTC = get_now(UTC)
 
 
 def get_now_local() -> ZonedDateTime:
-    """Get the current local date-time."""
+    """Get the current zoned date-time in the local time-zone."""
     return get_now(LOCAL_TIME_ZONE)
 
 
@@ -376,7 +377,7 @@ NOW_LOCAL = get_now_local()
 
 
 def get_now_plain(time_zone: TimeZoneLike = UTC, /) -> PlainDateTime:
-    """Get the current date-time as a plain date-time."""
+    """Get the current plain date-time."""
     return get_now(time_zone).to_plain()
 
 
@@ -384,7 +385,7 @@ NOW_PLAIN = get_now_plain()
 
 
 def get_now_local_plain() -> PlainDateTime:
-    """Get the current local date-time as a plain date-time."""
+    """Get the current plain date-time in the local time-zone."""
     return get_now_local().to_plain()
 
 
@@ -394,6 +395,25 @@ NOW_LOCAL_PLAIN = get_now_local_plain()
 ##
 
 
+def get_time(time_zone: TimeZoneLike = UTC, /) -> Time:
+    """Get the current time."""
+    return get_now(time_zone).time()
+
+
+TIME_UTC = get_time(UTC)
+
+
+def get_time_local() -> Time:
+    """Get the current time in the local time-zone."""
+    return get_time(LOCAL_TIME_ZONE)
+
+
+TIME_LOCAL = get_time_local()
+
+
+##
+
+
 def get_today(time_zone: TimeZoneLike = UTC, /) -> Date:
     """Get the current, timezone-aware local date."""
     return get_now(time_zone).date()
@@ -788,9 +808,6 @@ class _RoundDateOrDateTimeDateTimeIntraDayWithWeekdayError(RoundDateOrDateTimeEr
 ##
 
 
-_TTime_co = TypeVar("_TTime_co", bound=Time | dt.time, covariant=True)
-
-
 @dataclass(repr=False, order=True, unsafe_hash=True, kw_only=False)
 class TimePeriod:
     """A period of times."""
@@ -817,7 +834,7 @@ class TimePeriod:
         return DatePeriod(start, end).at((self.start, self.end), time_zone=time_zone)
 
     @classmethod
-    def from_dict(cls, mapping: PeriodDict[_TTime_co], /) -> Self:
+    def from_dict(cls, mapping: PeriodDict[Time] | PeriodDict[dt.time], /) -> Self:
         """Convert the dictionary to a period."""
         match mapping["start"]:
             case Time() as start:
@@ -845,6 +862,10 @@ class TimePeriod:
         """Convert the period to a dictionary."""
         return PeriodDict(start=self.start, end=self.end)
 
+    def to_py_dict(self) -> PeriodDict[dt.time]:
+        """Convert the period to a dictionary."""
+        return PeriodDict(start=self.start.py_time(), end=self.end.py_time())
+
 
 ##
 
@@ -1377,6 +1398,95 @@ class ToPyTimeDeltaError(Exception):
 ##
 
 
+def to_seconds(delta: Delta, /) -> int:
+    """Compute the number of seconds in a delta."""
+    match delta:
+        case DateDelta():
+            try:
+                days = to_days(delta)
+            except _ToDaysMonthsError as error:
+                raise _ToSecondsMonthsError(delta=delta, months=error.months) from None
+            return 24 * 60 * 60 * days
+        case TimeDelta():
+            nanos = to_nanoseconds(delta)
+            seconds, remainder = divmod(nanos, int(1e9))
+            if remainder != 0:
+                raise _ToSecondsNanosecondsError(delta=delta, nanoseconds=remainder)
+            return seconds
+        case DateTimeDelta():
+            try:
+                return to_seconds(delta.date_part()) + to_seconds(delta.time_part())
+            except _ToSecondsMonthsError as error:
+                raise _ToSecondsMonthsError(delta=delta, months=error.months) from None
+            except _ToSecondsNanosecondsError as error:
+                raise _ToSecondsNanosecondsError(
+                    delta=delta, nanoseconds=error.nanoseconds
+                ) from None
+        case never:
+            assert_never(never)
+
+
+@dataclass(kw_only=True, slots=True)
+class ToSecondsError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _ToSecondsMonthsError(ToSecondsError):
+    delta: DateOrDateTimeDelta
+    months: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Delta must not contain months; got {self.months}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ToSecondsNanosecondsError(ToSecondsError):
+    delta: TimeOrDateTimeDelta
+    nanoseconds: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Delta must not contain extra nanoseconds; got {self.nanoseconds}"
+
+
+##
+
+
+@overload
+def to_time(time: Sentinel, /, *, time_zone: TimeZoneLike = UTC) -> Sentinel: ...
+@overload
+def to_time(
+    time: MaybeCallableTimeLike | None | dt.time = get_time,
+    /,
+    *,
+    time_zone: TimeZoneLike = UTC,
+) -> Time: ...
+def to_time(
+    time: MaybeCallableTimeLike | dt.time | None | Sentinel = get_time,
+    /,
+    *,
+    time_zone: TimeZoneLike = UTC,
+) -> Time | Sentinel:
+    """Convert to a time."""
+    match time:
+        case Time() | Sentinel():
+            return time
+        case None:
+            return get_time(time_zone)
+        case str():
+            return Time.parse_common_iso(time)
+        case dt.time():
+            return Time.from_py_time(time)
+        case Callable() as func:
+            return to_time(func(), time_zone=time_zone)
+        case never:
+            assert_never(never)
+
+
+##
+
+
 def to_time_delta(nanos: int, /) -> TimeDelta:
     """Construct a time delta."""
     components = _to_time_delta_components(nanos)
@@ -1455,61 +1565,6 @@ def _to_time_delta_components(nanos: int, /) -> _TimeDeltaComponents:
 ##
 
 
-def to_seconds(delta: Delta, /) -> int:
-    """Compute the number of seconds in a delta."""
-    match delta:
-        case DateDelta():
-            try:
-                days = to_days(delta)
-            except _ToDaysMonthsError as error:
-                raise _ToSecondsMonthsError(delta=delta, months=error.months) from None
-            return 24 * 60 * 60 * days
-        case TimeDelta():
-            nanos = to_nanoseconds(delta)
-            seconds, remainder = divmod(nanos, int(1e9))
-            if remainder != 0:
-                raise _ToSecondsNanosecondsError(delta=delta, nanoseconds=remainder)
-            return seconds
-        case DateTimeDelta():
-            try:
-                return to_seconds(delta.date_part()) + to_seconds(delta.time_part())
-            except _ToSecondsMonthsError as error:
-                raise _ToSecondsMonthsError(delta=delta, months=error.months) from None
-            except _ToSecondsNanosecondsError as error:
-                raise _ToSecondsNanosecondsError(
-                    delta=delta, nanoseconds=error.nanoseconds
-                ) from None
-        case never:
-            assert_never(never)
-
-
-@dataclass(kw_only=True, slots=True)
-class ToSecondsError(Exception): ...
-
-
-@dataclass(kw_only=True, slots=True)
-class _ToSecondsMonthsError(ToSecondsError):
-    delta: DateOrDateTimeDelta
-    months: int
-
-    @override
-    def __str__(self) -> str:
-        return f"Delta must not contain months; got {self.months}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ToSecondsNanosecondsError(ToSecondsError):
-    delta: TimeOrDateTimeDelta
-    nanoseconds: int
-
-    @override
-    def __str__(self) -> str:
-        return f"Delta must not contain extra nanoseconds; got {self.nanoseconds}"
-
-
-##
-
-
 def to_weeks(delta: Delta, /) -> int:
     """Compute the number of weeks in a delta."""
     try:
@@ -1726,11 +1781,6 @@ class WheneverLogRecord(LogRecord):
 ##
 
 
-_TDateTime_co = TypeVar(
-    "_TDateTime_co", bound=ZonedDateTime | dt.datetime, covariant=True
-)
-
-
 @dataclass(repr=False, order=True, unsafe_hash=True, kw_only=False)
 class ZonedDateTimePeriod:
     """A period of time."""
@@ -1833,7 +1883,9 @@ class ZonedDateTimePeriod:
         return f"{fc(start.to_plain())}-{fc(end, fmt='%Y%m%dT%H')}"
 
     @classmethod
-    def from_dict(cls, mapping: PeriodDict[_TDateTime_co], /) -> Self:
+    def from_dict(
+        cls, mapping: PeriodDict[ZonedDateTime] | PeriodDict[dt.datetime], /
+    ) -> Self:
         """Convert the dictionary to a period."""
         match mapping["start"]:
             case ZonedDateTime() as start:
@@ -1869,6 +1921,10 @@ class ZonedDateTimePeriod:
         """Convert the period to a dictionary."""
         return PeriodDict(start=self.start, end=self.end)
 
+    def to_py_dict(self) -> PeriodDict[dt.datetime]:
+        """Convert the period to a dictionary."""
+        return PeriodDict(start=self.start.py_datetime(), end=self.end.py_datetime())
+
     def to_tz(self, time_zone: TimeZoneLike, /) -> Self:
         """Convert the time zone."""
         tz = to_time_zone_name(time_zone)
@@ -1933,6 +1989,8 @@ __all__ = [
     "SECOND",
     "TIME_DELTA_MAX",
     "TIME_DELTA_MIN",
+    "TIME_LOCAL",
+    "TIME_UTC",
     "TODAY_LOCAL",
     "TODAY_UTC",
     "WEEK",
@@ -1971,6 +2029,8 @@ __all__ = [
     "get_now_local",
     "get_now_local_plain",
     "get_now_plain",
+    "get_time",
+    "get_time_local",
     "get_today",
     "get_today_local",
     "mean_datetime",
@@ -1989,6 +2049,7 @@ __all__ = [
     "to_py_date_or_date_time",
     "to_py_time_delta",
     "to_seconds",
+    "to_time",
     "to_weeks",
     "to_years",
     "to_zoned_date_time",