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

utilities/luigi.py

@@ -2,16 +2,7 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Literal,
-    TypeVar,
-    assert_never,
-    cast,
-    overload,
-    override,
-)
+from typing import TYPE_CHECKING, Any, Literal, assert_never, cast, overload, override
 
 import luigi
 from luigi import Parameter, PathParameter, Target, Task
@@ -27,9 +18,6 @@ if TYPE_CHECKING:
     from utilities.types import DateTimeRoundUnit, LogLevel, PathLike, ZonedDateTimeLike
 
 
-_T = TypeVar("_T")
-
-
 # parameters
 
 
@@ -40,7 +28,7 @@ class ZonedDateTimeParameter(Parameter):
     _increment: int
 
     @override
-    def __init__(
+    def __init__[T](
         self,
         default: Any = _no_value,
         is_global: bool = False,
@@ -49,7 +37,7 @@ class ZonedDateTimeParameter(Parameter):
         config_path: None = None,
         positional: bool = True,
         always_in_help: bool = False,
-        batch_method: Callable[[Iterable[_T]], _T] | None = None,
+        batch_method: Callable[[Iterable[T]], T] | None = None,
         visibility: ParameterVisibility = ParameterVisibility.PUBLIC,
         *,
         unit: DateTimeRoundUnit = "second",

utilities/memory_profiler.py

@@ -2,31 +2,19 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from functools import wraps
-from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from memory_profiler import memory_usage
-from typing_extensions import ParamSpec
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-_P = ParamSpec("_P")
-_T = TypeVar("_T")
 
-
-@dataclass(kw_only=True, slots=True)
-class Output(Generic[_T]):
-    """A function output, and its memory usage."""
-
-    value: _T
-    memory: float
-
-
-def memory_profiled(func: Callable[_P, _T], /) -> Callable[_P, Output[_T]]:
+def memory_profiled[**P, T](func: Callable[P, T], /) -> Callable[P, Output[T]]:
     """Call a function, but also profile its maximum memory usage."""
 
     @wraps(func)
-    def wrapped(*args: _P.args, **kwargs: _P.kwargs) -> Output[_T]:
+    def wrapped(*args: P.args, **kwargs: P.kwargs) -> Output[T]:
         memory, value = memory_usage(
             cast("Any", (func, args, kwargs)), max_usage=True, retval=True
         )
@@ -35,4 +23,12 @@ def memory_profiled(func: Callable[_P, _T], /) -> Callable[_P, Output[_T]]:
     return wrapped
 
 
+@dataclass(kw_only=True, slots=True)
+class Output[T]:
+    """A function output, and its memory usage."""
+
+    value: T
+    memory: float
+
+
 __all__ = ["Output", "memory_profiled"]

utilities/more_itertools.py

@@ -1,16 +1,15 @@
 from __future__ import annotations
 
 import builtins
+from collections.abc import Hashable
 from dataclasses import dataclass
 from itertools import islice
 from textwrap import indent
 from typing import (
     TYPE_CHECKING,
     Any,
-    Generic,
     Literal,
     TypeGuard,
-    TypeVar,
     assert_never,
     cast,
     overload,
@@ -24,107 +23,99 @@ from utilities.functions import get_class_name
 from utilities.iterables import OneNonUniqueError, one
 from utilities.reprlib import get_repr
 from utilities.sentinel import Sentinel, sentinel
-from utilities.types import THashable
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
 
 
-_T = TypeVar("_T")
-_U = TypeVar("_U")
-
-
-##
-
-
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U],
+    transform: Callable[[T], U],
     list: bool = False,
     unique: Literal[True],
-) -> Mapping[THashable, _U]: ...
+) -> Mapping[UH, U]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U] | None = None,
+    transform: Callable[[T], U] | None = None,
     list: bool = False,
     unique: Literal[True],
-) -> Mapping[THashable, _T]: ...
+) -> Mapping[UH, T]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U],
+    transform: Callable[[T], U],
     list: Literal[True],
-) -> Mapping[THashable, Sequence[_U]]: ...
+) -> Mapping[UH, Sequence[U]]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U],
+    transform: Callable[[T], U],
     list: bool = False,
