dycw-utilities 0.131.11__py3-none-any.whl → 0.131.13__py3-none-any.whl

utilities/period.py

@@ -1,42 +1,20 @@
 from __future__ import annotations
 
-import datetime as dt
-from dataclasses import dataclass, field
-from functools import cached_property
-from itertools import permutations
-from typing import (
-    TYPE_CHECKING,
-    Generic,
-    Literal,
-    Self,
-    TypedDict,
-    TypeVar,
-    assert_never,
-    cast,
-    override,
-)
-
-from utilities.datetime import ZERO_TIME
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, Self, TypedDict, TypeVar, override
+from zoneinfo import ZoneInfo
+
+from whenever import Date, DateDelta, TimeDelta, ZonedDateTime
+
+from utilities.dataclasses import replace_non_sentinel
 from utilities.functions import get_class_name
-from utilities.iterables import OneUniqueNonUniqueError, always_iterable, one_unique
 from utilities.sentinel import Sentinel, sentinel
-from utilities.typing import is_instance_gen
-from utilities.whenever import (
-    serialize_date,
-    serialize_plain_datetime,
-    serialize_zoned_datetime,
-)
-from utilities.zoneinfo import EnsureTimeZoneError, ensure_time_zone
+from utilities.zoneinfo import get_time_zone_name
 
 if TYPE_CHECKING:
-    from zoneinfo import ZoneInfo
-
-    from utilities.iterables import MaybeIterable
-    from utilities.types import DateOrDateTime
+    from utilities.types import TimeZoneLike
 
-
-type _DateOrDateTime = Literal["date", "datetime"]
-_TPeriod = TypeVar("_TPeriod", dt.date, dt.datetime)
+_TPeriod = TypeVar("_TPeriod", Date, ZonedDateTime)
 
 
 class _PeriodAsDict(TypedDict, Generic[_TPeriod]):
@@ -44,281 +22,133 @@ class _PeriodAsDict(TypedDict, Generic[_TPeriod]):
     end: _TPeriod
 
 
-@dataclass(repr=False, order=True, unsafe_hash=True)
-class Period(Generic[_TPeriod]):
-    """A period of time."""
+@dataclass(repr=False, order=True, unsafe_hash=True, kw_only=False)
+class DatePeriod:
+    """A period of dates."""
 
-    start: _TPeriod
-    end: _TPeriod
-    req_duration: MaybeIterable[dt.timedelta] | None = field(
-        default=None, repr=False, kw_only=True
-    )
-    min_duration: dt.timedelta | None = field(default=None, repr=False, kw_only=True)
-    max_duration: dt.timedelta | None = field(default=None, repr=False, kw_only=True)
+    start: Date
+    end: Date
 
     def __post_init__(self) -> None:
-        if any(
-            is_instance_gen(left, cls) is not is_instance_gen(right, cls)
-            for left, right in permutations([self.start, self.end], 2)
-            for cls in [dt.date, dt.datetime]
-        ):
-            raise _PeriodDateAndDateTimeMixedError(start=self.start, end=self.end)
-        for date in [self.start, self.end]:
-            if isinstance(date, dt.datetime):
-                try:
-                    _ = ensure_time_zone(date)
-                except EnsureTimeZoneError:
-                    raise _PeriodNaiveDateTimeError(
-                        start=self.start, end=self.end
-                    ) from None
-        duration = self.end - self.start
-        if duration < ZERO_TIME:
+        if self.start > self.end:
             raise _PeriodInvalidError(start=self.start, end=self.end)
-        if (self.req_duration is not None) and (
-            duration not in always_iterable(self.req_duration)
-        ):
-            raise _PeriodReqDurationError(
-                start=self.start,
-                end=self.end,
-                duration=duration,
-                req_duration=self.req_duration,
-            )
-        if (self.min_duration is not None) and (duration < self.min_duration):
-            raise _PeriodMinDurationError(
-                start=self.start,
-                end=self.end,
-                duration=duration,
-                min_duration=self.min_duration,
-            )
-        if (self.max_duration is not None) and (duration > self.max_duration):
-            raise _PeriodMaxDurationError(
-                start=self.start,
-                end=self.end,
-                duration=duration,
-                max_duration=self.max_duration,
-            )
 
-    def __add__(self, other: dt.timedelta, /) -> Self:
+    def __add__(self, other: DateDelta, /) -> Self:
         """Offset the period."""
         return self.replace(start=self.start + other, end=self.end + other)
 
-    def __contains__(self, other: DateOrDateTime, /) -> bool:
+    def __contains__(self, other: Date, /) -> bool:
         """Check if a date/datetime lies in the period."""
-        match self.kind:
-            case "date":
-                if isinstance(other, dt.datetime):
-                    raise _PeriodDateContainsDateTimeError(
-                        start=self.start, end=self.end
-                    )
-            case "datetime":
-                if not isinstance(other, dt.datetime):
-                    raise _PeriodDateTimeContainsDateError(
-                        start=self.start, end=self.end
-                    )
-            case _ as never:
-                assert_never(never)
         return self.start <= other <= self.end
 
     @override
     def __repr__(self) -> str:
         cls = get_class_name(self)
-        match self.kind:
-            case "date":
-                result = cast("Period[dt.date]", self)
-                start, end = map(serialize_date, [result.start, result.end])
-                return f"{cls}({start}, {end})"
-            case "datetime":
-                result = cast("Period[dt.datetime]", self)
-                try:
-                    time_zone = result.time_zone
-                except _PeriodTimeZoneNonUniqueError:
-                    start, end = map(
-                        serialize_zoned_datetime, [result.start, result.end]
-                    )
-                    return f"{cls}({start}, {end})"
-                start, end = (
-                    serialize_plain_datetime(t.replace(tzinfo=None))
-                    for t in [result.start, result.end]
-                )
-                return f"{cls}({start}, {end}, {time_zone})"
-            case _ as never:
-                assert_never(never)
-
-    def __sub__(self, other: dt.timedelta, /) -> 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 astimezone(self, time_zone: ZoneInfo, /) -> Self:
-        """Convert the timezone of the period, if it is a datetime period."""
-        match self.kind:
-            case "date":
-                raise _PeriodAsTimeZoneInapplicableError(start=self.start, end=self.end)
-            case "datetime":
-                result = cast("Period[dt.datetime]", self)
-                result = result.replace(
-                    start=result.start.astimezone(time_zone),
-                    end=result.end.astimezone(time_zone),
-                )
-                return cast("Self", result)
-            case _ as never:
-                assert_never(never)
-
-    @cached_property
-    def duration(self) -> dt.timedelta:
-        """The duration of the period."""
+    @property
+    def delta(self) -> DateDelta:
+        """The delta of the period."""
         return self.end - self.start
 
-    @cached_property
-    def kind(self) -> _DateOrDateTime:
-        """The kind of the period."""
-        return "date" if is_instance_gen(self.start, dt.date) else "datetime"
-
     def replace(
-        self,
-        *,
-        start: _TPeriod | None = None,
-        end: _TPeriod | None = None,
-        req_duration: MaybeIterable[dt.timedelta] | None | Sentinel = sentinel,
-        min_duration: dt.timedelta | None | Sentinel = sentinel,
-        max_duration: dt.timedelta | None | Sentinel = sentinel,
+        self, *, start: Date | Sentinel = sentinel, end: Date | Sentinel = sentinel
     ) -> Self:
         """Replace elements of the period."""
-        return type(self)(
-            self.start if start is None else start,
-            self.end if end is None else end,
-            req_duration=self.req_duration
-            if isinstance(req_duration, Sentinel)
-            else req_duration,
-            min_duration=self.min_duration
-            if isinstance(min_duration, Sentinel)
-            else min_duration,
-            max_duration=self.max_duration
-            if isinstance(max_duration, Sentinel)
-            else max_duration,
-        )
-
-    @cached_property
-    def time_zone(self) -> ZoneInfo:
-        """The time zone of the period."""
-        match self.kind:
-            case "date":
-                raise _PeriodTimeZoneInapplicableError(
-                    start=self.start, end=self.end
-                ) from None
-            case "datetime":
-                result = cast("Period[dt.datetime]", self)
-                try:
-                    return one_unique(map(ensure_time_zone, [result.start, result.end]))
-                except OneUniqueNonUniqueError as error:
-                    raise _PeriodTimeZoneNonUniqueError(
-                        start=self.start,
-                        end=self.end,
-                        first=error.first,
-                        second=error.second,
-                    ) from None
-            case _ as never:
-                assert_never(never)
-
-    def to_dict(self) -> _PeriodAsDict:
-        """Convert the period to a dictionary."""
-        return {"start": self.start, "end": self.end}
-
-
-@dataclass(kw_only=True, slots=True)
-class PeriodError(Generic[_TPeriod], Exception):
-    start: _TPeriod
-    end: _TPeriod
+        return replace_non_sentinel(self, start=start, end=end)
 
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodDateAndDateTimeMixedError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return f"Invalid period; got date and datetime mix ({self.start}, {self.end})"
+    def to_dict(self) -> _PeriodAsDict[Date]:
+        """Convert the period to a dictionary."""
+        return _PeriodAsDict(start=self.start, end=self.end)
 
 
-@dataclass(kw_only=True, slots=True)
-class _PeriodNaiveDateTimeError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return f"Invalid period; got naive datetime(s) ({self.start}, {self.end})"
+@dataclass(repr=False, order=True, unsafe_hash=True, kw_only=False)
+class ZonedDateTimePeriod:
+    """A period of time."""
 
