dycw-utilities 0.129.10__py3-none-any.whl → 0.175.17__py3-none-any.whl

utilities/math.py

@@ -8,9 +8,10 @@ from re import Match, search
 from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
 from utilities.errors import ImpossibleCaseError
+from utilities.re import ExtractGroupsError, extract_groups
 
 if TYPE_CHECKING:
-    from utilities.types import Number, RoundMode, Sign
+    from utilities.types import MathRoundMode, Number, Sign
 
 
 MIN_FLOAT32, MAX_FLOAT32 = -3.4028234663852886e38, 3.4028234663852886e38
@@ -640,7 +641,10 @@ def _is_close(
 ##
 
 
-def number_of_decimals(x: float, /, *, max_decimals: int = 20) -> int:
+MAX_DECIMALS = 10
+
+
+def number_of_decimals(x: float, /, *, max_decimals: int = MAX_DECIMALS) -> int:
     """Get the number of decimals."""
     _, frac = divmod(x, 1)
     results = (
@@ -708,7 +712,7 @@ def round_(
     x: float,
     /,
     *,
-    mode: RoundMode = "standard",
+    mode: MathRoundMode = "standard",
     rel_tol: float | None = None,
     abs_tol: float | None = None,
 ) -> int:
@@ -730,7 +734,7 @@ def round_(
                     return 0
                 case -1:
                     return floor(x)
-                case _ as never:
+                case never:
                     assert_never(never)
         case "standard-tie-floor":
             return _round_tie_standard(x, "floor", rel_tol=rel_tol, abs_tol=abs_tol)
@@ -742,13 +746,13 @@ def round_(
             )
         case "standard-tie-away-zero":
             return _round_tie_standard(x, "away-zero", rel_tol=rel_tol, abs_tol=abs_tol)
-        case _ as never:
+        case never:
             assert_never(never)
 
 
 def _round_tie_standard(
     x: float,
-    mode: RoundMode,
+    mode: MathRoundMode,
     /,
     *,
     rel_tol: float | None = None,
@@ -757,9 +761,9 @@ def _round_tie_standard(
     """Round a float to an integer using the standard method."""
     frac, _ = modf(x)
     if _is_close(abs(frac), 0.5, rel_tol=rel_tol, abs_tol=abs_tol):
-        mode_use: RoundMode = mode
+        mode_use: MathRoundMode = mode
     else:
-        mode_use: RoundMode = "standard"
+        mode_use: MathRoundMode = "standard"
     return round_(x, mode=mode_use)
 
 
@@ -775,9 +779,9 @@ def round_float_imprecisions(
 ) -> float:
     """Round a float, removing binary representation imprecisions."""
     try:
-        ((head, tail),) = _ROUND_FLOAT_IMPRECISIONS_PATTERN.findall(str(x))
-    except ValueError:
-        ((head, tail),) = _ROUND_FLOAT_IMPRECISIONS_PATTERN.findall(f"{x:.20f}")
+        head, tail = extract_groups(_ROUND_FLOAT_IMPRECISIONS_PATTERN, str(x))
+    except ExtractGroupsError:
+        head, tail = extract_groups(_ROUND_FLOAT_IMPRECISIONS_PATTERN, f"{x:.20f}")
     half = ceil(decimals / 2)
     pattern0 = search(rf"^([0-9]+?)(0{{{half},}})([0-9]+?)$", tail)
     pattern9 = search(rf"^(0*)([0-9]+?)(9{{{half},}})([0-9]+?)$", tail)
@@ -823,7 +827,7 @@ def round_to_float(
     y: float,
     /,
     *,
-    mode: RoundMode = "standard",
+    mode: MathRoundMode = "standard",
     rel_tol: float | None = None,
     abs_tol: float | None = None,
 ) -> float:
@@ -875,7 +879,7 @@ def sign(
             if is_negative(x, rel_tol=rel_tol, abs_tol=abs_tol):
                 return -1
             return 0
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -888,6 +892,7 @@ def significant_figures(x: float, /, *, n: int = 2) -> str:
 
 
 __all__ = [
+    "MAX_DECIMALS",
     "MAX_FLOAT32",
     "MAX_FLOAT64",
     "MAX_INT8",

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,14 @@
 from __future__ import annotations
 
-import builtins
+from collections.abc import Callable, 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,
@@ -23,140 +21,213 @@ from more_itertools import peekable as _peekable
 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
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
-
-
-_T = TypeVar("_T")
-_U = TypeVar("_U")
-
-
-##
+    from collections.abc import Iterable, Iterator, Mapping, Sequence
 
 
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U],
-    list: bool = False,
-    unique: Literal[True],
-) -> Mapping[THashable, _U]: ...
+    pre: None = None,
+    post: None = None,
+) -> Mapping[UH, Iterator[T]]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U] | None = None,
-    list: bool = False,
-    unique: Literal[True],
-) -> Mapping[THashable, _T]: ...
+    pre: None = None,
+    post: Literal["list"],
+) -> Mapping[UH, list[T]]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U],
-    list: Literal[True],
-) -> Mapping[THashable, Sequence[_U]]: ...
+    pre: None = None,
+    post: Literal["tuple"],
+) -> Mapping[UH, tuple[T, ...]]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U],
-    list: bool = False,
-) -> Mapping[THashable, Iterator[_U]]: ...
+    pre: None = None,
+    post: Literal["set"],
+) -> Mapping[UH, set[T]]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U] | None = None,
-    list: Literal[True],
-) -> Mapping[THashable, Sequence[_T]]: ...
+    pre: None = None,
+    post: Literal["frozenset"],
+) -> Mapping[UH, frozenset[T]]: ...
 @overload
