dycw-utilities 0.131.12__py3-none-any.whl → 0.131.14__py3-none-any.whl

{dycw_utilities-0.131.12.dist-info → dycw_utilities-0.131.14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.131.12
+Version: 0.131.14
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.131.12.dist-info → dycw_utilities-0.131.14.dist-info}/RECORD

@@ -1,10 +1,10 @@
-utilities/__init__.py,sha256=Mewpkpu3DcrrhZzBvzBQpI4GkBsPPKRq0bdDX_sR7t4,61
+utilities/__init__.py,sha256=NYq6mGcB8IGMU4RPF-m9jjQGEJiGNJEcMMoXW81ZW3E,61
 utilities/aiolimiter.py,sha256=mD0wEiqMgwpty4XTbawFpnkkmJS6R4JRsVXFUaoitSU,628
 utilities/altair.py,sha256=HeZBVUocjkrTNwwKrClppsIqgNFF-ykv05HfZSoHYno,9104
 utilities/asyncio.py,sha256=yfKvAIDCRrWdyQMVZMo4DJQx4nVrXoAcqwhNuF95Ryo,38186
 utilities/atomicwrites.py,sha256=geFjn9Pwn-tTrtoGjDDxWli9NqbYfy3gGL6ZBctiqSo,5393
-utilities/atools.py,sha256=IYMuFSFGSKyuQmqD6v5IUtDlz8PPw0Sr87Cub_gRU3M,1168
-utilities/cachetools.py,sha256=C1zqOg7BYz0IfQFK8e3qaDDgEZxDpo47F15RTfJM37Q,2910
+utilities/atools.py,sha256=-bFGIrwYMFR7xl39j02DZMsO_u5x5_Ph7bRlBUFVYyw,1048
+utilities/cachetools.py,sha256=uBtEv4hD-TuCPX_cQy1lOpLF-QqfwnYGSf0o4Soqydc,2826
 utilities/click.py,sha256=8gRYeyu9KQ3uim0UpC8VnFnOOKD3DyGwMJ7k0Qns1lM,14659
 utilities/concurrent.py,sha256=s2scTEd2AhXVTW4hpASU2qxV_DiVLALfms55cCQzCvM,2886
 utilities/contextlib.py,sha256=lpaLJBy3X0UGLWjM98jkQZZq8so4fRmoK-Bheq0uOW4,1027
@@ -24,7 +24,7 @@ utilities/getpass.py,sha256=DfN5UgMAtFCqS3dSfFHUfqIMZX2shXvwphOz_6J6f6A,103
 utilities/git.py,sha256=oi7-_l5e9haSANSCvQw25ufYGoNahuUPHAZ6114s3JQ,1191
 utilities/hashlib.py,sha256=SVTgtguur0P4elppvzOBbLEjVM3Pea0eWB61yg2ilxo,309
 utilities/http.py,sha256=WcahTcKYRtZ04WXQoWt5EGCgFPcyHD3EJdlMfxvDt-0,946
-utilities/hypothesis.py,sha256=spJCB3bKcSMFKuSwi184xfTbom_HEBLB0_-AiPnSR-A,49822
+utilities/hypothesis.py,sha256=hEyuJoLH0c6So0P5OESvyANpfM49Ld1iYXC4bZvacm4,42603
 utilities/importlib.py,sha256=mV1xT_O_zt_GnZZ36tl3xOmMaN_3jErDWY54fX39F6Y,429
 utilities/inflect.py,sha256=DbqB5Q9FbRGJ1NbvEiZBirRMxCxgrz91zy5jCO9ZIs0,347
 utilities/ipython.py,sha256=V2oMYHvEKvlNBzxDXdLvKi48oUq2SclRg5xasjaXStw,763
@@ -41,11 +41,11 @@ utilities/more_itertools.py,sha256=tBbjjKx8_Uv_TCjxhPwrGfAx_jRHtvLIZqXVWAsjzqA,8
 utilities/numpy.py,sha256=Xn23sA2ZbVNqwUYEgNJD3XBYH6IbCri_WkHSNhg3NkY,26122
 utilities/operator.py,sha256=0M2yZJ0PODH47ogFEnkGMBe_cfxwZR02T_92LZVZvHo,3715
 utilities/optuna.py,sha256=loyJGWTzljgdJaoLhP09PT8Jz6o_pwBOwehY33lHkhw,1923
-utilities/orjson.py,sha256=oD9sQYd3bQKZi2dwpQsaRVwCSlSQ2sREl83UZP4LD7w,36962
+utilities/orjson.py,sha256=lhBSO-QCm2g-uhUE0hKe-PVhAt1TKRRx0iZLSFPmew4,36970
 utilities/os.py,sha256=D_FyyT-6TtqiN9KSS7c9g1fnUtgxmyMtzAjmYLkk46A,3587
 utilities/parse.py,sha256=vsZ2jf_ceSI_Kta9titixufysJaVXh0Whjz1T4awJZw,18938
 utilities/pathlib.py,sha256=PK41rf1c9Wqv7h8f5R7H3_Lhq_gQZTUJD5tu3gMHVaU,3247
-utilities/period.py,sha256=o4wXYEXVlFomop4-Ra4L0yRP4i99NZFjIe_fa7NdZck,11024
+utilities/period.py,sha256=opqpBevBGSGXbA7NYfRJjtthi1JPxdMaZ7QV3xosnTc,4774
 utilities/pickle.py,sha256=MBT2xZCsv0pH868IXLGKnlcqNx2IRVKYNpRcqiQQqxw,653
 utilities/platform.py,sha256=48IOKx1IC6ZJXWG-b56ZQptITcNFhWRjELW72o2dGTA,2398
 utilities/polars.py,sha256=QlmUpYTqHNkcLnWOQh1TW22W2QyLzvifCvBcbsqhpdE,63272
@@ -80,18 +80,19 @@ utilities/text.py,sha256=ymBFlP_cA8OgNnZRVNs7FAh7OG8HxE6YkiLEMZv5g_A,11297
 utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=VeSl3ot8-f4D1d3HjjSsgKvjxHJGXd_sW4KcTExOR64,2475
 utilities/traceback.py,sha256=cMXrCD59CROnezAU8VW67CxZ8Igc5QmaxlV8qrBvNMs,8504
+utilities/typed_settings.py,sha256=zUA0_CmVJT5rwrm3e-dZO83OdPXEel4NfVK24NAD5Vk,1779
 utilities/types.py,sha256=CHQke10ETEpypxppYVhWp1G68S6mvifalrRLolYBcCg,19506
 utilities/typing.py,sha256=VuGuztLSkTicxgVwI5wrVOTcY70OlzwsTU7LcFVjGlY,14169
-utilities/tzdata.py,sha256=yCf70NICwAeazN3_JcXhWvRqCy06XJNQ42j7r6gw3HY,1217
+utilities/tzdata.py,sha256=fgNVj66yUbCSI_-vrRVzSD3gtf-L_8IEJEPjP_Jel5Y,266
 utilities/tzlocal.py,sha256=xbBBzVIUKMk8AkhuIp1qxGRNBioIa5I09dpeoBnIOOU,662
 utilities/uuid.py,sha256=jJTFxz-CWgltqNuzmythB7iEQ-Q1mCwPevUfKthZT3c,611
 utilities/version.py,sha256=ufhJMmI6KPs1-3wBI71aj5wCukd3sP_m11usLe88DNA,5117
 utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
 utilities/whenever.py,sha256=2NQ-0SnLNW2kFpefP9dVE8H0RbaeusXYLPmv282Jpto,16755
-utilities/whenever2.py,sha256=WiDVsgHA-4E-KiIJ25-R4qAWvtyBQk1EkhjMszFzQMM,7455
+utilities/whenever2.py,sha256=iFVL4CjuIOpzsDU6li5smHnDEqam30-FtTgXWeHuWiE,7510
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
-utilities/zoneinfo.py,sha256=tvcgu3QzDxe2suTexi2QzRGpin7VK1TjHa0JYYxT69I,1862
-dycw_utilities-0.131.12.dist-info/METADATA,sha256=8G8r4jcsCl-iXqwXZ2vq8Kx7M4S2A6xCNxQA3Blrv64,1585
-dycw_utilities-0.131.12.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.131.12.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.131.12.dist-info/RECORD,,
+utilities/zoneinfo.py,sha256=gJPr9l7V8s3Y7TXpCGYEM1S81Rplb9e4MoV9Nvy2VU8,1852
+dycw_utilities-0.131.14.dist-info/METADATA,sha256=jRiyVj2uOFSRzUZjiKEZHtOXb9Z-uGw3f62yd-FWWb0,1585
+dycw_utilities-0.131.14.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.131.14.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.131.14.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.131.12"
+__version__ = "0.131.14"

