dycw-utilities 0.148.4__py3-none-any.whl → 0.174.12__py3-none-any.whl

utilities/whenever.py

@@ -10,12 +10,15 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Literal,
+    Self,
     SupportsFloat,
+    TypedDict,
     assert_never,
     cast,
     overload,
     override,
 )
+from zoneinfo import ZoneInfo
 
 from whenever import (
     Date,
@@ -29,27 +32,28 @@ from whenever import (
     ZonedDateTime,
 )
 
+from utilities.dataclasses import replace_non_sentinel
+from utilities.functions import get_class_name
 from utilities.math import sign
 from utilities.platform import get_strftime
 from utilities.sentinel import Sentinel, sentinel
 from utilities.tzlocal import LOCAL_TIME_ZONE, LOCAL_TIME_ZONE_NAME
-from utilities.zoneinfo import UTC, get_time_zone_name
+from utilities.zoneinfo import UTC, to_time_zone_name
 
 if TYPE_CHECKING:
-    from zoneinfo import ZoneInfo
-
     from utilities.types import (
         DateOrDateTimeDelta,
         DateTimeRoundMode,
         Delta,
-        MaybeCallableDate,
-        MaybeCallableZonedDateTime,
+        MaybeCallableDateLike,
+        MaybeCallableTimeLike,
+        MaybeCallableZonedDateTimeLike,
         TimeOrDateTimeDelta,
         TimeZoneLike,
     )
 
 
-## bounds
+# bounds
 
 
 ZONED_DATE_TIME_MIN = PlainDateTime.MIN.assume_tz(UTC.key)
@@ -142,6 +146,113 @@ def sub_year_month(x: YearMonth, /, *, years: int = 0, months: int = 0) -> YearM
 ##
 
 
+@dataclass(repr=False, order=True, unsafe_hash=True, kw_only=False)
+class DatePeriod:
+    """A period of dates."""
+
+    start: Date
+    end: Date
+
+    def __post_init__(self) -> None:
+        if self.start > self.end:
+            raise DatePeriodError(start=self.start, end=self.end)
+
+    def __add__(self, other: DateDelta, /) -> Self:
+        """Offset the period."""
+        return self.replace(start=self.start + other, end=self.end + other)
+
+    def __contains__(self, other: Date, /) -> bool:
+        """Check if a date/datetime lies in the period."""
+        return self.start <= other <= self.end
+
+    @override
+    def __repr__(self) -> str:
+        cls = get_class_name(self)
+        return f"{cls}({self.start}, {self.end})"
+
+    def __sub__(self, other: DateDelta, /) -> Self:
+        """Offset the period."""
+        return self.replace(start=self.start - other, end=self.end - other)
+
+    def at(
+        self, obj: Time | tuple[Time, Time], /, *, time_zone: TimeZoneLike = UTC
+    ) -> ZonedDateTimePeriod:
+        """Combine a date with a time to create a datetime."""
+        match obj:
+            case Time() as time:
+                start = end = time
+            case Time() as start, Time() as end:
+                ...
+            case never:
+                assert_never(never)
+        tz = to_time_zone_name(time_zone)
+        return ZonedDateTimePeriod(
+            self.start.at(start).assume_tz(tz), self.end.at(end).assume_tz(tz)
+        )
+
+    @property
+    def delta(self) -> DateDelta:
+        """The delta of the period."""
+        return self.end - self.start
+
+    def format_compact(self) -> str:
+        """Format the period in a compact fashion."""
+        fc, start, end = format_compact, self.start, self.end
+        if self.start == self.end:
+            return f"{fc(start)}="
+        if self.start.year_month() == self.end.year_month():
+            return f"{fc(start)}-{fc(end, fmt='%d')}"
+        if self.start.year == self.end.year:
+            return f"{fc(start)}-{fc(end, fmt='%m%d')}"
+        return f"{fc(start)}-{fc(end)}"
+
+    @classmethod
+    def from_dict(cls, mapping: PeriodDict[Date] | PeriodDict[dt.date], /) -> Self:
+        """Convert the dictionary to a period."""
+        match mapping["start"]:
+            case Date() as start:
+                ...
+            case dt.date() as py_date:
+                start = Date.from_py_date(py_date)
+            case never:
+                assert_never(never)
+        match mapping["end"]:
+            case Date() as end:
+                ...
+            case dt.date() as py_date:
+                end = Date.from_py_date(py_date)
+            case never:
+                assert_never(never)
+        return cls(start=start, end=end)
+
+    def replace(
+        self, *, start: Date | Sentinel = sentinel, end: Date | Sentinel = sentinel
+    ) -> Self:
+        """Replace elements of the period."""
+        return replace_non_sentinel(self, start=start, end=end)
+
+    def to_dict(self) -> PeriodDict[Date]:
+        """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):
+    start: Date
+    end: Date
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid period; got {self.start} > {self.end}"
+
+
+##
+
+
 def datetime_utc(
     year: int,
     month: int,
@@ -200,7 +311,11 @@ def diff_year_month(
 
 
 def format_compact(
-    obj: Date | Time | PlainDateTime | ZonedDateTime, /, *, fmt: str | None = None
+    obj: Date | Time | PlainDateTime | ZonedDateTime,
+    /,
+    *,
+    fmt: str | None = None,
+    path: bool = False,
 ) -> str:
     """Format the date/datetime in a compact fashion."""
     match obj:
@@ -210,12 +325,16 @@ def format_compact(
         case Time() as time:
             obj_use = time.round().py_time()
             fmt_use = "%H%M%S" if fmt is None else fmt
-        case PlainDateTime() as datetime:
-            obj_use = datetime.round().py_datetime()
+        case PlainDateTime() as date_time:
+            obj_use = date_time.round().py_datetime()
             fmt_use = "%Y%m%dT%H%M%S" if fmt is None else fmt
-        case ZonedDateTime() as datetime:
-            return f"{format_compact(datetime.to_plain(), fmt=fmt)}[{datetime.tz}]"
-        case _ as never:
+        case ZonedDateTime() as date_time:
+            plain = format_compact(date_time.to_plain(), fmt=fmt)
+            tz = date_time.tz
+            if path:
+                tz = tz.replace("/", "~")
+            return f"{plain}[{tz}]"
+        case never:
             assert_never(never)
     return obj_use.strftime(get_strftime(fmt_use))
 
@@ -225,52 +344,87 @@ def format_compact(
 
 def from_timestamp(i: float, /, *, time_zone: TimeZoneLike = UTC) -> ZonedDateTime:
     """Get a zoned datetime from a timestamp."""
-    return ZonedDateTime.from_timestamp(i, tz=get_time_zone_name(time_zone))
+    return ZonedDateTime.from_timestamp(i, tz=to_time_zone_name(time_zone))
 
 
 def from_timestamp_millis(i: int, /, *, time_zone: TimeZoneLike = UTC) -> ZonedDateTime:
     """Get a zoned datetime from a timestamp (in milliseconds)."""
-    return ZonedDateTime.from_timestamp_millis(i, tz=get_time_zone_name(time_zone))
+    return ZonedDateTime.from_timestamp_millis(i, tz=to_time_zone_name(time_zone))
 
 
 def from_timestamp_nanos(i: int, /, *, time_zone: TimeZoneLike = UTC) -> ZonedDateTime:
     """Get a zoned datetime from a timestamp (in nanoseconds)."""
-    return ZonedDateTime.from_timestamp_nanos(i, tz=get_time_zone_name(time_zone))
+    return ZonedDateTime.from_timestamp_nanos(i, tz=to_time_zone_name(time_zone))
 
 
 ##
 
 
-def get_now(*, time_zone: TimeZoneLike = UTC) -> ZonedDateTime:
-    """Get the current zoned datetime."""
-    return ZonedDateTime.now(get_time_zone_name(time_zone))
+def get_now(time_zone: TimeZoneLike = UTC, /) -> ZonedDateTime:
+    """Get the current zoned date-time."""
+    return ZonedDateTime.now(to_time_zone_name(time_zone))
 
 
-NOW_UTC = get_now(time_zone=UTC)
+NOW_UTC = get_now(UTC)
 
 
 def get_now_local() -> ZonedDateTime:
-    """Get the current local time."""
-    return get_now(time_zone=LOCAL_TIME_ZONE)
+    """Get the current zoned date-time in the local time-zone."""
+    return get_now(LOCAL_TIME_ZONE)
 
 
 NOW_LOCAL = get_now_local()
 
 
+def get_now_plain(time_zone: TimeZoneLike = UTC, /) -> PlainDateTime:
+    """Get the current plain date-time."""
+    return get_now(time_zone).to_plain()
+
+
+NOW_PLAIN = get_now_plain()
+
+
+def get_now_local_plain() -> PlainDateTime:
+    """Get the current plain date-time in the local time-zone."""
+    return get_now_local().to_plain()
+
+
+NOW_LOCAL_PLAIN = get_now_local_plain()
+
+
 ##
 
 
-def get_today(*, time_zone: TimeZoneLike = UTC) -> Date:
+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=time_zone).date()
+    return get_now(time_zone).date()
 
 
-TODAY_UTC = get_today(time_zone=UTC)
+TODAY_UTC = get_today(UTC)
 
 
 def get_today_local() -> Date:
     """Get the current, timezone-aware local date."""
-    return get_today(time_zone=LOCAL_TIME_ZONE)
+    return get_today(LOCAL_TIME_ZONE)
 
 
 TODAY_LOCAL = get_today_local()
@@ -279,6 +433,36 @@ TODAY_LOCAL = get_today_local()
 ##
 
 
+def is_weekend(
+    date_time: ZonedDateTime,
+    /,
+    *,
+    start: tuple[Weekday, Time] = (Weekday.SATURDAY, Time.MIN),
+    end: tuple[Weekday, Time] = (Weekday.SUNDAY, Time.MAX),
+) -> bool:
+    """Check if a datetime is in the weekend."""
+    weekday, time = date_time.date().day_of_week(), date_time.time()
+    start_weekday, start_time = start
+    end_weekday, end_time = end
+    if start_weekday.value == end_weekday.value:
+        return start_time <= time <= end_time
+    if start_weekday.value < end_weekday.value:
+        return (
+            ((weekday == start_weekday) and (time >= start_time))
+            or (start_weekday.value < weekday.value < end_weekday.value)
+            or ((weekday == end_weekday) and (time <= end_time))
+        )
+    return (
+        ((weekday == start_weekday) and (time >= start_time))
+        or (weekday.value > start_weekday.value)
+        or (weekday.value < end_weekday.value)
+        or ((weekday == end_weekday) and (time <= end_time))
+    )
+
+
+##
+
+
 def mean_datetime(
     datetimes: Iterable[ZonedDateTime],
     /,
@@ -317,7 +501,7 @@ def min_max_date(
     time_zone: TimeZoneLike = UTC,
 ) -> tuple[Date | None, Date | None]:
     """Compute the min/max date given a combination of dates/ages."""
-    today = get_today(time_zone=time_zone)
+    today = get_today(time_zone)
     min_parts: list[Date] = []
     if min_date is not None:
         min_parts.append(min_date)
@@ -357,6 +541,18 @@ class _MinMaxDatePeriodError(MinMaxDateError):
 ##
 
 
+class PeriodDict[T: Date | Time | ZonedDateTime | dt.date | dt.time | dt.datetime](
+    TypedDict
+):
+    """A period as a dictionary."""
+
+    start: T
+    end: T
+
+
+##
+
+
 type _RoundDateDailyUnit = Literal["W", "D"]
 type _RoundDateTimeUnit = Literal["H", "M", "S", "ms", "us", "ns"]
 type _RoundDateOrDateTimeUnit = _RoundDateDailyUnit | _RoundDateTimeUnit
@@ -397,7 +593,7 @@ def round_date_or_date_time[T: Date | PlainDateTime | ZonedDateTime](
             raise _RoundDateOrDateTimeDateTimeIntraDayWithWeekdayError(
                 date_time=date_time, delta=delta, weekday=weekday
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -491,7 +687,7 @@ def _round_date_weekly_or_daily(
             return _round_date_daily(date, increment, mode=mode)
         case "D", Weekday():
             raise _RoundDateOrDateTimeDateWithWeekdayError(weekday=weekday)
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -537,7 +733,7 @@ def _round_date_daily(
             threshold = increment // 2 + 1
         case "half_ceil":
             threshold = increment // 2 or 1
-        case _ as never:
+        case never:
             assert_never(never)
     round_up = remainder >= threshold
     return base.add(days=(quotient + round_up) * increment)
@@ -564,7 +760,7 @@ def _round_date_time_intraday[T: PlainDateTime | ZonedDateTime](
             unit_use = "microsecond"
         case "ns":
             unit_use = "nanosecond"
-        case _ as never:
+        case never:
             assert_never(never)
     return date_time.round(unit_use, increment=increment, mode=mode)
 
@@ -642,28 +838,96 @@ class _RoundDateOrDateTimeDateTimeIntraDayWithWeekdayError(RoundDateOrDateTimeEr
 ##
 
 
+@dataclass(repr=False, order=True, unsafe_hash=True, kw_only=False)
+class TimePeriod:
+    """A period of times."""
+
+    start: Time
+    end: Time
+
+    @override
+    def __repr__(self) -> str:
+        cls = get_class_name(self)
+        return f"{cls}({self.start}, {self.end})"
+
+    def at(
+        self, obj: Date | tuple[Date, Date], /, *, time_zone: TimeZoneLike = UTC
+    ) -> ZonedDateTimePeriod:
+        """Combine a date with a time to create a datetime."""
+        match obj:
+            case Date() as date:
+                start = end = date
+            case Date() as start, Date() as end:
+                ...
+            case never:
+                assert_never(never)
+        return DatePeriod(start, end).at((self.start, self.end), time_zone=time_zone)
+
+    @classmethod
+    def from_dict(cls, mapping: PeriodDict[Time] | PeriodDict[dt.time], /) -> Self:
+        """Convert the dictionary to a period."""
+        match mapping["start"]:
+            case Time() as start:
+                ...
+            case dt.time() as py_time:
+                start = Time.from_py_time(py_time)
+            case never:
+                assert_never(never)
+        match mapping["end"]:
+            case Time() as end:
+                ...
+            case dt.time() as py_time:
+                end = Time.from_py_time(py_time)
+            case never:
+                assert_never(never)
+        return cls(start=start, end=end)
+
+    def replace(
+        self, *, start: Time | Sentinel = sentinel, end: Time | Sentinel = sentinel
+    ) -> Self:
+        """Replace elements of the period."""
+        return replace_non_sentinel(self, start=start, end=end)
+
+    def to_dict(self) -> PeriodDict[Time]:
+        """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())
+
+
+##
+
+
 @overload
