dycw-utilities 0.146.2__py3-none-any.whl → 0.178.1__py3-none-any.whl

utilities/throttle.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import partial, wraps
+from inspect import iscoroutinefunction
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, NoReturn, assert_never, cast, override
+
+from whenever import ZonedDateTime
+
+from utilities.atomicwrites import writer
+from utilities.os import get_env_var
+from utilities.pathlib import to_path
+from utilities.types import MaybeCallablePathLike, MaybeCoro
+from utilities.whenever import SECOND, get_now_local
+
+if TYPE_CHECKING:
+    from utilities.types import Coro, Delta
+
+
+def throttle[F: Callable[..., MaybeCoro[None]]](
+    *,
+    on_try: bool = False,
+    delta: Delta = SECOND,
+    path: MaybeCallablePathLike = Path.cwd,
+    raiser: Callable[[], NoReturn] | None = None,
+) -> Callable[[F], F]:
+    """Throttle a function. On success by default, on try otherwise."""
+    return cast(
+        "Any",
+        partial(_throttle_inner, on_try=on_try, delta=delta, path=path, raiser=raiser),
+    )
+
+
+def _throttle_inner[F: Callable[..., MaybeCoro[None]]](
+    func: F,
+    /,
+    *,
+    on_try: bool = False,
+    delta: Delta = SECOND,
+    path: MaybeCallablePathLike = Path.cwd,
+    raiser: Callable[[], NoReturn] | None = None,
+) -> F:
+    match bool(iscoroutinefunction(func)), on_try:
+        case False, False:
+
+            @wraps(func)
+            def throttle_sync_on_pass(*args: Any, **kwargs: Any) -> None:
+                path_use = to_path(path)
+                if _is_throttle(path=path_use, delta=delta):
+                    _try_raise(raiser=raiser)
+                else:
+                    cast("Callable[..., None]", func)(*args, **kwargs)
+                    _write_throttle(path=path_use)
+
+            return cast("Any", throttle_sync_on_pass)
+
+        case False, True:
+
+            @wraps(func)
+            def throttle_sync_on_try(*args: Any, **kwargs: Any) -> None:
+                path_use = to_path(path)
+                if _is_throttle(path=path_use, delta=delta):
+                    _try_raise(raiser=raiser)
+                else:
+                    _write_throttle(path=path_use)
+                    cast("Callable[..., None]", func)(*args, **kwargs)
+
+            return cast("Any", throttle_sync_on_try)
+
+        case True, False:
+
+            @wraps(func)
+            async def throttle_async_on_pass(*args: Any, **kwargs: Any) -> None:
+                path_use = to_path(path)
+                if _is_throttle(path=path_use, delta=delta):
+                    _try_raise(raiser=raiser)
+                else:
+                    await cast("Callable[..., Coro[None]]", func)(*args, **kwargs)
+                    _write_throttle(path=path_use)
+
+            return cast("Any", throttle_async_on_pass)
+
+        case True, True:
+
+            @wraps(func)
+            async def throttle_async_on_try(*args: Any, **kwargs: Any) -> None:
+                path_use = to_path(path)
+                if _is_throttle(path=path_use, delta=delta):
+                    _try_raise(raiser=raiser)
+                else:
+                    _write_throttle(path=path_use)
+                    await cast("Callable[..., Coro[None]]", func)(*args, **kwargs)
+
+            return cast("Any", throttle_async_on_try)
+
+        case never:
+            assert_never(never)
+
+
+def _is_throttle(
+    *, path: MaybeCallablePathLike = Path.cwd, delta: Delta = SECOND
+) -> bool:
+    if get_env_var("THROTTLE", nullable=True):
+        return False
+    path = to_path(path)
+    if path.is_file():
+        text = path.read_text()
+        if text == "":
+            path.unlink(missing_ok=True)
+            return False
+        try:
+            last = ZonedDateTime.parse_iso(text)
+        except ValueError:
+            raise _ThrottleParseZonedDateTimeError(path=path, text=text) from None
+        threshold = get_now_local() - delta
+        return threshold <= last
+    if not path.exists():
+        return False
+    raise _ThrottleMarkerFileError(path=path)
+
+
+def _try_raise(*, raiser: Callable[[], NoReturn] | None = None) -> None:
+    if raiser is not None:
+        raiser()
+
+
+def _write_throttle(*, path: MaybeCallablePathLike = Path.cwd) -> None:
+    path = to_path(path)
+    with writer(path, overwrite=True) as temp:
+        _ = temp.write_text(get_now_local().format_iso())
+
+
+@dataclass(kw_only=True, slots=True)
+class ThrottleError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _ThrottleParseZonedDateTimeError(ThrottleError):
+    path: Path
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse the contents {self.text!r} of {str(self.path)!r} to a ZonedDateTime"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ThrottleMarkerFileError(ThrottleError):
+    path: Path
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid marker file {str(self.path)!r}"
+
+
+__all__ = ["ThrottleError", "throttle"]