utilities/atools.py

@@ -5,25 +5,22 @@ from typing import TYPE_CHECKING, ParamSpec, TypeVar
 
 from atools import memoize
 
-from utilities.datetime import datetime_duration_to_timedelta
 from utilities.types import Coroutine1
 
 if TYPE_CHECKING:
-    import datetime as dt
-
-    from utilities.types import Duration
+    from whenever import TimeDelta
 
 
 _P = ParamSpec("_P")
 _R = TypeVar("_R")
 _AsyncFunc = Callable[_P, Coroutine1[_R]]
-type _Key = tuple[_AsyncFunc, dt.timedelta]
+type _Key = tuple[_AsyncFunc, TimeDelta]
 _MEMOIZED_FUNCS: dict[_Key, _AsyncFunc] = {}
 
 
 async def call_memoized(
     func: _AsyncFunc[_P, _R],
-    refresh: Duration | None = None,
+    refresh: TimeDelta | None = None,
     /,
     *args: _P.args,
     **kwargs: _P.kwargs,
@@ -31,13 +28,14 @@ async def call_memoized(
     """Call an asynchronous function, with possible memoization."""
     if refresh is None:
         return await func(*args, **kwargs)
-    timedelta = datetime_duration_to_timedelta(refresh)
-    key: _Key = (func, timedelta)
+    key: _Key = (func, refresh)
     memoized_func: _AsyncFunc[_P, _R]
     try:
         memoized_func = _MEMOIZED_FUNCS[key]
     except KeyError:
-        memoized_func = _MEMOIZED_FUNCS[(key)] = memoize(duration=refresh)(func)
+        memoized_func = _MEMOIZED_FUNCS[(key)] = memoize(duration=refresh.in_seconds())(
+            func
+        )
     return await memoized_func(*args, **kwargs)
 
 

utilities/cachetools.py

@@ -8,10 +8,10 @@ from typing import TYPE_CHECKING, Any, TypeVar, override
 import cachetools
 from cachetools.func import ttl_cache
 
-from utilities.datetime import datetime_duration_to_float
-
 if TYPE_CHECKING:
-    from utilities.types import Duration, TCallable
+    from whenever import TimeDelta
+
+    from utilities.types import TCallable
 
 _K = TypeVar("_K")
 _T = TypeVar("_T")
@@ -25,15 +25,13 @@ class TTLCache(cachetools.TTLCache[_K, _V]):
         self,
         *,
         max_size: int | None = None,
-        max_duration: Duration | None = None,
+        max_duration: TimeDelta | None = None,
         timer: Callable[[], float] = monotonic,
         get_size_of: Callable[[Any], int] | None = None,
     ) -> None:
         super().__init__(
             maxsize=inf if max_size is None else max_size,
-            ttl=inf
-            if max_duration is None
-            else datetime_duration_to_float(max_duration),
+            ttl=inf if max_duration is None else max_duration.in_seconds(),
             timer=timer,
             getsizeof=get_size_of,
         )
@@ -54,7 +52,7 @@ class TTLSet(MutableSet[_T]):
         /,
         *,
         max_size: int | None = None,
-        max_duration: Duration | None = None,
+        max_duration: TimeDelta | None = None,
         timer: Callable[[], float] = monotonic,
         get_size_of: Callable[[Any], int] | None = None,
     ) -> None:
@@ -103,14 +101,14 @@ class TTLSet(MutableSet[_T]):
 def cache(
     *,
     max_size: int | None = None,
-    max_duration: Duration | None = None,
+    max_duration: TimeDelta | None = None,
     timer: Callable[[], float] = monotonic,
     typed_: bool = False,
 ) -> Callable[[TCallable], TCallable]:
     """Decorate a function with `max_size` and/or `ttl` settings."""
     return ttl_cache(
         maxsize=inf if max_size is None else max_size,
-        ttl=inf if max_duration is None else datetime_duration_to_float(max_duration),
+        ttl=inf if max_duration is None else max_duration.in_seconds(),
         timer=timer,
         typed=typed_,
     )

utilities/hypothesis.py

@@ -716,218 +716,6 @@ def lists_fixed_length(
 ##
 
 
-@composite
-def min_and_max_datetimes(
-    draw: DrawFn,
-    /,
-    *,
-    min_value: MaybeSearchStrategy[dt.datetime | None] = None,
-    max_value: MaybeSearchStrategy[dt.datetime | None] = None,
-    time_zone: MaybeSearchStrategy[ZoneInfo | timezone] = UTC,
-    round_: MathRoundMode | None = None,
-    timedelta: dt.timedelta | None = None,
-    rel_tol: float | None = None,
-    abs_tol: float | None = None,
-    valid: bool = False,
-) -> tuple[dt.datetime, dt.datetime]:
-    """Strategy for generating min/max datetimes."""
-    match min_value, max_value:
-        case None, None:
-            return draw(
-                pairs(
-                    zoned_datetimes(
-                        time_zone=time_zone,
-                        round_=round_,
-                        timedelta=timedelta,
-                        rel_tol=rel_tol,
-                        abs_tol=abs_tol,
-                        valid=valid,
-                    ),
-                    sorted=True,
-                )
-            )
-        case None, dt.datetime():
-            min_value_ = draw(
-                zoned_datetimes(
-                    max_value=max_value,
-                    time_zone=time_zone,
-                    round_=round_,
-                    timedelta=timedelta,
-                    rel_tol=rel_tol,
-                    abs_tol=abs_tol,
-                    valid=valid,
-                )
-            )
-            return min_value_, max_value
-        case dt.datetime(), None:
-            max_value_ = draw(
-                zoned_datetimes(
-                    min_value=min_value,
-                    time_zone=time_zone,
-                    round_=round_,
-                    timedelta=timedelta,
-                    rel_tol=rel_tol,
-                    abs_tol=abs_tol,
-                    valid=valid,
-                )
-            )
-            return min_value, max_value_
-        case dt.datetime(), dt.datetime():
-            _ = assume(min_value <= max_value)
-            return min_value, max_value
-        case _, _:
-            strategy = zoned_datetimes(
-                time_zone=time_zone,
-                round_=round_,
-                timedelta=timedelta,
-                rel_tol=rel_tol,
-                abs_tol=abs_tol,
-                valid=valid,
-            )
-            min_value_ = draw2(draw, min_value, strategy)
-            max_value_ = draw2(draw, max_value, strategy)
-            _ = assume(min_value_ <= max_value_)
-            return min_value_, max_value_
-        case _ as never:
-            assert_never(never)
-
-
-##
-
-
-@composite
-def min_and_maybe_max_datetimes(
-    draw: DrawFn,
-    /,
-    *,
-    min_value: MaybeSearchStrategy[dt.datetime | None] = None,
-    max_value: MaybeSearchStrategy[dt.datetime | None | Sentinel] = sentinel,
-    time_zone: MaybeSearchStrategy[ZoneInfo | timezone] = UTC,
-    round_: MathRoundMode | None = None,
-    timedelta: dt.timedelta | None = None,
-    rel_tol: float | None = None,
-    abs_tol: float | None = None,
-    valid: bool = False,
-) -> tuple[dt.datetime, dt.datetime | None]:
-    match min_value, max_value:
-        case None, Sentinel():
-            min_value_, max_value_ = draw(
-                pairs(
-                    zoned_datetimes(
-                        time_zone=time_zone,
-                        round_=round_,
-                        timedelta=timedelta,
-                        rel_tol=rel_tol,
-                        abs_tol=abs_tol,
-                        valid=valid,
-                    ),
-                    sorted=True,
-                )
-            )
-            return min_value_, draw(just(max_value_) | none())
-        case None, None:
-            min_value_ = draw(
-                zoned_datetimes(
-                    time_zone=time_zone,
-                    round_=round_,
-                    timedelta=timedelta,
-                    rel_tol=rel_tol,
-                    abs_tol=abs_tol,
-                    valid=valid,
-                )
-            )
-            return min_value_, None
-        case None, dt.datetime():
-            min_value_ = draw(
-                zoned_datetimes(
-                    max_value=max_value,
-                    time_zone=time_zone,
-                    round_=round_,
-                    timedelta=timedelta,
-                    rel_tol=rel_tol,
-                    abs_tol=abs_tol,
-                    valid=valid,
-                )
-            )
-            return min_value_, max_value
-        case dt.datetime(), Sentinel():
-            max_value_ = draw(
-                zoned_datetimes(
-                    min_value=min_value,
-                    time_zone=time_zone,
-                    round_=round_,
-                    timedelta=timedelta,
-                    rel_tol=rel_tol,
-                    abs_tol=abs_tol,
-                    valid=valid,
-                )
-                | none()
-            )
-            return min_value, max_value_
-        case dt.datetime(), None:
-            return min_value, None
-        case dt.datetime(), dt.datetime():
-            _ = assume(min_value <= max_value)
-            return min_value, max_value
-        case _, _:
-            strategy = zoned_datetimes(
-                time_zone=time_zone,
-                round_=round_,
-                timedelta=timedelta,
-                rel_tol=rel_tol,
-                abs_tol=abs_tol,
-                valid=valid,
-            )
-            min_value_ = draw2(draw, min_value, strategy)
-            max_value_ = draw2(draw, max_value, strategy | none(), sentinel=True)
-            _ = assume((max_value_ is None) or (min_value_ <= max_value_))
-            return min_value_, max_value_
-        case _ as never:
-            assert_never(never)
-
-
-##
-
-
-@composite
-def min_and_maybe_max_sizes(
-    draw: DrawFn,
-    /,
-    *,
-    min_value: MaybeSearchStrategy[int | None] = None,
-    max_value: MaybeSearchStrategy[int | None | Sentinel] = sentinel,
-) -> tuple[int, int | None]:
-    match min_value, max_value:
-        case None, Sentinel():
-            min_value_, max_value_ = draw(pairs(integers(min_value=0), sorted=True))
-            return min_value_, draw(just(max_value_) | none())
-        case None, None:
-            min_value_ = draw(integers(min_value=0))
-            return min_value_, None
-        case None, int():
-            min_value_ = draw(integers(0, max_value))
-            return min_value_, max_value
-        case int(), Sentinel():
-            max_value_ = draw(integers(min_value=min_value) | none())
-            return min_value, max_value_
-        case int(), None:
-            return min_value, None
-        case int(), int():
-            _ = assume(min_value <= max_value)
-            return min_value, max_value
-        case _, _:
-            strategy = integers(min_value=0)
-            min_value_ = draw2(draw, min_value, strategy)
-            max_value_ = draw2(draw, max_value, strategy | none(), sentinel=True)
-            _ = assume((max_value_ is None) or (min_value_ <= max_value_))
-            return min_value_, max_value_
-        case _ as never:
-            assert_never(never)
-
-
-##
-
-
 @composite
 def months(
     draw: DrawFn,
@@ -1694,17 +1482,12 @@ __all__ = [
     "int64s",
     "int_arrays",
     "lists_fixed_length",
-    "min_and_max_datetimes",
-    "min_and_maybe_max_datetimes",
-    "min_and_maybe_max_sizes",
-    "min_and_maybe_max_sizes",
     "months",
     "namespace_mixins",
     "numbers",
     "pairs",
     "paths",
     "plain_datetimes",
-    "plain_datetimes",
     "plain_datetimes_whenever",
     "random_states",
     "sentinels",

utilities/orjson.py

@@ -760,7 +760,7 @@ class OrjsonFormatter(Formatter):
             path_name=Path(record.pathname),
             line_num=record.lineno,
             message=record.getMessage(),
-            datetime=from_timestamp(record.created, time_zone="local"),
+            datetime=from_timestamp(record.created, time_zone=LOCAL_TIME_ZONE),
             func_name=record.funcName,
             extra=extra if len(extra) >= 1 else None,
         )

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/typed_settings.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar, override
+
+from typed_settings.converters import TSConverter
+from whenever import (
+    Date,
+    DateDelta,
+    DateTimeDelta,
+    PlainDateTime,
+    Time,
+    TimeDelta,
+    ZonedDateTime,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+_T = TypeVar("_T")
+
+
+class ExtendedTSConverter(TSConverter):
+    """An extension of the TSConverter for custom types."""
+
+    @override
+    def __init__(
+        self,
+        *,
+        resolve_paths: bool = True,
+        strlist_sep: str | Callable[[str], list] | None = ":",
+    ) -> None:
+        super().__init__(resolve_paths=resolve_paths, strlist_sep=strlist_sep)
+        cases: list[tuple[type[Any], Callable[..., Any]]] = [
+            (Date, Date.parse_common_iso),
+            (DateDelta, DateDelta.parse_common_iso),
+            (DateTimeDelta, DateTimeDelta.parse_common_iso),
+            (PlainDateTime, PlainDateTime.parse_common_iso),
+            (Time, Time.parse_common_iso),
+            (TimeDelta, TimeDelta.parse_common_iso),
+            (ZonedDateTime, ZonedDateTime.parse_common_iso),
+        ]
+        extras = {cls: _make_converter(cls, func) for cls, func in cases}
+        self.scalar_converters |= extras
+
+
+def _make_converter(
+    cls: type[_T], parser: Callable[[str], _T], /
+) -> Callable[[Any, type[Any]], Any]:
+    def hook(value: _T | str, _: type[_T] = cls, /) -> Any:
+        if not isinstance(value, (cls, str)):  # pragma: no cover
+            msg = f"Invalid type {type(value).__name__!r}; expected '{cls.__name__}' or 'str'"
+            raise TypeError(msg)
+        if isinstance(value, str):
+            return parser(value)
+        return value
+
+    return hook
+
+
+__all__ = ["ExtendedTSConverter"]

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/whenever2.py

@@ -18,7 +18,7 @@ from whenever import (
 
 from utilities.datetime import maybe_sub_pct_y
 from utilities.sentinel import Sentinel, sentinel
-from utilities.tzlocal import LOCAL_TIME_ZONE_NAME
+from utilities.tzlocal import LOCAL_TIME_ZONE, LOCAL_TIME_ZONE_NAME
 from utilities.zoneinfo import UTC, get_time_zone_name
 
 if TYPE_CHECKING:
@@ -111,7 +111,7 @@ NOW_UTC = get_now(time_zone=UTC)
 
 def get_now_local() -> ZonedDateTime:
     """Get the current local time."""
-    return get_now(time_zone="local")
+    return get_now(time_zone=LOCAL_TIME_ZONE)
 
 
 NOW_LOCAL = get_now_local()
@@ -130,7 +130,7 @@ TODAY_UTC = get_today(time_zone=UTC)
 
 def get_today_local() -> Date:
     """Get the current, timezone-aware local date."""
-    return get_today(time_zone="local")
+    return get_today(time_zone=LOCAL_TIME_ZONE)
 
 
 TODAY_LOCAL = get_today_local()
@@ -267,6 +267,7 @@ __all__ = [
     "ZONED_DATE_TIME_MIN",
     "WheneverLogRecord",
     "format_compact",
+    "format_compact",
     "from_timestamp",
     "from_timestamp_millis",
     "from_timestamp_nanos",

utilities/zoneinfo.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, assert_never, cast, override
 from zoneinfo import ZoneInfo
 
-from utilities.tzlocal import get_local_time_zone
+from utilities.tzlocal import LOCAL_TIME_ZONE
 
 if TYPE_CHECKING:
     from utilities.types import TimeZone, TimeZoneLike
@@ -23,7 +23,7 @@ def ensure_time_zone(obj: TimeZoneLike, /) -> ZoneInfo:
         case ZoneInfo() as zone_info:
             return zone_info
         case "local":
-            return get_local_time_zone()
+            return LOCAL_TIME_ZONE
         case str() as key:
             return ZoneInfo(key)
         case dt.tzinfo() as tzinfo: