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

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

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

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

@@ -1,11 +1,11 @@
-utilities/__init__.py,sha256=NYq6mGcB8IGMU4RPF-m9jjQGEJiGNJEcMMoXW81ZW3E,61
+utilities/__init__.py,sha256=I-o_EPHIejt3ggoklYx3Vx_Wi2XLiPZ3YlzjyX4JBKI,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=-bFGIrwYMFR7xl39j02DZMsO_u5x5_Ph7bRlBUFVYyw,1048
 utilities/cachetools.py,sha256=uBtEv4hD-TuCPX_cQy1lOpLF-QqfwnYGSf0o4Soqydc,2826
-utilities/click.py,sha256=8gRYeyu9KQ3uim0UpC8VnFnOOKD3DyGwMJ7k0Qns1lM,14659
+utilities/click.py,sha256=sdGAMoarAWJ4_A3o-UzM7hpe7R37yvC_X_Uh8vasa-A,13295
 utilities/concurrent.py,sha256=s2scTEd2AhXVTW4hpASU2qxV_DiVLALfms55cCQzCvM,2886
 utilities/contextlib.py,sha256=lpaLJBy3X0UGLWjM98jkQZZq8so4fRmoK-Bheq0uOW4,1027
 utilities/contextvars.py,sha256=RsSGGrbQqqZ67rOydnM7WWIsM2lIE31UHJLejnHJPWY,505
@@ -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=hEyuJoLH0c6So0P5OESvyANpfM49Ld1iYXC4bZvacm4,42603
+utilities/hypothesis.py,sha256=fcklSUIagoDZOTn8ITbkIU7BOZMV4g1Owj0khiz9yBY,43401
 utilities/importlib.py,sha256=mV1xT_O_zt_GnZZ36tl3xOmMaN_3jErDWY54fX39F6Y,429
 utilities/inflect.py,sha256=DbqB5Q9FbRGJ1NbvEiZBirRMxCxgrz91zy5jCO9ZIs0,347
 utilities/ipython.py,sha256=V2oMYHvEKvlNBzxDXdLvKi48oUq2SclRg5xasjaXStw,763
@@ -33,7 +33,7 @@ utilities/jupyter.py,sha256=ft5JA7fBxXKzP-L9W8f2-wbF0QeYc_2uLQNFDVk4Z-M,2917
 utilities/libcst.py,sha256=Jto5ppzRzsxn4AD32IS8n0lbgLYXwsVJB6EY8giNZyY,4974
 utilities/lightweight_charts.py,sha256=JrkrAZMo6JID2Eoc9QCc05Y_pK4l2zsApIhmii1z2Ig,2764
 utilities/logging.py,sha256=zm5k0Cduxtx2H2o7odxUTJtPNkJS85mqHYN1cS5Kc1w,17863
-utilities/luigi.py,sha256=fpH9MbxJDuo6-k9iCXRayFRtiVbUtibCJKugf7ygpv0,5988
+utilities/luigi.py,sha256=UAt4TDMtinLAN7sipX0jSvH-aZzHUTQbHB3Rwtbq994,4840
 utilities/math.py,sha256=_6vrDyjtaqE_OFE-F2DNWrDG_J_kMl3nFAJsok9v_bY,26862
 utilities/memory_profiler.py,sha256=tf2C51P2lCujPGvRt2Rfc7VEw5LDXmVPCG3z_AvBmbU,962
 utilities/modules.py,sha256=iuvLluJya-hvl1Q25-Jk3dLgx2Es3ck4SjJiEkAlVTs,3195
@@ -88,11 +88,11 @@ 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=iFVL4CjuIOpzsDU6li5smHnDEqam30-FtTgXWeHuWiE,7510
+utilities/whenever.py,sha256=oO0sgIIv4tvhIYmlZ4RFFfY6P54CPeyJCY9A4XHuyqo,11916
+utilities/whenever2.py,sha256=Jd_fEavXCWTdMj29L7j-HbeMvrl8e3Ah_nxcLEFAwOU,12026
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 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,,
+dycw_utilities-0.131.16.dist-info/METADATA,sha256=X0Yt3BUVE7Y7W884VYvx_9CVhE4c9ENSxbhD4ghFoKU,1585
+dycw_utilities-0.131.16.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.131.16.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.131.16.dist-info/RECORD,,

utilities/__init__.py

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

utilities/click.py

@@ -1,40 +1,38 @@
 from __future__ import annotations
 
-import datetime as dt
 import pathlib
-from typing import TYPE_CHECKING, Generic, TypedDict, TypeVar, override
-from uuid import UUID
+from typing import TYPE_CHECKING, Generic, TypedDict, TypeVar, assert_never, override
 
 import click
+import whenever
 from click import Choice, Context, Parameter, ParamType
-from click.types import (
-    BoolParamType,
-    FloatParamType,
-    IntParamType,
-    StringParamType,
-    UUIDParameterType,
-)
+from click.types import StringParamType
 
-import utilities.datetime
-import utilities.types
-from utilities.datetime import EnsureMonthError, MonthLike, ensure_month
+from utilities.datetime import EnsureMonthError, ensure_month
 from utilities.enum import EnsureEnumError, ensure_enum
 from utilities.functions import EnsureStrError, ensure_str, get_class_name
 from utilities.iterables import is_iterable_not_str
 from utilities.text import split_str
 from utilities.types import (
-    DateTimeLike,
+    DateDeltaLike,
+    DateLike,
+    DateTimeDeltaLike,
     EnumLike,
     MaybeStr,
-    PyDateLike,
-    PyTimeDeltaLike,
-    PyTimeLike,
+    PlainDateTimeLike,
     TEnum,
+    TimeDeltaLike,
+    TimeLike,
+    ZonedDateTimeLike,
 )
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
 
+    import utilities.datetime
+    from utilities.datetime import MonthLike
+
+
 _T = TypeVar("_T")
 _TParam = TypeVar("_TParam", bound=ParamType)
 
@@ -76,21 +74,25 @@ class Date(ParamType):
 
     @override
     def convert(
-        self, value: PyDateLike, param: Parameter | None, ctx: Context | None
-    ) -> dt.date:
+        self, value: DateLike, param: Parameter | None, ctx: Context | None
+    ) -> whenever.Date:
         """Convert a value into the `Date` type."""
-        from utilities.whenever import EnsureDateError, ensure_date
-
-        try:
-            return ensure_date(value)
-        except EnsureDateError as error:
-            self.fail(str(error), param, ctx)
+        match value:
+            case whenever.Date():
+                return value
+            case str():
+                try:
+                    return whenever.Date.parse_common_iso(value)
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            case _ as never:
+                assert_never(never)
 
 
-class Duration(ParamType):
-    """A duration-valued parameter."""
+class DateDelta(ParamType):
+    """A date-delta-valued parameter."""
 
-    name = "duration"
+    name = "date delta"
 
     @override
     def __repr__(self) -> str:
@@ -98,18 +100,45 @@ class Duration(ParamType):
 
     @override
     def convert(
-        self,
-        value: MaybeStr[utilities.types.Duration],
-        param: Parameter | None,
-        ctx: Context | None,
-    ) -> utilities.types.Duration:
-        """Convert a value into the `Duration` type."""
-        from utilities.whenever import EnsureDurationError, ensure_duration
+        self, value: DateDeltaLike, param: Parameter | None, ctx: Context | None
+    ) -> whenever.DateDelta:
+        """Convert a value into the `DateDelta` type."""
+        match value:
+            case whenever.DateDelta():
+                return value
+            case str():
+                try:
+                    return whenever.DateDelta.parse_common_iso(value)
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            case _ as never:
+                assert_never(never)
+
+
+class DateTimeDelta(ParamType):
+    """A date-delta-valued parameter."""
+
+    name = "date-time delta"
 
-        try:
-            return ensure_duration(value)
-        except EnsureDurationError as error:
-            self.fail(str(error), param, ctx)
+    @override
+    def __repr__(self) -> str:
+        return self.name.upper()
+
+    @override
+    def convert(
+        self, value: DateTimeDeltaLike, param: Parameter | None, ctx: Context | None
+    ) -> whenever.DateTimeDelta:
+        """Convert a value into the `DateTimeDelta` type."""
+        match value:
+            case whenever.DateTimeDelta():
+                return value
+            case str():
+                try:
+                    return whenever.DateTimeDelta.parse_common_iso(value)
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            case _ as never:
+                assert_never(never)
 
 
 class Enum(ParamType, Generic[TEnum]):
@@ -167,7 +196,7 @@ class Month(ParamType):
 class PlainDateTime(ParamType):
     """A local-datetime-valued parameter."""
 
-    name = "plain datetime"
+    name = "plain date-time"
 
     @override
     def __repr__(self) -> str:
@@ -175,15 +204,19 @@ class PlainDateTime(ParamType):
 
     @override
     def convert(
-        self, value: DateTimeLike, param: Parameter | None, ctx: Context | None
-    ) -> dt.date:
-        """Convert a value into the `LocalDateTime` type."""
-        from utilities.whenever import EnsurePlainDateTimeError, ensure_plain_datetime
-
-        try:
-            return ensure_plain_datetime(value)
-        except EnsurePlainDateTimeError as error:
-            self.fail(str(error), param, ctx)
+        self, value: PlainDateTimeLike, param: Parameter | None, ctx: Context | None
+    ) -> whenever.PlainDateTime:
+        """Convert a value into the `PlainDateTime` type."""
+        match value:
+            case whenever.PlainDateTime():
+                return value
+            case str():
+                try:
+                    return whenever.PlainDateTime.parse_common_iso(value)
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            case _ as never:
+                assert_never(never)
 
 
 class Time(ParamType):
@@ -197,21 +230,25 @@ class Time(ParamType):
 
     @override
     def convert(
-        self, value: PyTimeLike, param: Parameter | None, ctx: Context | None
-    ) -> dt.time:
+        self, value: TimeLike, param: Parameter | None, ctx: Context | None
+    ) -> whenever.Time:
         """Convert a value into the `Time` type."""
-        from utilities.whenever import EnsureTimeError, ensure_time
-
-        try:
-            return ensure_time(value)
-        except EnsureTimeError as error:
-            return self.fail(str(error), param=param, ctx=ctx)
-
-
-class Timedelta(ParamType):
+        match value:
+            case whenever.Time():
+                return value
+            case str():
+                try:
+                    return whenever.Time.parse_common_iso(value)
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            case _ as never:
+                assert_never(never)
+
+
+class TimeDelta(ParamType):
     """A timedelta-valued parameter."""
 
-    name = "timedelta"
+    name = "time-delta"
 
     @override
     def __repr__(self) -> str:
@@ -219,21 +256,25 @@ class Timedelta(ParamType):
 
     @override
     def convert(
-        self, value: PyTimeDeltaLike, param: Parameter | None, ctx: Context | None
-    ) -> dt.timedelta:
-        """Convert a value into the `Timedelta` type."""
-        from utilities.whenever import EnsureTimedeltaError, ensure_timedelta
-
-        try:
-            return ensure_timedelta(value)
-        except EnsureTimedeltaError as error:
-            self.fail(str(error), param, ctx)
+        self, value: TimeDeltaLike, param: Parameter | None, ctx: Context | None
+    ) -> whenever.TimeDelta:
+        """Convert a value into the `TimeDelta` type."""
+        match value:
+            case whenever.TimeDelta():
+                return value
+            case str():
+                try:
+                    return whenever.TimeDelta.parse_common_iso(value)
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            case _ as never:
+                assert_never(never)
 
 
 class ZonedDateTime(ParamType):
     """A zoned-datetime-valued parameter."""
 
-    name = "zoned datetime"
+    name = "zoned date-time"
 
     @override
     def __repr__(self) -> str:
@@ -241,15 +282,19 @@ class ZonedDateTime(ParamType):
 
     @override
     def convert(
-        self, value: DateTimeLike, param: Parameter | None, ctx: Context | None
-    ) -> dt.date:
-        """Convert a value into the `DateTime` type."""
-        from utilities.whenever import EnsureZonedDateTimeError, ensure_zoned_datetime
-
-        try:
-            return ensure_zoned_datetime(value)
-        except EnsureZonedDateTimeError as error:
-            self.fail(str(error), param, ctx)
+        self, value: ZonedDateTimeLike, param: Parameter | None, ctx: Context | None
+    ) -> whenever.ZonedDateTime:
+        """Convert a value into the `ZonedDateTime` type."""
+        match value:
+            case whenever.ZonedDateTime():
+                return value
+            case str():
+                try:
+                    return whenever.ZonedDateTime.parse_common_iso(value)
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            case _ as never:
+                assert_never(never)
 
 
 # parameters - frozenset
@@ -297,20 +342,6 @@ class FrozenSetParameter(ParamType, Generic[_TParam, _T]):
         return _make_metavar(param, desc)
 
 
-class FrozenSetBools(FrozenSetParameter[BoolParamType, str]):
-    """A frozenset-of-bools-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(BoolParamType(), separator=separator)
-
-
-class FrozenSetDates(FrozenSetParameter[Date, dt.date]):
-    """A frozenset-of-dates-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(Date(), separator=separator)
-
-
 class FrozenSetChoices(FrozenSetParameter[Choice, str]):
     """A frozenset-of-choices-valued parameter."""
 
@@ -341,27 +372,6 @@ class FrozenSetEnums(FrozenSetParameter[Enum[TEnum], TEnum]):
         super().__init__(Enum(enum, case_sensitive=case_sensitive), separator=separator)
 
 
-class FrozenSetFloats(FrozenSetParameter[FloatParamType, float]):
-    """A frozenset-of-floats-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(FloatParamType(), separator=separator)
-
-
-class FrozenSetInts(FrozenSetParameter[IntParamType, int]):
-    """A frozenset-of-ints-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(IntParamType(), separator=separator)
-
-
-class FrozenSetMonths(FrozenSetParameter[Month, utilities.datetime.Month]):
-    """A frozenset-of-months-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(Month(), separator=separator)
-
-
 class FrozenSetStrs(FrozenSetParameter[StringParamType, str]):
     """A frozenset-of-strs-valued parameter."""
 
@@ -369,13 +379,6 @@ class FrozenSetStrs(FrozenSetParameter[StringParamType, str]):
         super().__init__(StringParamType(), separator=separator)
 
 
-class FrozenSetUUIDs(FrozenSetParameter[UUIDParameterType, UUID]):
-    """A frozenset-of-UUIDs-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(UUIDParameterType(), separator=separator)
-
-
 # parameters - list
 
 
@@ -421,20 +424,6 @@ class ListParameter(ParamType, Generic[_TParam, _T]):
         return _make_metavar(param, desc)
 
 
-class ListBools(ListParameter[BoolParamType, str]):
-    """A list-of-bools-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(BoolParamType(), separator=separator)
-
-
-class ListDates(ListParameter[Date, dt.date]):
-    """A list-of-dates-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(Date(), separator=separator)
-
-
 class ListEnums(ListParameter[Enum[TEnum], TEnum]):
     """A list-of-enums-valued parameter."""
 
@@ -449,27 +438,6 @@ class ListEnums(ListParameter[Enum[TEnum], TEnum]):
         super().__init__(Enum(enum, case_sensitive=case_sensitive), separator=separator)
 
 