-) -> Mapping[THashable, Iterator[_U]]: ...
+) -> Mapping[UH, Iterator[U]]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U] | None = None,
+    transform: Callable[[T], U] | None = None,
     list: Literal[True],
-) -> Mapping[THashable, Sequence[_T]]: ...
+) -> Mapping[UH, Sequence[T]]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U] | None = None,
+    transform: Callable[[T], U] | None = None,
     list: bool = False,
-) -> Mapping[THashable, Iterator[_T]]: ...
+) -> Mapping[UH, Iterator[T]]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U] | None = None,
+    transform: Callable[[T], U] | None = None,
     list: bool = False,
     unique: bool = False,
 ) -> (
-    Mapping[THashable, Iterator[_T]]
-    | Mapping[THashable, Iterator[_U]]
-    | Mapping[THashable, Sequence[_T]]
-    | Mapping[THashable, Sequence[_U]]
-    | Mapping[THashable, _T]
-    | Mapping[THashable, _U]
+    Mapping[UH, Iterator[T]]
+    | Mapping[UH, Iterator[U]]
+    | Mapping[UH, Sequence[T]]
+    | Mapping[UH, Sequence[U]]
+    | Mapping[UH, T]
+    | Mapping[UH, U]
 ): ...
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U] | None = None,
+    transform: Callable[[T], U] | None = None,
     list: bool = False,  # noqa: A002
     unique: bool = False,
 ) -> (
-    Mapping[THashable, Iterator[_T]]
-    | Mapping[THashable, Iterator[_U]]
-    | Mapping[THashable, Sequence[_T]]
-    | Mapping[THashable, Sequence[_U]]
-    | Mapping[THashable, _T]
-    | Mapping[THashable, _U]
+    Mapping[UH, Iterator[T]]
+    | Mapping[UH, Iterator[U]]
+    | Mapping[UH, Sequence[T]]
+    | Mapping[UH, Sequence[U]]
+    | Mapping[UH, T]
+    | Mapping[UH, U]
 ):
     """Bucket the values of iterable into a mapping."""
     b = bucket(iterable, func)
