dycw-utilities 0.131.18__py3-none-any.whl → 0.131.19__py3-none-any.whl

utilities/pytest.py

@@ -8,10 +8,11 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, ParamSpec, assert_never, cast, override
 
 from pytest import fixture
+from whenever import ZonedDateTime
 
 from utilities.atomicwrites import writer
-from utilities.datetime import datetime_duration_to_float, get_now
 from utilities.functools import cache
+from utilities.git import get_repo_root
 from utilities.hashlib import md5_hash
 from utilities.pathlib import ensure_suffix
 from utilities.platform import (
@@ -23,17 +24,15 @@ from utilities.platform import (
     IS_WINDOWS,
 )
 from utilities.random import get_state
+from utilities.whenever2 import SECOND, get_now_local
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Sequence
     from random import Random
 
-    from utilities.types import (
-        Coroutine1,
-        Duration,
-        PathLike,
-        TCallableMaybeCoroutine1None,
-    )
+    from whenever import TimeDelta
+
+    from utilities.types import Coroutine1, PathLike, TCallableMaybeCoroutine1None
 
 try:  # WARNING: this package cannot use unguarded `pytest` imports
     from _pytest.config import Config
@@ -169,88 +168,109 @@ def random_state(*, seed: int) -> Random:
 
 
 def throttle(
-    *, root: PathLike | None = None, duration: Duration = 1.0, on_try: bool = False
+    *, root: PathLike | None = None, delta: TimeDelta = SECOND, on_try: bool = False
 ) -> Callable[[TCallableMaybeCoroutine1None], TCallableMaybeCoroutine1None]:
     """Throttle a test. On success by default, on try otherwise."""
-    root_use = Path(".pytest_cache", "throttle") if root is None else Path(root)
-    return cast(
-        "Any", partial(_throttle_inner, root=root_use, duration=duration, on_try=on_try)
-    )
+    return cast("Any", partial(_throttle_inner, root=root, delta=delta, on_try=on_try))
 
 
 def _throttle_inner(
     func: TCallableMaybeCoroutine1None,
     /,
     *,
-    root: Path,
-    duration: Duration = 1.0,
+    root: PathLike | None = None,
+    delta: TimeDelta = SECOND,
     on_try: bool = False,
 ) -> TCallableMaybeCoroutine1None:
     """Throttle a test function/method."""
-    match bool(iscoroutinefunction(func)):
-        case False:
-            func_typed = cast("Callable[..., None]", func)
+    match bool(iscoroutinefunction(func)), on_try:
+        case False, False:
+
+            @wraps(func)
+            def throttle_sync_on_pass(*args: _P.args, **kwargs: _P.kwargs) -> None:
+                _skipif_recent(root=root, delta=delta)
+                cast("Callable[..., None]", func)(*args, **kwargs)
+                _write(root=root)
+
+            return cast("Any", throttle_sync_on_pass)
+
+        case False, True:
+
+            @wraps(func)
+            def throttle_sync_on_try(*args: _P.args, **kwargs: _P.kwargs) -> None:
+                _skipif_recent(root=root, delta=delta)
+                _write(root=root)
+                cast("Callable[..., None]", func)(*args, **kwargs)
+
+            return cast("Any", throttle_sync_on_try)
+
+        case True, False:
 
             @wraps(func)
-            def throttle_sync(*args: _P.args, **kwargs: _P.kwargs) -> None:
-                """Call the throttled sync test function/method."""
-                path, now = _throttle_path_and_now(root, duration=duration)
-                if on_try:
-                    _throttle_write(path, now)
-                    return func_typed(*args, **kwargs)
-                func_typed(*args, **kwargs)
-                _throttle_write(path, now)
-                return None
-
-            return cast("TCallableMaybeCoroutine1None", throttle_sync)
-        case True:
-            func_typed = cast("Callable[..., Coroutine1[None]]", func)
+            async def throttle_async_on_pass(
+                *args: _P.args, **kwargs: _P.kwargs
+            ) -> None:
+                _skipif_recent(root=root, delta=delta)
+                await cast("Callable[..., Coroutine1[None]]", func)(*args, **kwargs)
+                _write(root=root)
+
+            return cast("Any", throttle_async_on_pass)
+
+        case True, True:
 
             @wraps(func)
-            async def throttle_async(*args: _P.args, **kwargs: _P.kwargs) -> None:
-                """Call the throttled async test function/method."""
-                path, now = _throttle_path_and_now(root, duration=duration)
-                if on_try:
-                    _throttle_write(path, now)
-                    return await func_typed(*args, **kwargs)
-                await func_typed(*args, **kwargs)
-                _throttle_write(path, now)
-                return None
-
-            return cast("TCallableMaybeCoroutine1None", throttle_async)
+            async def throttle_async_on_try(
+                *args: _P.args, **kwargs: _P.kwargs
+            ) -> None:
+                _skipif_recent(root=root, delta=delta)
+                _write(root=root)
+                await cast("Callable[..., Coroutine1[None]]", func)(*args, **kwargs)
+
+            return cast("Any", throttle_async_on_try)
+
         case _ as never:
             assert_never(never)
 
 
-def _throttle_path_and_now(
-    root: Path, /, *, duration: Duration = 1.0
-) -> tuple[Path, float]:
-    test = environ["PYTEST_CURRENT_TEST"]
-    path = Path(root, _throttle_md5_hash(test))
-    if path.exists():
-        with path.open(mode="r") as fh:
-            contents = fh.read()
-        prev = float(contents)
+def _skipif_recent(*, root: PathLike | None = None, delta: TimeDelta = SECOND) -> None:
+    if skip is None:
+        return  # pragma: no cover
+    path = _get_path(root=root)
+    try:
+        contents = path.read_text()
+    except FileNotFoundError:
+        return
+    try:
+        last = ZonedDateTime.parse_common_iso(contents)
+    except ValueError:
+        return
+    if (age := (get_now_local() - last)) < delta:
+        _ = skip(reason=f"{_get_name()} throttled (age {age})")
+
+
+def _get_path(*, root: PathLike | None = None) -> Path:
+    if root is None:
+        root_use = get_repo_root().joinpath(  # pragma: no cover
+            ".pytest_cache", "throttle"
+        )
     else:
-        prev = None
-    now = get_now().timestamp()
-    if (
-        (skip is not None)
-        and (prev is not None)
-        and ((now - prev) < datetime_duration_to_float(duration))
-    ):
-        _ = skip(reason=f"{test} throttled")
-    return path, now
+        root_use = root
+    return Path(root_use, _md5_hash_cached(_get_name()))
 
 
 @cache
-def _throttle_md5_hash(text: str, /) -> str:
+def _md5_hash_cached(text: str, /) -> str:
     return md5_hash(text)
 
 
-def _throttle_write(path: Path, now: float, /) -> None:
-    with writer(path, overwrite=True) as temp, temp.open(mode="w") as fh:
-        _ = fh.write(str(now))
+def _get_name() -> str:
+    return environ["PYTEST_CURRENT_TEST"]
+
+
+def _write(*, root: PathLike | None = None) -> None:
+    path = _get_path(root=root)
+    with writer(path, overwrite=True) as temp:
+        _ = temp.write_text(get_now_local().format_common_iso())
 
 
 __all__ = [

utilities/types.py

@@ -97,19 +97,6 @@ class Dataclass(Protocol):
 TDataclass = TypeVar("TDataclass", bound=Dataclass)
 
 
-# datetime
-type DateOrDateTime = dt.date | dt.datetime
-type DateTimeLike = MaybeStr[dt.datetime]
-type Duration = Number | dt.timedelta
-type DurationLike = MaybeStr[Duration]
-type DurationOrEveryDuration = Duration | tuple[Literal["every"], Duration]
-type MaybeCallablePyDate = MaybeCallable[dt.date]
-type MaybeCallablePyDateTime = MaybeCallable[dt.datetime]
-type PyDateLike = MaybeStr[dt.date]
-type PyTimeDeltaLike = MaybeStr[dt.timedelta]
-type PyTimeLike = MaybeStr[dt.time]
-
-
 # enum
 type EnumLike[_TEnum: Enum] = MaybeStr[_TEnum]
 TEnum = TypeVar("TEnum", bound=Enum)
@@ -293,7 +280,9 @@ type TimeZone = Literal[
     "Africa/Abidjan", "Africa/Accra", "Africa/Addis_Ababa", "Africa/Algiers", "Africa/Asmara", "Africa/Asmera", "Africa/Bamako", "Africa/Bangui", "Africa/Banjul", "Africa/Bissau", "Africa/Blantyre", "Africa/Brazzaville", "Africa/Bujumbura", "Africa/Cairo", "Africa/Casablanca", "Africa/Ceuta", "Africa/Conakry", "Africa/Dakar", "Africa/Dar_es_Salaam", "Africa/Djibouti", "Africa/Douala", "Africa/El_Aaiun", "Africa/Freetown", "Africa/Gaborone", "Africa/Harare", "Africa/Johannesburg", "Africa/Juba", "Africa/Kampala", "Africa/Khartoum", "Africa/Kigali", "Africa/Kinshasa", "Africa/Lagos", "Africa/Libreville", "Africa/Lome", "Africa/Luanda", "Africa/Lubumbashi", "Africa/Lusaka", "Africa/Malabo", "Africa/Maputo", "Africa/Maseru", "Africa/Mbabane", "Africa/Mogadishu", "Africa/Monrovia", "Africa/Nairobi", "Africa/Ndjamena", "Africa/Niamey", "Africa/Nouakchott", "Africa/Ouagadougou", "Africa/Porto-Novo", "Africa/Sao_Tome", "Africa/Timbuktu", "Africa/Tripoli", "Africa/Tunis", "Africa/Windhoek", "America/Adak", "America/Anchorage", "America/Anguilla", "America/Antigua", "America/Araguaina", "America/Argentina/Buenos_Aires", "America/Argentina/Catamarca", "America/Argentina/ComodRivadavia", "America/Argentina/Cordoba", "America/Argentina/Jujuy", "America/Argentina/La_Rioja", "America/Argentina/Mendoza", "America/Argentina/Rio_Gallegos", "America/Argentina/Salta", "America/Argentina/San_Juan", "America/Argentina/San_Luis", "America/Argentina/Tucuman", "America/Argentina/Ushuaia", "America/Aruba", "America/Asuncion", "America/Atikokan", "America/Atka", "America/Bahia", "America/Bahia_Banderas", "America/Barbados", "America/Belem", "America/Belize", "America/Blanc-Sablon", "America/Boa_Vista", "America/Bogota", "America/Boise", "America/Buenos_Aires", "America/Cambridge_Bay", "America/Campo_Grande", "America/Cancun", "America/Caracas", "America/Catamarca", "America/Cayenne", "America/Cayman", "America/Chicago", "America/Chihuahua", "America/Ciudad_Juarez", "America/Coral_Harbour", "America/Cordoba", "America/Costa_Rica", "America/Coyhaique", "America/Creston", "America/Cuiaba", "America/Curacao", "America/Danmarkshavn", "America/Dawson", "America/Dawson_Creek", "America/Denver", "America/Detroit", "America/Dominica", "America/Edmonton", "America/Eirunepe", "America/El_Salvador", "America/Ensenada", "America/Fort_Nelson", "America/Fort_Wayne", "America/Fortaleza", "America/Glace_Bay", "America/Godthab", "America/Goose_Bay", "America/Grand_Turk", "America/Grenada", "America/Guadeloupe", "America/Guatemala", "America/Guayaquil", "America/Guyana", "America/Halifax", "America/Havana", "America/Hermosillo", "America/Indiana/Indianapolis", "America/Indiana/Knox", "America/Indiana/Marengo", "America/Indiana/Petersburg", "America/Indiana/Tell_City", "America/Indiana/Vevay", "America/Indiana/Vincennes", "America/Indiana/Winamac", "America/Indianapolis", "America/Inuvik", "America/Iqaluit", "America/Jamaica", "America/Jujuy", "America/Juneau", "America/Kentucky/Louisville", "America/Kentucky/Monticello", "America/Knox_IN", "America/Kralendijk", "America/La_Paz", "America/Lima", "America/Los_Angeles", "America/Louisville", "America/Lower_Princes", "America/Maceio", "America/Managua", "America/Manaus", "America/Marigot", "America/Martinique", "America/Matamoros", "America/Mazatlan", "America/Mendoza", "America/Menominee", "America/Merida", "America/Metlakatla", "America/Mexico_City", "America/Miquelon", "America/Moncton", "America/Monterrey", "America/Montevideo", "America/Montreal", "America/Montserrat", "America/Nassau", "America/New_York", "America/Nipigon", "America/Nome", "America/Noronha", "America/North_Dakota/Beulah", "America/North_Dakota/Center", "America/North_Dakota/New_Salem", "America/Nuuk", "America/Ojinaga", "America/Panama", "America/Pangnirtung", "America/Paramaribo", "America/Phoenix", "America/Port-au-Prince", "America/Port_of_Spain", "America/Porto_Acre", "America/Porto_Velho", "America/Puerto_Rico", "America/Punta_Arenas", "America/Rainy_River", "America/Rankin_Inlet", "America/Recife", "America/Regina", "America/Resolute", "America/Rio_Branco", "America/Rosario", "America/Santa_Isabel", "America/Santarem", "America/Santiago", "America/Santo_Domingo", "America/Sao_Paulo", "America/Scoresbysund", "America/Shiprock", "America/Sitka", "America/St_Barthelemy", "America/St_Johns", "America/St_Kitts", "America/St_Lucia", "America/St_Thomas", "America/St_Vincent", "America/Swift_Current", "America/Tegucigalpa", "America/Thule", "America/Thunder_Bay", "America/Tijuana", "America/Toronto", "America/Tortola", "America/Vancouver", "America/Virgin", "America/Whitehorse", "America/Winnipeg", "America/Yakutat", "America/Yellowknife", "Antarctica/Casey", "Antarctica/Davis", "Antarctica/DumontDUrville", "Antarctica/Macquarie", "Antarctica/Mawson", "Antarctica/McMurdo", "Antarctica/Palmer", "Antarctica/Rothera", "Antarctica/South_Pole", "Antarctica/Syowa", "Antarctica/Troll", "Antarctica/Vostok", "Arctic/Longyearbyen", "Asia/Aden", "Asia/Almaty", "Asia/Amman", "Asia/Anadyr", "Asia/Aqtau", "Asia/Aqtobe", "Asia/Ashgabat", "Asia/Ashkhabad", "Asia/Atyrau", "Asia/Baghdad", "Asia/Bahrain", "Asia/Baku", "Asia/Bangkok", "Asia/Barnaul", "Asia/Beirut", "Asia/Bishkek", "Asia/Brunei", "Asia/Calcutta", "Asia/Chita", "Asia/Choibalsan", "Asia/Chongqing", "Asia/Chungking", "Asia/Colombo", "Asia/Dacca", "Asia/Damascus", "Asia/Dhaka", "Asia/Dili", "Asia/Dubai", "Asia/Dushanbe", "Asia/Famagusta", "Asia/Gaza", "Asia/Harbin", "Asia/Hebron", "Asia/Ho_Chi_Minh", "Asia/Hong_Kong", "Asia/Hovd", "Asia/Irkutsk", "Asia/Istanbul", "Asia/Jakarta", "Asia/Jayapura", "Asia/Jerusalem", "Asia/Kabul", "Asia/Kamchatka", "Asia/Karachi", "Asia/Kashgar", "Asia/Kathmandu", "Asia/Katmandu", "Asia/Khandyga", "Asia/Kolkata", "Asia/Krasnoyarsk", "Asia/Kuala_Lumpur", "Asia/Kuching", "Asia/Kuwait", "Asia/Macao", "Asia/Macau", "Asia/Magadan", "Asia/Makassar", "Asia/Manila", "Asia/Muscat", "Asia/Nicosia", "Asia/Novokuznetsk", "Asia/Novosibirsk", "Asia/Omsk", "Asia/Oral", "Asia/Phnom_Penh", "Asia/Pontianak", "Asia/Pyongyang", "Asia/Qatar", "Asia/Qostanay", "Asia/Qyzylorda", "Asia/Rangoon", "Asia/Riyadh", "Asia/Saigon", "Asia/Sakhalin", "Asia/Samarkand", "Asia/Seoul", "Asia/Shanghai", "Asia/Singapore", "Asia/Srednekolymsk", "Asia/Taipei", "Asia/Tashkent", "Asia/Tbilisi", "Asia/Tehran", "Asia/Tel_Aviv", "Asia/Thimbu", "Asia/Thimphu", "Asia/Tokyo", "Asia/Tomsk", "Asia/Ujung_Pandang", "Asia/Ulaanbaatar", "Asia/Ulan_Bator", "Asia/Urumqi", "Asia/Ust-Nera", "Asia/Vientiane", "Asia/Vladivostok", "Asia/Yakutsk", "Asia/Yangon", "Asia/Yekaterinburg", "Asia/Yerevan", "Atlantic/Azores", "Atlantic/Bermuda", "Atlantic/Canary", "Atlantic/Cape_Verde", "Atlantic/Faeroe", "Atlantic/Faroe", "Atlantic/Jan_Mayen", "Atlantic/Madeira", "Atlantic/Reykjavik", "Atlantic/South_Georgia", "Atlantic/St_Helena", "Atlantic/Stanley", "Australia/ACT", "Australia/Adelaide", "Australia/Brisbane", "Australia/Broken_Hill", "Australia/Canberra", "Australia/Currie", "Australia/Darwin", "Australia/Eucla", "Australia/Hobart", "Australia/LHI", "Australia/Lindeman", "Australia/Lord_Howe", "Australia/Melbourne", "Australia/NSW", "Australia/North", "Australia/Perth", "Australia/Queensland", "Australia/South", "Australia/Sydney", "Australia/Tasmania", "Australia/Victoria", "Australia/West", "Australia/Yancowinna", "Brazil/Acre", "Brazil/DeNoronha", "Brazil/East", "Brazil/West", "CET", "CST6CDT", "Canada/Atlantic", "Canada/Central", "Canada/Eastern", "Canada/Mountain", "Canada/Newfoundland", "Canada/Pacific", "Canada/Saskatchewan", "Canada/Yukon", "Chile/Continental", "Chile/EasterIsland", "Cuba", "EET", "EST", "EST5EDT", "Egypt", "Eire", "Etc/GMT", "Etc/GMT+0", "Etc/GMT+1", "Etc/GMT+10", "Etc/GMT+11", "Etc/GMT+12", "Etc/GMT+2", "Etc/GMT+3", "Etc/GMT+4", "Etc/GMT+5", "Etc/GMT+6", "Etc/GMT+7", "Etc/GMT+8", "Etc/GMT+9", "Etc/GMT-0", "Etc/GMT-1", "Etc/GMT-10", "Etc/GMT-11", "Etc/GMT-12", "Etc/GMT-13", "Etc/GMT-14", "Etc/GMT-2", "Etc/GMT-3", "Etc/GMT-4", "Etc/GMT-5", "Etc/GMT-6", "Etc/GMT-7", "Etc/GMT-8", "Etc/GMT-9", "Etc/GMT0", "Etc/Greenwich", "Etc/UCT", "Etc/UTC", "Etc/Universal", "Etc/Zulu", "Europe/Amsterdam", "Europe/Andorra", "Europe/Astrakhan", "Europe/Athens", "Europe/Belfast", "Europe/Belgrade", "Europe/Berlin", "Europe/Bratislava", "Europe/Brussels", "Europe/Bucharest", "Europe/Budapest", "Europe/Busingen", "Europe/Chisinau", "Europe/Copenhagen", "Europe/Dublin", "Europe/Gibraltar", "Europe/Guernsey", "Europe/Helsinki", "Europe/Isle_of_Man", "Europe/Istanbul", "Europe/Jersey", "Europe/Kaliningrad", "Europe/Kiev", "Europe/Kirov", "Europe/Kyiv", "Europe/Lisbon", "Europe/Ljubljana", "Europe/London", "Europe/Luxembourg", "Europe/Madrid", "Europe/Malta", "Europe/Mariehamn", "Europe/Minsk", "Europe/Monaco", "Europe/Moscow", "Europe/Nicosia", "Europe/Oslo", "Europe/Paris", "Europe/Podgorica", "Europe/Prague", "Europe/Riga", "Europe/Rome", "Europe/Samara", "Europe/San_Marino", "Europe/Sarajevo", "Europe/Saratov", "Europe/Simferopol", "Europe/Skopje", "Europe/Sofia", "Europe/Stockholm", "Europe/Tallinn", "Europe/Tirane", "Europe/Tiraspol", "Europe/Ulyanovsk", "Europe/Uzhgorod", "Europe/Vaduz", "Europe/Vatican", "Europe/Vienna", "Europe/Vilnius", "Europe/Volgograd", "Europe/Warsaw", "Europe/Zagreb", "Europe/Zaporozhye", "Europe/Zurich", "Factory", "GB", "GB-Eire", "GMT", "GMT+0", "GMT-0", "GMT0", "Greenwich", "HST", "Hongkong", "Iceland", "Indian/Antananarivo", "Indian/Chagos", "Indian/Christmas", "Indian/Cocos", "Indian/Comoro", "Indian/Kerguelen", "Indian/Mahe", "Indian/Maldives", "Indian/Mauritius", "Indian/Mayotte", "Indian/Reunion", "Iran", "Israel", "Jamaica", "Japan", "Kwajalein", "Libya", "MET", "MST", "MST7MDT", "Mexico/BajaNorte", "Mexico/BajaSur", "Mexico/General", "NZ", "NZ-CHAT", "Navajo", "PRC", "PST8PDT", "Pacific/Apia", "Pacific/Auckland", "Pacific/Bougainville", "Pacific/Chatham", "Pacific/Chuuk", "Pacific/Easter", "Pacific/Efate", "Pacific/Enderbury", "Pacific/Fakaofo", "Pacific/Fiji", "Pacific/Funafuti", "Pacific/Galapagos", "Pacific/Gambier", "Pacific/Guadalcanal", "Pacific/Guam", "Pacific/Honolulu", "Pacific/Johnston", "Pacific/Kanton", "Pacific/Kiritimati", "Pacific/Kosrae", "Pacific/Kwajalein", "Pacific/Majuro", "Pacific/Marquesas", "Pacific/Midway", "Pacific/Nauru", "Pacific/Niue", "Pacific/Norfolk", "Pacific/Noumea", "Pacific/Pago_Pago", "Pacific/Palau", "Pacific/Pitcairn", "Pacific/Pohnpei", "Pacific/Ponape", "Pacific/Port_Moresby", "Pacific/Rarotonga", "Pacific/Saipan", "Pacific/Samoa", "Pacific/Tahiti", "Pacific/Tarawa", "Pacific/Tongatapu", "Pacific/Truk", "Pacific/Wake", "Pacific/Wallis", "Pacific/Yap", "Poland", "Portugal", "ROC", "ROK", "Singapore", "Turkey", "UCT", "US/Alaska", "US/Aleutian", "US/Arizona", "US/Central", "US/East-Indiana", "US/Eastern", "US/Hawaii", "US/Indiana-Starke", "US/Michigan", "US/Mountain", "US/Pacific", "US/Samoa", "UTC", "Universal", "W-SU", "WET", "Zulu"
 ]
 # fmt: on
-type TimeZoneLike = ZoneInfo | Literal["local"] | TimeZone | dt.tzinfo | dt.datetime
+type TimeZoneLike = (
+    ZoneInfo | ZonedDateTime | Literal["local"] | TimeZone | dt.tzinfo | dt.datetime
+)
 
 
 __all__ = [
@@ -301,14 +290,9 @@ __all__ = [
     "Dataclass",
     "DateDeltaLike",
     "DateLike",
-    "DateOrDateTime",
     "DateTimeDeltaLike",
-    "DateTimeLike",
     "DateTimeRoundMode",
     "DateTimeRoundUnit",
-    "Duration",
-    "DurationLike",
-    "DurationOrEveryDuration",
     "EnumLike",
     "ExcInfo",
     "IterableHashable",
@@ -320,8 +304,6 @@ __all__ = [
     "MaybeCallableDate",
     "MaybeCallableEvent",
     "MaybeCallablePathLike",
-    "MaybeCallablePyDate",
-    "MaybeCallablePyDateTime",
     "MaybeCallableZonedDateTime",
     "MaybeCoroutine1",
     "MaybeIterable",
@@ -336,9 +318,6 @@ __all__ = [
     "PathLike",
     "PatternLike",
     "PlainDateTimeLike",
-    "PyDateLike",
-    "PyTimeDeltaLike",
-    "PyTimeLike",
     "Seed",
     "SerializeObjectExtra",
     "Sign",

utilities/typing.py

@@ -11,7 +11,6 @@ from typing import (
     Literal,
     NamedTuple,
     Optional,  # pyright: ignore[reportDeprecated]
-    Self,
     TypeAliasType,
     TypeGuard,
     TypeVar,
@@ -50,14 +49,6 @@ _T5 = TypeVar("_T5")
 ##
 
 
-def contains_self(obj: Any, /) -> bool:
-    """Check if an annotation contains `Self`."""
-    return (obj is Self) or any(map(contains_self, get_args(obj)))
-
-
-##
-
-
 def get_args(obj: Any, /, *, optional_drop_none: bool = False) -> tuple[Any, ...]:
     """Get the arguments of an annotation."""
     if isinstance(obj, TypeAliasType):
@@ -183,12 +174,9 @@ def get_union_type_classes(obj: Any, /) -> tuple[type[Any], ...]:
         raise _GetUnionTypeClassesUnionTypeError(obj=obj)
     types_: Sequence[type[Any]] = []
     for arg in get_args(obj):
-        if isinstance(arg, type):
-            types_.append(arg)
-        elif is_union_type(arg):
-            types_.extend(get_union_type_classes(arg))
-        else:
+        if not isinstance(arg, type):
             raise _GetUnionTypeClassesInternalTypeError(obj=obj, inner=arg)
+        types_.append(arg)
     return tuple(types_)
 
 
@@ -495,7 +483,6 @@ __all__ = [
     "GetUnionTypeClassesError",
     "IsInstanceGenError",
     "IsSubclassGenError",
-    "contains_self",
     "get_literal_elements",
     "get_type_classes",
     "get_type_hints",

utilities/whenever2.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
 import datetime as dt
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from dataclasses import dataclass
 from functools import cache
 from logging import LogRecord
-from typing import TYPE_CHECKING, Any, assert_never, overload, override
+from statistics import fmean
+from typing import TYPE_CHECKING, Any, SupportsFloat, assert_never, overload, override
 
 from whenever import (
     Date,
@@ -99,6 +100,7 @@ DATE_DELTA_PARSABLE_MAX = DateDelta(days=999999)
 ## common constants
 
 
+ZERO_DAYS = DateDelta()
 ZERO_TIME = TimeDelta()
 MICROSECOND = TimeDelta(microseconds=1)
 MILLISECOND = TimeDelta(milliseconds=1)
@@ -107,6 +109,37 @@ MINUTE = TimeDelta(minutes=1)
 HOUR = TimeDelta(hours=1)
 DAY = DateDelta(days=1)
 WEEK = DateDelta(weeks=1)
+MONTH = DateDelta(months=1)
+YEAR = DateDelta(years=1)
+
+
+##
+
+
+def datetime_utc(
+    year: int,
+    month: int,
+    day: int,
+    /,
+    hour: int = 0,
+    minute: int = 0,
+    second: int = 0,
+    millisecond: int = 0,
+    microsecond: int = 0,
+    nanosecond: int = 0,
+) -> ZonedDateTime:
+    """Create a UTC-zoned datetime."""
+    nanos = int(1e6) * millisecond + int(1e3) * microsecond + nanosecond
+    return ZonedDateTime(
+        year,
+        month,
+        day,
+        hour=hour,
+        minute=minute,
+        second=second,
+        nanosecond=nanos,
+        tz=UTC.key,
+    )
 
 
 ##
@@ -173,6 +206,110 @@ def get_today_local() -> Date:
 
 TODAY_LOCAL = get_today_local()
 
+
+##
+
+
+def mean_datetime(
+    datetimes: Iterable[ZonedDateTime],
+    /,
+    *,
+    weights: Iterable[SupportsFloat] | None = None,
+) -> ZonedDateTime:
+    """Compute the mean of a set of datetimes."""
+    datetimes = list(datetimes)
+    match len(datetimes):
+        case 0:
+            raise MeanDateTimeError from None
+        case 1:
+            return datetimes[0]
+        case _:
+            timestamps = [d.timestamp_nanos() for d in datetimes]
+            timestamp = round(fmean(timestamps, weights=weights))
+            return ZonedDateTime.from_timestamp_nanos(timestamp, tz=datetimes[0].tz)
+
+
+@dataclass(kw_only=True, slots=True)
+class MeanDateTimeError(Exception):
+    @override
+    def __str__(self) -> str:
+        return "Mean requires at least 1 datetime"
+
+
+##
+
+
+def min_max_date(
+    *,
+    min_date: Date | None = None,
+    max_date: Date | None = None,
+    min_age: DateDelta | None = None,
+    max_age: DateDelta | None = None,
+    time_zone: TimeZoneLike = UTC,
+) -> tuple[Date | None, Date | None]:
+    """Ucompute the min/max date given a combination of dates/ages."""
+    today = get_today(time_zone=time_zone)
+    min_parts: list[Date] = []
+    if min_date is not None:
+        if min_date > today:
+            raise _MinMaxDateMinDateError(min_date=min_date, today=today)
+        min_parts.append(min_date)
+    if max_age is not None:
+        min_parts.append(today - max_age)
+    min_date_use = max(min_parts, default=None)
+    max_parts: list[Date] = []
+    if max_date is not None:
+        if max_date > today:
+            raise _MinMaxDateMaxDateError(max_date=max_date, today=today)
+        max_parts.append(max_date)
+    if min_age is not None:
+        max_parts.append(today - min_age)
+    max_date_use = min(max_parts, default=None)
+    if (
+        (min_date_use is not None)
+        and (max_date_use is not None)
+        and (min_date_use > max_date_use)
+    ):
+        raise _MinMaxDatePeriodError(min_date=min_date_use, max_date=max_date_use)
+    return min_date_use, max_date_use
+
+
+@dataclass(kw_only=True, slots=True)
+class MinMaxDateError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _MinMaxDateMinDateError(MinMaxDateError):
+    min_date: Date
+    today: Date
+
+    @override
+    def __str__(self) -> str:
+        return f"Min date must be at most today; got {self.min_date} > {self.today}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _MinMaxDateMaxDateError(MinMaxDateError):
+    max_date: Date
+    today: Date
+
+    @override
+    def __str__(self) -> str:
+        return f"Max date must be at most today; got {self.max_date} > {self.today}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _MinMaxDatePeriodError(MinMaxDateError):
+    min_date: Date
+    max_date: Date
+
+    @override
+    def __str__(self) -> str:
+        return (
+            f"Min date must be at most max date; got {self.min_date} > {self.max_date}"
+        )
+
+
 ##
 
 
@@ -447,6 +584,7 @@ __all__ = [
     "MICROSECOND",
     "MILLISECOND",
     "MINUTE",
+    "MONTH",
     "NOW_LOCAL",
     "PLAIN_DATE_TIME_MAX",
     "PLAIN_DATE_TIME_MIN",
@@ -458,13 +596,17 @@ __all__ = [
     "TODAY_LOCAL",
     "TODAY_UTC",
     "WEEK",
+    "YEAR",
+    "ZERO_DAYS",
     "ZERO_TIME",
     "ZONED_DATE_TIME_MAX",
     "ZONED_DATE_TIME_MIN",
+    "MeanDateTimeError",
+    "MinMaxDateError",
     "ToDaysError",
     "ToNanosError",
     "WheneverLogRecord",
-    "format_compact",
+    "datetime_utc",
     "format_compact",
     "from_timestamp",
     "from_timestamp_millis",
@@ -473,6 +615,8 @@ __all__ = [
     "get_now_local",
     "get_today",
     "get_today_local",
+    "mean_datetime",
+    "min_max_date",
     "to_date",
     "to_date_time_delta",
     "to_days",

utilities/zoneinfo.py

@@ -5,6 +5,8 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, assert_never, cast, override
 from zoneinfo import ZoneInfo
 
+from whenever import ZonedDateTime
+
 from utilities.tzlocal import LOCAL_TIME_ZONE
 
 if TYPE_CHECKING:
@@ -22,6 +24,8 @@ def ensure_time_zone(obj: TimeZoneLike, /) -> ZoneInfo:
     match obj:
         case ZoneInfo() as zone_info:
             return zone_info
+        case ZonedDateTime() as datetime:
+            return ZoneInfo(datetime.tz)
         case "local":
             return LOCAL_TIME_ZONE
         case str() as key: