dycw-utilities 0.109.0__py3-none-any.whl → 0.109.2__py3-none-any.whl

{dycw_utilities-0.109.0.dist-info → dycw_utilities-0.109.2.dist-info}/METADATA

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

{dycw_utilities-0.109.0.dist-info → dycw_utilities-0.109.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=us3aLi645m07ZoZciss9gQZW8TJND1cejqEh_im4aL8,60
+utilities/__init__.py,sha256=BFspQsIuZJOmuE31YyhwkR4P62-Ad5dFurosyyABzLA,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=4siQUalzjYckhJ7R9Cn4Pmerxzx18_mjPIwUmeuwwKs,23049
 utilities/datetime.py,sha256=GOs-MIEW_A49kzqa1yhIoeNeSqqPVgGO-h2AThtgTDk,37326
 utilities/enum.py,sha256=HoRwVCWzsnH0vpO9ZEcAAIZLMv0Sn2vJxxA4sYMQgDs,5793
 utilities/errors.py,sha256=BtSNP0JC3ik536ddPyTerLomCRJV9f6kdMe6POz0QHM,361
@@ -38,22 +38,22 @@ utilities/more_itertools.py,sha256=CPUxrMAcTwRxbzbhiqPKi3Xx9hxqI0t6gkWjutaibGk,5
 utilities/numpy.py,sha256=rA1b0_GkBUSMjnv77tinRM70KRnkcmZxI9xbrsXFDRg,21819
 utilities/operator.py,sha256=0M2yZJ0PODH47ogFEnkGMBe_cfxwZR02T_92LZVZvHo,3715
 utilities/optuna.py,sha256=loyJGWTzljgdJaoLhP09PT8Jz6o_pwBOwehY33lHkhw,1923
-utilities/orjson.py,sha256=DW5pOpMyrR5Q8caQYly9AqRPazDBqrWv5GRWfULqka4,36291
+utilities/orjson.py,sha256=Wj5pzG_VdgoAy14a7Luhem-BgYrRtRFvvl_POiszRd0,36930
 utilities/os.py,sha256=D_FyyT-6TtqiN9KSS7c9g1fnUtgxmyMtzAjmYLkk46A,3587
 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=ZXiHLkn6CbRh0_e0db5KRjHPU0LAedwzGno7k9fsiIo,48917
+utilities/polars.py,sha256=USK_Rck8nmFYg2Rs-akqN9jV4w52lpz4rgkWUMQdLMk,49087
 utilities/pqdm.py,sha256=foRytQybmOQ05pjt5LF7ANyzrIa--4ScDE3T2wd31a4,3118
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 utilities/pydantic.py,sha256=f6qtR5mO2YMuyvNmbaEj5YeD9eGA4YYfb7Bjzh9jUs0,1845
 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/pytest_regressions.py,sha256=-SVT9647Dg6-JcdsiaDKXe3NdOmmrvGevLKWwGjxq3c,5088
+utilities/python_dotenv.py,sha256=10DHEB7AVeZqH7I4wr6nACdJQYQJanlEj6EsyLvCN9w,3059
 utilities/random.py,sha256=lYdjgxB7GCfU_fwFVl5U-BIM_HV3q6_urL9byjrwDM8,4157
 utilities/re.py,sha256=5J4d8VwIPFVrX2Eb8zfoxImDv7IwiN_U7mJ07wR2Wvs,3958
 utilities/redis.py,sha256=CsDQqc9V6ASLzLQwtbQXZQEndyG9pJiCOhPlPeszt7Y,21203
@@ -75,7 +75,7 @@ utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=Rkc49KSpHuC8s7vUxGO9DU55U9I6yDKnchsQqrUCVBs,4075
 utilities/traceback.py,sha256=KwHPLdEbdj0fFhXo8MBfxcvem8A-VXYDwFMNJ6f0cTM,27328
 utilities/types.py,sha256=QK8kgH80TJdh_vktaZHrCEk7f1f8kHiDr8dJlK8aSac,17814
-utilities/typing.py,sha256=qX0o3NfImTXt40iGpERIVjuOQGb0XINfWUOxMmlh1s4,5157
+utilities/typing.py,sha256=h1vt82GUs-3ww7yFbZ3BWjdUM4NBPHaptcJHSKuRa5E,5341
 utilities/tzdata.py,sha256=2ZsPmhTVM9Ptrxb4QrWKtKOB9RiH8IOO-A1u7ULdVbg,176
 utilities/tzlocal.py,sha256=42BCquGF54oIqIKe5RGziP4K8Nbm3Ey7uqcNn6m5ge8,534
 utilities/uuid.py,sha256=jJTFxz-CWgltqNuzmythB7iEQ-Q1mCwPevUfKthZT3c,611
@@ -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.109.0.dist-info/METADATA,sha256=7Urd3hro439NaLJ2Kkzu7mJNlYt5qxb3HmbzrcZwbkQ,13004
-dycw_utilities-0.109.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.109.0.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.109.0.dist-info/RECORD,,
+dycw_utilities-0.109.2.dist-info/METADATA,sha256=9cmTxKEFxwqlG4VNbAnM88UGivDzayFQlB0ntOvtBno,13004
+dycw_utilities-0.109.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.109.2.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.109.2.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.109.0"
+__version__ = "0.109.2"

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
@@ -48,6 +48,7 @@ def dataclass_repr(
     exclude: Iterable[str] | None = None,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
     rel_tol: float | None = None,
     abs_tol: float | None = None,
     extra: Mapping[type[_T], Callable[[_T, _T], bool]] | None = None,
@@ -56,7 +57,9 @@ def dataclass_repr(
 ) -> str:
     """Repr a dataclass, without its defaults."""
     out: dict[str, str] = {}
-    for fld in yield_fields(obj, globalns=globalns, localns=localns):
+    for fld in yield_fields(
+        obj, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
+    ):
         if (
             fld.keep(
                 include=include,
@@ -76,6 +79,7 @@ def dataclass_repr(
                         exclude=exclude,
                         globalns=globalns,
                         localns=localns,
+                        warn_name_errors=warn_name_errors,
                         rel_tol=rel_tol,
                         abs_tol=abs_tol,
                         extra=extra,
@@ -90,6 +94,7 @@ def dataclass_repr(
                             exclude=exclude,
                             globalns=globalns,
                             localns=localns,
+                            warn_name_errors=warn_name_errors,
                             rel_tol=rel_tol,
                             abs_tol=abs_tol,
                             extra=extra,
@@ -122,6 +127,7 @@ def dataclass_to_dict(
     exclude: Iterable[str] | None = None,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
     rel_tol: float | None = None,
     abs_tol: float | None = None,
     extra: Mapping[type[_T], Callable[[_T, _T], bool]] | None = None,
@@ -131,7 +137,9 @@ def dataclass_to_dict(
 ) -> StrMapping:
     """Convert a dataclass to a dictionary."""
     out: StrMapping = {}
-    for fld in yield_fields(obj, globalns=globalns, localns=localns):
+    for fld in yield_fields(
+        obj, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
+    ):
         if fld.keep(
             include=include,
             exclude=exclude,
@@ -146,6 +154,7 @@ def dataclass_to_dict(
                         fld.value,
                         globalns=globalns,
                         localns=localns,
+                        warn_name_errors=warn_name_errors,
                         rel_tol=rel_tol,
                         abs_tol=abs_tol,
                         extra=extra,
@@ -159,6 +168,7 @@ def dataclass_to_dict(
                             v,
                             globalns=globalns,
                             localns=localns,
+                            warn_name_errors=warn_name_errors,
                             rel_tol=rel_tol,
                             abs_tol=abs_tol,
                             extra=extra,
@@ -186,76 +196,157 @@ def mapping_to_dataclass(
     mapping: StrMapping,
     /,
     *,
+    fields: Iterable[_YieldFieldsClass[Any]] | None = None,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
+    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
+    if fields is None:
+        fields_use = list(
+            yield_fields(
+                cls,
+                globalns=globalns,
+                localns=localns,
+                warn_name_errors=warn_name_errors,
+            )
         )
-        for f in fields
+    else:
+        fields_use = fields
+    fields_to_values = str_mapping_to_field_mapping(
+        cls,
+        mapping,
+        fields=fields_use,
+        globalns=globalns,
+        localns=localns,
+        warn_name_errors=warn_name_errors,
+        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,
+    warn_name_errors: bool = False,
+    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,
+                warn_name_errors=warn_name_errors,
+            )
+        )
+    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 +381,68 @@ 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,
+    warn_name_errors: bool = False,
+    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,
+                warn_name_errors=warn_name_errors,
+                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 +450,49 @@ def text_to_dataclass(
     *,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
+    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
+    fields = list(
+        yield_fields(
+            cls, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
         )
-        for key, value in text_mapping.items()
     )
+    fields_to_serializes = str_mapping_to_field_mapping(
+        cls,
+        keys_to_serializes,
+        fields=fields,
+        globalns=globalns,
+        localns=localns,
+        warn_name_errors=warn_name_errors,
+        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,
+        warn_name_errors=warn_name_errors,
+        head=head,
         case_sensitive=case_sensitive,
+        allow_extra=allow_extra,
     )
 
 
@@ -340,38 +513,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 +541,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 +559,18 @@ def yield_fields(
     obj: Dataclass,
     /,
     *,
-    globalns: StrMapping | None = ...,
-    localns: StrMapping | None = ...,
+    globalns: StrMapping | None = None,
+    localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
 ) -> Iterator[_YieldFieldsInstance[Any]]: ...
 @overload
 def yield_fields(
     obj: type[Dataclass],
     /,
     *,
-    globalns: StrMapping | None = ...,
-    localns: StrMapping | None = ...,
+    globalns: StrMapping | None = None,
+    localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
 ) -> Iterator[_YieldFieldsClass[Any]]: ...
 def yield_fields(
     obj: Dataclass | type[Dataclass],
@@ -448,10 +578,16 @@ def yield_fields(
     *,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
 ) -> Iterator[_YieldFieldsInstance[Any]] | Iterator[_YieldFieldsClass[Any]]:
     """Yield the fields of a dataclass."""
     if is_dataclass_instance(obj):
-        for field in yield_fields(type(obj), globalns=globalns, localns=localns):
+        for field in yield_fields(
+            type(obj),
+            globalns=globalns,
+            localns=localns,
+            warn_name_errors=warn_name_errors,
+        ):
             yield _YieldFieldsInstance(
                 name=field.name,
                 value=getattr(obj, field.name),
@@ -466,7 +602,9 @@ def yield_fields(
                 kw_only=field.kw_only,
             )
     elif is_dataclass_class(obj):
-        hints = get_type_hints(obj, globalns=globalns, localns=localns)
+        hints = get_type_hints(
+            obj, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
+        )
         for field in fields(obj):
             if isinstance(field.type, type):
                 type_ = field.type
@@ -580,12 +718,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/orjson.py

@@ -114,6 +114,7 @@ def serialize(
     before: Callable[[Any], Any] | None = None,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
     dataclass_hook: _DataclassHook | None = None,
     dataclass_defaults: bool = False,
 ) -> bytes:
@@ -123,6 +124,7 @@ def serialize(
         before=before,
         globalns=globalns,
         localns=localns,
+        warn_name_errors=warn_name_errors,
         dataclass_hook=dataclass_hook,
         dataclass_defaults=dataclass_defaults,
     )
@@ -139,6 +141,7 @@ def _pre_process(
     before: Callable[[Any], Any] | None = None,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
     dataclass_hook: _DataclassHook | None = None,
     dataclass_defaults: bool = False,
     error: _ErrorMode = "raise",
@@ -150,6 +153,7 @@ def _pre_process(
         before=before,
         globalns=globalns,
         localns=localns,
+        warn_name_errors=warn_name_errors,
         dataclass_hook=dataclass_hook,
         dataclass_defaults=dataclass_defaults,
         error=error,
@@ -196,6 +200,7 @@ def _pre_process(
                 dataclass,
                 globalns=globalns,
                 localns=localns,
+                warn_name_errors=warn_name_errors,
                 final=partial(_dataclass_final, hook=dataclass_hook),
                 defaults=dataclass_defaults,
             )
@@ -212,6 +217,7 @@ def _pre_process(
                 before=before,
                 globalns=globalns,
                 localns=localns,
+                warn_name_errors=warn_name_errors,
                 dataclass_hook=dataclass_hook,
             )
         case list() as list_:
@@ -222,6 +228,7 @@ def _pre_process(
                 before=before,
                 globalns=globalns,
                 localns=localns,
+                warn_name_errors=warn_name_errors,
                 dataclass_hook=dataclass_hook,
             )
         case Mapping() as mapping:
@@ -234,6 +241,7 @@ def _pre_process(
                 before=before,
                 globalns=globalns,
                 localns=localns,
+                warn_name_errors=warn_name_errors,
                 dataclass_hook=dataclass_hook,
             )
         case tuple() as tuple_:
@@ -244,6 +252,7 @@ def _pre_process(
                 before=before,
                 globalns=globalns,
                 localns=localns,
+                warn_name_errors=warn_name_errors,
                 dataclass_hook=dataclass_hook,
             )
         # other
@@ -263,6 +272,7 @@ def _pre_process_container(
     before: Callable[[Any], Any] | None = None,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
     dataclass_hook: _DataclassHook | None = None,
     dataclass_include_defaults: bool = False,
 ) -> Any:
@@ -272,6 +282,7 @@ def _pre_process_container(
             before=before,
             globalns=globalns,
             localns=localns,
+            warn_name_errors=warn_name_errors,
             dataclass_hook=dataclass_hook,
             dataclass_defaults=dataclass_include_defaults,
         )
@@ -716,6 +727,7 @@ class OrjsonFormatter(Formatter):
         before: Callable[[Any], Any] | None = None,
         globalns: StrMapping | None = None,
         localns: StrMapping | None = None,
+        warn_name_errors: bool = False,
         dataclass_hook: _DataclassHook | None = None,
         dataclass_defaults: bool = False,
     ) -> None:
@@ -723,6 +735,7 @@ class OrjsonFormatter(Formatter):
         self._before = before
         self._globalns = globalns
         self._localns = localns
+        self._warn_name_errors = warn_name_errors
         self._dataclass_hook = dataclass_hook
         self._dataclass_defaults = dataclass_defaults
 
@@ -752,6 +765,7 @@ class OrjsonFormatter(Formatter):
             before=self._before,
             globalns=self._globalns,
             localns=self._localns,
+            warn_name_errors=self._warn_name_errors,
             dataclass_hook=self._dataclass_hook,
             dataclass_defaults=self._dataclass_defaults,
         ).decode()

utilities/polars.py

@@ -726,10 +726,13 @@ def dataclass_to_schema(
     *,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
 ) -> SchemaDict:
     """Cast a dataclass as a schema dict."""
     out: dict[str, Any] = {}
-    for field in yield_fields(obj, globalns=globalns, localns=localns):
+    for field in yield_fields(
+        obj, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
+    ):
         if is_dataclass_instance(field.value):
             dtypes = dataclass_to_schema(
                 field.value, globalns=globalns, localns=localns
@@ -1388,12 +1391,15 @@ def struct_from_dataclass(
     *,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
     time_zone: TimeZoneLike | None = None,
 ) -> Struct:
     """Construct the Struct data type for a dataclass."""
     if not is_dataclass_class(cls):
         raise _StructFromDataClassNotADataclassError(cls=cls)
-    anns = get_type_hints(cls, globalns=globalns, localns=localns)
+    anns = get_type_hints(
+        cls, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
+    )
     data_types = {
         k: _struct_from_dataclass_one(v, time_zone=time_zone) for k, v in anns.items()
     }

utilities/pytest_regressions.py

@@ -51,6 +51,7 @@ class OrjsonRegressionFixture:
         *,
         globalns: StrMapping | None = None,
         localns: StrMapping | None = None,
+        warn_name_errors: bool = False,
         dataclass_defaults: bool = False,
         suffix: str | None = None,
     ) -> None:
@@ -61,6 +62,7 @@ class OrjsonRegressionFixture:
             obj,
             globalns=globalns,
             localns=localns,
+            warn_name_errors=warn_name_errors,
             dataclass_defaults=dataclass_defaults,
         )
         basename = self._basename

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,9 @@ def load_settings(
     cwd: PathLike = PWD,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
+    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 +37,30 @@ 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),
+            warn_name_errors=warn_name_errors,
+            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 +72,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 +87,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"]

utilities/typing.py

@@ -19,6 +19,7 @@ from typing import (
 from typing import get_args as _get_args
 from typing import get_type_hints as _get_type_hints
 from uuid import UUID
+from warnings import warn
 
 from utilities.iterables import unique_everseen
 from utilities.sentinel import Sentinel
@@ -68,16 +69,18 @@ def get_type_hints(
     *,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
+    warn_name_errors: bool = False,
 ) -> dict[str, Any]:
     """Get the type hints of an object."""
     result: dict[str, Any] = cls.__annotations__
     _ = {Literal, Path, Sentinel, StrMapping, UUID, dt}
-    globalns = globals() | ({} if globalns is None else dict(globalns))
-    localns = {} if localns is None else dict(localns)
+    globalns_use = globals() | ({} if globalns is None else dict(globalns))
+    localns_use = {} if localns is None else dict(localns)
     try:
-        hints = _get_type_hints(cls, globalns=globalns, localns=localns)
-    except NameError:
-        pass
+        hints = _get_type_hints(cls, globalns=globalns_use, localns=localns_use)
+    except NameError as error:
+        if warn_name_errors:
+            warn(f"Error getting type hints for {cls!r}; {error}", stacklevel=2)
     else:
         result.update({
             key: value