dycw-utilities 0.109.29__py3-none-any.whl → 0.110.0__py3-none-any.whl

{dycw_utilities-0.109.29.dist-info → dycw_utilities-0.110.0.dist-info}/METADATA

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

{dycw_utilities-0.109.29.dist-info → dycw_utilities-0.110.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=AIZiPdrHMOKkgJqoeU29sMxSZXZMURdyCYzqvmBulyI,61
+utilities/__init__.py,sha256=H5Ma2FOh3z_dBcZTVaSY2VI14JUFHWspBQs7dYAHnjc,60
 utilities/altair.py,sha256=Gpja-flOo-Db0PIPJLJsgzAlXWoKUjPU1qY-DQ829ek,9156
 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=8-38WHrScAvElBNvFxBnhJwab1XXkSXpDOiNPOAvh2Q,23295
+utilities/dataclasses.py,sha256=vkrcV-qnMS4qGHJ2z3kmcugNH_Fk20SPXfttXb3H5Bs,25950
 utilities/datetime.py,sha256=GOs-MIEW_A49kzqa1yhIoeNeSqqPVgGO-h2AThtgTDk,37326
 utilities/enum.py,sha256=HoRwVCWzsnH0vpO9ZEcAAIZLMv0Sn2vJxxA4sYMQgDs,5793
 utilities/errors.py,sha256=BtSNP0JC3ik536ddPyTerLomCRJV9f6kdMe6POz0QHM,361
@@ -41,7 +41,7 @@ utilities/operator.py,sha256=0M2yZJ0PODH47ogFEnkGMBe_cfxwZR02T_92LZVZvHo,3715
 utilities/optuna.py,sha256=loyJGWTzljgdJaoLhP09PT8Jz6o_pwBOwehY33lHkhw,1923
 utilities/orjson.py,sha256=Wj5pzG_VdgoAy14a7Luhem-BgYrRtRFvvl_POiszRd0,36930
 utilities/os.py,sha256=D_FyyT-6TtqiN9KSS7c9g1fnUtgxmyMtzAjmYLkk46A,3587
-utilities/parse.py,sha256=l8W5ik1CvmPEsas-dB7cS5gCKpeyr0hQDtjZqI-9azI,16283
+utilities/parse.py,sha256=wxqh4YwBfQ7nm249-F_6uqiLo1js9_xji9AVvUxZ5nI,17091
 utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=ikHXsWtDLr553cfH6p9mMaiCnIAP69B7q84ckWV3HaA,10884
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
@@ -55,7 +55,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=-SVT9647Dg6-JcdsiaDKXe3NdOmmrvGevLKWwGjxq3c,5088
-utilities/python_dotenv.py,sha256=JDIGuaGIiVkOcOBDpA7OZZM_0vxrkZyrrfqOssB6cqE,3170
+utilities/python_dotenv.py,sha256=6viKAI7zx9YQU2ewITaOcad7wMwkrf6FbYpBmCl4vCA,3170
 utilities/random.py,sha256=lYdjgxB7GCfU_fwFVl5U-BIM_HV3q6_urL9byjrwDM8,4157
 utilities/re.py,sha256=5J4d8VwIPFVrX2Eb8zfoxImDv7IwiN_U7mJ07wR2Wvs,3958
 utilities/redis.py,sha256=CsDQqc9V6ASLzLQwtbQXZQEndyG9pJiCOhPlPeszt7Y,21203
@@ -77,7 +77,7 @@ utilities/text.py,sha256=Ax_n-nY80_onWxag9M0PkmbaAqwyut9AEA9tEMd5lBs,6694
 utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=Rkc49KSpHuC8s7vUxGO9DU55U9I6yDKnchsQqrUCVBs,4075
 utilities/traceback.py,sha256=KwHPLdEbdj0fFhXo8MBfxcvem8A-VXYDwFMNJ6f0cTM,27328
-utilities/types.py,sha256=z1hbBOT5TkzTn2JOvSldw6DScxi3erG9qpJ3xci66GI,17963
+utilities/types.py,sha256=Hi9aKaxN3G9zFVlLjx6U9xd_HMGq-eqHLxmG1cSdVpg,17967
 utilities/typing.py,sha256=gLg4EbE1FX52fJ1d3ji4i08qolwu9qgWt8w_w_Y5DTk,5512
 utilities/tzdata.py,sha256=2ZsPmhTVM9Ptrxb4QrWKtKOB9RiH8IOO-A1u7ULdVbg,176
 utilities/tzlocal.py,sha256=42BCquGF54oIqIKe5RGziP4K8Nbm3Ey7uqcNn6m5ge8,534
@@ -87,7 +87,7 @@ utilities/warnings.py,sha256=yUgjnmkCRf6QhdyAXzl7u0qQFejhQG3PrjoSwxpbHrs,1819
 utilities/whenever.py,sha256=TjoTAJ1R27-rKXiXzdE4GzPidmYqm0W58XydDXp-QZM,17786
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-DQz5a0Ikw9jfSZtL0BEQkXOMC9yGn_xiJYNCLMiqEc,1989
-dycw_utilities-0.109.29.dist-info/METADATA,sha256=wN-G6OupzEqFsIek2lE458u5MkSYceoapxbzRnWL8Z8,13005
-dycw_utilities-0.109.29.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.109.29.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.109.29.dist-info/RECORD,,
+dycw_utilities-0.110.0.dist-info/METADATA,sha256=z9nJyYO-djaRWCX7iT7S0vdy40gXfUedyu_jhw3O-Cs,13004
+dycw_utilities-0.110.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.110.0.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.110.0.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.109.29"
+__version__ = "0.110.0"

utilities/dataclasses.py

@@ -1,7 +1,6 @@
 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,13 +21,26 @@ 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.parse import (
+    LIST_SEPARATOR,
+    PAIR_SEPARATOR,
+    ParseObjectError,
+    parse_object,
+    serialize_object,
+)
 from utilities.sentinel import Sentinel, sentinel
-from utilities.types import ParseTextExtra, StrStrMapping, TDataclass
+from utilities.text import (
+    _SplitKeyValuePairsDuplicateKeysError,
+    _SplitKeyValuePairsSplitError,
+    join_strs,
+    split_key_value_pairs,
+)
+from utilities.types import ParseObjectExtra, StrStrMapping, TDataclass
 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
 
@@ -44,11 +56,11 @@ def dataclass_repr(
     obj: Dataclass,
     /,
     *,
-    include: Iterable[str] | None = None,
-    exclude: Iterable[str] | None = None,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
     warn_name_errors: bool = False,
+    include: Iterable[str] | None = None,
+    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,
@@ -75,11 +87,11 @@ def dataclass_repr(
                 if is_dataclass_instance(fld.value):
                     repr_ = dataclass_repr(
                         fld.value,
-                        include=include,
-                        exclude=exclude,
                         globalns=globalns,
                         localns=localns,
                         warn_name_errors=warn_name_errors,
+                        include=include,
+                        exclude=exclude,
                         rel_tol=rel_tol,
                         abs_tol=abs_tol,
                         extra=extra,
@@ -90,11 +102,11 @@ def dataclass_repr(
                     repr_ = [
                         dataclass_repr(
                             v,
-                            include=include,
-                            exclude=exclude,
                             globalns=globalns,
                             localns=localns,
                             warn_name_errors=warn_name_errors,
+                            include=include,
+                            exclude=exclude,
                             rel_tol=rel_tol,
                             abs_tol=abs_tol,
                             extra=extra,
@@ -123,11 +135,11 @@ def dataclass_to_dict(
     obj: Dataclass,
     /,
     *,
-    include: Iterable[str] | None = None,
-    exclude: Iterable[str] | None = None,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
     warn_name_errors: bool = False,
+    include: Iterable[str] | None = None,
+    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,
@@ -155,6 +167,8 @@ def dataclass_to_dict(
                         globalns=globalns,
                         localns=localns,
                         warn_name_errors=warn_name_errors,
+                        include=include,
+                        exclude=exclude,
                         rel_tol=rel_tol,
                         abs_tol=abs_tol,
                         extra=extra,
@@ -169,6 +183,8 @@ def dataclass_to_dict(
                             globalns=globalns,
                             localns=localns,
                             warn_name_errors=warn_name_errors,
+                            include=include,
+                            exclude=exclude,
                             rel_tol=rel_tol,
                             abs_tol=abs_tol,
                             extra=extra,
@@ -381,85 +397,68 @@ def replace_non_sentinel(
 ##
 
 
-def str_mapping_to_field_mapping(
-    cls: type[TDataclass],
-    mapping: Mapping[str, _T],
+def serialize_dataclass(
+    obj: Dataclass,
     /,
     *,
-    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,
+    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,
+    defaults: bool = False,
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
+) -> str:
+    """Serialize a Dataclass."""
+    mapping: StrStrMapping = {}
+    fields = list(
+        yield_fields(
+            obj, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
+        )
+    )
+    for fld in fields:
+        if fld.keep(
+            include=include,
+            exclude=exclude,
+            rel_tol=rel_tol,
+            abs_tol=abs_tol,
+            extra=extra,
+            defaults=defaults,
+        ):
+            mapping[fld.name] = serialize_object(
+                fld.value, list_separator=list_separator, pair_separator=pair_separator
             )
-        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}"
-
-
-##
+    joined_items = (
+        join_strs(item, separator=pair_separator) for item in mapping.items()
+    )
+    return join_strs(joined_items, separator=list_separator)
 
 
-def text_to_dataclass(
-    text_or_mapping: str | StrStrMapping,
+def parse_dataclass(
+    text_or_mapping: str | Mapping[str, str],
     cls: type[TDataclass],
     /,
     *,
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
     warn_name_errors: bool = False,
     head: bool = False,
     case_sensitive: bool = False,
     allow_extra_keys: bool = False,
-    extra_parsers: ParseTextExtra | None = None,
+    extra_parsers: ParseObjectExtra | None = None,
 ) -> TDataclass:
     """Construct a dataclass from a string or a mapping or strings."""
     match text_or_mapping:
         case str() as text:
-            keys_to_serializes = _text_to_dataclass_split_text(text, cls)
+            keys_to_serializes = _parse_dataclass_split_key_value_pairs(
+                text, cls, list_separator=list_separator, pair_separator=pair_separator
+            )
         case Mapping() as keys_to_serializes:
             ...
         case _ as never:
@@ -481,7 +480,7 @@ def text_to_dataclass(
         allow_extra=allow_extra_keys,
     )
     field_names_to_values = {
-        f.name: _text_to_dataclass_parse(
+        f.name: _parse_dataclass_parse_text(
             f, t, cls, head=head, case_sensitive=case_sensitive, extra=extra_parsers
         )
         for f, t in fields_to_serializes.items()
@@ -499,57 +498,82 @@ def text_to_dataclass(
     )
 
 
-def _text_to_dataclass_split_text(text: str, cls: type[TDataclass], /) -> StrStrMapping:
-    pairs = (t for t in text.split(",") if t != "")
-    return dict(_text_to_dataclass_split_key_value_pair(pair, cls) for pair in pairs)
-
-
-def _text_to_dataclass_split_key_value_pair(
-    text: str, cls: type[Dataclass], /
-) -> tuple[str, str]:
+def _parse_dataclass_split_key_value_pairs(
+    text: str,
+    cls: type[TDataclass],
+    /,
+    *,
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
+) -> Mapping[str, str]:
     try:
-        key, value = text.split("=")
-    except ValueError:
-        raise _TextToDataClassSplitKeyValuePairError(cls=cls, text=text) from None
-    return key, value
+        return split_key_value_pairs(
+            text,
+            list_separator=list_separator,
+            pair_separator=pair_separator,
+            mapping=True,
+        )
+    except _SplitKeyValuePairsSplitError as error:
+        raise _ParseDataClassSplitKeyValuePairsSplitError(
+            text=error.inner, cls=cls
+        ) from None
+    except _SplitKeyValuePairsDuplicateKeysError as error:
+        raise _ParseDataClassSplitKeyValuePairsDuplicateKeysError(
+            text=error.text, cls=cls, counts=error.counts
+        ) from None
 
 
-def _text_to_dataclass_parse(
+def _parse_dataclass_parse_text(
     field: _YieldFieldsClass[Any],
     text: str,
     cls: type[Dataclass],
     /,
     *,
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
     head: bool = False,
     case_sensitive: bool = False,
-    extra: ParseTextExtra | None = None,
+    extra: ParseObjectExtra | None = None,
 ) -> Any:
     try:
-        return parse_text(
-            field.type_, text, head=head, case_sensitive=case_sensitive, extra=extra
+        return parse_object(
+            field.type_,
+            text,
+            list_separator=list_separator,
+            pair_separator=pair_separator,
+            head=head,
+            case_sensitive=case_sensitive,
+            extra=extra,
         )
-    except ParseTextError:
-        raise _TextToDataClassParseValueError(cls=cls, field=field, text=text) from None
+    except ParseObjectError:
+        raise _ParseDataClassParseValueError(cls=cls, field=field, text=text) from None
 
 
 @dataclass(kw_only=True, slots=True)
-class TextToDataClassError(Exception, Generic[TDataclass]):
+class ParseDataClassError(Exception, Generic[TDataclass]):
+    text: str
     cls: type[TDataclass]
 
 
 @dataclass(kw_only=True, slots=True)
-class _TextToDataClassSplitKeyValuePairError(TextToDataClassError):
-    text: str
-
+class _ParseDataClassSplitKeyValuePairsSplitError(ParseDataClassError):
     @override
     def __str__(self) -> str:
         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 _TextToDataClassParseValueError(TextToDataClassError[TDataclass]):
+class _ParseDataClassSplitKeyValuePairsDuplicateKeysError(ParseDataClassError):
+    counts: Mapping[str, int]
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to construct {get_class_name(self.cls)!r} since there are duplicate keys; got {self.counts!r}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _ParseDataClassParseValueError(ParseDataClassError[TDataclass]):
     field: _YieldFieldsClass[Any]
-    text: str
 
     @override
     def __str__(self) -> str:
@@ -559,6 +583,68 @@ class _TextToDataClassParseValueError(TextToDataClassError[TDataclass]):
 ##
 
 
+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}"
+
+
+##
+
+
 @overload
 def yield_fields(
     obj: Dataclass,
@@ -726,15 +812,15 @@ __all__ = [
     "OneFieldEmptyError",
     "OneFieldError",
     "OneFieldNonUniqueError",
+    "ParseDataClassError",
     "StrMappingToFieldMappingError",
-    "TextToDataClassError",
     "YieldFieldsError",
     "dataclass_repr",
     "dataclass_to_dict",
     "mapping_to_dataclass",
     "one_field",
+    "parse_dataclass",
     "replace_non_sentinel",
     "str_mapping_to_field_mapping",
-    "text_to_dataclass",
     "yield_fields",
 ]

utilities/parse.py

@@ -28,7 +28,7 @@ from utilities.text import (
     split_key_value_pairs,
     split_str,
 )
-from utilities.types import Duration, Number, ParseTextExtra
+from utilities.types import Duration, Number, ParseObjectExtra
 from utilities.typing import (
     get_args,
     is_dict_type,
@@ -47,27 +47,33 @@ if TYPE_CHECKING:
     from collections.abc import Set as AbstractSet
 
 
-def parse_text(
+LIST_SEPARATOR = ","
+PAIR_SEPARATOR = "="
+
+
+def parse_object(
     type_: Any,
     text: str,
     /,
     *,
-    list_separator: str = ",",
-    pair_separator: str = "=",
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
     head: bool = False,
     case_sensitive: bool = False,
-    extra: ParseTextExtra | None = None,
+    extra: ParseObjectExtra | None = None,
 ) -> Any:
     """Parse text."""
     if type_ is None:
         try:
             return parse_none(text)
         except ParseNoneError:
-            raise _ParseTextParseError(type_=type_, text=text) from None
+            raise _ParseObjectParseError(type_=type_, text=text) from None
     if isinstance(type_, type):
-        return _parse_text_type(type_, text, case_sensitive=case_sensitive, extra=extra)
+        return _parse_object_type(
+            type_, text, case_sensitive=case_sensitive, extra=extra
+        )
     if is_dict_type(type_):
-        return _parse_text_dict_type(
+        return _parse_object_dict_type(
             type_,
             text,
             list_separator=list_separator,
@@ -78,7 +84,7 @@ def parse_text(
         )
     if is_frozenset_type(type_):
         return frozenset(
-            _parse_text_set_type(
+            _parse_object_set_type(
                 type_,
                 text,
                 list_separator=list_separator,
@@ -89,7 +95,7 @@ def parse_text(
             )
         )
     if is_list_type(type_):
-        return _parse_text_list_type(
+        return _parse_object_list_type(
             type_,
             text,
             list_separator=list_separator,
@@ -105,7 +111,7 @@ def parse_text(
             return parse_none(text)
         inner = one(arg for arg in get_args(type_) if arg is not NoneType)
         try:
-            return parse_text(
+            return parse_object(
                 inner,
                 text,
                 list_separator=list_separator,
@@ -114,10 +120,10 @@ def parse_text(
                 case_sensitive=case_sensitive,
                 extra=extra,
             )
-        except _ParseTextParseError:
-            raise _ParseTextParseError(type_=type_, text=text) from None
+        except _ParseObjectParseError:
+            raise _ParseObjectParseError(type_=type_, text=text) from None
     if is_set_type(type_):
-        return _parse_text_set_type(
+        return _parse_object_set_type(
             type_,
             text,
             list_separator=list_separator,
@@ -127,7 +133,7 @@ def parse_text(
             extra=extra,
         )
     if is_tuple_type(type_):
-        return _parse_text_tuple_type(
+        return _parse_object_tuple_type(
             type_,
             text,
             list_separator=list_separator,
@@ -137,116 +143,116 @@ def parse_text(
             extra=extra,
         )
     if is_union_type(type_):
-        return _parse_text_union_type(type_, text, extra=extra)
-    raise _ParseTextParseError(type_=type_, text=text) from None
+        return _parse_object_union_type(type_, text, extra=extra)
+    raise _ParseObjectParseError(type_=type_, text=text) from None
 
 
-def _parse_text_type(
+def _parse_object_type(
     cls: type[Any],
     text: str,
     /,
     *,
     case_sensitive: bool = False,
-    extra: ParseTextExtra | None = None,
+    extra: ParseObjectExtra | None = None,
 ) -> Any:
     """Parse text."""
     if issubclass(cls, NoneType):
         try:
             return parse_none(text)
         except ParseNoneError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, str):
         return text
     if issubclass(cls, bool):
         try:
             return parse_bool(text)
         except ParseBoolError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if is_subclass_int_not_bool(cls):
         try:
             return int(text)
         except ValueError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, float):
         try:
             return float(text)
         except ValueError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, Enum):
         try:
             return parse_enum(text, cls, case_sensitive=case_sensitive)
         except ParseEnumError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, Path):
         return Path(text).expanduser()
     if issubclass(cls, Sentinel):
         try:
             return parse_sentinel(text)
         except ParseSentinelError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, Version):
         try:
             return parse_version(text)
         except ParseVersionError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if is_subclass_date_not_datetime(cls):
         from utilities.whenever import ParseDateError, parse_date
 
         try:
             return parse_date(text)
         except ParseDateError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, dt.datetime):
         from utilities.whenever import ParseDateTimeError, parse_datetime
 
         try:
             return parse_datetime(text)
         except ParseDateTimeError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, dt.time):
         from utilities.whenever import ParseTimeError, parse_time
 
         try:
             return parse_time(text)
         except ParseTimeError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, dt.timedelta):
         from utilities.whenever import ParseTimedeltaError, parse_timedelta
 
         try:
             return parse_timedelta(text)
         except ParseTimedeltaError:
-            raise _ParseTextParseError(type_=cls, text=text) from None
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if extra is not None:
         try:
             parser = one(p for c, p in extra.items() if issubclass(cls, c))
         except OneEmptyError:
             pass
         except OneNonUniqueError as error:
-            raise _ParseTextExtraNonUniqueError(
+            raise _ParseObjectExtraNonUniqueError(
                 type_=cls, text=text, first=error.first, second=error.second
             ) from None
         else:
             return parser(text)
-    raise _ParseTextParseError(type_=cls, text=text) from None
+    raise _ParseObjectParseError(type_=cls, text=text) from None
 
 
-def _parse_text_dict_type(
+def _parse_object_dict_type(
     type_: Any,
     text: str,
     /,
     *,
-    list_separator: str = ",",
-    pair_separator: str = "=",
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
     head: bool = False,
     case_sensitive: bool = False,
-    extra: ParseTextExtra | None = None,
+    extra: ParseObjectExtra | None = None,
 ) -> dict[Any, Any]:
     key_type, value_type = get_args(type_)
     try:
         inner_text = extract_group(r"^{(.*)}$", text, flags=DOTALL)
     except ExtractGroupError:
-        raise _ParseTextParseError(type_=type_, text=text) from None
+        raise _ParseObjectParseError(type_=type_, text=text) from None
     pairs = split_key_value_pairs(
         inner_text,
         list_separator=list_separator,
@@ -254,7 +260,7 @@ def _parse_text_dict_type(
         mapping=True,
     )
     keys = (
-        parse_text(
+        parse_object(
             key_type,
             k,
             list_separator=list_separator,
@@ -266,7 +272,7 @@ def _parse_text_dict_type(
         for k in pairs
     )
     values = (
-        parse_text(
+        parse_object(
             value_type,
             v,
             list_separator=list_separator,
@@ -279,30 +285,30 @@ def _parse_text_dict_type(
     )
     try:
         return dict(zip(keys, values, strict=True))
-    except _ParseTextParseError:
-        raise _ParseTextParseError(type_=type_, text=text) from None
+    except _ParseObjectParseError:
+        raise _ParseObjectParseError(type_=type_, text=text) from None
 
 
-def _parse_text_list_type(
+def _parse_object_list_type(
     type_: Any,
     text: str,
     /,
     *,
-    list_separator: str = ",",
-    pair_separator: str = "=",
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
     head: bool = False,
     case_sensitive: bool = False,
-    extra: ParseTextExtra | None = None,
+    extra: ParseObjectExtra | None = None,
 ) -> list[Any]:
     inner_type = one(get_args(type_))
     try:
         inner_text = extract_group(r"^\[(.*)\]$", text, flags=DOTALL)
     except ExtractGroupError:
-        raise _ParseTextParseError(type_=type_, text=text) from None
+        raise _ParseObjectParseError(type_=type_, text=text) from None
     texts = split_str(inner_text, separator=list_separator)
     try:
         return [
-            parse_text(
+            parse_object(
                 inner_type,
                 t,
                 list_separator=list_separator,
@@ -313,30 +319,30 @@ def _parse_text_list_type(
             )
             for t in texts
         ]
-    except _ParseTextParseError:
-        raise _ParseTextParseError(type_=type_, text=text) from None
+    except _ParseObjectParseError:
+        raise _ParseObjectParseError(type_=type_, text=text) from None
 
 
-def _parse_text_set_type(
+def _parse_object_set_type(
     type_: Any,
     text: str,
     /,
     *,
-    list_separator: str = ",",
-    pair_separator: str = "=",
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
     head: bool = False,
     case_sensitive: bool = False,
-    extra: ParseTextExtra | None = None,
+    extra: ParseObjectExtra | None = None,
 ) -> set[Any]:
     inner_type = one(get_args(type_))
     try:
         inner_text = extract_group(r"^{(.*)}$", text, flags=DOTALL)
     except ExtractGroupError:
-        raise _ParseTextParseError(type_=type_, text=text) from None
+        raise _ParseObjectParseError(type_=type_, text=text) from None
     texts = split_str(inner_text, separator=list_separator)
     try:
         return {
-            parse_text(
+            parse_object(
                 inner_type,
                 t,
                 list_separator=list_separator,
@@ -347,25 +353,25 @@ def _parse_text_set_type(
             )
             for t in texts
         }
-    except _ParseTextParseError:
-        raise _ParseTextParseError(type_=type_, text=text) from None
+    except _ParseObjectParseError:
+        raise _ParseObjectParseError(type_=type_, text=text) from None
 
 
-def _parse_text_union_type(
-    type_: Any, text: str, /, *, extra: ParseTextExtra | None = None
+def _parse_object_union_type(
+    type_: Any, text: str, /, *, extra: ParseObjectExtra | None = None
 ) -> Any:
     if type_ is Number:
         try:
             return parse_number(text)
         except ParseNumberError:
-            raise _ParseTextParseError(type_=type_, text=text) from None
+            raise _ParseObjectParseError(type_=type_, text=text) from None
     if type_ is Duration:
         from utilities.whenever import ParseDurationError, parse_duration
 
         try:
             return parse_duration(text)
         except ParseDurationError:
-            raise _ParseTextParseError(type_=type_, text=text) from None
+            raise _ParseObjectParseError(type_=type_, text=text) from None
     if extra is not None:
         try:
             parser = one(p for c, p in extra.items() if c is type_)
@@ -373,31 +379,31 @@ def _parse_text_union_type(
             pass
         else:
             return parser(text)
-    raise _ParseTextParseError(type_=type_, text=text) from None
+    raise _ParseObjectParseError(type_=type_, text=text) from None
 
 
-def _parse_text_tuple_type(
+def _parse_object_tuple_type(
     type_: Any,
     text: str,
     /,
     *,
-    list_separator: str = ",",
-    pair_separator: str = "=",
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
     head: bool = False,
     case_sensitive: bool = False,
-    extra: ParseTextExtra | None = None,
+    extra: ParseObjectExtra | None = None,
 ) -> tuple[Any, ...]:
     args = get_args(type_)
     try:
         inner = extract_group(r"^\((.*)\)$", text, flags=DOTALL)
     except ExtractGroupError:
-        raise _ParseTextParseError(type_=type_, text=text) from None
-    texts = inner.split(",")
+        raise _ParseObjectParseError(type_=type_, text=text) from None
+    texts = inner.split(list_separator)
     if len(args) != len(texts):
-        raise _ParseTextParseError(type_=type_, text=text)
+        raise _ParseObjectParseError(type_=type_, text=text)
     try:
         return tuple(
-            parse_text(
+            parse_object(
                 arg,
                 text,
                 list_separator=list_separator,
@@ -408,25 +414,25 @@ def _parse_text_tuple_type(
             )
             for arg, text in zip(args, texts, strict=True)
         )
-    except _ParseTextParseError:
-        raise _ParseTextParseError(type_=type_, text=text) from None
+    except _ParseObjectParseError:
+        raise _ParseObjectParseError(type_=type_, text=text) from None
 
 
 @dataclass
-class ParseTextError(Exception):
+class ParseObjectError(Exception):
     type_: Any
     text: str
 
 
 @dataclass
-class _ParseTextParseError(ParseTextError):
+class _ParseObjectParseError(ParseObjectError):
     @override
     def __str__(self) -> str:
         return f"Unable to parse {self.type_!r}; got {self.text!r}"
 
 
 @dataclass
-class _ParseTextExtraNonUniqueError(ParseTextError):
+class _ParseObjectExtraNonUniqueError(ParseObjectError):
     first: type[Any]
     second: type[Any]
 
@@ -438,8 +444,12 @@ class _ParseTextExtraNonUniqueError(ParseTextError):
 ##
 
 
-def to_text(
-    obj: Any, /, *, list_separator: str = ",", pair_separator: str = "="
+def serialize_object(
+    obj: Any,
+    /,
+    *,
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
 ) -> str:
     """Convert an object to text."""
     if (obj is None) or isinstance(
@@ -465,33 +475,41 @@ def to_text(
     if isinstance(obj, Enum):
         return obj.name
     if isinstance(obj, dict):
-        return _to_text_dict(
+        return _serialize_object_dict(
             obj, list_separator=list_separator, pair_separator=pair_separator
         )
     if isinstance(obj, list):
-        return _to_text_list(
+        return _serialize_object_list(
             obj, list_separator=list_separator, pair_separator=pair_separator
         )
     if isinstance(obj, tuple):
-        return _to_text_tuple(
+        return _serialize_object_tuple(
             obj, list_separator=list_separator, pair_separator=pair_separator
         )
     if isinstance(obj, set | frozenset):
-        return _to_text_set(
+        return _serialize_object_set(
             obj, list_separator=list_separator, pair_separator=pair_separator
         )
     raise NotImplementedError(obj)
 
 
-def _to_text_dict(
-    obj: Mapping[Any, Any], /, *, list_separator: str = ",", pair_separator: str = "="
+def _serialize_object_dict(
+    obj: Mapping[Any, Any],
+    /,
+    *,
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
 ) -> str:
     keys = (
-        to_text(k, list_separator=list_separator, pair_separator=pair_separator)
+        serialize_object(
+            k, list_separator=list_separator, pair_separator=pair_separator
+        )
         for k in obj
     )
     values = (
-        to_text(v, list_separator=list_separator, pair_separator=pair_separator)
+        serialize_object(
+            v, list_separator=list_separator, pair_separator=pair_separator
+        )
         for v in obj.values()
     )
     items = zip(keys, values, strict=True)
@@ -500,37 +518,55 @@ def _to_text_dict(
     return f"{{{joined}}}"
 
 
-def _to_text_list(
-    obj: Sequence[Any], /, *, list_separator: str = ",", pair_separator: str = "="
+def _serialize_object_list(
+    obj: Sequence[Any],
+    /,
+    *,
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
 ) -> str:
     items = (
-        to_text(i, list_separator=list_separator, pair_separator=pair_separator)
+        serialize_object(
+            i, list_separator=list_separator, pair_separator=pair_separator
+        )
         for i in obj
     )
     joined = join_strs(items, separator=list_separator)
     return f"[{joined}]"
 
 
-def _to_text_set(
-    obj: AbstractSet[Any], /, *, list_separator: str = ",", pair_separator: str = "="
+def _serialize_object_set(
+    obj: AbstractSet[Any],
+    /,
+    *,
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
 ) -> str:
     items = (
-        to_text(i, list_separator=list_separator, pair_separator=pair_separator)
+        serialize_object(
+            i, list_separator=list_separator, pair_separator=pair_separator
+        )
         for i in obj
     )
     joined = join_strs(items, sort=True, separator=list_separator)
     return f"{{{joined}}}"
 
 
-def _to_text_tuple(
-    obj: tuple[Any, ...], /, *, list_separator: str = ",", pair_separator: str = "="
+def _serialize_object_tuple(
+    obj: tuple[Any, ...],
+    /,
+    *,
+    list_separator: str = LIST_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
 ) -> str:
     items = (
-        to_text(i, list_separator=list_separator, pair_separator=pair_separator)
+        serialize_object(
+            i, list_separator=list_separator, pair_separator=pair_separator
+        )
         for i in obj
     )
     joined = join_strs(items, separator=list_separator)
     return f"({joined})"
 
 
-__all__ = ["parse_text"]
+__all__ = ["LIST_SEPARATOR", "PAIR_SEPARATOR", "parse_object", "serialize_object"]

utilities/python_dotenv.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, override
 
 from dotenv import dotenv_values
 
-from utilities.dataclasses import MappingToDataclassError, text_to_dataclass
+from utilities.dataclasses import MappingToDataclassError, parse_dataclass
 from utilities.git import get_repo_root
 from utilities.iterables import MergeStrMappingsError, merge_str_mappings
 from utilities.pathlib import PWD
@@ -17,7 +17,7 @@ if TYPE_CHECKING:
     from collections.abc import Set as AbstractSet
     from pathlib import Path
 
-    from utilities.types import ParseTextExtra, PathLike, StrMapping, TDataclass
+    from utilities.types import ParseObjectExtra, PathLike, StrMapping, TDataclass
 
 
 def load_settings(
@@ -30,7 +30,7 @@ def load_settings(
     warn_name_errors: bool = False,
     head: bool = False,
     case_sensitive: bool = False,
-    extra_parsers: ParseTextExtra | None = None,
+    extra_parsers: ParseObjectExtra | None = None,
 ) -> TDataclass:
     """Load a set of settings from the `.env` file."""
     path = get_repo_root(cwd=cwd).joinpath(".env")
@@ -50,7 +50,7 @@ def load_settings(
         ) from None
     values = {k: v for k, v in maybe_values.items() if v is not None}
     try:
-        return text_to_dataclass(
+        return parse_dataclass(
             values,
             cls,
             globalns=globalns,

utilities/types.py

@@ -231,7 +231,7 @@ class SupportsRound(Protocol[_T_co]):
 
 
 # parse
-type ParseTextExtra = Mapping[Any, Callable[[str], Any]]
+type ParseObjectExtra = Mapping[Any, Callable[[str], Any]]
 
 
 # pathlib
@@ -283,7 +283,7 @@ __all__ = [
     "OpenMode",
     "OptExcInfo",
     "Parallelism",
-    "ParseTextExtra",
+    "ParseObjectExtra",
     "PathLike",
     "PathLikeOrCallable",
     "RoundMode",