-def to_date(*, date: MaybeCallableDate) -> Date: ...
-@overload
-def to_date(*, date: None) -> None: ...
-@overload
-def to_date(*, date: Sentinel) -> Sentinel: ...
-@overload
-def to_date(*, date: MaybeCallableDate | Sentinel) -> Date | Sentinel: ...
+def to_date(date: Sentinel, /, *, time_zone: TimeZoneLike = UTC) -> Sentinel: ...
 @overload
 def to_date(
-    *, date: MaybeCallableDate | None | Sentinel = sentinel
-) -> Date | None | Sentinel: ...
+    date: MaybeCallableDateLike | None | dt.date = get_today,
+    /,
+    *,
+    time_zone: TimeZoneLike = UTC,
+) -> Date: ...
 def to_date(
-    *, date: MaybeCallableDate | None | Sentinel = sentinel
-) -> Date | None | Sentinel:
-    """Get the date."""
+    date: MaybeCallableDateLike | dt.date | None | Sentinel = get_today,
+    /,
+    *,
+    time_zone: TimeZoneLike = UTC,
+) -> Date | Sentinel:
+    """Convert to a date."""
     match date:
-        case Date() | None | Sentinel():
+        case Date() | Sentinel():
             return date
+        case None:
+            return get_today(time_zone)
+        case str():
+            return Date.parse_iso(date)
+        case dt.date():
+            return Date.from_py_date(date)
         case Callable() as func:
