dycw-utilities 0.108.4__py3-none-any.whl → 0.109.1__py3-none-any.whl

{dycw_utilities-0.108.4.dist-info → dycw_utilities-0.109.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.108.4
+Version: 0.109.1
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.108.4.dist-info → dycw_utilities-0.109.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=-2lmFv1UZnPQpN8IvJ-ViPH2DA03IC4wyaSgQYQI0zc,60
+utilities/__init__.py,sha256=hXFp40lgEbzHJocIbjY5_v_hKGMzhE6Os9g06SFuZME,60
 utilities/altair.py,sha256=NSyDsm8QlkAGmsGdxVwCkHnPxt_35yJBa9Lg7bz9Ays,9054
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
 utilities/asyncio.py,sha256=41oQUurWMvadFK5gFnaG21hMM0Vmfn2WS6OpC0R9mas,14757
@@ -11,7 +11,7 @@ utilities/contextlib.py,sha256=OOIIEa5lXKGzFAnauaul40nlQnQko6Na4ryiMJcHkIg,478
 utilities/contextvars.py,sha256=RsSGGrbQqqZ67rOydnM7WWIsM2lIE31UHJLejnHJPWY,505
 utilities/cryptography.py,sha256=HyOewI20cl3uRXsKivhIaeLVDInQdzgXZGaly7hS5dE,771
 utilities/cvxpy.py,sha256=Rv1-fD-XYerosCavRF8Pohop2DBkU3AlFaGTfD8AEAA,13776
-utilities/dataclasses.py,sha256=SOWaLVMK6p_HTMPhiXtgCk5F1KGiY8wNxQkYRBz1dVg,18683
+utilities/dataclasses.py,sha256=12Cxq0ZXFuc4lPD6Y92Ny-b25C0EnkAZ3Hz59tetcbQ,21709
 utilities/datetime.py,sha256=GOs-MIEW_A49kzqa1yhIoeNeSqqPVgGO-h2AThtgTDk,37326
 utilities/enum.py,sha256=HoRwVCWzsnH0vpO9ZEcAAIZLMv0Sn2vJxxA4sYMQgDs,5793
 utilities/errors.py,sha256=BtSNP0JC3ik536ddPyTerLomCRJV9f6kdMe6POz0QHM,361
@@ -40,12 +40,12 @@ utilities/operator.py,sha256=0M2yZJ0PODH47ogFEnkGMBe_cfxwZR02T_92LZVZvHo,3715
 utilities/optuna.py,sha256=loyJGWTzljgdJaoLhP09PT8Jz6o_pwBOwehY33lHkhw,1923
 utilities/orjson.py,sha256=DW5pOpMyrR5Q8caQYly9AqRPazDBqrWv5GRWfULqka4,36291
 utilities/os.py,sha256=D_FyyT-6TtqiN9KSS7c9g1fnUtgxmyMtzAjmYLkk46A,3587
-utilities/parse.py,sha256=vKVWIqR5JykQzPSnMHQr7_h43M6TwfYEnPmjmbgSA-o,4585
+utilities/parse.py,sha256=yLLH51VNwmcWbEvwqh6M-weWt7NIayd7No67Oe80S3k,4585
 utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=ikHXsWtDLr553cfH6p9mMaiCnIAP69B7q84ckWV3HaA,10884
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
 utilities/platform.py,sha256=NU7ycTvAXAG-fdYmDXaM1m4EOml2cGiaYwaUzfzSqyU,1767
-utilities/polars.py,sha256=ENkJunh7goUT0IOQ9LFbh-AFj7plC5ePKHBsnXk6slo,52122
+utilities/polars.py,sha256=ZXiHLkn6CbRh0_e0db5KRjHPU0LAedwzGno7k9fsiIo,48917
 utilities/pqdm.py,sha256=foRytQybmOQ05pjt5LF7ANyzrIa--4ScDE3T2wd31a4,3118
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 utilities/pydantic.py,sha256=f6qtR5mO2YMuyvNmbaEj5YeD9eGA4YYfb7Bjzh9jUs0,1845
@@ -53,7 +53,7 @@ utilities/pyinstrument.py,sha256=ROq2txPwbe2ZUuYJ2IDNbfT97lu2ca0v5_C_yn6sSlM,800
 utilities/pyrsistent.py,sha256=TLJfiiKO4cKNU_pCoM3zDqmSM421qpuoaeaBNnyC_Ac,2489
 utilities/pytest.py,sha256=85QUax4g2VBBAqAHtM9wekcSLB7_9O8AKFTaCshztL8,7989
 utilities/pytest_regressions.py,sha256=Kp1NS_cyXvBFqyiF_oSzYmSJzIOdAZ0SFcSGmbL_UtI,5001
-utilities/python_dotenv.py,sha256=7N4ZbBxXpPNttOTfg-hpaLFFWA5iJwF7tREBzUnbPOM,3415
+utilities/python_dotenv.py,sha256=-d2bQ3Ayyv9JUK59k6F3-mTzQmb2SV0HzqG9fpsD8C8,2976
 utilities/random.py,sha256=lYdjgxB7GCfU_fwFVl5U-BIM_HV3q6_urL9byjrwDM8,4157
 utilities/re.py,sha256=5J4d8VwIPFVrX2Eb8zfoxImDv7IwiN_U7mJ07wR2Wvs,3958
 utilities/redis.py,sha256=CsDQqc9V6ASLzLQwtbQXZQEndyG9pJiCOhPlPeszt7Y,21203
@@ -84,7 +84,7 @@ utilities/warnings.py,sha256=yUgjnmkCRf6QhdyAXzl7u0qQFejhQG3PrjoSwxpbHrs,1819
 utilities/whenever.py,sha256=5x2t47VJmJRWcd_NLFy54NkB3uom-XQYxEbLtEfL1bs,17775
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-DQz5a0Ikw9jfSZtL0BEQkXOMC9yGn_xiJYNCLMiqEc,1989
-dycw_utilities-0.108.4.dist-info/METADATA,sha256=rAF0wyx5NT-CYkx5Meatz3jzjaRSMeBHx6mSCdfBcM8,13004
-dycw_utilities-0.108.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.108.4.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.108.4.dist-info/RECORD,,
+dycw_utilities-0.109.1.dist-info/METADATA,sha256=dCcv9ZcxodWQ1Ze4u30ZUglTEC7NipHnFMOMN9zv6Oc,13004
+dycw_utilities-0.109.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.109.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.109.1.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.108.4"
+__version__ = "0.109.1"

utilities/dataclasses.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
+from collections.abc import Set as AbstractSet
 from dataclasses import MISSING, dataclass, field, fields, replace
 from typing import (
     TYPE_CHECKING,
@@ -22,7 +23,6 @@ from utilities.functions import (
 from utilities.iterables import OneStrEmptyError, OneStrNonUniqueError, one_str
 from utilities.operator import is_equal
 from utilities.parse import ParseTextError, parse_text
-from utilities.reprlib import get_repr
 from utilities.sentinel import Sentinel, sentinel
 from utilities.types import TDataclass
 from utilities.typing import get_type_hints
@@ -186,76 +186,140 @@ def mapping_to_dataclass(
     mapping: StrMapping,
     /,
     *,
+    fields: Iterable[_YieldFieldsClass[Any]] | None = None,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    head: bool = False,
     case_sensitive: bool = False,
-    post: Callable[[_YieldFieldsClass[Any], Any], Any] | None = None,
+    allow_extra: bool = False,
 ) -> TDataclass:
     """Construct a dataclass from a mapping."""
-    fields = yield_fields(cls, globalns=globalns, localns=localns)
-    mapping_use = {
-        f.name: _mapping_to_dataclass_one(
-            f, mapping, case_sensitive=case_sensitive, post=post
-        )
-        for f in fields
+    if fields is None:
+        fields_use = list(yield_fields(cls, globalns=globalns, localns=localns))
+    else:
+        fields_use = fields
+    fields_to_values = str_mapping_to_field_mapping(
+        cls,
+        mapping,
+        fields=fields_use,
+        globalns=globalns,
+        localns=localns,
+        head=head,
+        case_sensitive=case_sensitive,
+        allow_extra=allow_extra,
+    )
+    field_names_to_values = {f.name: v for f, v in fields_to_values.items()}
+    default = {
+        f.name
+        for f in fields_use
+        if (not isinstance(f.default, Sentinel))
+        or (not isinstance(f.default_factory, Sentinel))
     }
-    return cls(**mapping_use)
+    have = set(field_names_to_values) | default
+    missing = {f.name for f in fields_use} - have
+    if len(missing) >= 1:
+        raise MappingToDataclassError(cls=cls, fields=missing)
+    return cls(**field_names_to_values)
 
 
-def _mapping_to_dataclass_one(
-    field: _YieldFieldsClass[Any],
-    mapping: StrMapping,
+@dataclass(kw_only=True, slots=True)
+class MappingToDataclassError(Exception, Generic[TDataclass]):
+    cls: type[TDataclass]
+    fields: AbstractSet[str]
+
+    @override
+    def __str__(self) -> str:
+        desc = ", ".join(map(repr, sorted(self.fields)))
+        return f"Unable to construct {get_class_name(self.cls)!r}; missing values for {desc}"
+
+
+##
+
+
+def one_field(
+    cls: type[Dataclass],
+    key: str,
     /,
     *,
+    fields: Iterable[_YieldFieldsClass[Any]] | None = None,
+    globalns: StrMapping | None = None,
+    localns: StrMapping | None = None,
+    head: bool = False,
     case_sensitive: bool = False,
-    post: Callable[[_YieldFieldsClass[Any], Any], Any] | None = None,
-) -> Any:
+) -> _YieldFieldsClass[Any]:
+    """Get the unique field a key matches to."""
+    if fields is None:
+        fields_use = list(yield_fields(cls, globalns=globalns, localns=localns))
+    else:
+        fields_use = fields
+    mapping = {f.name: f for f in fields_use}
     try:
-        key = one_str(mapping, field.name, case_sensitive=case_sensitive)
+        name = one_str(mapping, key, head=head, case_sensitive=case_sensitive)
     except OneStrEmptyError:
-        if not isinstance(field.default, Sentinel):
-            value = field.default
-        elif not isinstance(field.default_factory, Sentinel):
-            value = field.default_factory()
-        else:
-            raise _MappingToDataclassEmptyError(
-                mapping=mapping, field=field.name, case_sensitive=case_sensitive
-            ) from None
+        raise OneFieldEmptyError(
+            cls=cls, key=key, head=head, case_sensitive=case_sensitive
+        ) from None
     except OneStrNonUniqueError as error:
-        raise _MappingToDataclassCaseInsensitiveNonUniqueError(
-            mapping=mapping, field=field.name, first=error.first, second=error.second
+        raise OneFieldNonUniqueError(
+            cls=cls,
+            key=key,
+            head=head,
+            case_sensitive=case_sensitive,
+            first=error.first,
+            second=error.second,
         ) from None
-    else:
-        value = mapping[key]
-    if post is not None:
-        value = post(field, value)
-    return value
+    return mapping[name]
 
 
 @dataclass(kw_only=True, slots=True)
-class MappingToDataclassError(Exception):
-    mapping: StrMapping
-    field: str
+class OneFieldError(Exception, Generic[TDataclass]):
+    cls: type[TDataclass]
+    key: str
+    head: bool = False
+    case_sensitive: bool = False
 
 
 @dataclass(kw_only=True, slots=True)
-class _MappingToDataclassEmptyError(MappingToDataclassError):
-    case_sensitive: bool = False
-
+class OneFieldEmptyError(OneFieldError[TDataclass]):
     @override
     def __str__(self) -> str:
-        desc = f"Mapping {get_repr(self.mapping)} does not contain {self.field!r}"
-        return desc if self.case_sensitive else f"{desc} (modulo case)"
+        head = f"Dataclass {get_class_name(self.cls)!r} does not contain"
+        match self.head, self.case_sensitive:
+            case False, True:
+                tail = f"a field {self.key!r}"
+            case False, False:
+                tail = f"a field {self.key!r} (modulo case)"
+            case True, True:
+                tail = f"any field starting with {self.key!r}"
+            case True, False:
+                tail = f"any field starting with {self.key!r} (modulo case)"
+            case _ as never:
+                assert_never(never)
+        return f"{head} {tail}"
 
 
 @dataclass(kw_only=True, slots=True)
-class _MappingToDataclassCaseInsensitiveNonUniqueError(MappingToDataclassError):
+class OneFieldNonUniqueError(OneFieldError[TDataclass]):
     first: str
     second: str
 
     @override
     def __str__(self) -> str:
-        return f"Mapping {get_repr(self.mapping)} must contain {self.field!r} exactly once (modulo case); got {self.first!r}, {self.second!r} and perhaps more"
+        head = f"Dataclass {get_class_name(self.cls)!r} must contain"
+        match self.head, self.case_sensitive:
+            case False, True:
+                raise ImpossibleCaseError(  # pragma: no cover
+                    case=[f"{self.head=}", f"{self.case_sensitive=}"]
+                )
+            case False, False:
+                mid = f"field {self.key!r} exactly once (modulo case)"
+            case True, True:
+                mid = f"exactly one field starting with {self.key!r}"
+            case True, False:
+                mid = f"exactly one field starting with {self.key!r} (modulo case)"
+            case _ as never:
+                assert_never(never)
+        return f"{head} {mid}; got {self.first!r}, {self.second!r} and perhaps more"
 
 
 ##
@@ -290,6 +354,66 @@ def replace_non_sentinel(
 ##
 
 
+def str_mapping_to_field_mapping(
+    cls: type[TDataclass],
+    mapping: Mapping[str, _T],
+    /,
+    *,
+    fields: Iterable[_YieldFieldsClass[Any]] | None = None,
+    globalns: StrMapping | None = None,
+    localns: StrMapping | None = None,
+    head: bool = False,
+    case_sensitive: bool = False,
+    allow_extra: bool = False,
+) -> Mapping[_YieldFieldsClass[Any], _T]:
+    """Convert a string-mapping into a field-mapping."""
+    keys_to_fields: Mapping[str, _YieldFieldsClass[Any]] = {}
+    for key in mapping:
+        try:
+            keys_to_fields[key] = one_field(
+                cls,
+                key,
+                fields=fields,
+                globalns=globalns,
+                localns=localns,
+                head=head,
+                case_sensitive=case_sensitive,
+            )
+        except OneFieldEmptyError:
+            if not allow_extra:
+                raise StrMappingToFieldMappingError(
+                    cls=cls, key=key, head=head, case_sensitive=case_sensitive
+                ) from None
+    return {field: mapping[key] for key, field in keys_to_fields.items()}
+
+
+@dataclass(kw_only=True, slots=True)
+class StrMappingToFieldMappingError(Exception):
+    cls: type[Dataclass]
+    key: str
+    head: bool = False
+    case_sensitive: bool = False
+
+    @override
+    def __str__(self) -> str:
+        head = f"Dataclass {get_class_name(self.cls)!r} does not contain"
+        match self.head, self.case_sensitive:
+            case False, True:
+                tail = f"a field {self.key!r}"
+            case False, False:
+                tail = f"a field {self.key!r} (modulo case)"
+            case True, True:
+                tail = f"any field starting with {self.key!r}"
+            case True, False:
+                tail = f"any field starting with {self.key!r} (modulo case)"
+            case _ as never:
+                assert_never(never)
+        return f"{head} {tail}"
+
+
+##
+
+
 def text_to_dataclass(
     text_or_mapping: str | Mapping[str, str],
     cls: type[TDataclass],
@@ -297,29 +421,42 @@ def text_to_dataclass(
     *,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    head: bool = False,
     case_sensitive: bool = False,
+    allow_extra: bool = False,
 ) -> TDataclass:
     """Construct a dataclass from a string or a mapping or strings."""
-    fields = list(yield_fields(cls, globalns=globalns, localns=localns))
     match text_or_mapping:
         case str() as text:
-            text_mapping = _text_to_dataclass_split_text(text, cls)
-        case Mapping() as text_mapping:
+            keys_to_serializes = _text_to_dataclass_split_text(text, cls)
+        case Mapping() as keys_to_serializes:
             ...
         case _ as never:
             assert_never(never)
-    value_mapping = dict(
-        _text_to_dataclass_get_and_parse(
-            fields, key, value, cls, case_sensitive=case_sensitive
-        )
-        for key, value in text_mapping.items()
+    fields = list(yield_fields(cls, globalns=globalns, localns=localns))
+    fields_to_serializes = str_mapping_to_field_mapping(
+        cls,
+        keys_to_serializes,
+        fields=fields,
+        globalns=globalns,
+        localns=localns,
+        head=head,
+        case_sensitive=case_sensitive,
+        allow_extra=allow_extra,
     )
+    field_names_to_values = {
+        f.name: _text_to_dataclass_parse(f, t, cls, case_sensitive=case_sensitive)
+        for f, t in fields_to_serializes.items()
+    }
     return mapping_to_dataclass(
         cls,
-        value_mapping,
+        field_names_to_values,
+        fields=fields,
         globalns=globalns,
         localns=localns,
+        head=head,
         case_sensitive=case_sensitive,
+        allow_extra=allow_extra,
     )
 
 
@@ -340,38 +477,18 @@ def _text_to_dataclass_split_key_value_pair(
     return key, value
 
 
-def _text_to_dataclass_get_and_parse(
-    fields: Iterable[_YieldFieldsClass[Any]],
-    key: str,
-    value: str,
+def _text_to_dataclass_parse(
+    field: _YieldFieldsClass[Any],
+    text: str,
     cls: type[Dataclass],
     /,
     *,
     case_sensitive: bool = False,
-) -> tuple[str, Any]:
-    mapping = {f.name: f for f in fields}
-    try:
-        name = one_str(mapping, key, head=True, case_sensitive=case_sensitive)
-    except OneStrEmptyError:
-        raise _TextToDataClassGetFieldEmptyError(
-            cls=cls, key=key, case_sensitive=case_sensitive
-        ) from None
-    except OneStrNonUniqueError as error:
-        raise _TextToDataClassGetFieldNonUniqueError(
-            cls=cls,
-            key=key,
-            case_sensitive=case_sensitive,
-            first=error.first,
-            second=error.second,
-        ) from None
-    field = mapping[name]
+) -> Any:
     try:
-        parsed = parse_text(field.type_, value, case_sensitive=case_sensitive)
+        return parse_text(field.type_, text, case_sensitive=case_sensitive)
     except ParseTextError:
-        raise _TextToDataClassParseValueError(
-            cls=cls, field=field, text=value
-        ) from None
-    return key, parsed
+        raise _TextToDataClassParseValueError(cls=cls, field=field, text=text) from None
 
 
 @dataclass(kw_only=True, slots=True)
@@ -388,31 +505,6 @@ class _TextToDataClassSplitKeyValuePairError(TextToDataClassError):
         return f"Unable to construct {get_class_name(self.cls)!r}; failed to split key-value pair {self.text!r}"
 
 
-@dataclass(kw_only=True, slots=True)
-class _TextToDataClassGetFieldEmptyError(TextToDataClassError[TDataclass]):
-    key: str
-    case_sensitive: bool = False
-
-    @override
-    def __str__(self) -> str:
-        desc = f"Dataclass {get_class_name(self.cls)!r} does not contain any field starting with {self.key!r}"
-        return desc if self.case_sensitive else f"{desc} (modulo case)"
-
-
-@dataclass(kw_only=True, slots=True)
-class _TextToDataClassGetFieldNonUniqueError(TextToDataClassError[TDataclass]):
-    key: str
-    case_sensitive: bool = False
-    first: str
-    second: str
-
-    @override
-    def __str__(self) -> str:
-        head = f"Dataclass {get_class_name(self.cls)!r} must contain exactly one field starting with {self.key!r}"
-        mid = "" if self.case_sensitive else " (modulo case)"
-        return f"{head}{mid}; got {self.first!r}, {self.second!r} and perhaps more"
-
-
 @dataclass(kw_only=True, slots=True)
 class _TextToDataClassParseValueError(TextToDataClassError[TDataclass]):
     field: _YieldFieldsClass[Any]
@@ -431,16 +523,16 @@ def yield_fields(
     obj: Dataclass,
     /,
     *,
-    globalns: StrMapping | None = ...,
-    localns: StrMapping | None = ...,
+    globalns: StrMapping | None = None,
+    localns: StrMapping | None = None,
 ) -> Iterator[_YieldFieldsInstance[Any]]: ...
 @overload
 def yield_fields(
     obj: type[Dataclass],
     /,
     *,
-    globalns: StrMapping | None = ...,
-    localns: StrMapping | None = ...,
+    globalns: StrMapping | None = None,
+    localns: StrMapping | None = None,
 ) -> Iterator[_YieldFieldsClass[Any]]: ...
 def yield_fields(
     obj: Dataclass | type[Dataclass],
@@ -580,12 +672,18 @@ class YieldFieldsError(Exception):
 
 __all__ = [
     "MappingToDataclassError",
+    "OneFieldEmptyError",
+    "OneFieldError",
+    "OneFieldNonUniqueError",
+    "StrMappingToFieldMappingError",
     "TextToDataClassError",
     "YieldFieldsError",
     "dataclass_repr",
     "dataclass_to_dict",
     "mapping_to_dataclass",
+    "one_field",
     "replace_non_sentinel",
+    "str_mapping_to_field_mapping",
     "text_to_dataclass",
     "yield_fields",
 ]

utilities/parse.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
 from types import NoneType
-from typing import Any, get_args, override
+from typing import Any, override
 
 from utilities.datetime import is_subclass_date_not_datetime
 from utilities.enum import ParseEnumError, parse_enum
@@ -14,7 +14,7 @@ from utilities.functions import is_subclass_int_not_bool
 from utilities.iterables import one, one_str
 from utilities.sentinel import ParseSentinelError, Sentinel, parse_sentinel
 from utilities.text import ParseBoolError, ParseNoneError, parse_bool, parse_none
-from utilities.typing import is_literal_type, is_optional_type
+from utilities.typing import get_args, is_literal_type, is_optional_type
 from utilities.version import ParseVersionError, Version, parse_version
 
 

utilities/polars.py

@@ -71,7 +71,6 @@ from utilities.iterables import (
     CheckMappingsEqualError,
     CheckSubSetError,
     CheckSuperMappingError,
-    CheckSuperSetError,
     OneEmptyError,
     OneNonUniqueError,
     always_iterable,
@@ -79,7 +78,6 @@ from utilities.iterables import (
     check_mappings_equal,
     check_subset,
     check_supermapping,
-    check_superset,
     is_iterable_not_str,
     one,
 )
@@ -92,7 +90,6 @@ from utilities.math import (
     number_of_decimals,
 )
 from utilities.reprlib import get_repr
-from utilities.sentinel import Sentinel
 from utilities.types import MaybeStr, Number, WeekDay
 from utilities.typing import (
     get_args,
@@ -1484,100 +1481,6 @@ def week_num(column: IntoExprColumn, /, *, start: WeekDay = "mon") -> Expr | Ser
 ##
 
 
-def yield_rows_as_dataclasses(
-    df: DataFrame,
-    cls: type[TDataclass],
-    /,
-    *,
-    globalns: StrMapping | None = None,
-    localns: StrMapping | None = None,
-    check_types: Literal["none", "first", "all"] = "first",
-) -> Iterator[TDataclass]:
-    """Yield the rows of a DataFrame as dataclasses."""
-    from dacite import from_dict
-    from dacite.exceptions import WrongTypeError
-
-    columns = df.columns
-    required: set[str] = set()
-    for field in yield_fields(cls, globalns=globalns, localns=localns):
-        if isinstance(field.default, Sentinel) and isinstance(
-            field.default_factory, Sentinel
-        ):
-            required.add(field.name)
-    try:
-        check_superset(columns, required)
-    except CheckSuperSetError as error:
-        raise _YieldRowsAsDataClassesColumnsSuperSetError(
-            df=df, cls=cls, left=error.left, right=error.right, extra=error.extra
-        ) from None
-    rows = df.iter_rows(named=True)
-    match check_types:
-        case "none":
-            yield from _yield_rows_as_dataclasses_no_check_types(rows, cls)
-        case "first":
-            try:
-                first = next(rows)
-            except StopIteration:
-                return
-            try:
-                yield from_dict(cls, cast("Data", first))
-            except WrongTypeError as error:
-                raise _YieldRowsAsDataClassesWrongTypeError(
-                    df=df, cls=cls, msg=str(error)
-                ) from None
-            yield from _yield_rows_as_dataclasses_no_check_types(rows, cls)
-        case "all":
-            try:
-                for row in rows:
-                    yield from_dict(cls, cast("Data", row))
-            except WrongTypeError as error:
-                raise _YieldRowsAsDataClassesWrongTypeError(
-                    df=df, cls=cls, msg=str(error)
-                ) from None
-        case _ as never:
-            assert_never(never)
-
-
-def _yield_rows_as_dataclasses_no_check_types(
-    rows: Iterator[dict[str, Any]], cls: type[TDataclass], /
-) -> Iterator[TDataclass]:
-    """Yield the rows of a DataFrame as dataclasses without type checking."""
-    from dacite import Config, from_dict
-
-    config = Config(check_types=False)
-    for row in rows:
-        yield from_dict(cls, cast("Data", row), config=config)
-
-
-@dataclass(kw_only=True, slots=True)
-class YieldRowsAsDataClassesError(Exception):
-    df: DataFrame
-    cls: type[Dataclass]
-
-
-@dataclass(kw_only=True, slots=True)
-class _YieldRowsAsDataClassesColumnsSuperSetError(YieldRowsAsDataClassesError):
-    left: AbstractSet[str]
-    right: AbstractSet[str]
-    extra: AbstractSet[str]
-
-    @override
-    def __str__(self) -> str:
-        return f"DataFrame columns {get_repr(self.left)} must be a superset of dataclass fields {get_repr(self.right)}; dataclass had extra fields {get_repr(self.extra)}."
-
-
-@dataclass(kw_only=True, slots=True)
-class _YieldRowsAsDataClassesWrongTypeError(YieldRowsAsDataClassesError):
-    msg: str
-
-    @override
-    def __str__(self) -> str:
-        return self.msg
-
-
-##
-
-
 @overload
 def yield_struct_series_elements(
     series: Series, /, *, strict: Literal[True]
@@ -1714,7 +1617,6 @@ __all__ = [
     "IsNullStructSeriesError",
     "SetFirstRowAsColumnsError",
     "StructFromDataClassError",
-    "YieldRowsAsDataClassesError",
     "YieldStructSeriesElementsError",
     "append_dataclass",
     "are_frames_equal",
@@ -1749,7 +1651,6 @@ __all__ = [
     "struct_from_dataclass",
     "touch",
     "unique_element",
-    "yield_rows_as_dataclasses",
     "yield_struct_series_dataclasses",
     "yield_struct_series_elements",
     "zoned_datetime",

utilities/python_dotenv.py

@@ -1,25 +1,20 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from functools import partial
 from os import environ
-from typing import TYPE_CHECKING, Any, override
+from typing import TYPE_CHECKING, override
 
 from dotenv import dotenv_values
 
-from utilities.dataclasses import (
-    _MappingToDataclassEmptyError,
-    _YieldFieldsClass,
-    mapping_to_dataclass,
-)
+from utilities.dataclasses import MappingToDataclassError, text_to_dataclass
 from utilities.git import get_repo_root
 from utilities.iterables import MergeStrMappingsError, merge_str_mappings
-from utilities.parse import ParseTextError, parse_text
 from utilities.pathlib import PWD
 from utilities.reprlib import get_repr
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
+    from collections.abc import Set as AbstractSet
     from pathlib import Path
 
     from utilities.types import PathLike, StrMapping, TDataclass
@@ -32,6 +27,8 @@ def load_settings(
     cwd: PathLike = PWD,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    head: bool = False,
+    case_sensitive: bool = False,
 ) -> TDataclass:
     """Load a set of settings from the `.env` file."""
     path = get_repo_root(cwd=cwd).joinpath(".env")
@@ -39,35 +36,29 @@ def load_settings(
         raise _LoadSettingsFileNotFoundError(path=path) from None
     maybe_values_dotenv = dotenv_values(path)
     try:
-        maybe_values = merge_str_mappings(maybe_values_dotenv, environ)
+        maybe_values: Mapping[str, str | None] = merge_str_mappings(
+            maybe_values_dotenv, environ, case_sensitive=case_sensitive
+        )
     except MergeStrMappingsError as error:
         raise _LoadSettingsDuplicateKeysError(
-            path=path, values=error.mapping, counts=error.counts
+            path=path,
+            values=error.mapping,
+            counts=error.counts,
+            case_sensitive=case_sensitive,
         ) from None
     values = {k: v for k, v in maybe_values.items() if v is not None}
     try:
-        return mapping_to_dataclass(
-            cls,
+        return text_to_dataclass(
             values,
+            cls,
             globalns=globalns,
             localns=localns,
-            post=partial(_load_settings_post, path=path, values=values),
+            head=head,
+            case_sensitive=case_sensitive,
+            allow_extra=True,
         )
-    except _MappingToDataclassEmptyError as error:
-        raise _LoadSettingsEmptyError(
-            path=path, values=error.mapping, field=error.field
-        ) from None
-
-
-def _load_settings_post(
-    field: _YieldFieldsClass[Any], text: str, /, *, path: Path, values: StrMapping
-) -> Any:
-    try:
-        return parse_text(field.type_, text)
-    except ParseTextError:
-        raise _LoadSettingsParseTextError(
-            path=path, values=values, field=field, text=text
-        ) from None
+    except MappingToDataclassError as error:
+        raise _LoadSettingsMissingKeysError(path=path, fields=error.fields) from None
 
 
 @dataclass(kw_only=True, slots=True)
@@ -79,22 +70,13 @@ class LoadSettingsError(Exception):
 class _LoadSettingsDuplicateKeysError(LoadSettingsError):
     values: StrMapping
     counts: Mapping[str, int]
+    case_sensitive: bool = False
 
     @override
     def __str__(self) -> str:
         return f"Mapping {get_repr(dict(self.values))} keys must not contain duplicates (modulo case); got {get_repr(self.counts)}"
 
 
-@dataclass(kw_only=True, slots=True)
-class _LoadSettingsEmptyError(LoadSettingsError):
-    values: StrMapping
-    field: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Field {self.field!r} must exist (modulo case)"
-
-
 @dataclass(kw_only=True, slots=True)
 class _LoadSettingsFileNotFoundError(LoadSettingsError):
     @override
@@ -103,14 +85,13 @@ class _LoadSettingsFileNotFoundError(LoadSettingsError):
 
 
 @dataclass(kw_only=True, slots=True)
-class _LoadSettingsParseTextError(LoadSettingsError):
-    values: StrMapping
-    field: _YieldFieldsClass[Any]
-    text: str
+class _LoadSettingsMissingKeysError(LoadSettingsError):
+    fields: AbstractSet[str]
 
     @override
     def __str__(self) -> str:
-        return f"Unable to parse field {self.field.name!r} of type {self.field.type_!r}; got {self.text!r}"
+        desc = ", ".join(map(repr, sorted(self.fields)))
+        return f"Unable to load {str(self.path)!r}; missing value(s) for {desc}"
 
 
 __all__ = ["LoadSettingsError", "load_settings"]