+    start: ZonedDateTime
+    end: ZonedDateTime
 
-@dataclass(kw_only=True, slots=True)
-class _PeriodInvalidError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return f"Invalid period; got {self.start} > {self.end}"
+    def __post_init__(self) -> None:
+        if self.start > self.end:
+            raise _PeriodInvalidError(start=self.start, end=self.end)
+        if self.start.tz != self.end.tz:
+            raise _PeriodTimeZoneError(
+                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)
 
-@dataclass(kw_only=True, slots=True)
-class _PeriodReqDurationError(PeriodError[_TPeriod]):
-    duration: dt.timedelta
-    req_duration: MaybeIterable[dt.timedelta]
+    def __contains__(self, other: ZonedDateTime, /) -> bool:
+        """Check if a date/datetime lies in the period."""
+        return self.start <= other <= self.end
 
     @override
-    def __str__(self) -> str:
-        return f"Period must have duration {self.req_duration}; got {self.duration})"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodMinDurationError(PeriodError[_TPeriod]):
-    duration: dt.timedelta
-    min_duration: dt.timedelta
+    def __repr__(self) -> str:
+        cls = get_class_name(self)
+        return f"{cls}({self.start.to_plain()}, {self.end.to_plain()}[{self.time_zone.key}])"
 
-    @override
-    def __str__(self) -> str:
-        return (
-            f"Period must have min duration {self.min_duration}; got {self.duration})"
-        )
+    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
 
-@dataclass(kw_only=True, slots=True)
-class _PeriodMaxDurationError(PeriodError[_TPeriod]):
-    duration: dt.timedelta
-    max_duration: dt.timedelta
+    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)
 
-    @override
-    def __str__(self) -> str:
-        return f"Period must have duration at most {self.max_duration}; got {self.duration})"
+    @property
+    def time_zone(self) -> ZoneInfo:
+        """The time zone of the period."""
+        return ZoneInfo(self.start.tz)
 
+    def to_dict(self) -> _PeriodAsDict[ZonedDateTime]:
+        """Convert the period to a dictionary."""
+        return _PeriodAsDict(start=self.start, end=self.end)
 
-@dataclass(kw_only=True, slots=True)
-class _PeriodAsTimeZoneInapplicableError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return "Period of dates does not have a timezone attribute"
+    def to_tz(self, time_zone: TimeZoneLike, /) -> Self:
+        """Convert the time zone."""
+        tz = get_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 _PeriodDateContainsDateTimeError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return "Period of dates cannot contain datetimes"
+class PeriodError(Exception): ...
 
 
 @dataclass(kw_only=True, slots=True)
-class _PeriodDateTimeContainsDateError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return "Period of datetimes cannot contain dates"
-
+class _PeriodInvalidError(PeriodError, Generic[_TPeriod]):
+    start: _TPeriod
+    end: _TPeriod
 
-@dataclass(kw_only=True, slots=True)
-class _PeriodTimeZoneInapplicableError(PeriodError[_TPeriod]):
     @override
     def __str__(self) -> str:
-        return "Period of dates does not have a timezone attribute"
+        return f"Invalid period; got {self.start} > {self.end}"
 
 
 @dataclass(kw_only=True, slots=True)
-class _PeriodTimeZoneNonUniqueError(PeriodError[_TPeriod]):
-    first: ZoneInfo
-    second: ZoneInfo
+class _PeriodTimeZoneError(PeriodError):
+    start: ZoneInfo
+    end: ZoneInfo
 
     @override
     def __str__(self) -> str:
-        return f"Period must contain exactly one time zone; got {self.first} and {self.second}"
+        return f"Period must contain exactly one time zone; got {self.start} and {self.end}"
 
 
-__all__ = ["Period", "PeriodError"]
+__all__ = ["DatePeriod", "PeriodError", "ZonedDateTimePeriod"]

utilities/pyinstrument.py

@@ -7,9 +7,8 @@ from typing import TYPE_CHECKING
 from pyinstrument.profiler import Profiler
 
 from utilities.atomicwrites import writer
