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

utilities/dataclasses.py

@@ -3,16 +3,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from contextlib import suppress
 from dataclasses import MISSING, dataclass, field, fields, replace
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Generic,
-    Literal,
-    TypeVar,
-    assert_never,
-    overload,
-    override,
-)
+from typing import TYPE_CHECKING, Any, Literal, assert_never, overload, override
 
 from utilities.errors import ImpossibleCaseError
 from utilities.functions import (
@@ -43,30 +34,23 @@ from utilities.text import (
     _SplitKeyValuePairsSplitError,
     split_key_value_pairs,
 )
-from utilities.types import (
-    ParseObjectExtra,
-    SerializeObjectExtra,
-    StrStrMapping,
-    TDataclass,
-    TSupportsLT,
-)
+from utilities.types import SupportsLT
 from utilities.typing import get_type_hints
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
     from collections.abc import Set as AbstractSet
 
-    from utilities.types import Dataclass, StrMapping
-
-
-_T = TypeVar("_T")
-_U = TypeVar("_U")
-
-
-##
+    from utilities.types import (
+        Dataclass,
+        ParseObjectExtra,
+        SerializeObjectExtra,
+        StrMapping,
+        StrStrMapping,
+    )
 
 
-def dataclass_repr(
+def dataclass_repr[T](
     obj: Dataclass,
     /,
     *,
@@ -77,7 +61,7 @@ def dataclass_repr(
     exclude: Iterable[str] | None = None,
     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,
     defaults: bool = False,
     recursive: bool = False,
 ) -> str:
@@ -145,7 +129,7 @@ def dataclass_repr(
 ##
 
 
-def dataclass_to_dict(
+def dataclass_to_dict[T](
     obj: Dataclass,
     /,
     *,
@@ -156,7 +140,7 @@ def dataclass_to_dict(
     exclude: Iterable[str] | None = None,
     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,
     defaults: bool = False,
     final: Callable[[type[Dataclass], StrMapping], StrMapping] | None = None,
     recursive: bool = False,
@@ -221,7 +205,7 @@ def dataclass_to_dict(
 ##
 
 
-def is_nullable_lt(x: TSupportsLT | None, y: TSupportsLT | None, /) -> bool | None:
+def is_nullable_lt[T: SupportsLT](x: T | None, y: T | None, /) -> bool | None:
     """Compare two nullable fields."""
     match cmp_nullable(x, y):
         case 1:
@@ -237,8 +221,8 @@ def is_nullable_lt(x: TSupportsLT | None, y: TSupportsLT | None, /) -> bool | No
 ##
 
 
-def mapping_to_dataclass(
-    cls: type[TDataclass],
+def mapping_to_dataclass[T: Dataclass](
+    cls: type[T],
     mapping: StrMapping,
     /,
     *,
@@ -249,7 +233,7 @@ def mapping_to_dataclass(
     head: bool = False,
     case_sensitive: bool = False,
     allow_extra: bool = False,
-) -> TDataclass:
+) -> T:
     """Construct a dataclass from a mapping."""
     if fields is None:
         fields_use = list(
@@ -302,12 +286,12 @@ def mapping_to_dataclass(
 
 
 @dataclass(kw_only=True, slots=True)
-class MappingToDataclassError(Exception, Generic[TDataclass]):
-    cls: type[TDataclass]
+class MappingToDataclassError[T: Dataclass](Exception):
+    cls: type[T]
 
 
 @dataclass(kw_only=True, slots=True)
-class _MappingToDataClassEmptyError(MappingToDataclassError[TDataclass]):
+class _MappingToDataClassEmptyError(MappingToDataclassError):
     key: str
     head: bool = False
     case_sensitive: bool = False
@@ -320,7 +304,7 @@ class _MappingToDataClassEmptyError(MappingToDataclassError[TDataclass]):
 
 
 @dataclass(kw_only=True, slots=True)
-class _MappingToDataClassNonUniqueError(MappingToDataclassError[TDataclass]):
+class _MappingToDataClassNonUniqueError(MappingToDataclassError):
     key: str
     head: bool = False
     case_sensitive: bool = False
@@ -340,7 +324,7 @@ class _MappingToDataClassNonUniqueError(MappingToDataclassError[TDataclass]):
 
 
 @dataclass(kw_only=True, slots=True)
-class _MappingToDataClassMissingValuesError(MappingToDataclassError[TDataclass]):
+class _MappingToDataClassMissingValuesError(MappingToDataclassError):
     fields: AbstractSet[str]
 
     @override
@@ -396,15 +380,15 @@ def one_field(
 
 
 @dataclass(kw_only=True, slots=True)
-class OneFieldError(Exception, Generic[TDataclass]):
-    cls: type[TDataclass]
+class OneFieldError[T: Dataclass](Exception):
+    cls: type[T]
     key: str
     head: bool = False
     case_sensitive: bool = False
 
 
 @dataclass(kw_only=True, slots=True)
-class _OneFieldEmptyError(OneFieldError[TDataclass]):
+class _OneFieldEmptyError(OneFieldError):
     @override
     def __str__(self) -> str:
         return _empty_error_str(
@@ -413,7 +397,7 @@ class _OneFieldEmptyError(OneFieldError[TDataclass]):
 
 
 @dataclass(kw_only=True, slots=True)
-class _OneFieldNonUniqueError(OneFieldError[TDataclass]):
+class _OneFieldNonUniqueError(OneFieldError):
     first: str
     second: str
 
@@ -434,19 +418,19 @@ class _OneFieldNonUniqueError(OneFieldError[TDataclass]):
 
 @overload
 def replace_non_sentinel(
-    obj: Any, /, *, in_place: Literal[True], **kwargs: Any
+    obj: Dataclass, /, *, in_place: Literal[True], **kwargs: Any
 ) -> None: ...
 @overload
-def replace_non_sentinel(
-    obj: TDataclass, /, *, in_place: Literal[False] = False, **kwargs: Any
-) -> TDataclass: ...
+def replace_non_sentinel[T: Dataclass](
+    obj: T, /, *, in_place: Literal[False] = False, **kwargs: Any
+) -> T: ...
 @overload
-def replace_non_sentinel(
-    obj: TDataclass, /, *, in_place: bool = False, **kwargs: Any
-) -> TDataclass | None: ...
-def replace_non_sentinel(
-    obj: TDataclass, /, *, in_place: bool = False, **kwargs: Any
-) -> TDataclass | None:
+def replace_non_sentinel[T: Dataclass](
+    obj: T, /, *, in_place: bool = False, **kwargs: Any
+) -> T | None: ...
+def replace_non_sentinel[T: Dataclass](
+    obj: T, /, *, in_place: bool = False, **kwargs: Any
+) -> T | None:
     """Replace attributes on a dataclass, filtering out sentinel values."""
     if in_place:
         for k, v in kwargs.items():
@@ -461,7 +445,7 @@ def replace_non_sentinel(
 ##
 
 
-def serialize_dataclass(
+def serialize_dataclass[T](
     obj: Dataclass,
     /,
     *,
@@ -472,7 +456,7 @@ def serialize_dataclass(
     exclude: Iterable[str] | None = None,
     rel_tol: float | None = None,
     abs_tol: float | None = None,
-    extra_equal: Mapping[type[_U], Callable[[_U, _U], bool]] | None = None,
+    extra_equal: Mapping[type[T], Callable[[T, T], bool]] | None = None,
     defaults: bool = False,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
@@ -508,9 +492,9 @@ def serialize_dataclass(
     )
 
 
-def parse_dataclass(
+def parse_dataclass[T: Dataclass](
     text_or_mapping: str | StrStrMapping,
-    cls: type[TDataclass],
+    cls: type[T],
     /,
     *,
     list_separator: str = LIST_SEPARATOR,
@@ -523,7 +507,7 @@ def parse_dataclass(
     case_sensitive: bool = False,
     allow_extra_keys: bool = False,
     extra_parsers: ParseObjectExtra | None = None,
-) -> TDataclass:
+) -> T:
     """Construct a dataclass from a string or a mapping or strings."""
     match text_or_mapping:
         case str() as text:
@@ -597,9 +581,9 @@ def parse_dataclass(
         raise _ParseDataClassMissingValuesError(cls=cls, fields=error.fields) from None
 
 
-def _parse_dataclass_split_key_value_pairs(
+def _parse_dataclass_split_key_value_pairs[T: Dataclass](
     text: str,
-    cls: type[TDataclass],
+    cls: type[T],
     /,
     *,
     list_separator: str = LIST_SEPARATOR,
@@ -657,12 +641,12 @@ def _parse_dataclass_parse_text(
 
 
 @dataclass(kw_only=True, slots=True)
-class ParseDataClassError(Exception, Generic[TDataclass]):
-    cls: type[TDataclass]
+class ParseDataClassError[T: Dataclass](Exception):
+    cls: type[T]
 
 
 @dataclass(kw_only=True, slots=True)
-class _ParseDataClassSplitKeyValuePairsSplitError(ParseDataClassError[TDataclass]):
+class _ParseDataClassSplitKeyValuePairsSplitError(ParseDataClassError):
     text: str
 
     @override
@@ -671,9 +655,7 @@ class _ParseDataClassSplitKeyValuePairsSplitError(ParseDataClassError[TDataclass
 
 
 @dataclass(kw_only=True, slots=True)
-class _ParseDataClassSplitKeyValuePairsDuplicateKeysError(
-    ParseDataClassError[TDataclass]
-):
+class _ParseDataClassSplitKeyValuePairsDuplicateKeysError(ParseDataClassError):
     counts: Mapping[str, int]
 
     @override
@@ -682,7 +664,7 @@ class _ParseDataClassSplitKeyValuePairsDuplicateKeysError(
 
 
 @dataclass(kw_only=True, slots=True)
-class _ParseDataClassTextParseError(ParseDataClassError[TDataclass]):
+class _ParseDataClassTextParseError(ParseDataClassError):
     field: _YieldFieldsClass[Any]
     text: str
 
@@ -692,7 +674,7 @@ class _ParseDataClassTextParseError(ParseDataClassError[TDataclass]):
 
 
 @dataclass(kw_only=True, slots=True)
-class _ParseDataClassTextExtraNonUniqueError(ParseDataClassError[TDataclass]):
+class _ParseDataClassTextExtraNonUniqueError(ParseDataClassError):
     field: _YieldFieldsClass[Any]
     first: type[Any]
     second: type[Any]
@@ -703,9 +685,7 @@ class _ParseDataClassTextExtraNonUniqueError(ParseDataClassError[TDataclass]):
 
 
 @dataclass(kw_only=True, slots=True)
-class _ParseDataClassStrMappingToFieldMappingEmptyError(
-    ParseDataClassError[TDataclass]
-):
+class _ParseDataClassStrMappingToFieldMappingEmptyError(ParseDataClassError):
     key: str
     head: bool = False
     case_sensitive: bool = False
@@ -720,9 +700,7 @@ class _ParseDataClassStrMappingToFieldMappingEmptyError(
 
 
 @dataclass(kw_only=True, slots=True)
-class _ParseDataClassStrMappingToFieldMappingNonUniqueError(
-    ParseDataClassError[TDataclass]
-):
+class _ParseDataClassStrMappingToFieldMappingNonUniqueError(ParseDataClassError):
     key: str
     head: bool = False
     case_sensitive: bool = False
@@ -743,7 +721,7 @@ class _ParseDataClassStrMappingToFieldMappingNonUniqueError(
 
 
 @dataclass(kw_only=True, slots=True)
-class _ParseDataClassMissingValuesError(ParseDataClassError[TDataclass]):
+class _ParseDataClassMissingValuesError(ParseDataClassError):
     fields: AbstractSet[str]
 
     @override
@@ -755,9 +733,9 @@ class _ParseDataClassMissingValuesError(ParseDataClassError[TDataclass]):
 ##
 
 
-def str_mapping_to_field_mapping(
-    cls: type[TDataclass],
-    mapping: Mapping[str, _T],
+def str_mapping_to_field_mapping[T: Dataclass, U](
+    cls: type[T],
+    mapping: Mapping[str, U],
     /,
     *,
     fields: Iterable[_YieldFieldsClass[Any]] | None = None,
@@ -767,7 +745,7 @@ def str_mapping_to_field_mapping(
     head: bool = False,
     case_sensitive: bool = False,
     allow_extra: bool = False,
-) -> Mapping[_YieldFieldsClass[Any], _T]:
+) -> Mapping[_YieldFieldsClass[Any], U]:
     """Convert a string-mapping into a field-mapping."""
     keys_to_fields: Mapping[str, _YieldFieldsClass[Any]] = {}
     for key in mapping:
@@ -800,8 +778,8 @@ def str_mapping_to_field_mapping(
 
 
 @dataclass(kw_only=True, slots=True)
-class StrMappingToFieldMappingError(Exception, Generic[TDataclass]):
-    cls: type[TDataclass]
+class StrMappingToFieldMappingError[T: Dataclass](Exception):
+    cls: type[T]
     key: str
     head: bool = False
     case_sensitive: bool = False
@@ -913,12 +891,12 @@ def yield_fields(
 
 
 @dataclass(order=True, unsafe_hash=True, kw_only=True, slots=True)
-class _YieldFieldsInstance(Generic[_T]):
+class _YieldFieldsInstance[T]:
     name: str
-    value: _T = field(hash=False)
+    value: T = field(hash=False)
     type_: Any = field(hash=False)
-    default: _T | Sentinel = field(default=sentinel, hash=False)
-    default_factory: Callable[[], _T] | Sentinel = field(default=sentinel, hash=False)
+    default: T | Sentinel = field(default=sentinel, hash=False)
+    default_factory: Callable[[], T] | Sentinel = field(default=sentinel, hash=False)
     repr: bool = True
     hash_: bool | None = None
     init: bool = True
@@ -926,12 +904,12 @@ class _YieldFieldsInstance(Generic[_T]):
     metadata: StrMapping = field(default_factory=dict, hash=False)
     kw_only: bool | Sentinel = sentinel
 
-    def equals_default(
+    def equals_default[U](
         self,
         *,
         rel_tol: float | None = None,
         abs_tol: float | None = None,
-        extra: Mapping[type[_U], Callable[[_U, _U], bool]] | None = None,
+        extra: Mapping[type[U], Callable[[U, U], bool]] | None = None,
     ) -> bool:
         """Check if the field value equals its default."""
         if isinstance(self.default, Sentinel) and isinstance(
@@ -954,14 +932,14 @@ class _YieldFieldsInstance(Generic[_T]):
             self.value, expected, rel_tol=rel_tol, abs_tol=abs_tol, extra=extra
         )
 
-    def keep(
+    def keep[U](
         self,
         *,
         include: Iterable[str] | None = None,
         exclude: Iterable[str] | None = None,
         rel_tol: float | None = None,
         abs_tol: float | None = None,
-        extra: Mapping[type[_U], Callable[[_U, _U], bool]] | None = None,
+        extra: Mapping[type[U], Callable[[U, U], bool]] | None = None,
         defaults: bool = False,
     ) -> bool:
         """Whether to include a field."""
@@ -974,11 +952,11 @@ class _YieldFieldsInstance(Generic[_T]):
 
 
 @dataclass(order=True, unsafe_hash=True, kw_only=True, slots=True)
-class _YieldFieldsClass(Generic[_T]):
+class _YieldFieldsClass[T]:
     name: str
     type_: Any = field(hash=False)
-    default: _T | Sentinel = field(default=sentinel, hash=False)
-    default_factory: Callable[[], _T] | Sentinel = field(default=sentinel, hash=False)
+    default: T | Sentinel = field(default=sentinel, hash=False)
+    default_factory: Callable[[], T] | Sentinel = field(default=sentinel, hash=False)
     repr: bool = True
     hash_: bool | None = None
     init: bool = True

utilities/enum.py

@@ -2,26 +2,29 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum, StrEnum
-from typing import Generic, Literal, assert_never, overload, override
+from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
 from utilities.functions import ensure_str
 from utilities.iterables import OneStrEmptyError, OneStrNonUniqueError, one_str
-from utilities.types import EnumLike, TEnum
+
+if TYPE_CHECKING:
+    from utilities.types import EnumLike
+
 
 ##
 
 
 @overload
-def ensure_enum(
-    value: None, enum: type[TEnum], /, *, case_sensitive: bool = False
+def ensure_enum[E: Enum](
+    value: None, enum: type[E], /, *, case_sensitive: bool = False
 ) -> None: ...
 @overload
-def ensure_enum(
-    value: EnumLike[TEnum], enum: type[TEnum], /, *, case_sensitive: bool = False
-) -> TEnum: ...
-def ensure_enum(
-    value: EnumLike[TEnum] | None, enum: type[TEnum], /, *, case_sensitive: bool = False
-) -> TEnum | None:
+def ensure_enum[E: Enum](
+    value: EnumLike[E], enum: type[E], /, *, case_sensitive: bool = False
+) -> E: ...
+def ensure_enum[E: Enum](
+    value: EnumLike[E] | None, enum: type[E], /, *, case_sensitive: bool = False
+) -> E | None:
     """Ensure the object is a member of the enum."""
     if value is None:
         return None
@@ -36,9 +39,9 @@ def ensure_enum(
 
 
 @dataclass(kw_only=True, slots=True)
-class EnsureEnumError(Exception, Generic[TEnum]):
-    value: EnumLike[TEnum]
-    enum: type[TEnum]
+class EnsureEnumError[E: Enum](Exception):
+    value: EnumLike[E]
+    enum: type[E]
 
 
 @dataclass(kw_only=True, slots=True)
@@ -58,9 +61,9 @@ class _EnsureEnumParseError(EnsureEnumError):
 ##
 
 
-def parse_enum(
-    value: str, enum: type[TEnum], /, *, case_sensitive: bool = False
-) -> TEnum:
+def parse_enum[E: Enum](
+    value: str, enum: type[E], /, *, case_sensitive: bool = False
+) -> E:
     """Parse a string into the enum."""
     by_name = _parse_enum_one(value, enum, "names", case_sensitive=case_sensitive)
     if not issubclass(enum, StrEnum):
@@ -99,14 +102,14 @@ def parse_enum(
 type _NamesOrValues = Literal["names", "values"]
 
 
-def _parse_enum_one(
+def _parse_enum_one[E: Enum](
     value: str,
-    enum: type[TEnum],
+    enum: type[E],
     names_or_values: _NamesOrValues,
     /,
     *,
     case_sensitive: bool = False,
-) -> TEnum | None:
+) -> E | None:
     """Pair one aspect of the enums."""
     match names_or_values:
         case "names":
@@ -132,9 +135,9 @@ def _parse_enum_one(
 
 
 @dataclass(kw_only=True, slots=True)
-class ParseEnumError(Exception, Generic[TEnum]):
+class ParseEnumError[E: Enum](Exception):
     value: str
-    enum: type[TEnum]
+    enum: type[E]
 
 
 @dataclass(kw_only=True, slots=True)