utilities/timer.py

@@ -56,11 +56,11 @@ class Timer:
 
     @override
     def __repr__(self) -> str:
-        return self.timedelta.format_common_iso()
+        return self.timedelta.format_iso()
 
     @override
     def __str__(self) -> str:
-        return self.timedelta.format_common_iso()
+        return self.timedelta.format_iso()
 
     # comparison
 

utilities/traceback.py

@@ -6,16 +6,17 @@ from dataclasses import dataclass
 from functools import partial
 from getpass import getuser
 from itertools import repeat
+from os import getpid
 from pathlib import Path
 from socket import gethostname
+from sys import stderr
 from traceback import TracebackException
 from typing import TYPE_CHECKING, override
 
 from utilities.atomicwrites import writer
 from utilities.errors import repr_error
-from utilities.functions import to_bool
 from utilities.iterables import OneEmptyError, one
-from utilities.pathlib import get_path, module_path
+from utilities.pathlib import module_path, to_path
 from utilities.reprlib import (
     RICH_EXPAND_ALL,
     RICH_INDENT_SIZE,
@@ -25,24 +26,26 @@ from utilities.reprlib import (
     RICH_MAX_WIDTH,
     yield_mapping_repr,
 )
-from utilities.version import get_version
+from utilities.text import to_bool
+from utilities.tzlocal import LOCAL_TIME_ZONE_NAME
+from utilities.version import to_version
 from utilities.whenever import (
     format_compact,
     get_now,
     get_now_local,
-    to_local_plain,
     to_zoned_date_time,
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator, Sequence
+    from collections.abc import Callable, Iterator
     from traceback import FrameSummary
     from types import TracebackType
 
     from utilities.types import (
-        MaybeCallableBool,
+        Delta,
+        MaybeCallableBoolLike,
         MaybeCallablePathLike,
-        MaybeCallableZonedDateTime,
+        MaybeCallableZonedDateTimeLike,
         PathLike,
     )
     from utilities.version import MaybeCallableVersionLike
@@ -51,15 +54,12 @@ if TYPE_CHECKING:
 ##
 
 
-_START = get_now()
-
-
 def format_exception_stack(
     error: BaseException,
     /,
     *,
     header: bool = False,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
     capture_locals: bool = False,
     max_width: int = RICH_MAX_WIDTH,
@@ -70,7 +70,7 @@ def format_exception_stack(
     expand_all: bool = RICH_EXPAND_ALL,
 ) -> str:
     """Format an exception stack."""
-    lines: Sequence[str] = []
+    lines: list[str] = []
     if header:
         lines.extend(_yield_header_lines(start=start, version=version))
     lines.extend(
@@ -90,22 +90,20 @@ def format_exception_stack(
 
 def _yield_header_lines(
     *,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
 ) -> Iterator[str]:
     """Yield the header lines."""
     now = get_now_local()
-    start_use = to_zoned_date_time(date_time=start)
-    yield f"Date/time | {format_compact(now)}"
-    start_str = "" if start_use is None else format_compact(start_use)
-    yield f"Started   | {start_str}"
-    delta = None if start_use is None else (now - start_use)
-    delta_str = "" if delta is None else delta.format_common_iso()
-    yield f"Duration  | {delta_str}"
-    yield f"User      | {getuser()}"
-    yield f"Host      | {gethostname()}"
-    version_use = "" if version is None else get_version(version=version)
-    yield f"Version   | {version_use}"
+    yield f"Date/time  | {format_compact(now)}"
+    start_use = to_zoned_date_time(start).to_tz(LOCAL_TIME_ZONE_NAME)
+    yield f"Started    | {format_compact(start_use)}"
+    yield f"Duration   | {(now - start_use).format_iso()}"
+    yield f"User       | {getuser()}"
+    yield f"Host       | {gethostname()}"
+    yield f"Process ID | {getpid()}"
+    version_use = "" if version is None else to_version(version)
+    yield f"Version    | {version_use}"
     yield ""
 
 
@@ -198,9 +196,10 @@ def _trim_path(path: PathLike, pattern: str, /) -> Path | None:
 
 def make_except_hook(
     *,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
     path: MaybeCallablePathLike | None = None,
+    path_max_age: Delta | None = None,
     max_width: int = RICH_MAX_WIDTH,
     indent_size: int = RICH_INDENT_SIZE,
     max_length: int | None = RICH_MAX_LENGTH,
@@ -208,7 +207,7 @@ def make_except_hook(
     max_depth: int | None = RICH_MAX_DEPTH,
     expand_all: bool = RICH_EXPAND_ALL,
     slack_url: str | None = None,
-    pudb: MaybeCallableBool = False,
+    pudb: MaybeCallableBoolLike = False,
 ) -> Callable[
     [type[BaseException] | None, BaseException | None, TracebackType | None], None
 ]:
@@ -218,6 +217,7 @@ def make_except_hook(
         start=start,
         version=version,
         path=path,
+        path_max_age=path_max_age,
         max_width=max_width,
         indent_size=indent_size,
         max_length=max_length,
@@ -235,9 +235,10 @@ def _make_except_hook_inner(
     traceback: TracebackType | None,
     /,
     *,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
     path: MaybeCallablePathLike | None = None,
+    path_max_age: Delta | None = None,
     max_width: int = RICH_MAX_WIDTH,
     indent_size: int = RICH_INDENT_SIZE,
     max_length: int | None = RICH_MAX_LENGTH,
@@ -245,7 +246,7 @@ def _make_except_hook_inner(
     max_depth: int | None = RICH_MAX_DEPTH,
     expand_all: bool = RICH_EXPAND_ALL,
     slack_url: str | None = None,
-    pudb: MaybeCallableBool = False,
+    pudb: MaybeCallableBoolLike = False,
 ) -> None:
     """Exception hook to log the traceback."""
     _ = (exc_type, traceback)
@@ -254,11 +255,10 @@ def _make_except_hook_inner(
     slim = format_exception_stack(exc_val, header=True, start=start, version=version)
     _ = sys.stderr.write(f"{slim}\n")  # don't 'from sys import stderr'
     if path is not None:
-        path = (
-            get_path(path=path)
-            .joinpath(format_compact(to_local_plain(get_now())))
-            .with_suffix(".txt")
-        )
+        path = to_path(path)
+        path_log = path.joinpath(
+            format_compact(get_now_local(), path=True)
+        ).with_suffix(".txt")
         full = format_exception_stack(
             exc_val,
             header=True,
@@ -272,18 +272,39 @@ def _make_except_hook_inner(
             max_depth=max_depth,
             expand_all=expand_all,
         )
-        with writer(path, overwrite=True) as temp:
+        with writer(path_log, overwrite=True) as temp:
             _ = temp.write_text(full)
+        if path_max_age is not None:
+            _make_except_hook_purge(path, path_max_age)
     if slack_url is not None:  # pragma: no cover
-        from utilities.slack_sdk import send_to_slack
+        from utilities.slack_sdk import SendToSlackError, send_to_slack
 
-        send_to_slack(slack_url, f"```{slim}```")
-    if to_bool(bool_=pudb):  # pragma: no cover
-        from pudb import post_mortem
+        try:
+            send_to_slack(slack_url, f"```{slim}```")
+        except SendToSlackError as error:
+            _ = stderr.write(f"{error}\n")
+    if to_bool(pudb):  # pragma: no cover
+        from pudb import post_mortem  # pyright: ignore[reportMissingImports]
 
         post_mortem(tb=traceback, e_type=exc_type, e_value=exc_val)
 
 
+def _make_except_hook_purge(path: PathLike, max_age: Delta, /) -> None:
+    threshold = get_now_local() - max_age
+    paths: set[Path] = set()
+    for p in Path(path).iterdir():
+        if p.is_file():
+            try:
+                date_time = to_zoned_date_time(p.stem)
+            except ValueError:
+                pass
+            else:
+                if date_time <= threshold:
+                    paths.add(p)
+    for p in paths:
+        p.unlink(missing_ok=True)
+
+
 @dataclass(kw_only=True, slots=True)
 class MakeExceptHookError(Exception):
     @override

utilities/types.py

@@ -1,8 +1,7 @@
 from __future__ import annotations
 
 import datetime as dt
-from asyncio import Event
-from collections.abc import Callable, Coroutine, Hashable, Iterable, Mapping, Sequence
+from collections.abc import Callable, Collection, Coroutine, Iterable, Mapping
 from enum import Enum
 from ipaddress import IPv4Address, IPv6Address
 from logging import Logger
@@ -16,9 +15,11 @@ from typing import (
     Literal,
     Protocol,
     TypeVar,
+    get_args,
     overload,
     runtime_checkable,
 )
+from uuid import UUID
 from zoneinfo import ZoneInfo
 
 from whenever import (
@@ -62,22 +63,26 @@ type OpenMode = Literal[
     "a+b",
 ]
 type MaybeCallable[T] = T | Callable[[], T]
-type MaybeCallableBool = MaybeCallable[bool]
 type MaybeStr[T] = T | str
 type MaybeType[T] = T | type[T]
 type StrMapping = Mapping[str, Any]
 type StrStrMapping = Mapping[str, str]
-type TypeLike[T] = type[T] | tuple[type[T], ...]
 type TupleOrStrMapping = tuple[Any, ...] | StrMapping
+type TypeLike[T] = type[T] | tuple[type[T], ...]
+# basic - derived
+type MaybeCallableBoolLike = MaybeCallable[BoolLike]
+type BoolLike = MaybeStr[bool]
 
 
 # asyncio
 type Coro[T] = Coroutine[Any, Any, T]
-type MaybeCallableEvent = MaybeCallable[Event]
 type MaybeCoro[T] = T | Coro[T]
 
 
 # collections.abc
+type SupportsFloatOrIndex = SupportsFloat | SupportsIndex
+
+
 @runtime_checkable
 class SupportsKeysAndGetItem(Protocol[_T, _T_co]):
     def keys(self) -> Iterable[_T]: ...  # pragma: no cover
@@ -104,23 +109,33 @@ type MonthInt = Literal[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
 type EnumLike[E: Enum] = MaybeStr[E]
 
 
+# errors
+type ExceptionTypeLike[T: Exception] = type[T] | tuple[type[T], ...]
+
+
 # ipaddress
 IPv4AddressLike = MaybeStr[IPv4Address]
 IPv6AddressLike = MaybeStr[IPv6Address]
 
 
 # iterables
+type MaybeCollection[T] = T | Collection[T]
 type MaybeIterable[T] = T | Iterable[T]
-type IterableHashable[T: Hashable] = tuple[T, ...] | frozenset[T]
 type MaybeList[T] = T | list[T]
-type MaybeListStr = MaybeList[str]
-type MaybeSequence[T] = T | Sequence[T]
-type MaybeIterableHashable[T: Hashable] = T | IterableHashable[T]
+type MaybeSet[T] = T | set[T] | frozenset[T]
+type SequenceLT[T] = list[T] | tuple[T, ...]
+# iterables - dervied
+type MaybeSequence[T] = T | SequenceLT[T]
+type SequenceStr = SequenceLT[str]
+type CollectionStr = dict[str, Any] | frozenset[str] | set[str] | SequenceStr
+# iterables - maybe str
+type MaybeCollectionStr = str | CollectionStr
+type MaybeSequenceStr = str | SequenceStr
 
 
 # logging
 type LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
-type LoggerOrName = MaybeStr[Logger]
+type LoggerLike = MaybeStr[Logger]
 
 
 # math
@@ -204,8 +219,8 @@ type SerializeObjectExtra = Mapping[Any, Callable[[Any], str]]
 
 
 # pathlib
-type MaybeCallablePathLike = MaybeCallable[PathLike]
 type PathLike = MaybeStr[Path]
+type MaybeCallablePathLike = MaybeCallable[PathLike]
 
 
 # random
@@ -216,11 +231,24 @@ type Seed = int | float | str | bytes | bytearray | Random
 type PatternLike = MaybeStr[Pattern[str]]
 
 
+# retry
+type Retry = tuple[int, Delta | None]
+
+
+# text
+type MaybeCallableStr = MaybeCallable[str]
+
+
 # traceback
 type ExcInfo = tuple[type[BaseException], BaseException, TracebackType]
 type OptExcInfo = ExcInfo | tuple[None, None, None]
 
 
+# uuid
+type UUIDLike = MaybeStr[UUID]
+type MaybeCallableUUIDLike = MaybeCallable[UUIDLike | Seed]
+
+
 # whenever
 type DateDeltaLike = MaybeStr[DateDelta]
 type DateLike = MaybeStr[Date]
@@ -230,8 +258,9 @@ type DateTimeRoundMode = Literal[
     "ceil", "floor", "half_ceil", "half_floor", "half_even"
 ]
 type Delta = DateDelta | TimeDelta | DateTimeDelta
-type MaybeCallableDate = MaybeCallable[Date]
-type MaybeCallableZonedDateTime = MaybeCallable[ZonedDateTime]
+type MaybeCallableDateLike = MaybeCallable[DateLike]
+type MaybeCallableTimeLike = MaybeCallable[TimeLike]
+type MaybeCallableZonedDateTimeLike = MaybeCallable[ZonedDateTimeLike]
 type MonthDayLike = MaybeStr[MonthDay]
 type PlainDateTimeLike = MaybeStr[PlainDateTime]
 type TimeDeltaLike = MaybeStr[TimeDelta]
@@ -248,12 +277,21 @@ 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
+TIME_ZONES: list[TimeZone] = list(get_args(TimeZone.__value__))
+
+
 type TimeZoneLike = (
-    ZoneInfo | ZonedDateTime | Literal["local"] | TimeZone | dt.tzinfo | dt.datetime
+    ZoneInfo
+    | ZonedDateTime
+    | Literal["local", "localtime"]
+    | TimeZone
+    | dt.tzinfo
+    | dt.datetime
 )
 
 
 __all__ = [
+    "TIME_ZONES",
     "Coro",
     "Dataclass",
     "DateDeltaLike",
@@ -264,24 +302,28 @@ __all__ = [
     "Delta",
     "EnumLike",
     "ExcInfo",
+    "ExceptionTypeLike",
     "IPv4AddressLike",
     "IPv6AddressLike",
-    "IterableHashable",
     "LogLevel",
-    "LoggerOrName",
+    "LoggerLike",
     "MathRoundMode",
     "MaybeCallable",
-    "MaybeCallableBool",
-    "MaybeCallableDate",
-    "MaybeCallableEvent",
+    "MaybeCallableBoolLike",
+    "MaybeCallableDateLike",
     "MaybeCallablePathLike",
-    "MaybeCallableZonedDateTime",
+    "MaybeCallableStr",
+    "MaybeCallableTimeLike",
+    "MaybeCallableUUIDLike",
+    "MaybeCallableZonedDateTimeLike",
+    "MaybeCollection",
+    "MaybeCollectionStr",
     "MaybeCoro",
     "MaybeIterable",
-    "MaybeIterableHashable",
     "MaybeList",
-    "MaybeListStr",
     "MaybeSequence",
+    "MaybeSequenceStr",
+    "MaybeSet",
     "MaybeStr",
     "MaybeType",
     "MonthDayLike",
@@ -294,7 +336,9 @@ __all__ = [
     "PathLike",
     "PatternLike",
     "PlainDateTimeLike",
+    "Retry",
     "Seed",
+    "SequenceStr",
     "SerializeObjectExtra",
     "Sign",
     "StrMapping",
@@ -304,6 +348,7 @@ __all__ = [
     "SupportsBytes",
     "SupportsComplex",
     "SupportsFloat",
+    "SupportsFloatOrIndex",
     "SupportsGT",
     "SupportsInt",
     "SupportsInt",
@@ -318,6 +363,7 @@ __all__ = [
     "TimeZoneLike",
     "TupleOrStrMapping",
     "TypeLike",
+    "UUIDLike",
     "WeekDay",
     "YearMonthLike",
     "ZonedDateTimeLike",