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

utilities/dataclasses.py

@@ -3,23 +3,10 @@ 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 (
-    get_class_name,
-    is_dataclass_class,
-    is_dataclass_instance,
-)
+from utilities.functions import get_class_name
 from utilities.iterables import (
     OneStrEmptyError,
     OneStrNonUniqueError,
@@ -34,7 +21,7 @@ from utilities.parse import (
     serialize_object,
 )
 from utilities.re import ExtractGroupError, extract_group
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.text import (
     BRACKETS,
     LIST_SEPARATOR,
@@ -43,30 +30,23 @@ from utilities.text import (
     _SplitKeyValuePairsSplitError,
     split_key_value_pairs,
 )
-from utilities.types import (
-    ParseObjectExtra,
-    SerializeObjectExtra,
-    StrStrMapping,
-    TDataclass,
-    TSupportsLT,
-)
-from utilities.typing import get_type_hints
+from utilities.types import MaybeType, SupportsLT
+from utilities.typing import get_type_hints, is_dataclass_class, is_dataclass_instance
 
 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 +57,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 +125,7 @@ def dataclass_repr(
 ##
 
 
-def dataclass_to_dict(
+def dataclass_to_dict[T](
     obj: Dataclass,
     /,
     *,
@@ -156,7 +136,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 +201,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:
@@ -230,15 +210,15 @@ def is_nullable_lt(x: TSupportsLT | None, y: TSupportsLT | None, /) -> bool | No
             return True
         case 0:
             return None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
 ##
 
 
-def mapping_to_dataclass(
-    cls: type[TDataclass],
+def mapping_to_dataclass[T: Dataclass](
+    cls: type[T],
     mapping: StrMapping,
     /,
     *,
@@ -249,7 +229,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(
@@ -291,8 +271,7 @@ def mapping_to_dataclass(
     default = {
         f.name
         for f in fields_use
-        if (not isinstance(f.default, Sentinel))
-        or (not isinstance(f.default_factory, Sentinel))
+        if (not is_sentinel(f.default)) or (not is_sentinel(f.default_factory))
     }
     have = set(field_names_to_values) | default
     missing = {f.name for f in fields_use} - have
@@ -302,12 +281,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 +299,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 +319,7 @@ class _MappingToDataClassNonUniqueError(MappingToDataclassError[TDataclass]):
 
 
 @dataclass(kw_only=True, slots=True)
-class _MappingToDataClassMissingValuesError(MappingToDataclassError[TDataclass]):
+class _MappingToDataClassMissingValuesError(MappingToDataclassError):
     fields: AbstractSet[str]
 
     @override
@@ -396,15 +375,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 +392,7 @@ class _OneFieldEmptyError(OneFieldError[TDataclass]):
 
 
 @dataclass(kw_only=True, slots=True)
-class _OneFieldNonUniqueError(OneFieldError[TDataclass]):
+class _OneFieldNonUniqueError(OneFieldError):
     first: str
     second: str
 
@@ -434,34 +413,32 @@ 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():
-            if not isinstance(v, Sentinel):
+            if not is_sentinel(v):
                 setattr(obj, k, v)
         return None
-    return replace(
-        obj, **{k: v for k, v in kwargs.items() if not isinstance(v, Sentinel)}
-    )
+    return replace(obj, **{k: v for k, v in kwargs.items() if not is_sentinel(v)})
 
 
 ##
 
 
-def serialize_dataclass(
+def serialize_dataclass[T](
     obj: Dataclass,
     /,
     *,
@@ -472,7 +449,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 +485,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 +500,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:
@@ -536,7 +513,7 @@ def parse_dataclass(
             )
         case Mapping() as keys_to_serializes:
             ...
-        case _ as never:
+        case never:
             assert_never(never)
     fields = list(
         yield_fields(
@@ -597,9 +574,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 +634,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 +648,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 +657,7 @@ class _ParseDataClassSplitKeyValuePairsDuplicateKeysError(
 
 
 @dataclass(kw_only=True, slots=True)
-class _ParseDataClassTextParseError(ParseDataClassError[TDataclass]):
+class _ParseDataClassTextParseError(ParseDataClassError):
     field: _YieldFieldsClass[Any]
     text: str
 
@@ -692,7 +667,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 +678,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 +693,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 +714,7 @@ class _ParseDataClassStrMappingToFieldMappingNonUniqueError(
 
 
 @dataclass(kw_only=True, slots=True)
-class _ParseDataClassMissingValuesError(ParseDataClassError[TDataclass]):
+class _ParseDataClassMissingValuesError(ParseDataClassError):
     fields: AbstractSet[str]
 
     @override
@@ -755,9 +726,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 +738,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 +771,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
@@ -855,7 +826,7 @@ def yield_fields(
     warn_name_errors: bool = False,
 ) -> Iterator[_YieldFieldsClass[Any]]: ...
 def yield_fields(
-    obj: Dataclass | type[Dataclass],
+    obj: MaybeType[Dataclass],
     /,
     *,
     globalns: StrMapping | None = None,
@@ -913,12 +884,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,25 +897,19 @@ 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(
-            self.default_factory, Sentinel
-        ):
+        if is_sentinel(self.default) and is_sentinel(self.default_factory):
             return False
-        if (not isinstance(self.default, Sentinel)) and isinstance(
-            self.default_factory, Sentinel
-        ):
+        if (not is_sentinel(self.default)) and is_sentinel(self.default_factory):
             expected = self.default
-        elif isinstance(self.default, Sentinel) and (
-            not isinstance(self.default_factory, Sentinel)
-        ):
+        elif is_sentinel(self.default) and (not is_sentinel(self.default_factory)):
             expected = self.default_factory()
         else:  # pragma: no cover
             raise ImpossibleCaseError(
@@ -954,14 +919,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 +939,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
@@ -1024,7 +989,7 @@ def _empty_error_str_core(
             return f"any field starting with {key!r}"
         case True, False:
             return f"any field starting with {key!r} (modulo case)"
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1065,7 +1030,7 @@ def _non_unique_error_str_core(
             head_msg = f"exactly one field starting with {key!r}"
         case True, False:
             head_msg = f"exactly one field starting with {key!r} (modulo case)"
-        case _ as never:
+        case never:
             assert_never(never)
     return f"{head_msg}; got {first!r}, {second!r} and perhaps more"