dycw-utilities 0.133.6__py3-none-any.whl → 0.134.0__py3-none-any.whl

utilities/atools.py

@@ -1,35 +1,32 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import TYPE_CHECKING, ParamSpec, TypeVar
+from typing import TYPE_CHECKING, Any
 
 from atools import memoize
 
-from utilities.types import Coroutine1
+from utilities.types import Coro
 
 if TYPE_CHECKING:
     from whenever import TimeDelta
 
 
-_P = ParamSpec("_P")
-_R = TypeVar("_R")
-_AsyncFunc = Callable[_P, Coroutine1[_R]]
-type _Key = tuple[_AsyncFunc, TimeDelta]
-_MEMOIZED_FUNCS: dict[_Key, _AsyncFunc] = {}
+type _Key[**P, T] = tuple[Callable[P, Coro[T]], TimeDelta]
+_MEMOIZED_FUNCS: dict[_Key, Callable[..., Coro[Any]]] = {}
 
 
-async def call_memoized(
-    func: _AsyncFunc[_P, _R],
+async def call_memoized[**P, T](
+    func: Callable[P, Coro[T]],
     refresh: TimeDelta | None = None,
     /,
-    *args: _P.args,
-    **kwargs: _P.kwargs,
-) -> _R:
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> T:
     """Call an asynchronous function, with possible memoization."""
     if refresh is None:
         return await func(*args, **kwargs)
     key: _Key = (func, refresh)
-    memoized_func: _AsyncFunc[_P, _R]
+    memoized_func: Callable[P, Coro[T]]
     try:
         memoized_func = _MEMOIZED_FUNCS[key]
     except KeyError:

utilities/cachetools.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable, Iterator, MutableSet
+from collections.abc import Callable, Hashable, Iterable, Iterator, MutableSet
 from math import inf
 from time import monotonic
-from typing import TYPE_CHECKING, Any, TypeVar, override
+from typing import TYPE_CHECKING, Any, override
 
 import cachetools
 from cachetools.func import ttl_cache
@@ -11,14 +11,8 @@ from cachetools.func import ttl_cache
 if TYPE_CHECKING:
     from whenever import TimeDelta
 
-    from utilities.types import TCallable
 
-_K = TypeVar("_K")
-_T = TypeVar("_T")
-_V = TypeVar("_V")
-
-
-class TTLCache(cachetools.TTLCache[_K, _V]):
+class TTLCache[K: Hashable, V](cachetools.TTLCache[K, V]):
     """A TTL-cache."""
 
     def __init__(
@@ -40,15 +34,15 @@ class TTLCache(cachetools.TTLCache[_K, _V]):
 ##
 
 
-class TTLSet(MutableSet[_T]):
+class TTLSet[T: Hashable](MutableSet[T]):
     """A TTL-set."""
 
-    _cache: TTLCache[_T, None]
+    _cache: TTLCache[T, None]
 
     @override
     def __init__(
         self,
-        iterable: Iterable[_T] | None = None,
+        iterable: Iterable[T] | None = None,
         /,
         *,
         max_size: int | None = None,
@@ -71,7 +65,7 @@ class TTLSet(MutableSet[_T]):
         return self._cache.__contains__(x)
 
     @override
-    def __iter__(self) -> Iterator[_T]:
+    def __iter__(self) -> Iterator[T]:
         return self._cache.__iter__()
 
     @override
@@ -87,24 +81,24 @@ class TTLSet(MutableSet[_T]):
         return set(self._cache).__str__()
 
     @override
-    def add(self, value: _T) -> None:
+    def add(self, value: T) -> None:
         self._cache[value] = None
 
     @override
-    def discard(self, value: _T) -> None:
+    def discard(self, value: T) -> None:
         del self._cache[value]
 
 
 ##
 
 
-def cache(
+def cache[F: Callable](
     *,
     max_size: int | None = None,
     max_duration: TimeDelta | None = None,
     timer: Callable[[], float] = monotonic,
     typed_: bool = False,
-) -> Callable[[TCallable], TCallable]:
+) -> Callable[[F], F]:
     """Decorate a function with `max_size` and/or `ttl` settings."""
     return ttl_cache(
         maxsize=inf if max_size is None else max_size,

utilities/click.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
+import enum
 import ipaddress
 import pathlib
-from typing import TYPE_CHECKING, Generic, TypedDict, TypeVar, assert_never, override
+from typing import TYPE_CHECKING, TypedDict, assert_never, override
 
 import click
 import whenever
@@ -15,32 +16,27 @@ from utilities.functions import EnsureStrError, ensure_str, get_class_name
 from utilities.iterables import is_iterable_not_str
 from utilities.parse import ParseObjectError, parse_object
 from utilities.text import split_str
-from utilities.types import (
-    DateDeltaLike,
-    DateLike,
-    DateTimeDeltaLike,
-    EnumLike,
-    IPv4AddressLike,
-    IPv6AddressLike,
-    MaybeStr,
-    PlainDateTimeLike,
-    TEnum,
-    TimeDeltaLike,
-    TimeLike,
-    ZonedDateTimeLike,
-)
 from utilities.whenever import FreqLike, _FreqParseError, _MonthParseCommonISOError
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
 
+    from utilities.types import (
+        DateDeltaLike,
+        DateLike,
+        DateTimeDeltaLike,
+        EnumLike,
+        IPv4AddressLike,
+        IPv6AddressLike,
+        MaybeStr,
+        PlainDateTimeLike,
+        TimeDeltaLike,
+        TimeLike,
+        ZonedDateTimeLike,
+    )
     from utilities.whenever import MonthLike
 
 
-_T = TypeVar("_T")
-_TParam = TypeVar("_TParam", bound=ParamType)
-
-
 FilePath = click.Path(file_okay=True, dir_okay=False, path_type=pathlib.Path)
 DirPath = click.Path(file_okay=False, dir_okay=True, path_type=pathlib.Path)
 ExistingFilePath = click.Path(
@@ -145,12 +141,13 @@ class DateTimeDelta(ParamType):
                 assert_never(never)
 
 
-class Enum(ParamType, Generic[TEnum]):
+class Enum[E: enum.Enum](ParamType):
     """An enum-valued parameter."""
 
-    def __init__(self, enum: type[TEnum], /, *, case_sensitive: bool = False) -> None:
+    @override
+    def __init__(self, enum: type[E], /, *, case_sensitive: bool = False) -> None:
         cls = get_class_name(enum)
-        self.name = f"ENUM[{cls}]"
+        self.name = f"enum[{cls}]"
         self._enum = enum
         self._case_sensitive = case_sensitive
         super().__init__()
@@ -162,8 +159,8 @@ class Enum(ParamType, Generic[TEnum]):
 
     @override
     def convert(
-        self, value: EnumLike[TEnum], param: Parameter | None, ctx: Context | None
-    ) -> TEnum:
+        self, value: EnumLike[E], param: Parameter | None, ctx: Context | None
+    ) -> E:
         """Convert a value into the `Enum` type."""
         try:
             return ensure_enum(value, self._enum, case_sensitive=self._case_sensitive)
@@ -180,9 +177,11 @@ class Enum(ParamType, Generic[TEnum]):
 class Freq(ParamType):
     """An frequency-valued parameter."""
 
+    name = "freq"
+
     @override
     def __repr__(self) -> str:
-        return "FREQ"
+        return self.name.upper()
 
     @override
     def convert(
@@ -380,27 +379,24 @@ class ZonedDateTime(ParamType):
 # parameters - frozenset
 
 
-class FrozenSetParameter(ParamType, Generic[_TParam, _T]):
+class FrozenSetParameter[P: ParamType, T](ParamType):
     """A frozenset-valued parameter."""
 
-    def __init__(self, param: _TParam, /, *, separator: str = ",") -> None:
-        self.name = f"FROZENSET[{param.name}]"
+    @override
+    def __init__(self, param: P, /, *, separator: str = ",") -> None:
+        self.name = f"frozenset[{param.name}]"
         self._param = param
         self._separator = separator
         super().__init__()
 
     @override
     def __repr__(self) -> str:
-        desc = repr(self._param)
-        return f"FROZENSET[{desc}]"
+        return f"FROZENSET[{self._param!r}]"
 
     @override
     def convert(
-        self,
-        value: MaybeStr[Iterable[_T]],
-        param: Parameter | None,
-        ctx: Context | None,
-    ) -> frozenset[_T]:
+        self, value: MaybeStr[Iterable[T]], param: Parameter | None, ctx: Context | None
+    ) -> frozenset[T]:
         """Convert a value into the `ListDates` type."""
         if is_iterable_not_str(value):
             return frozenset(value)
@@ -425,6 +421,7 @@ class FrozenSetParameter(ParamType, Generic[_TParam, _T]):
 class FrozenSetChoices(FrozenSetParameter[Choice, str]):
     """A frozenset-of-choices-valued parameter."""
 
+    @override
     def __init__(
         self,
         choices: Sequence[str],
@@ -438,16 +435,12 @@ class FrozenSetChoices(FrozenSetParameter[Choice, str]):
         )
 
 
-class FrozenSetEnums(FrozenSetParameter[Enum[TEnum], TEnum]):
+class FrozenSetEnums[E: enum.Enum](FrozenSetParameter[Enum[E], E]):
     """A frozenset-of-enums-valued parameter."""
 
+    @override
     def __init__(
-        self,
-        enum: type[TEnum],
-        /,
-        *,
-        case_sensitive: bool = False,
-        separator: str = ",",
+        self, enum: type[E], /, *, case_sensitive: bool = False, separator: str = ","
     ) -> None:
         super().__init__(Enum(enum, case_sensitive=case_sensitive), separator=separator)
 
@@ -455,6 +448,7 @@ class FrozenSetEnums(FrozenSetParameter[Enum[TEnum], TEnum]):
 class FrozenSetStrs(FrozenSetParameter[StringParamType, str]):
     """A frozenset-of-strs-valued parameter."""
 
+    @override
     def __init__(self, *, separator: str = ",") -> None:
         super().__init__(StringParamType(), separator=separator)
 
@@ -462,27 +456,24 @@ class FrozenSetStrs(FrozenSetParameter[StringParamType, str]):
 # parameters - list
 
 
-class ListParameter(ParamType, Generic[_TParam, _T]):
+class ListParameter[P: ParamType, T](ParamType):
     """A list-valued parameter."""
 
-    def __init__(self, param: _TParam, /, *, separator: str = ",") -> None:
-        self.name = f"LIST[{param.name}]"
+    @override
+    def __init__(self, param: P, /, *, separator: str = ",") -> None:
+        self.name = f"list[{param.name}]"
         self._param = param
         self._separator = separator
         super().__init__()
 
     @override
     def __repr__(self) -> str:
-        desc = repr(self._param)
-        return f"LIST[{desc}]"
+        return f"LIST[{self._param!r}]"
 
     @override
     def convert(
-        self,
-        value: MaybeStr[Iterable[_T]],
-        param: Parameter | None,
-        ctx: Context | None,
-    ) -> list[_T]:
+        self, value: MaybeStr[Iterable[T]], param: Parameter | None, ctx: Context | None
+    ) -> list[T]:
         """Convert a value into the `List` type."""
         if is_iterable_not_str(value):
             return list(value)
@@ -504,16 +495,29 @@ class ListParameter(ParamType, Generic[_TParam, _T]):
         return _make_metavar(param, desc)
 
 
-class ListEnums(ListParameter[Enum[TEnum], TEnum]):
-    """A list-of-enums-valued parameter."""
+class ListChoices(ListParameter[Choice, str]):
+    """A frozenset-of-choices-valued parameter."""
 
+    @override
     def __init__(
         self,
-        enum: type[TEnum],
+        choices: Sequence[str],
         /,
         *,
         case_sensitive: bool = False,
         separator: str = ",",
+    ) -> None:
+        super().__init__(
+            Choice(choices, case_sensitive=case_sensitive), separator=separator
+        )
+
+
+class ListEnums[E: enum.Enum](ListParameter[Enum[E], E]):
+    """A list-of-enums-valued parameter."""
+
+    @override
+    def __init__(
+        self, enum: type[E], /, *, case_sensitive: bool = False, separator: str = ","
     ) -> None:
         super().__init__(Enum(enum, case_sensitive=case_sensitive), separator=separator)
 
@@ -521,6 +525,7 @@ class ListEnums(ListParameter[Enum[TEnum], TEnum]):
 class ListStrs(ListParameter[StringParamType, str]):
     """A list-of-strs-valued parameter."""
 
+    @override
     def __init__(self, *, separator: str = ",") -> None:
         super().__init__(StringParamType(), separator=separator)
 
@@ -550,6 +555,7 @@ __all__ = [
     "FrozenSetStrs",
     "IPv4Address",
     "IPv6Address",
+    "ListChoices",
     "ListEnums",
     "ListParameter",
     "ListStrs",

utilities/concurrent.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
 from functools import partial
-from typing import TYPE_CHECKING, Any, TypeVar, assert_never
+from typing import TYPE_CHECKING, Any, assert_never
 
 from utilities.iterables import apply_to_tuple
 from utilities.os import get_cpu_use
@@ -15,11 +15,8 @@ if TYPE_CHECKING:
     from utilities.os import IntOrAll
 
 
-_T = TypeVar("_T")
-
-
-def concurrent_map(
-    func: Callable[..., _T],
+def concurrent_map[T](
+    func: Callable[..., T],
     /,
     *iterables: Iterable[Any],
     parallelism: Parallelism = "processes",
@@ -31,7 +28,7 @@ def concurrent_map(
     thread_name_prefix: str = "",
     timeout: float | None = None,
     chunksize: int = 1,
-) -> list[_T]:
+) -> list[T]:
     """Concurrent map."""
     return concurrent_starmap(
         func,
@@ -51,8 +48,8 @@ def concurrent_map(
 ##
 
 
-def concurrent_starmap(
-    func: Callable[..., _T],
+def concurrent_starmap[T](
+    func: Callable[..., T],
     iterable: Iterable[tuple[Any, ...]],
     /,
     *,
@@ -65,7 +62,7 @@ def concurrent_starmap(
     thread_name_prefix: str = "",
     timeout: float | None = None,
     chunksize: int = 1,
-) -> list[_T]:
+) -> list[T]:
     """Concurrent map."""
     max_workers_use = get_cpu_use(n=max_workers)
     apply = partial(apply_to_tuple, func)