-def bucket_mapping(
-    iterable: Iterable[_T],
-    func: Callable[[_T], THashable],
+def bucket_mapping[T, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
     /,
     *,
-    transform: Callable[[_T], _U] | None = None,
-    list: bool = False,
-) -> Mapping[THashable, Iterator[_T]]: ...
+    pre: None = None,
+    post: Literal["unique"],
+) -> 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] | None = None,
-    list: bool = False,
-    unique: bool = False,
+    pre: Callable[[T], U] | None = None,
+    post: None = None,
+) -> Mapping[UH, Iterator[U]]: ...
+@overload
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
+    /,
+    *,
+    pre: Callable[[T], U],
+    post: Literal["list"],
+) -> Mapping[UH, list[U]]: ...
+@overload
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
+    /,
+    *,
+    pre: Callable[[T], U],
+    post: Literal["tuple"],
+) -> Mapping[UH, tuple[U, ...]]: ...
+@overload
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
+    /,
+    *,
+    pre: Callable[[T], U],
+    post: Literal["set"],
+) -> Mapping[UH, set[U]]: ...
+@overload
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
+    /,
+    *,
+    pre: Callable[[T], U],
+    post: Literal["frozenset"],
+) -> Mapping[UH, frozenset[U]]: ...
+@overload
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
+    /,
+    *,
+    pre: Callable[[T], U] | None = None,
+    post: Literal["unique"],
+) -> Mapping[UH, U]: ...
+@overload
+def bucket_mapping[T, U, UH: Hashable](
+    iterable: Iterable[T],
+    func: Callable[[T], UH],
+    /,
+    *,
+    pre: Callable[[T], U] | None = None,
+    post: Literal["list", "tuple", "set", "frozenset", "unique"] | None = None,
 ) -> (
-    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, list[T]]
+    | Mapping[UH, tuple[T, ...]]
+    | Mapping[UH, set[T]]
+    | Mapping[UH, frozenset[T]]
+    | Mapping[UH, T]
+    | Mapping[UH, Iterator[U]]
+    | Mapping[UH, list[U]]
+    | Mapping[UH, tuple[U, ...]]
+    | Mapping[UH, set[U]]
+    | Mapping[UH, frozenset[U]]
+    | 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,
-    list: bool = False,  # noqa: A002
-    unique: bool = False,
+    pre: Callable[[T], U] | None = None,
+    post: Literal["list", "tuple", "set", "frozenset", "unique"] | None = None,
 ) -> (
-    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, list[T]]
+    | Mapping[UH, tuple[T, ...]]
+    | Mapping[UH, set[T]]
+    | Mapping[UH, frozenset[T]]
+    | Mapping[UH, T]
+    | Mapping[UH, Iterator[U]]
+    | Mapping[UH, list[U]]
+    | Mapping[UH, tuple[U, ...]]
+    | Mapping[UH, set[U]]
+    | Mapping[UH, frozenset[U]]
+    | Mapping[UH, U]
 ):
     """Bucket the values of iterable into a mapping."""
-    b = bucket(iterable, func)
-    mapping = {key: b[key] for key in b}
-    match transform, list:
-        case None, False:
-            ...
-        case None, True:
-            mapping = {k: builtins.list(v) for k, v in mapping.items()}
-        case _, False:
-            mapping = {k: map(transform, v) for k, v in mapping.items()}
-        case _, True:
-            mapping = {k: builtins.list(map(transform, v)) for k, v in mapping.items()}
-        case _ as never:
+    bckt = bucket(iterable, func)
+    mapping = {key: bckt[key] for key in bckt}
+    match pre, post:
+        case None, None:
+            return mapping
+        case None, "list":
+            return {k: list(v) for k, v in mapping.items()}
+        case None, "tuple":
+            return {k: tuple(v) for k, v in mapping.items()}
+        case None, "set":
+            return {k: set(v) for k, v in mapping.items()}
+        case None, "frozenset":
+            return {k: frozenset(v) for k, v in mapping.items()}
+        case None, "unique":
+            return _bucket_mapping_unique(mapping)
+        case Callable(), None:
+            return {k: map(pre, v) for k, v in mapping.items()}
+        case Callable(), "list":
+            return {k: list(map(pre, v)) for k, v in mapping.items()}
+        case Callable(), "tuple":
+            return {k: tuple(map(pre, v)) for k, v in mapping.items()}
+        case Callable(), "set":
+            return {k: set(map(pre, v)) for k, v in mapping.items()}
+        case Callable(), "frozenset":
+            return {k: frozenset(map(pre, v)) for k, v in mapping.items()}
+        case Callable(), "unique":
+            return _bucket_mapping_unique({k: map(pre, v) for k, v in mapping.items()})
+        case never:
             assert_never(never)
-    if not unique:
-        return mapping
-    results = {}
-    error_no_transform: dict[THashable, tuple[_T, _T]] = {}
+
+
+def _bucket_mapping_unique[K: Hashable, V](
+    mapping: Mapping[K, Iterable[V]], /
+) -> Mapping[K, V]:
+    results: dict[K, V] = {}
+    errors: dict[K, tuple[V, V]] = {}
     for key, value in mapping.items():
         try:
             results[key] = one(value)
         except OneNonUniqueError as error:
-            error_no_transform[key] = (error.first, error.second)
-    if len(error_no_transform) >= 1:
-        raise BucketMappingError(errors=error_no_transform)
+            errors[key] = (error.first, error.second)
+    if len(errors) >= 1:
+        raise BucketMappingError(errors=errors)
     return results
 
 
 @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 +242,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 +253,46 @@ 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)
+        return super().peek() if is_sentinel(default) else 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 +301,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 +319,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 +336,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 +352,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)
@@ -303,17 +372,17 @@ def _yield_splits2(
                 len_tail = max(len_win - head, 0)
                 if len_tail >= 1:
                     yield window, head, len_tail
-            case _ as never:
+            case never:
                 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))
         )