-class ListFloats(ListParameter[FloatParamType, float]):
-    """A list-of-floats-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(FloatParamType(), separator=separator)
-
-
-class ListInts(ListParameter[IntParamType, int]):
-    """A list-of-ints-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(IntParamType(), separator=separator)
-
-
-class ListMonths(ListParameter[Month, utilities.datetime.Month]):
-    """A list-of-months-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(Month(), separator=separator)
-
-
 class ListStrs(ListParameter[StringParamType, str]):
     """A list-of-strs-valued parameter."""
 
@@ -477,13 +445,6 @@ class ListStrs(ListParameter[StringParamType, str]):
         super().__init__(StringParamType(), separator=separator)
 
 
-class ListUUIDs(ListParameter[UUIDParameterType, UUID]):
-    """A list-of-UUIDs-valued parameter."""
-
-    def __init__(self, *, separator: str = ",") -> None:
-        super().__init__(UUIDParameterType(), separator=separator)
-
-
 # private
 
 
@@ -495,34 +456,22 @@ def _make_metavar(param: Parameter, desc: str, /) -> str:
 __all__ = [
     "CONTEXT_SETTINGS_HELP_OPTION_NAMES",
     "Date",
+    "DateDelta",
+    "DateTimeDelta",
     "DirPath",
-    "Duration",
     "Enum",
     "ExistingDirPath",
     "ExistingFilePath",
     "FilePath",
-    "FrozenSetBools",
     "FrozenSetChoices",
-    "FrozenSetDates",
     "FrozenSetEnums",
-    "FrozenSetFloats",
-    "FrozenSetInts",
-    "FrozenSetMonths",
     "FrozenSetParameter",
     "FrozenSetStrs",
-    "FrozenSetUUIDs",
-    "ListBools",
-    "ListDates",
     "ListEnums",
-    "ListFloats",
-    "ListInts",
-    "ListMonths",
     "ListParameter",
     "ListStrs",
-    "ListUUIDs",
-    "Month",
     "PlainDateTime",
     "Time",
-    "Timedelta",
+    "TimeDelta",
     "ZonedDateTime",
 ]

utilities/hypothesis.py

@@ -48,7 +48,15 @@ from hypothesis.strategies import (
     uuids,
 )
 from hypothesis.utils.conventions import not_set
-from whenever import Date, DateDelta, PlainDateTime, Time, TimeDelta, ZonedDateTime
+from whenever import (
+    Date,
+    DateDelta,
+    DateTimeDelta,
+    PlainDateTime,
+    Time,
+    TimeDelta,
+    ZonedDateTime,
+)
 
 from utilities.datetime import (
     DATETIME_MAX_NAIVE,
@@ -97,12 +105,19 @@ from utilities.whenever2 import (
     DATE_DELTA_PARSABLE_MIN,
     DATE_MAX,
     DATE_MIN,
+    DATE_TIME_DELTA_MAX,
+    DATE_TIME_DELTA_MIN,
+    DATE_TIME_DELTA_PARSABLE_MAX,
+    DATE_TIME_DELTA_PARSABLE_MIN,
     PLAIN_DATE_TIME_MAX,
     PLAIN_DATE_TIME_MIN,
     TIME_DELTA_MAX,
     TIME_DELTA_MIN,
     TIME_MAX,
     TIME_MIN,
+    to_date_time_delta,
+    to_days,
+    to_nanos,
 )
 from utilities.zoneinfo import UTC, ensure_time_zone
 
@@ -199,25 +214,11 @@ def date_deltas_whenever(
             ...
         case _ as never:
             assert_never(never)
-    min_years, min_months, min_days = min_value_.in_years_months_days()
-    assert min_years == 0
-    assert min_months == 0
-    max_years, max_months, max_days = max_value_.in_years_months_days()
-    assert max_years == 0
-    assert max_months == 0
+    min_days = to_days(min_value_)
+    max_days = to_days(max_value_)
     if draw2(draw, parsable):
-        parsable_min_years, parsable_min_months, parsable_min_days = (
-            DATE_DELTA_PARSABLE_MIN.in_years_months_days()
-        )
-        assert parsable_min_years == 0
-        assert parsable_min_months == 0
-        min_days = max(min_days, parsable_min_days)
-        parsable_max_years, parsable_max_months, parsable_max_days = (
-            DATE_DELTA_PARSABLE_MAX.in_years_months_days()
-        )
-        assert parsable_max_years == 0
-        assert parsable_max_months == 0
-        max_days = min(max_days, parsable_max_days)
+        min_days = max(min_days, to_days(DATE_DELTA_PARSABLE_MIN))
+        max_days = min(max_days, to_days(DATE_DELTA_PARSABLE_MAX))
     days = draw(integers(min_value=min_days, max_value=max_days))
     return DateDelta(days=days)
 
@@ -287,6 +288,42 @@ def _is_between_timedelta(
 ##
 
 
+@composite
+def date_time_deltas_whenever(
+    draw: DrawFn,
+    /,
+    *,
+    min_value: MaybeSearchStrategy[DateTimeDelta | None] = None,
+    max_value: MaybeSearchStrategy[DateTimeDelta | None] = None,
+    parsable: MaybeSearchStrategy[bool] = False,
+) -> DateTimeDelta:
+    """Strategy for generating date deltas."""
+    min_value_, max_value_ = [draw2(draw, v) for v in [min_value, max_value]]
+    match min_value_:
+        case None:
+            min_value_ = DATE_TIME_DELTA_MIN
+        case DateTimeDelta():
+            ...
+        case _ as never:
+            assert_never(never)
+    match max_value_:
+        case None:
+            max_value_ = DATE_TIME_DELTA_MAX
+        case DateTimeDelta():
+            ...
+        case _ as never:
+            assert_never(never)
+    min_nanos, max_nanos = map(to_nanos, [min_value_, max_value_])
+    if draw2(draw, parsable):
+        min_nanos = max(min_nanos, to_nanos(DATE_TIME_DELTA_PARSABLE_MIN))
+        max_nanos = min(max_nanos, to_nanos(DATE_TIME_DELTA_PARSABLE_MAX))
+    nanos = draw(integers(min_value=min_nanos, max_value=max_nanos))
+    return to_date_time_delta(nanos)
+
+
+##
+
+
 @composite
 def dates_two_digit_year(
     draw: DrawFn,
@@ -1468,6 +1505,7 @@ __all__ = [
     "bool_arrays",
     "date_deltas_whenever",
     "date_durations",
+    "date_time_deltas_whenever",
     "dates_two_digit_year",
     "dates_whenever",
     "datetime_durations",

utilities/luigi.py

@@ -2,121 +2,91 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, cast, overload, override
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    TypeVar,
+    assert_never,
+    cast,
+    overload,
+    override,
+)
 
 import luigi
 from luigi import Parameter, PathParameter, Target, Task
 from luigi import build as _build
-
-from utilities.datetime import EPOCH_UTC
+from luigi.parameter import ParameterVisibility, _no_value
+from whenever import ZonedDateTime
 
 if TYPE_CHECKING:
-    import datetime as dt
-    from collections.abc import Iterable
+    from collections.abc import Callable, Iterable
 
     from luigi.execution_summary import LuigiRunResult
 
-    from utilities.types import LogLevel, MaybeStr, PathLike
-
-
-# parameters
-
-
-class DateHourParameter(luigi.DateHourParameter):
-    """A parameter which takes the value of an hourly `dt.datetime`."""
-
-    def __init__(self, interval: int = 1, **kwargs: Any) -> None:
-        super().__init__(interval, EPOCH_UTC, **kwargs)
-
-    @override
-    def normalize(self, dt: MaybeStr[dt.datetime]) -> dt.datetime:
-        from utilities.whenever import ensure_zoned_datetime
-
-        return ensure_zoned_datetime(dt)
-
-    @override
-    def parse(self, s: str) -> dt.datetime:
-        from utilities.whenever import parse_zoned_datetime
-
-        return parse_zoned_datetime(s)
-
-    @override
-    def serialize(self, dt: dt.datetime) -> str:
-        from utilities.whenever import serialize_zoned_datetime
-
-        return serialize_zoned_datetime(dt)
-
-
-class DateMinuteParameter(luigi.DateMinuteParameter):
-    """A parameter which takes the value of a minutely `dt.datetime`."""
-
-    def __init__(self, interval: int = 1, **kwargs: Any) -> None:
-        super().__init__(interval=interval, start=EPOCH_UTC, **kwargs)
-
-    @override
-    def normalize(self, dt: MaybeStr[dt.datetime]) -> dt.datetime:
-        from utilities.whenever import ensure_zoned_datetime
-
-        return ensure_zoned_datetime(dt)
-
-    @override
-    def parse(self, s: str) -> dt.datetime:
-        from utilities.whenever import parse_zoned_datetime
-
-        return parse_zoned_datetime(s)
-
-    @override
-    def serialize(self, dt: dt.datetime) -> str:
-        from utilities.whenever import serialize_zoned_datetime
-
-        return serialize_zoned_datetime(dt)
-
+    from utilities.types import DateTimeRoundUnit, LogLevel, PathLike, ZonedDateTimeLike
 
-class DateSecondParameter(luigi.DateSecondParameter):
-    """A parameter which takes the value of a secondly `dt.datetime`."""
 
-    def __init__(self, interval: int = 1, **kwargs: Any) -> None:
-        super().__init__(interval, EPOCH_UTC, **kwargs)
+_T = TypeVar("_T")
 
-    @override
-    def normalize(self, dt: MaybeStr[dt.datetime]) -> dt.datetime:
-        from utilities.whenever import ensure_zoned_datetime
-
-        return ensure_zoned_datetime(dt)
-
-    @override
-    def parse(self, s: str) -> dt.datetime:
-        from utilities.whenever import parse_zoned_datetime
-
-        return parse_zoned_datetime(s)
 
-    @override
-    def serialize(self, dt: dt.datetime) -> str:
-        from utilities.whenever import serialize_zoned_datetime
-
-        return serialize_zoned_datetime(dt)
-
-
-class TimeParameter(Parameter):
-    """A parameter which takes the value of a `dt.time`."""
-
-    @override
-    def normalize(self, x: MaybeStr[dt.time]) -> dt.time:
-        from utilities.whenever import ensure_time
-
-        return ensure_time(x)
-
-    @override
-    def parse(self, x: str) -> dt.time:
-        from utilities.whenever import parse_time
-
-        return parse_time(x)
+# parameters
 
-    @override
-    def serialize(self, x: dt.time) -> str:
-        from utilities.whenever import serialize_time
 
-        return serialize_time(x)
+class ZonedDateTimeParameter(Parameter):
+    """A parameter which takes the value of a zoned datetime."""
+
+    _unit: DateTimeRoundUnit
+    _increment: int
+
+    @override
+    def __init__(
+        self,
+        default: Any = _no_value,
+        is_global: bool = False,
+        significant: bool = True,
+        description: str | None = None,
+        config_path: None = None,
+        positional: bool = True,
+        always_in_help: bool = False,
+        batch_method: Callable[[Iterable[_T]], _T] | None = None,
+        visibility: ParameterVisibility = ParameterVisibility.PUBLIC,
+        *,
+        unit: DateTimeRoundUnit = "second",
+        increment: int = 1,
+    ) -> None:
+        super().__init__(
+            default,
+            is_global,
+            significant,
+            description,
+            config_path,
+            positional,
+            always_in_help,
+            batch_method,
+            visibility,
+        )
+        self._unit = unit
+        self._increment = increment
+
+    @override
+    def normalize(self, x: ZonedDateTimeLike) -> ZonedDateTime:
+        match x:
+            case ZonedDateTime() as date_time:
+                ...
+            case str() as text:
+                date_time = ZonedDateTime.parse_common_iso(text)
+            case _ as never:
+                assert_never(never)
+        return date_time.round(self._unit, increment=self._increment, mode="floor")
+
+    @override
+    def parse(self, x: str) -> ZonedDateTime:
+        return ZonedDateTime.parse_common_iso(x)
+
+    @override
+    def serialize(self, x: ZonedDateTime) -> str:
+        return x.format_common_iso()
 
 
 # targets
@@ -217,12 +187,9 @@ def build(
 
 
 __all__ = [
-    "DateHourParameter",
-    "DateMinuteParameter",
-    "DateSecondParameter",
     "ExternalFile",
     "ExternalTask",
     "PathTarget",
-    "TimeParameter",
+    "ZonedDateTimeParameter",
     "build",
 ]

utilities/whenever.py

@@ -33,14 +33,7 @@ from utilities.re import (
 from utilities.zoneinfo import UTC, ensure_time_zone, get_time_zone_name
 
 if TYPE_CHECKING:
-    from utilities.types import (
-        DateTimeLike,
-        Duration,
-        DurationLike,
-        PyDateLike,
-        PyTimeDeltaLike,
-        PyTimeLike,
-    )
+    from utilities.types import Duration
 
 
 MAX_SERIALIZABLE_TIMEDELTA = dt.timedelta(days=3652060, microseconds=-1)
@@ -91,177 +84,6 @@ class _CheckValidZonedDateTimeUnequalError(CheckValidZonedDateTimeError):
 ##
 
 
-def ensure_date(date: PyDateLike, /) -> dt.date:
-    """Ensure the object is a date."""
-    if isinstance(date, dt.date):
-        check_date_not_datetime(date)
-        return date
-    try:
-        return parse_date(date)
-    except ParseDateError as error:
-        raise EnsureDateError(date=error.date) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsureDateError(Exception):
-    date: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to ensure date; got {self.date!r}"
-
-
-##
-
-
-def ensure_datetime(datetime: DateTimeLike, /) -> dt.datetime:
-    """Ensure the object is a datetime."""
-    if isinstance(datetime, dt.datetime):
-        return datetime  # skipif-ci-and-windows
-    try:
-        return parse_datetime(datetime)
-    except ParseDateTimeError as error:
-        raise EnsureDateTimeError(datetime=error.datetime) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsureDateTimeError(Exception):
-    datetime: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to ensure datetime; got {self.datetime!r}"
-
-
-##
-
-
-def ensure_duration(duration: DurationLike, /) -> Duration:
-    """Ensure the object is a Duration."""
-    if isinstance(duration, int | float | dt.timedelta):
-        return duration
-    try:
-        return parse_duration(duration)
-    except ParseDurationError as error:
-        raise EnsureDurationError(duration=error.duration) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsureDurationError(Exception):
-    duration: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to ensure duration; got {self.duration!r}"
-
-
-##
-
-
-def ensure_plain_datetime(datetime: DateTimeLike, /) -> dt.datetime:
-    """Ensure the object is a plain datetime."""
-    if isinstance(datetime, dt.datetime):
-        return datetime
-    try:
-        return parse_plain_datetime(datetime)
-    except ParsePlainDateTimeError as error:
-        raise EnsurePlainDateTimeError(datetime=error.datetime) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsurePlainDateTimeError(Exception):
-    datetime: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to ensure plain datetime; got {self.datetime!r}"
-
-
-##
-
-
-def ensure_time(time: PyTimeLike, /) -> dt.time:
-    """Ensure the object is a time."""
-    if isinstance(time, dt.time):
-        return time
-    try:
-        return parse_time(time)
-    except ParseTimeError as error:
-        raise EnsureTimeError(time=error.time) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsureTimeError(Exception):
-    time: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to ensure time; got {self.time!r}"
-
-
-##
-
-
-def ensure_timedelta(timedelta: PyTimeDeltaLike, /) -> dt.timedelta:
-    """Ensure the object is a timedelta."""
-    if isinstance(timedelta, dt.timedelta):
-        return timedelta
-    try:
-        return parse_timedelta(timedelta)
-    except _ParseTimedeltaParseError as error:
-        raise _EnsureTimedeltaParseError(timedelta=error.timedelta) from None
-    except _ParseTimedeltaNanosecondError as error:
-        raise _EnsureTimedeltaNanosecondError(
-            timedelta=error.timedelta, nanoseconds=error.nanoseconds
-        ) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsureTimedeltaError(Exception):
-    timedelta: str
-
-
-@dataclass(kw_only=True, slots=True)
-class _EnsureTimedeltaParseError(EnsureTimedeltaError):
-    @override
-    def __str__(self) -> str:
-        return f"Unable to ensure timedelta; got {self.timedelta!r}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _EnsureTimedeltaNanosecondError(EnsureTimedeltaError):
-    nanoseconds: int
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to ensure timedelta; got {self.nanoseconds} nanoseconds"
-
-
-##
-
-
-def ensure_zoned_datetime(datetime: DateTimeLike, /) -> dt.datetime:
-    """Ensure the object is a zoned datetime."""
-    if isinstance(datetime, dt.datetime):
-        return datetime
-    try:
-        return parse_zoned_datetime(datetime)
-    except ParseZonedDateTimeError as error:
-        raise EnsureZonedDateTimeError(datetime=error.datetime) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsureZonedDateTimeError(Exception):
-    datetime: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to ensure zoned datetime; got {self.datetime!r}"
-
-
-##
-
-
 _PARSE_DATE_YYMMDD_REGEX = re.compile(r"^(\d{2})(\d{2})(\d{2})$")
 
 
@@ -593,12 +415,6 @@ __all__ = [
     "MAX_SERIALIZABLE_TIMEDELTA",
     "MIN_SERIALIZABLE_TIMEDELTA",
     "CheckValidZonedDateTimeError",
-    "EnsureDateError",
-    "EnsureDateTimeError",
-    "EnsurePlainDateTimeError",
-    "EnsureTimeError",
-    "EnsureTimedeltaError",
-    "EnsureZonedDateTimeError",
     "ParseDateError",
     "ParseDateTimeError",
     "ParseDurationError",
@@ -611,13 +427,6 @@ __all__ = [
     "SerializeTimeDeltaError",
     "SerializeZonedDateTimeError",
     "check_valid_zoned_datetime",
-    "ensure_date",
-    "ensure_datetime",
-    "ensure_duration",
-    "ensure_plain_datetime",
-    "ensure_time",
-    "ensure_timedelta",
-    "ensure_zoned_datetime",
     "parse_date",
     "parse_datetime",
     "parse_duration",

utilities/whenever2.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import datetime as dt
 from collections.abc import Callable
+from dataclasses import dataclass
 from functools import cache
 from logging import LogRecord
 from typing import TYPE_CHECKING, Any, assert_never, overload, override
@@ -17,6 +18,7 @@ from whenever import (
 )
 
 from utilities.datetime import maybe_sub_pct_y
+from utilities.math import sign
 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
@@ -44,16 +46,52 @@ PLAIN_DATE_TIME_MIN = PlainDateTime.from_py_datetime(dt.datetime.min)  # noqa: D
 PLAIN_DATE_TIME_MAX = PlainDateTime.from_py_datetime(dt.datetime.max)  # noqa: DTZ901
 ZONED_DATE_TIME_MIN = PLAIN_DATE_TIME_MIN.assume_tz(UTC.key)
 ZONED_DATE_TIME_MAX = PLAIN_DATE_TIME_MAX.assume_tz(UTC.key)
-DATE_TIME_DELTA_MIN = DateTimeDelta(days=-3652059, seconds=-316192377600)
-DATE_TIME_DELTA_MAX = DateTimeDelta(days=3652059, seconds=316192377600)
-DATE_DELTA_MIN = DATE_TIME_DELTA_MIN.date_part()
-DATE_DELTA_MAX = DATE_TIME_DELTA_MAX.date_part()
-TIME_DELTA_MIN = DATE_TIME_DELTA_MIN.time_part()
-TIME_DELTA_MAX = DATE_TIME_DELTA_MAX.time_part()
 
 
-DATE_TIME_DELTA_PARSABLE_MIN = DateTimeDelta(days=-999999, seconds=-316192377600)
-DATE_TIME_DELTA_PARSABLE_MAX = DateTimeDelta(days=999999, seconds=316192377600)
+DATE_TIME_DELTA_MIN = DateTimeDelta(
+    weeks=-521722,
+    days=-5,
+    hours=-23,
+    minutes=-59,
+    seconds=-59,
+    milliseconds=-999,
+    microseconds=-999,
+    nanoseconds=-999,
+)
+DATE_TIME_DELTA_MAX = DateTimeDelta(
+    weeks=521722,
+    days=5,
+    hours=23,
+    minutes=59,
+    seconds=59,
+    milliseconds=999,
+    microseconds=999,
+    nanoseconds=999,
+)
+DATE_DELTA_MIN = DATE_TIME_DELTA_MIN.date_part()
+DATE_DELTA_MAX = DATE_TIME_DELTA_MAX.date_part()
+TIME_DELTA_MIN = TimeDelta(hours=-87831216)
+TIME_DELTA_MAX = TimeDelta(hours=87831216)
+
+
+DATE_TIME_DELTA_PARSABLE_MIN = DateTimeDelta(
+    weeks=-142857,
+    hours=-23,
+    minutes=-59,
+    seconds=-59,
+    milliseconds=-999,
+    microseconds=-999,
+    nanoseconds=-999,
+)
+DATE_TIME_DELTA_PARSABLE_MAX = DateTimeDelta(
+    weeks=142857,
+    hours=23,
+    minutes=59,
+    seconds=59,
+    milliseconds=999,
+    microseconds=999,
+    nanoseconds=999,
+)
 DATE_DELTA_PARSABLE_MIN = DateDelta(days=-999999)
 DATE_DELTA_PARSABLE_MAX = DateDelta(days=999999)
 
@@ -163,6 +201,164 @@ def to_date(
             assert_never(never)
 
 
+##
+
+
+def to_days(delta: DateDelta, /) -> int:
+    """Compute the number of days in a date delta."""
+    months, days = delta.in_months_days()
+    if months != 0:
+        raise ToDaysError(months=months)
+    return days
+
+
+@dataclass(kw_only=True, slots=True)
+class ToDaysError(Exception):
+    months: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Date delta must not contain months; got {self.months}"
+
+
+##
+
+
+def to_date_time_delta(nanos: int, /) -> DateTimeDelta:
+    """Construct a date-time delta."""
+    components = _to_time_delta_components(nanos)
+    days, hours = divmod(components.hours, 24)
+    weeks, days = divmod(days, 7)
+    match sign(nanos):  # pragma: no cover
+        case 1:
+            if hours < 0:
+                hours += 24
+                days -= 1
+            if days < 0:
+                days += 7
+                weeks -= 1
+        case -1:
+            if hours > 0:
+                hours -= 24
+                days += 1
+            if days > 0:
+                days -= 7
+                weeks += 1
+        case 0:
+            ...
+    return DateTimeDelta(
+        weeks=weeks,
+        days=days,
+        hours=hours,
+        minutes=components.minutes,
+        seconds=components.seconds,
+        microseconds=components.microseconds,
+        milliseconds=components.milliseconds,
+        nanoseconds=components.nanoseconds,
+    )
+
+
+##
+
+
+def to_nanos(delta: DateTimeDelta, /) -> int:
+    """Compute the number of nanoseconds in a date-time delta."""
+    months, days, _, _ = delta.in_months_days_secs_nanos()
+    if months != 0:
+        raise ToNanosError(months=months)
+    return 24 * 60 * 60 * int(1e9) * days + delta.time_part().in_nanoseconds()
+
+
+@dataclass(kw_only=True, slots=True)
+class ToNanosError(Exception):
+    months: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Date-time delta must not contain months; got {self.months}"
+
+
+##
+
+
+def to_time_delta(nanos: int, /) -> TimeDelta:
+    """Construct a time delta."""
+    components = _to_time_delta_components(nanos)
+    return TimeDelta(
+        hours=components.hours,
+        minutes=components.minutes,
+        seconds=components.seconds,
+        microseconds=components.microseconds,
+        milliseconds=components.milliseconds,
+        nanoseconds=components.nanoseconds,
+    )
+
+
+@dataclass(kw_only=True, slots=True)
+class _TimeDeltaComponents:
+    hours: int
+    minutes: int
+    seconds: int
+    microseconds: int
+    milliseconds: int
+    nanoseconds: int
+
+
+def _to_time_delta_components(nanos: int, /) -> _TimeDeltaComponents:
+    sign_use = sign(nanos)
+    micros, nanos = divmod(nanos, int(1e3))
+    millis, micros = divmod(micros, int(1e3))
+    secs, millis = divmod(millis, int(1e3))
+    mins, secs = divmod(secs, 60)
+    hours, mins = divmod(mins, 60)
+    match sign_use:  # pragma: no cover
+        case 1:
+            if nanos < 0:
+                nanos += int(1e3)
+                micros -= 1
+            if micros < 0:
+                micros += int(1e3)
+                millis -= 1
+            if millis < 0:
+                millis += int(1e3)
+                secs -= 1
+            if secs < 0:
+                secs += 60
+                mins -= 1
+            if mins < 0:
+                mins += 60
+                hours -= 1
+        case -1:
+            if nanos > 0:
+                nanos -= int(1e3)
+                micros += 1
+            if micros > 0:
+                micros -= int(1e3)
+                millis += 1
+            if millis > 0:
+                millis -= int(1e3)
+                secs += 1
+            if secs > 0:
+                secs -= 60
+                mins += 1
+            if mins > 0:
+                mins -= 60
+                hours += 1
+        case 0:
+            ...
+    return _TimeDeltaComponents(
+        hours=hours,
+        minutes=mins,
+        seconds=secs,
+        microseconds=micros,
+        milliseconds=millis,
+        nanoseconds=nanos,
+    )
+
+
+##
+
+
 @overload
 def to_zoned_date_time(*, date_time: MaybeCallableZonedDateTime) -> ZonedDateTime: ...
 @overload
@@ -265,6 +461,8 @@ __all__ = [
     "ZERO_TIME",
     "ZONED_DATE_TIME_MAX",
     "ZONED_DATE_TIME_MIN",
+    "ToDaysError",
+    "ToNanosError",
     "WheneverLogRecord",
     "format_compact",
     "format_compact",
@@ -276,5 +474,8 @@ __all__ = [
     "get_today",
     "get_today_local",
     "to_date",
+    "to_date_time_delta",
+    "to_days",
+    "to_nanos",
     "to_zoned_date_time",
 ]