-from utilities.datetime import serialize_compact
 from utilities.pathlib import get_path
-from utilities.tzlocal import get_now_local
+from utilities.whenever2 import format_compact, get_now
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
@@ -23,7 +22,7 @@ def profile(*, path: MaybeCallablePathLike | None = Path.cwd) -> Iterator[None]:
     with Profiler() as profiler:
         yield
     filename = get_path(path=path).joinpath(
-        f"profile__{serialize_compact(get_now_local())}.html"
+        f"profile__{format_compact(get_now())}.html"
     )
     with writer(filename) as temp, temp.open(mode="w") as fh:
         _ = fh.write(profiler.output_html())

utilities/traceback.py

@@ -14,7 +14,6 @@ from traceback import TracebackException
 from typing import TYPE_CHECKING, override
 
 from utilities.atomicwrites import writer
-from utilities.datetime import get_datetime, get_now, serialize_compact
 from utilities.errors import repr_error
 from utilities.iterables import OneEmptyError, one
 from utilities.pathlib import get_path
@@ -27,16 +26,19 @@ from utilities.reprlib import (
     RICH_MAX_WIDTH,
     yield_mapping_repr,
 )
-from utilities.tzlocal import get_local_time_zone, get_now_local
 from utilities.version import get_version
-from utilities.whenever import serialize_duration, serialize_zoned_datetime
+from utilities.whenever2 import format_compact, get_now, to_zoned_date_time
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator, Sequence
     from traceback import FrameSummary
     from types import TracebackType
 
-    from utilities.types import MaybeCallablePathLike, MaybeCallablePyDateTime, PathLike
+    from utilities.types import (
+        MaybeCallablePathLike,
+        MaybeCallableZonedDateTime,
+        PathLike,
+    )
     from utilities.version import MaybeCallableVersionLike
 
 
@@ -51,7 +53,7 @@ def format_exception_stack(
     /,
     *,
     header: bool = False,
-    start: MaybeCallablePyDateTime | None = _START,
+    start: MaybeCallableZonedDateTime | None = _START,
     version: MaybeCallableVersionLike | None = None,
     capture_locals: bool = False,
     max_width: int = RICH_MAX_WIDTH,
@@ -82,21 +84,18 @@ def format_exception_stack(
 
 def _yield_header_lines(
     *,
-    start: MaybeCallablePyDateTime | None = _START,
+    start: MaybeCallableZonedDateTime | None = _START,
     version: MaybeCallableVersionLike | None = None,
 ) -> Iterator[str]:
     """Yield the header lines."""
-    now = get_now_local()
-    start_use = get_datetime(datetime=start)
-    start_use = (
-        None if start_use is None else start_use.astimezone(get_local_time_zone())
-    )
-    yield f"Date/time | {serialize_zoned_datetime(now)}"
-    start_str = "" if start_use is None else serialize_zoned_datetime(start_use)
+    now = get_now()
+    start_use = to_zoned_date_time(date_time=start)
+    yield f"Date/time | {format_compact(now)}"
+    start_str = "" if start_use is None else format_compact(start_use)
     yield f"Started   | {start_str}"
-    duration = None if start_use is None else (now - start_use)
-    duration_str = "" if duration is None else serialize_duration(duration)
-    yield f"Duration  | {duration_str}"
+    delta = None if start_use is None else (now - start_use)
+    delta_str = "" if delta is None else delta.format_common_iso()
+    yield f"Duration  | {delta_str}"
     yield f"User      | {getuser()}"
     yield f"Host      | {gethostname()}"
     version_use = "" if version is None else get_version(version=version)
@@ -193,7 +192,7 @@ def _trim_path(path: PathLike, pattern: str, /) -> Path | None:
 
 def make_except_hook(
     *,
-    start: MaybeCallablePyDateTime | None = _START,
+    start: MaybeCallableZonedDateTime | None = _START,
     version: MaybeCallableVersionLike | None = None,
     path: MaybeCallablePathLike | None = None,
     max_width: int = RICH_MAX_WIDTH,
@@ -228,7 +227,7 @@ def _make_except_hook_inner(
     traceback: TracebackType | None,
     /,
     *,
-    start: MaybeCallablePyDateTime | None = _START,
+    start: MaybeCallableZonedDateTime | None = _START,
     version: MaybeCallableVersionLike | None = None,
     path: MaybeCallablePathLike | None = None,
     max_width: int = RICH_MAX_WIDTH,
@@ -247,9 +246,7 @@ def _make_except_hook_inner(
     _ = sys.stderr.write(f"{slim}\n")  # don't 'from sys import stderr'
     if path is not None:
         path = (
-            get_path(path=path)
-            .joinpath(serialize_compact(get_now_local()))
-            .with_suffix(".txt")
+            get_path(path=path).joinpath(format_compact(get_now())).with_suffix(".txt")
         )
         full = format_exception_stack(
             exc_val,

utilities/typing.py

@@ -25,6 +25,16 @@ from typing import get_type_hints as _get_type_hints
 from uuid import UUID
 from warnings import warn
 
+from whenever import (
+    Date,
+    DateDelta,
+    DateTimeDelta,
+    PlainDateTime,
+    Time,
+    TimeDelta,
+    ZonedDateTime,
+)
+
 from utilities.iterables import unique_everseen
 from utilities.sentinel import Sentinel
 from utilities.types import StrMapping
@@ -133,7 +143,21 @@ def get_type_hints(
 ) -> dict[str, Any]:
     """Get the type hints of an object."""
     result: dict[str, Any] = obj.__annotations__
-    _ = {Literal, Path, Sentinel, StrMapping, UUID, dt}
+    _ = {
+        Date,
+        DateDelta,
+        DateTimeDelta,
+        Literal,
+        Path,
+        PlainDateTime,
+        Sentinel,
+        StrMapping,
+        Time,
+        TimeDelta,
+        UUID,
+        ZonedDateTime,
+        dt,
+    }
     globalns_use = globals() | ({} if globalns is None else dict(globalns))
     localns_use = {} if localns is None else dict(localns)
     try:

utilities/tzdata.py

@@ -1,63 +1,11 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
 from zoneinfo import ZoneInfo
 
-from utilities.datetime import get_now, get_today
-
-if TYPE_CHECKING:
-    import datetime as dt
-
-
 HongKong = ZoneInfo("Asia/Hong_Kong")
 Tokyo = ZoneInfo("Asia/Tokyo")
 USCentral = ZoneInfo("US/Central")
 USEastern = ZoneInfo("US/Eastern")
 
 
-def get_now_hong_kong() -> dt.datetime:
-    """Get the current time in Hong Kong."""
-    return get_now(time_zone=HongKong)
-
-
-NOW_HONG_KONG = get_now_hong_kong()
-
-
-def get_now_tokyo() -> dt.datetime:
-    """Get the current time in Tokyo."""
-    return get_now(time_zone=Tokyo)
-
-
-NOW_TOKYO = get_now_tokyo()
-
-
-def get_today_hong_kong() -> dt.date:
-    """Get the current date in Hong Kong."""
-    return get_today(time_zone=HongKong)
-
-
-TODAY_HONG_KONG = get_today_hong_kong()
-
-
-def get_today_tokyo() -> dt.date:
-    """Get the current date in Tokyo."""
-    return get_today(time_zone=Tokyo)
-
-
-TODAY_TOKYO = get_today_tokyo()
-
-
-__all__ = [
-    "NOW_HONG_KONG",
-    "NOW_TOKYO",
-    "TODAY_HONG_KONG",
-    "TODAY_TOKYO",
-    "HongKong",
-    "Tokyo",
-    "USCentral",
-    "USEastern",
-    "get_now_hong_kong",
-    "get_now_tokyo",
-    "get_today_hong_kong",
-    "get_today_tokyo",
-]
+__all__ = ["HongKong", "Tokyo", "USCentral", "USEastern"]

utilities/tzlocal.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import datetime as dt
 from logging import getLogger
 from typing import TYPE_CHECKING
 
@@ -21,30 +20,7 @@ def get_local_time_zone() -> ZoneInfo:
 
 
 LOCAL_TIME_ZONE = get_local_time_zone()
+LOCAL_TIME_ZONE_NAME = LOCAL_TIME_ZONE.key
 
 
-def get_now_local() -> dt.datetime:
-    """Get the current local time."""
-    return dt.datetime.now(tz=LOCAL_TIME_ZONE)
-
-
-NOW_LOCAL = get_now_local()
-
-
-def get_today_local() -> dt.date:
-    """Get the current, timezone-aware local date."""
-    return get_now_local().date()
-
-
-TODAY_LOCAL = get_today_local()
-
-
-__all__ = [
-    "LOCAL_TIME_ZONE",
-    "LOCAL_TIME_ZONE",
-    "NOW_LOCAL",
-    "TODAY_LOCAL",
-    "get_local_time_zone",
-    "get_now_local",
-    "get_today_local",
-]
+__all__ = ["LOCAL_TIME_ZONE", "LOCAL_TIME_ZONE_NAME", "get_local_time_zone"]