dycw-utilities 0.166.1__py3-none-any.whl → 0.166.3__py3-none-any.whl

{dycw_utilities-0.166.1.dist-info → dycw_utilities-0.166.3.dist-info}/METADATA

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

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=pk8s8uyCf9TfamkXymCVi1C6C_xH9yc5UV3b1hbP1Nk,60
+utilities/__init__.py,sha256=UJOTjSCJcrHgKEbkrpzbpKR9zl61qcqWMWYPiX3nvjI,60
 utilities/aeventkit.py,sha256=ddoleSwW9zdc2tjX5Ge0pMKtYwV_JMxhHYOxnWX2AGM,12609
 utilities/altair.py,sha256=92E2lCdyHY4Zb-vCw6rEJIsWdKipuu-Tu2ab1ufUfAk,9079
 utilities/asyncio.py,sha256=PUedzQ5deqlSECQ33sam9cRzI9TnygHz3FdOqWJWPTM,15288
@@ -75,21 +75,21 @@ utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=oXfTii6ymu57niP0BDGZjFD55LEHi2a19kqZKiTgaFQ,2588
 utilities/traceback.py,sha256=b1nSvlyrGmI1MyZLkkoLVET3DQBSGt9qqIlAAQbyjEw,9629
 utilities/typed_settings.py,sha256=SFWqS3lAzV7IfNRwqFcTk0YynTcQ7BmrcW2mr_KUnos,4466
-utilities/types.py,sha256=oeH-hEC3-67Eja4nLz-Nj9WvK6Z9-3T1zobO_XJpuVg,18735
+utilities/types.py,sha256=IlRrCtPdLkGYVfpe-QIg2qNUgBr8OJNN7BhTKxnhh-M,18817
 utilities/typing.py,sha256=QYoCIc71e_u5W-kBeiNzrD-GXxpLtMOGc9PqgZjMXeE,25274
 utilities/tzdata.py,sha256=fgNVj66yUbCSI_-vrRVzSD3gtf-L_8IEJEPjP_Jel5Y,266
 utilities/tzlocal.py,sha256=KyCXEgCTjqGFx-389JdTuhMRUaT06U1RCMdWoED-qro,728
 utilities/uuid.py,sha256=nQZs6tFX4mqtc2Ku3KqjloYCqwpTKeTj8eKwQwh3FQI,1572
 utilities/version.py,sha256=ipBj5-WYY_nelp2uwFlApfWWCzTLzPwpovUi9x_OBMs,5085
 utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
-utilities/whenever.py,sha256=8jQZkE3_8E4A10oQM-OYIJpWtvBBtYTf-WIv3cVxL9w,57555
+utilities/whenever.py,sha256=0N5JcZU9cPyIrkTN3wqdcR86PsmIKVlLI1yU1aEbIgk,59198
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=tdIScrTB2-B-LH0ukb1HUXKooLknOfJNwHk10MuMYvA,3619
 utilities/pytest_plugins/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
 utilities/pytest_plugins/pytest_randomly.py,sha256=B1qYVlExGOxTywq2r1SMi5o7btHLk2PNdY_b1p98dkE,409
 utilities/pytest_plugins/pytest_regressions.py,sha256=9v8kAXDM2ycIXJBimoiF4EgrwbUvxTycFWJiGR_GHhM,1466
-dycw_utilities-0.166.1.dist-info/METADATA,sha256=tFhmfKrHbWlljJMUoGWMcLeXSJiVMMXbAAqlqwE6rTQ,1696
-dycw_utilities-0.166.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.166.1.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
-dycw_utilities-0.166.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.166.1.dist-info/RECORD,,
+dycw_utilities-0.166.3.dist-info/METADATA,sha256=icTUtPfUwAxKgqCxRokuMZ-Oc5KA1cCeawM_4WM5KQY,1696
+dycw_utilities-0.166.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.166.3.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
+dycw_utilities-0.166.3.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.166.3.dist-info/RECORD,,

utilities/__init__.py

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

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

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