-            return to_date(date=func())
-        case _ as never:
+            return to_date(func(), time_zone=time_zone)
+        case never:
             assert_never(never)
 
 
@@ -730,7 +994,7 @@ def to_days(delta: Delta, /) -> int:
                 raise _ToDaysNanosecondsError(
                     delta=delta, nanoseconds=error.nanoseconds
                 ) from None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -786,7 +1050,7 @@ def to_hours(delta: Delta, /) -> int:
                 raise _ToHoursNanosecondsError(
                     delta=delta, nanoseconds=error.nanoseconds
                 ) from None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -817,14 +1081,6 @@ class _ToHoursNanosecondsError(ToHoursError):
 ##
 
 
-def to_local_plain(date_time: ZonedDateTime, /) -> PlainDateTime:
-    """Convert a datetime to its local/plain variant."""
-    return date_time.to_tz(LOCAL_TIME_ZONE_NAME).to_plain()
-
-
-##
-
-
 def to_microseconds(delta: Delta, /) -> int:
     """Compute the number of microseconds in a delta."""
     match delta:
@@ -857,7 +1113,7 @@ def to_microseconds(delta: Delta, /) -> int:
                 raise _ToMicrosecondsNanosecondsError(
                     delta=delta, nanoseconds=error.nanoseconds
                 ) from None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -920,7 +1176,7 @@ def to_milliseconds(delta: Delta, /) -> int:
                 raise _ToMillisecondsNanosecondsError(
                     delta=delta, nanoseconds=error.nanoseconds
                 ) from None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -975,7 +1231,7 @@ def to_minutes(delta: Delta, /) -> int:
                 raise _ToMinutesNanosecondsError(
                     delta=delta, nanoseconds=error.nanoseconds
                 ) from None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1021,7 +1277,7 @@ def to_months(delta: DateOrDateTimeDelta, /) -> int:
                 return to_months(delta.date_part())
             except _ToMonthsDaysError as error:
                 raise _ToMonthsDaysError(delta=delta, days=error.days) from None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1060,7 +1316,7 @@ def to_months_and_days(delta: DateOrDateTimeDelta, /) -> tuple[int, int]:
             if delta.time_part() != TimeDelta():
                 raise ToMonthsAndDaysError(delta=delta)
             return to_months_and_days(delta.date_part())
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1094,7 +1350,7 @@ def to_nanoseconds(delta: Delta, /) -> int:
                 )
             except ToNanosecondsError as error:
                 raise ToNanosecondsError(delta=delta, months=error.months) from None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1128,7 +1384,7 @@ def to_py_date_or_date_time(
             return date_time.py_datetime()
         case None:
             return None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1156,7 +1412,7 @@ def to_py_time_delta(delta: Delta | None, /) -> dt.timedelta | None:
             )
         case None:
             return None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1172,6 +1428,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_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)