@@ -143,7 +134,7 @@ def bucket_mapping(
     if not unique:
         return mapping
     results = {}
-    error_no_transform: dict[THashable, tuple[_T, _T]] = {}
+    error_no_transform: dict[UH, tuple[T, T]] = {}
     for key, value in mapping.items():
         try:
             results[key] = one(value)
@@ -155,8 +146,8 @@ def bucket_mapping(
 
 
 @dataclass(kw_only=True, slots=True)
-class BucketMappingError(Exception, Generic[THashable, _U]):
-    errors: Mapping[THashable, tuple[_U, _U]]
+class BucketMappingError[K: Hashable, V](Exception):
+    errors: Mapping[K, tuple[V, V]]
 
     @override
     def __str__(self) -> str:
@@ -171,9 +162,9 @@ class BucketMappingError(Exception, Generic[THashable, _U]):
 ##
 
 
-def partition_list(
-    pred: Callable[[_T], bool], iterable: Iterable[_T], /
-) -> tuple[list[_T], list[_T]]:
+def partition_list[T](
+    pred: Callable[[T], bool], iterable: Iterable[T], /
+) -> tuple[list[T], list[T]]:
     """Partition with lists."""
     false, true = partition(pred, iterable)
     return list(false), list(true)
@@ -182,48 +173,48 @@ def partition_list(
 ##
 
 
-def partition_typeguard(
-    pred: Callable[[_T], TypeGuard[_U]], iterable: Iterable[_T], /
-) -> tuple[Iterator[_T], Iterator[_U]]:
+def partition_typeguard[T, U](
+    pred: Callable[[T], TypeGuard[U]], iterable: Iterable[T], /
+) -> tuple[Iterator[T], Iterator[U]]:
     """Partition with a typeguarded function."""
     false, true = partition(pred, iterable)
-    true = cast("Iterator[_U]", true)
+    true = cast("Iterator[U]", true)
     return false, true
 
 
 ##
 
 
-class peekable(_peekable, Generic[_T]):  # noqa: N801
+class peekable[T](_peekable):  # noqa: N801
     """Peekable which supports dropwhile/takewhile methods."""
 
-    def __init__(self, iterable: Iterable[_T], /) -> None:
+    def __init__(self, iterable: Iterable[T], /) -> None:
         super().__init__(iterable)
 
     @override
-    def __iter__(self) -> Iterator[_T]:  # pyright: ignore[reportIncompatibleMethodOverride]
+    def __iter__(self) -> Iterator[T]:  # pyright: ignore[reportIncompatibleMethodOverride]
         while bool(self):
             yield next(self)
 
     @override
-    def __next__(self) -> _T:
+    def __next__(self) -> T:
         return super().__next__()
 
-    def dropwhile(self, predicate: Callable[[_T], bool], /) -> None:
+    def dropwhile(self, predicate: Callable[[T], bool], /) -> None:
         while bool(self) and predicate(self.peek()):
             _ = next(self)
 
     @overload
-    def peek(self, *, default: Sentinel = sentinel) -> _T: ...
+    def peek(self, *, default: Sentinel = sentinel) -> T: ...
     @overload
-    def peek(self, *, default: _U) -> _T | _U: ...
+    def peek[U](self, *, default: U) -> T | U: ...
     @override
     def peek(self, *, default: Any = sentinel) -> Any:  # pyright: ignore[reportIncompatibleMethodOverride]
         if isinstance(default, Sentinel):
             return super().peek()
         return super().peek(default=default)
 
-    def takewhile(self, predicate: Callable[[_T], bool], /) -> Iterator[_T]:
+    def takewhile(self, predicate: Callable[[T], bool], /) -> Iterator[T]:
         while bool(self) and predicate(self.peek()):
             yield next(self)
 
@@ -232,11 +223,11 @@ class peekable(_peekable, Generic[_T]):  # noqa: N801
 
 
 @dataclass(kw_only=True, slots=True)
-class Split(Generic[_T]):
+class Split[T]:
     """An iterable split into head/tail."""
 
-    head: _T
-    tail: _T
+    head: T
+    tail: T
 
     @override
     def __repr__(self) -> str:
@@ -250,15 +241,15 @@ class Split(Generic[_T]):
         return f"{cls}(\n{joined}\n)"
 
 
-def yield_splits(
-    iterable: Iterable[_T],
+def yield_splits[T](
+    iterable: Iterable[T],
     head: int,
     tail: int,
     /,
     *,
     min_frac: float | None = None,
     freq: int | None = None,
-) -> Iterator[Split[Sequence[_T]]]:
+) -> Iterator[Split[Sequence[T]]]:
     """Yield the splits of an iterable."""
     it1 = _yield_splits1(iterable, head + tail)
     it2 = _yield_splits2(it1, head, tail, min_frac=min_frac)
@@ -267,9 +258,9 @@ def yield_splits(
     return islice(it3, 0, None, freq_use)
 
 
-def _yield_splits1(
-    iterable: Iterable[_T], total: int, /
-) -> Iterator[tuple[Literal["head", "body"], Sequence[_T]]]:
+def _yield_splits1[T](
+    iterable: Iterable[T], total: int, /
+) -> Iterator[tuple[Literal["head", "body"], Sequence[T]]]:
     peek = peekable(iterable)
     for i in range(1, total + 1):
         if len(result := peek[:i]) < i:
@@ -283,14 +274,14 @@ def _yield_splits1(
             break
 
 
-def _yield_splits2(
-    iterable: Iterable[tuple[Literal["head", "body"], Sequence[_T]],],
+def _yield_splits2[T](
+    iterable: Iterable[tuple[Literal["head", "body"], Sequence[T]],],
     head: int,
     tail: int,
     /,
     *,
     min_frac: float | None = None,
-) -> Iterator[tuple[Iterable[_T], int, int]]:
+) -> Iterator[tuple[Iterable[T], int, int]]:
     min_length = head if min_frac is None else min_frac * head
     for kind, window in iterable:
         len_win = len(window)
@@ -307,13 +298,13 @@ def _yield_splits2(
                 assert_never(never)
 
 
-def _yield_splits3(
-    iterable: Iterable[tuple[Iterable[_T], int, int]], /
-) -> Iterator[Split[Sequence[_T]]]:
+def _yield_splits3[T](
+    iterable: Iterable[tuple[Iterable[T], int, int]], /
+) -> Iterator[Split[Sequence[T]]]:
     for window, len_head, len_tail in iterable:
         head_win, tail_win = split_into(window, [len_head, len_tail])
         yield cast(
-            "Split[Sequence[_T]]", Split(head=list(head_win), tail=list(tail_win))
+            "Split[Sequence[T]]", Split(head=list(head_win), tail=list(tail_win))
         )
 
 

utilities/operator.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from collections.abc import Callable, Mapping, Sequence
 from collections.abc import Set as AbstractSet
 from dataclasses import asdict, dataclass
-from typing import TYPE_CHECKING, Any, TypeVar, cast, override
+from typing import TYPE_CHECKING, Any, cast, override
 
 import utilities.math
 from utilities.functions import is_dataclass_instance
@@ -13,17 +13,15 @@ from utilities.reprlib import get_repr
 if TYPE_CHECKING:
     from utilities.types import Dataclass, Number
 
-_T = TypeVar("_T")
 
-
-def is_equal(
+def is_equal[T](
     x: Any,
     y: Any,
     /,
     *,
     rel_tol: float | None = None,
     abs_tol: float | None = None,
-    extra: Mapping[type[_T], Callable[[_T, _T], bool]] | None = None,
+    extra: Mapping[type[T], Callable[[T, T], bool]] | None = None,
 ) -> bool:
     """Check if two objects are equal."""
     if type(x) is type(y):
@@ -34,8 +32,8 @@ def is_equal(
             except StopIteration:
                 pass
             else:
-                x = cast("_T", x)
-                y = cast("_T", y)
+                x = cast("T", x)
+                y = cast("T", y)
                 return cmp(x, y)
 
         # singletons

utilities/optuna.py

@@ -6,6 +6,8 @@ from typing import TYPE_CHECKING
 from optuna import create_study
 from sqlalchemy import URL
 
+from utilities.types import Dataclass
+
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
 
@@ -14,7 +16,7 @@ if TYPE_CHECKING:
     from optuna.samplers import BaseSampler
     from optuna.study import StudyDirection
 
-    from utilities.types import PathLike, TDataclass
+    from utilities.types import PathLike
 
 
 def create_sqlite_study(
@@ -45,7 +47,7 @@ def create_sqlite_study(
 ##
 
 
-def get_best_params(study: Study, cls: type[TDataclass], /) -> TDataclass:
+def get_best_params[T: Dataclass](study: Study, cls: type[T], /) -> T:
     """Get the best params as a dataclass."""
     return cls(**study.best_params)
 
@@ -53,10 +55,8 @@ def get_best_params(study: Study, cls: type[TDataclass], /) -> TDataclass:
 ##
 
 
-def make_objective(
-    suggest_params: Callable[[Trial], TDataclass],
-    objective: Callable[[TDataclass], float],
-    /,
+def make_objective[T: Dataclass](
+    suggest_params: Callable[[Trial], T], objective: Callable[[T], float], /
 ) -> Callable[[Trial], float]:
     """Make an objective given separate trialling & evaluating functions."""
 

utilities/pathlib.py

@@ -18,6 +18,7 @@ if TYPE_CHECKING:
 
     from utilities.types import MaybeCallablePathLike, PathLike
 
+
 PWD = Path.cwd()
 
 

utilities/period.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Generic, Self, TypedDict, TypeVar, override
+from typing import TYPE_CHECKING, Self, TypedDict, override
 from zoneinfo import ZoneInfo
 
 from whenever import Date, DateDelta, TimeDelta, ZonedDateTime
@@ -14,12 +14,10 @@ from utilities.zoneinfo import get_time_zone_name
 if TYPE_CHECKING:
     from utilities.types import TimeZoneLike
 
-_TPeriod = TypeVar("_TPeriod", Date, ZonedDateTime)
 
-
-class _PeriodAsDict(TypedDict, Generic[_TPeriod]):
-    start: _TPeriod
-    end: _TPeriod
+class _PeriodAsDict[T: (Date, ZonedDateTime)](TypedDict):
+    start: T
+    end: T
 
 
 @dataclass(repr=False, order=True, unsafe_hash=True, kw_only=False)
@@ -132,9 +130,9 @@ class PeriodError(Exception): ...
 
 
 @dataclass(kw_only=True, slots=True)
-class _PeriodInvalidError(PeriodError, Generic[_TPeriod]):
-    start: _TPeriod
-    end: _TPeriod
+class _PeriodInvalidError[T: (Date, ZonedDateTime)](PeriodError):
+    start: T
+    end: T
 
     @override
     def __str__(self) -> str:

utilities/polars.py

@@ -10,17 +10,7 @@ from functools import partial, reduce
 from itertools import chain, product
 from math import ceil, log
 from pathlib import Path
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Generic,
-    Literal,
-    TypeVar,
-    assert_never,
-    cast,
-    overload,
-    override,
-)
+from typing import TYPE_CHECKING, Any, Literal, assert_never, cast, overload, override
 from uuid import UUID
 from zoneinfo import ZoneInfo
 
@@ -127,7 +117,6 @@ if TYPE_CHECKING:
     from utilities.types import Dataclass, MaybeIterable, StrMapping, TimeZoneLike
 
 
-_T = TypeVar("_T")
 type ExprLike = MaybeStr[Expr]
 DatetimeHongKong = Datetime(time_zone="Asia/Hong_Kong")
 DatetimeTokyo = Datetime(time_zone="Asia/Tokyo")
@@ -286,10 +275,10 @@ def append_dataclass(df: DataFrame, obj: Dataclass, /) -> DataFrame:
 
 
 @dataclass(kw_only=True, slots=True)
-class AppendDataClassError(Exception, Generic[_T]):
-    left: AbstractSet[_T]
-    right: AbstractSet[_T]
-    extra: AbstractSet[_T]
+class AppendDataClassError[T](Exception):
+    left: AbstractSet[T]
+    right: AbstractSet[T]
+    extra: AbstractSet[T]
 
     @override
     def __str__(self) -> str:

utilities/pqdm.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from functools import partial
-from typing import TYPE_CHECKING, Any, Literal, TypeVar, assert_never
+from typing import TYPE_CHECKING, Any, Literal, assert_never
 
 from pqdm import processes, threads
 from tqdm.auto import tqdm as tqdm_auto
@@ -20,12 +20,11 @@ if TYPE_CHECKING:
     from utilities.types import Parallelism
 
 
-_T = TypeVar("_T")
 type _ExceptionBehaviour = Literal["ignore", "immediate", "deferred"]
 
 
-def pqdm_map(
-    func: Callable[..., _T],
+def pqdm_map[T](
+    func: Callable[..., T],
     /,
     *iterables: Iterable[Any],
     parallelism: Parallelism = "processes",
@@ -35,7 +34,7 @@ def pqdm_map(
     tqdm_class: tqdm_type = tqdm_auto,  # pyright: ignore[reportArgumentType]
     desc: str | None | Sentinel = sentinel,
     **kwargs: Any,
-) -> list[_T]:
+) -> list[T]:
     """Parallel map, powered by `pqdm`."""
     return pqdm_starmap(
         func,
@@ -50,8 +49,8 @@ def pqdm_map(
     )
 
 
-def pqdm_starmap(
-    func: Callable[..., _T],
+def pqdm_starmap[T](
+    func: Callable[..., T],
     iterable: Iterable[tuple[Any, ...]],
     /,
     *,
@@ -62,7 +61,7 @@ def pqdm_starmap(
     tqdm_class: tqdm_type = tqdm_auto,  # pyright: ignore[reportArgumentType]
     desc: str | None | Sentinel = sentinel,
     **kwargs: Any,
-) -> list[_T]:
+) -> list[T]:
     """Parallel starmap, powered by `pqdm`."""
     apply = partial(apply_to_varargs, func)
     n_jobs_use = get_cpu_use(n=n_jobs)