@@ -1250,61 +1595,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 _ as 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:
@@ -1377,7 +1667,7 @@ def to_years(delta: DateOrDateTimeDelta, /) -> int:
                 raise _ToYearsMonthsError(delta=delta, months=error.months) from None
             except _ToYearsDaysError as error:
                 raise _ToYearsDaysError(delta=delta, days=error.days) from None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1418,22 +1708,56 @@ class _ToYearsTimeError(ToYearsError):
 
 
 @overload
-def to_zoned_date_time(*, date_time: MaybeCallableZonedDateTime) -> ZonedDateTime: ...
-@overload
-def to_zoned_date_time(*, date_time: None) -> None: ...
+def to_zoned_date_time(
+    date_time: Sentinel, /, *, time_zone: TimeZoneLike | None = None
+) -> Sentinel: ...
 @overload
-def to_zoned_date_time(*, date_time: Sentinel) -> Sentinel: ...
 def to_zoned_date_time(
-    *, date_time: MaybeCallableZonedDateTime | None | Sentinel = sentinel
-) -> ZonedDateTime | None | Sentinel:
-    """Resolve into a zoned date_time."""
+    date_time: MaybeCallableZonedDateTimeLike | dt.datetime | None = get_now,
+    /,
+    *,
+    time_zone: TimeZoneLike | None = None,
+) -> ZonedDateTime: ...
+def to_zoned_date_time(
+    date_time: MaybeCallableZonedDateTimeLike | dt.datetime | None | Sentinel = get_now,
+    /,
+    *,
+    time_zone: TimeZoneLike | None = None,
+) -> ZonedDateTime | Sentinel:
+    """Convert to a zoned date-time."""
     match date_time:
-        case ZonedDateTime() | None | Sentinel():
-            return date_time
+        case ZonedDateTime() as date_time_use:
+            ...
+        case Sentinel():
+            return sentinel
+        case None:
+            return get_now(UTC if time_zone is None else time_zone)
+        case str() as text:
+            date_time_use = ZonedDateTime.parse_iso(text.replace("~", "/"))
+        case dt.datetime() as py_date_time:
+            if isinstance(date_time.tzinfo, ZoneInfo):
+                py_date_time_use = py_date_time
+            elif date_time.tzinfo is dt.UTC:
+                py_date_time_use = py_date_time.astimezone(UTC)
+            else:
+                raise ToZonedDateTimeError(date_time=date_time)
+            date_time_use = ZonedDateTime.from_py_datetime(py_date_time_use)
         case Callable() as func:
-            return to_zoned_date_time(date_time=func())
-        case _ as never:
+            return to_zoned_date_time(func(), time_zone=time_zone)
+        case never:
             assert_never(never)
+    if time_zone is None:
+        return date_time_use
+    return date_time_use.to_tz(to_time_zone_name(time_zone))
+
+
+@dataclass(kw_only=True, slots=True)
+class ToZonedDateTimeError(Exception):
+    date_time: dt.datetime
+
+    @override
+    def __str__(self) -> str:
+        return f"Expected date-time to have a `ZoneInfo` or `dt.UTC` as its timezone; got {self.date_time.tzinfo}"
 
 
 ##
@@ -1473,32 +1797,203 @@ class WheneverLogRecord(LogRecord):
             name, level, pathname, lineno, msg, args, exc_info, func, sinfo
         )
         length = self._get_length()
-        plain = format(get_now_local().to_plain().format_common_iso(), f"{length}s")
-        time_zone = self._get_time_zone_key()
-        self.zoned_datetime = f"{plain}[{time_zone}]"
-
-    @classmethod
-    @cache
-    def _get_time_zone(cls) -> ZoneInfo:
-        """Get the local timezone."""
-        try:
-            from utilities.tzlocal import get_local_time_zone
-        except ModuleNotFoundError:  # pragma: no cover
-            return UTC
-        return get_local_time_zone()
-
-    @classmethod
-    @cache
-    def _get_time_zone_key(cls) -> str:
-        """Get the local timezone as a string."""
-        return cls._get_time_zone().key
+        plain = format(get_now_local().to_plain().format_iso(), f"{length}s")
+        self.zoned_datetime = f"{plain}[{LOCAL_TIME_ZONE_NAME}]"
 
     @classmethod
     @cache
     def _get_length(cls) -> int:
         """Get maximum length of a formatted string."""
         now = get_now_local().replace(nanosecond=1000).to_plain()
-        return len(now.format_common_iso())
+        return len(now.format_iso())
+
+
+##
+
+
+@dataclass(repr=False, order=True, unsafe_hash=True, kw_only=False)
+class ZonedDateTimePeriod:
+    """A period of time."""
+
+    start: ZonedDateTime
+    end: ZonedDateTime
+
+    def __post_init__(self) -> None:
+        if self.start > self.end:
+            raise _ZonedDateTimePeriodInvalidError(start=self.start, end=self.end)
+        if self.start.tz != self.end.tz:
+            raise _ZonedDateTimePeriodTimeZoneError(
+                start=ZoneInfo(self.start.tz), end=ZoneInfo(self.end.tz)
+            )
+
+    def __add__(self, other: TimeDelta, /) -> Self:
+        """Offset the period."""
+        return self.replace(start=self.start + other, end=self.end + other)
+
+    def __contains__(self, other: ZonedDateTime, /) -> bool:
+        """Check if a date/datetime lies in the period."""
+        return self.start <= other <= self.end
+
+    @override
+    def __repr__(self) -> str:
+        cls = get_class_name(self)
+        return f"{cls}({self.start.to_plain()}, {self.end.to_plain()}[{self.time_zone.key}])"
+
+    def __sub__(self, other: TimeDelta, /) -> Self:
+        """Offset the period."""
+        return self.replace(start=self.start - other, end=self.end - other)
+
+    @property
+    def delta(self) -> TimeDelta:
+        """The duration of the period."""
+        return self.end - self.start
+
+    @overload
+    def exact_eq(self, period: ZonedDateTimePeriod, /) -> bool: ...
+    @overload
+    def exact_eq(self, start: ZonedDateTime, end: ZonedDateTime, /) -> bool: ...
+    @overload
+    def exact_eq(
+        self, start: PlainDateTime, end: PlainDateTime, time_zone: ZoneInfo, /
+    ) -> bool: ...
+    def exact_eq(self, *args: Any) -> bool:
+        """Check if a period is exactly equal to another."""
+        if (len(args) == 1) and isinstance(args[0], ZonedDateTimePeriod):
+            return self.start.exact_eq(args[0].start) and self.end.exact_eq(args[0].end)
+        if (
+            (len(args) == 2)
+            and isinstance(args[0], ZonedDateTime)
+            and isinstance(args[1], ZonedDateTime)
+        ):
+            return self.exact_eq(ZonedDateTimePeriod(args[0], args[1]))
+        if (
+            (len(args) == 3)
+            and isinstance(args[0], PlainDateTime)
+            and isinstance(args[1], PlainDateTime)
+            and isinstance(args[2], ZoneInfo)
+        ):
+            return self.exact_eq(
+                ZonedDateTimePeriod(
+                    args[0].assume_tz(args[2].key), args[1].assume_tz(args[2].key)
+                )
+            )
+        raise _ZonedDateTimePeriodExactEqError(args=args)
+
+    def format_compact(self) -> str:
+        """Format the period in a compact fashion."""
+        fc, start, end = format_compact, self.start, self.end
+        if start == end:
+            if end.second != 0:
+                return f"{fc(start)}="
+            if end.minute != 0:
+                return f"{fc(start, fmt='%Y%m%dT%H%M')}="
+            return f"{fc(start, fmt='%Y%m%dT%H')}="
+        if start.date() == end.date():
+            if end.second != 0:
+                return f"{fc(start.to_plain())}-{fc(end, fmt='%H%M%S')}"
+            if end.minute != 0:
+                return f"{fc(start.to_plain())}-{fc(end, fmt='%H%M')}"
+            return f"{fc(start.to_plain())}-{fc(end, fmt='%H')}"
+        if start.date().year_month() == end.date().year_month():
+            if end.second != 0:
+                return f"{fc(start.to_plain())}-{fc(end, fmt='%dT%H%M%S')}"
+            if end.minute != 0:
+                return f"{fc(start.to_plain())}-{fc(end, fmt='%dT%H%M')}"
+            return f"{fc(start.to_plain())}-{fc(end, fmt='%dT%H')}"
+        if start.year == end.year:
+            if end.second != 0:
+                return f"{fc(start.to_plain())}-{fc(end, fmt='%m%dT%H%M%S')}"
+            if end.minute != 0:
+                return f"{fc(start.to_plain())}-{fc(end, fmt='%m%dT%H%M')}"
+            return f"{fc(start.to_plain())}-{fc(end, fmt='%m%dT%H')}"
+        if end.second != 0:
+            return f"{fc(start.to_plain())}-{fc(end)}"
+        if end.minute != 0:
+            return f"{fc(start.to_plain())}-{fc(end, fmt='%Y%m%dT%H%M')}"
+        return f"{fc(start.to_plain())}-{fc(end, fmt='%Y%m%dT%H')}"
+
+    @classmethod
+    def from_dict(
+        cls, mapping: PeriodDict[ZonedDateTime] | PeriodDict[dt.datetime], /
+    ) -> Self:
+        """Convert the dictionary to a period."""
+        match mapping["start"]:
+            case ZonedDateTime() as start:
+                ...
+            case dt.date() as py_datetime:
+                start = ZonedDateTime.from_py_datetime(py_datetime)
+            case never:
+                assert_never(never)
+        match mapping["end"]:
+            case ZonedDateTime() as end:
+                ...
+            case dt.date() as py_datetime:
+                end = ZonedDateTime.from_py_datetime(py_datetime)
+            case never:
+                assert_never(never)
+        return cls(start=start, end=end)
+
+    def replace(
+        self,
+        *,
+        start: ZonedDateTime | Sentinel = sentinel,
+        end: ZonedDateTime | Sentinel = sentinel,
+    ) -> Self:
+        """Replace elements of the period."""
+        return replace_non_sentinel(self, start=start, end=end)
+
+    @property
+    def time_zone(self) -> ZoneInfo:
+        """The time zone of the period."""
+        return ZoneInfo(self.start.tz)
+
+    def to_dict(self) -> PeriodDict[ZonedDateTime]:
+        """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)
+        return self.replace(start=self.start.to_tz(tz), end=self.end.to_tz(tz))
+
+
+@dataclass(kw_only=True, slots=True)
+class ZonedDateTimePeriodError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _ZonedDateTimePeriodInvalidError[T: Date | ZonedDateTime](
+    ZonedDateTimePeriodError
+):
+    start: T
+    end: T
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid period; got {self.start} > {self.end}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ZonedDateTimePeriodTimeZoneError(ZonedDateTimePeriodError):
+    start: ZoneInfo
+    end: ZoneInfo
+
+    @override
+    def __str__(self) -> str:
+        return f"Period must contain exactly one time zone; got {self.start} and {self.end}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ZonedDateTimePeriodExactEqError(ZonedDateTimePeriodError):
+    args: tuple[Any, ...]
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid arguments; got {self.args}"
 
 
 __all__ = [
@@ -1519,9 +2014,13 @@ __all__ = [
     "MINUTE",
     "MONTH",
     "NOW_LOCAL",
+    "NOW_LOCAL_PLAIN",
+    "NOW_PLAIN",
     "SECOND",
     "TIME_DELTA_MAX",
     "TIME_DELTA_MIN",
+    "TIME_LOCAL",
+    "TIME_UTC",
     "TODAY_LOCAL",
     "TODAY_UTC",
     "WEEK",
@@ -1530,9 +2029,13 @@ __all__ = [
     "ZERO_TIME",
     "ZONED_DATE_TIME_MAX",
     "ZONED_DATE_TIME_MIN",
+    "DatePeriod",
+    "DatePeriodError",
     "MeanDateTimeError",
     "MinMaxDateError",
+    "PeriodDict",
     "RoundDateOrDateTimeError",
+    "TimePeriod",
     "ToDaysError",
     "ToMinutesError",
     "ToMonthsAndDaysError",
@@ -1543,6 +2046,8 @@ __all__ = [
     "ToWeeksError",
     "ToYearsError",
     "WheneverLogRecord",
+    "ZonedDateTimePeriod",
+    "ZonedDateTimePeriodError",
     "add_year_month",
     "datetime_utc",
     "diff_year_month",
@@ -1552,8 +2057,13 @@ __all__ = [
     "from_timestamp_nanos",
     "get_now",
     "get_now_local",
+    "get_now_local_plain",
+    "get_now_plain",
+    "get_time",
+    "get_time_local",
     "get_today",
     "get_today_local",
+    "is_weekend",
     "mean_datetime",
     "min_max_date",
     "round_date_or_date_time",
@@ -1561,7 +2071,6 @@ __all__ = [
     "to_date",
     "to_date_time_delta",
     "to_days",
-    "to_local_plain",
     "to_microseconds",
     "to_milliseconds",
     "to_minutes",
@@ -1571,6 +2080,7 @@ __all__ = [
     "to_py_date_or_date_time",
     "to_py_time_delta",
     "to_seconds",
+    "to_time",
     "to_weeks",
     "to_years",
     "to_zoned_date_time",