dycw-utilities 0.110.2__py3-none-any.whl → 0.110.4__py3-none-any.whl

{dycw_utilities-0.110.2.dist-info → dycw_utilities-0.110.4.dist-info}/METADATA

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

{dycw_utilities-0.110.2.dist-info → dycw_utilities-0.110.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=N5L_-mBy__dabTcP63GXeZ0UmhNEqKjJ0SR5XKVgg5Y,60
+utilities/__init__.py,sha256=jGUTgOEiXSlv_bOz8eQW5saCU2Pq4oTqEXt6FeWlFII,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=e2YuCj1DF4eecFFxsu20MknghXJ4SNkWCmbIAOXXr18,25942
+utilities/dataclasses.py,sha256=Q197PVnE_vUMn_SNnqJBCo4eRy4bdHtgMHWRbSJPtFk,26670
 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=wxqh4YwBfQ7nm249-F_6uqiLo1js9_xji9AVvUxZ5nI,17091
+utilities/parse.py,sha256=6erE2TpZP-z0FWtxnnDVO3-X1d1MHoNrr2IYiaJEuk8,18960
 utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=ikHXsWtDLr553cfH6p9mMaiCnIAP69B7q84ckWV3HaA,10884
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
@@ -73,11 +73,11 @@ utilities/streamlit.py,sha256=U9PJBaKP1IdSykKhPZhIzSPTZsmLsnwbEPZWzNhJPKk,2955
 utilities/sys.py,sha256=h0Xr7Vj86wNalvwJVP1wj5Y0kD_VWm1vzuXZ_jw94mE,2743
 utilities/tempfile.py,sha256=VqmZJAhTJ1OaVywFzk5eqROV8iJbW9XQ_QYAV0bpdRo,1384
 utilities/tenacity.py,sha256=1PUvODiBVgeqIh7G5TRt5WWMSqjLYkEqP53itT97WQc,4914
-utilities/text.py,sha256=VcNAJtjA2BOGEVY6yXnC9UIAsgECgiWCQ_QnpilZV2o,10089
+utilities/text.py,sha256=hfcBKF22fKT6s_U-ZdP-g5TjFQ0-NrIrQdvIwERWT80,10971
 utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=Rkc49KSpHuC8s7vUxGO9DU55U9I6yDKnchsQqrUCVBs,4075
 utilities/traceback.py,sha256=KwHPLdEbdj0fFhXo8MBfxcvem8A-VXYDwFMNJ6f0cTM,27328
-utilities/types.py,sha256=Hi9aKaxN3G9zFVlLjx6U9xd_HMGq-eqHLxmG1cSdVpg,17967
+utilities/types.py,sha256=PZjxTCDYSPFKppi3ZWnSh441mv0rgEvZkh8npqL6awo,18064
 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.110.2.dist-info/METADATA,sha256=TK9SINDsRCnIKjF2YyzOvlQ5mTpD1hjJJ6SD_aNKFI4,13004
-dycw_utilities-0.110.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.110.2.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.110.2.dist-info/RECORD,,
+dycw_utilities-0.110.4.dist-info/METADATA,sha256=N7v2g5hRFwzAbpEjcnZs0OZQhPZPECwQHsevYVzsXZg,13004
+dycw_utilities-0.110.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.110.4.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.110.4.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.110.2"
+__version__ = "0.110.4"

utilities/dataclasses.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
+from contextlib import suppress
 from dataclasses import MISSING, dataclass, field, fields, replace
 from typing import (
     TYPE_CHECKING,
@@ -21,21 +22,23 @@ from utilities.functions import (
 )
 from utilities.iterables import OneStrEmptyError, OneStrNonUniqueError, one_str
 from utilities.operator import is_equal
-from utilities.parse import (
-    LIST_SEPARATOR,
-    PAIR_SEPARATOR,
-    ParseObjectError,
-    parse_object,
-    serialize_object,
-)
+from utilities.parse import ParseObjectError, parse_object, serialize_object
+from utilities.re import ExtractGroupError, extract_group
 from utilities.sentinel import Sentinel, sentinel
 from utilities.text import (
+    BRACKETS,
+    LIST_SEPARATOR,
+    PAIR_SEPARATOR,
     _SplitKeyValuePairsDuplicateKeysError,
     _SplitKeyValuePairsSplitError,
-    join_strs,
     split_key_value_pairs,
 )
-from utilities.types import ParseObjectExtra, StrStrMapping, TDataclass
+from utilities.types import (
+    ParseObjectExtra,
+    SerializeObjectExtra,
+    StrStrMapping,
+    TDataclass,
+)
 from utilities.typing import get_type_hints
 
 if TYPE_CHECKING:
@@ -408,10 +411,11 @@ def serialize_dataclass(
     exclude: Iterable[str] | None = None,
     rel_tol: float | None = None,
     abs_tol: float | None = None,
-    extra: Mapping[type[_U], Callable[[_U, _U], bool]] | None = None,
+    extra_equal: Mapping[type[_U], Callable[[_U, _U], bool]] | None = None,
     defaults: bool = False,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
+    extra_serializers: SerializeObjectExtra | None = None,
 ) -> str:
     """Serialize a Dataclass."""
     mapping: StrStrMapping = {}
@@ -426,16 +430,21 @@ def serialize_dataclass(
             exclude=exclude,
             rel_tol=rel_tol,
             abs_tol=abs_tol,
-            extra=extra,
+            extra=extra_equal,
             defaults=defaults,
         ):
             mapping[fld.name] = serialize_object(
-                fld.value, list_separator=list_separator, pair_separator=pair_separator
+                fld.value,
+                list_separator=list_separator,
+                pair_separator=pair_separator,
+                extra=extra_serializers,
             )
-    joined_items = (
-        join_strs(item, separator=pair_separator) for item in mapping.items()
+    return serialize_object(
+        mapping,
+        list_separator=list_separator,
+        pair_separator=pair_separator,
+        extra=extra_serializers,
     )
-    return join_strs(joined_items, separator=list_separator)
 
 
 def parse_dataclass(
@@ -445,6 +454,7 @@ def parse_dataclass(
     *,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
     warn_name_errors: bool = False,
@@ -457,7 +467,11 @@ def parse_dataclass(
     match text_or_mapping:
         case str() as text:
             keys_to_serializes = _parse_dataclass_split_key_value_pairs(
-                text, cls, list_separator=list_separator, pair_separator=pair_separator
+                text,
+                cls,
+                list_separator=list_separator,
+                pair_separator=pair_separator,
+                brackets=brackets,
             )
         case Mapping() as keys_to_serializes:
             ...
@@ -481,7 +495,14 @@ def parse_dataclass(
     )
     field_names_to_values = {
         f.name: _parse_dataclass_parse_text(
-            f, t, cls, head=head, case_sensitive=case_sensitive, extra=extra_parsers
+            f,
+            t,
+            cls,
+            list_separator=list_separator,
+            pair_separator=pair_separator,
+            head=head,
+            case_sensitive=case_sensitive,
+            extra=extra_parsers,
         )
         for f, t in fields_to_serializes.items()
     }
@@ -505,12 +526,16 @@ def _parse_dataclass_split_key_value_pairs(
     *,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
 ) -> StrStrMapping:
+    with suppress(ExtractGroupError):
+        text = extract_group(r"^\{?(.*?)\}?$", text)
     try:
         return split_key_value_pairs(
             text,
             list_separator=list_separator,
             pair_separator=pair_separator,
+            brackets=brackets,
             mapping=True,
         )
     except _SplitKeyValuePairsSplitError as error:

utilities/parse.py

@@ -20,6 +20,9 @@ from utilities.math import ParseNumberError, parse_number
 from utilities.re import ExtractGroupError, extract_group
 from utilities.sentinel import ParseSentinelError, Sentinel, parse_sentinel
 from utilities.text import (
+    BRACKETS,
+    LIST_SEPARATOR,
+    PAIR_SEPARATOR,
     ParseBoolError,
     ParseNoneError,
     join_strs,
@@ -28,7 +31,7 @@ from utilities.text import (
     split_key_value_pairs,
     split_str,
 )
-from utilities.types import Duration, Number, ParseObjectExtra
+from utilities.types import Duration, Number, ParseObjectExtra, SerializeObjectExtra
 from utilities.typing import (
     get_args,
     is_dict_type,
@@ -43,14 +46,10 @@ from utilities.typing import (
 from utilities.version import ParseVersionError, Version, parse_version
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping, Sequence
+    from collections.abc import Iterable, Mapping, Sequence
     from collections.abc import Set as AbstractSet
 
 
-LIST_SEPARATOR = ","
-PAIR_SEPARATOR = "="
-
-
 def parse_object(
     type_: Any,
     text: str,
@@ -58,6 +57,7 @@ def parse_object(
     *,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     head: bool = False,
     case_sensitive: bool = False,
     extra: ParseObjectExtra | None = None,
@@ -78,6 +78,7 @@ def parse_object(
             text,
             list_separator=list_separator,
             pair_separator=pair_separator,
+            brackets=brackets,
             head=head,
             case_sensitive=case_sensitive,
             extra=extra,
@@ -89,6 +90,7 @@ def parse_object(
                 text,
                 list_separator=list_separator,
                 pair_separator=pair_separator,
+                brackets=brackets,
                 head=head,
                 case_sensitive=case_sensitive,
                 extra=extra,
@@ -100,6 +102,7 @@ def parse_object(
             text,
             list_separator=list_separator,
             pair_separator=pair_separator,
+            brackets=brackets,
             head=head,
             case_sensitive=case_sensitive,
             extra=extra,
@@ -116,6 +119,7 @@ def parse_object(
                 text,
                 list_separator=list_separator,
                 pair_separator=pair_separator,
+                brackets=brackets,
                 head=head,
                 case_sensitive=case_sensitive,
                 extra=extra,
@@ -128,6 +132,7 @@ def parse_object(
             text,
             list_separator=list_separator,
             pair_separator=pair_separator,
+            brackets=brackets,
             head=head,
             case_sensitive=case_sensitive,
             extra=extra,
@@ -138,6 +143,7 @@ def parse_object(
             text,
             list_separator=list_separator,
             pair_separator=pair_separator,
+            brackets=brackets,
             head=head,
             case_sensitive=case_sensitive,
             extra=extra,
@@ -234,7 +240,7 @@ def _parse_object_type(
             ) from None
         else:
             return parser(text)
-    raise _ParseObjectParseError(type_=cls, text=text) from None
+    raise _ParseObjectParseError(type_=cls, text=text)
 
 
 def _parse_object_dict_type(
@@ -244,6 +250,7 @@ def _parse_object_dict_type(
     *,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     head: bool = False,
     case_sensitive: bool = False,
     extra: ParseObjectExtra | None = None,
@@ -257,6 +264,7 @@ def _parse_object_dict_type(
         inner_text,
         list_separator=list_separator,
         pair_separator=pair_separator,
+        brackets=brackets,
         mapping=True,
     )
     keys = (
@@ -265,6 +273,7 @@ def _parse_object_dict_type(
             k,
             list_separator=list_separator,
             pair_separator=pair_separator,
+            brackets=brackets,
             head=head,
             case_sensitive=case_sensitive,
             extra=extra,
@@ -277,6 +286,7 @@ def _parse_object_dict_type(
             v,
             list_separator=list_separator,
             pair_separator=pair_separator,
+            brackets=brackets,
             head=head,
             case_sensitive=case_sensitive,
             extra=extra,
@@ -296,6 +306,7 @@ def _parse_object_list_type(
     *,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     head: bool = False,
     case_sensitive: bool = False,
     extra: ParseObjectExtra | None = None,
@@ -313,6 +324,7 @@ def _parse_object_list_type(
                 t,
                 list_separator=list_separator,
                 pair_separator=pair_separator,
+                brackets=brackets,
                 head=head,
                 case_sensitive=case_sensitive,
                 extra=extra,
@@ -330,6 +342,7 @@ def _parse_object_set_type(
     *,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     head: bool = False,
     case_sensitive: bool = False,
     extra: ParseObjectExtra | None = None,
@@ -347,6 +360,7 @@ def _parse_object_set_type(
                 t,
                 list_separator=list_separator,
                 pair_separator=pair_separator,
+                brackets=brackets,
                 head=head,
                 case_sensitive=case_sensitive,
                 extra=extra,
@@ -389,6 +403,7 @@ def _parse_object_tuple_type(
     *,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     head: bool = False,
     case_sensitive: bool = False,
     extra: ParseObjectExtra | None = None,
@@ -408,6 +423,7 @@ def _parse_object_tuple_type(
                 text,
                 list_separator=list_separator,
                 pair_separator=pair_separator,
+                brackets=brackets,
                 head=head,
                 case_sensitive=case_sensitive,
                 extra=extra,
@@ -450,6 +466,7 @@ def serialize_object(
     *,
     list_separator: str = LIST_SEPARATOR,
     pair_separator: str = PAIR_SEPARATOR,
+    extra: SerializeObjectExtra | None = None,
 ) -> str:
     """Convert an object to text."""
     if (obj is None) or isinstance(
@@ -490,7 +507,9 @@ def serialize_object(
         return _serialize_object_set(
             obj, list_separator=list_separator, pair_separator=pair_separator
         )
-    raise NotImplementedError(obj)
+    if extra is not None:
+        return _serialize_object_extra(obj, extra)
+    raise _SerializeObjectSerializeError(obj=obj)
 
 
 def _serialize_object_dict(
@@ -518,6 +537,19 @@ def _serialize_object_dict(
     return f"{{{joined}}}"
 
 
+def _serialize_object_extra(obj: Any, extra: SerializeObjectExtra, /) -> str:
+    try:
+        serializer = one(s for c, s in extra.items() if isinstance(obj, c))
+    except OneEmptyError:
+        raise _SerializeObjectSerializeError(obj=obj) from None
+    except OneNonUniqueError as error:
+        raise _SerializeObjectExtraNonUniqueError(
+            obj=obj, first=error.first, second=error.second
+        ) from None
+    else:
+        return serializer(obj)
+
+
 def _serialize_object_list(
     obj: Sequence[Any],
     /,
@@ -569,4 +601,25 @@ def _serialize_object_tuple(
     return f"({joined})"
 
 
-__all__ = ["LIST_SEPARATOR", "PAIR_SEPARATOR", "parse_object", "serialize_object"]
+@dataclass(kw_only=True, slots=True)
+class SerializeObjectError(Exception):
+    obj: Any
+
+
+class _SerializeObjectSerializeError(SerializeObjectError):
+    @override
+    def __str__(self) -> str:
+        return f"Unable to serialize object {self.obj!r}"
+
+
+@dataclass
+class _SerializeObjectExtraNonUniqueError(SerializeObjectError):
+    first: type[Any]
+    second: type[Any]
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to serialize object {self.obj!r} since `extra` must contain exactly one parent class; got {self.first!r}, {self.second!r} and perhaps more"
+
+
+__all__ = ["parse_object", "serialize_object"]

utilities/text.py

@@ -17,6 +17,12 @@ if TYPE_CHECKING:
     from utilities.types import StrStrMapping
 
 
+DEFAULT_SEPARATOR = ","
+
+
+##
+
+
 def parse_bool(text: str, /) -> bool:
     """Parse text into a boolean value."""
     if text == "0" or search("false", text, flags=IGNORECASE):
@@ -88,13 +94,19 @@ def _snake_case_title(match: Match[str], /) -> str:
 ##
 
 
+LIST_SEPARATOR = DEFAULT_SEPARATOR
+PAIR_SEPARATOR = "="
+BRACKETS = [("(", ")"), ("[", "]"), ("{", "}")]
+
+
 @overload
 def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = ",",
-    pair_separator: str = "=",
+    list_separator: str = DEFAULT_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: Literal[True],
 ) -> StrStrMapping: ...
 @overload
@@ -102,8 +114,9 @@ def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = ",",
-    pair_separator: str = "=",
+    list_separator: str = DEFAULT_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: Literal[False] = False,
 ) -> Sequence[tuple[str, str]]: ...
 @overload
@@ -111,23 +124,29 @@ def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = ",",
-    pair_separator: str = "=",
+    list_separator: str = DEFAULT_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: bool = False,
 ) -> Sequence[tuple[str, str]] | StrStrMapping: ...
 def split_key_value_pairs(
     text: str,
     /,
     *,
-    list_separator: str = ",",
-    pair_separator: str = "=",
+    list_separator: str = DEFAULT_SEPARATOR,
+    pair_separator: str = PAIR_SEPARATOR,
+    brackets: Iterable[tuple[str, str]] | None = BRACKETS,
     mapping: bool = False,
 ) -> Sequence[tuple[str, str]] | StrStrMapping:
     """Split a string into key-value pairs."""
+    try:
+        texts = split_str(text, separator=list_separator, brackets=brackets)
+    except SplitStrError as error:
+        raise _SplitKeyValuePairsSplitError(text=text, inner=error.text) from None
     try:
         pairs = [
-            split_str(text_i, separator=pair_separator, n=2)
-            for text_i in split_str(text, separator=list_separator)
+            split_str(text_i, separator=pair_separator, brackets=brackets, n=2)
+            for text_i in texts
         ]
     except SplitStrError as error:
         raise _SplitKeyValuePairsSplitError(text=text, inner=error.text) from None
@@ -153,7 +172,7 @@ class _SplitKeyValuePairsSplitError(SplitKeyValuePairsError):
 
     @override
     def __str__(self) -> str:
-        return f"Unable to split {self.text!r} into key-value pairs; got {self.inner!r}"
+        return f"Unable to split {self.text!r} into key-value pairs"
 
 
 @dataclass(kw_only=True, slots=True)
@@ -173,7 +192,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = ",",
+    separator: str = DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[1],
 ) -> tuple[str]: ...
@@ -182,7 +201,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = ",",
+    separator: str = DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[2],
 ) -> tuple[str, str]: ...
@@ -191,7 +210,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = ",",
+    separator: str = DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[3],
 ) -> tuple[str, str, str]: ...
@@ -200,7 +219,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = ",",
+    separator: str = DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[4],
 ) -> tuple[str, str, str, str]: ...
@@ -209,7 +228,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = ",",
+    separator: str = DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: Literal[5],
 ) -> tuple[str, str, str, str, str]: ...
@@ -218,7 +237,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = ",",
+    separator: str = DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: int | None = None,
 ) -> Sequence[str]: ...
@@ -226,7 +245,7 @@ def split_str(
     text: str,
     /,
     *,
-    separator: str = ",",
+    separator: str = DEFAULT_SEPARATOR,
     brackets: Iterable[tuple[str, str]] | None = None,
     n: int | None = None,
 ) -> Sequence[str]:
@@ -247,7 +266,11 @@ def split_str(
 
 
 def _split_str_brackets(
-    text: str, brackets: Iterable[tuple[str, str]], /, *, separator: str = ","
+    text: str,
+    brackets: Iterable[tuple[str, str]],
+    /,
+    *,
+    separator: str = DEFAULT_SEPARATOR,
 ) -> Sequence[str]:
     brackets = list(brackets)
     opens, closes = transpose(brackets)
@@ -338,7 +361,7 @@ class _SplitStrOpeningBracketUnmatchedError(SplitStrError):
 
 
 def join_strs(
-    texts: Iterable[str], /, *, sort: bool = False, separator: str = ","
+    texts: Iterable[str], /, *, sort: bool = False, separator: str = DEFAULT_SEPARATOR
 ) -> str:
     """Join a collection of strings, with a special provision for the empty list."""
     texts = list(texts)
@@ -351,7 +374,7 @@ def join_strs(
     return separator.join(texts)
 
 
-def _escape_separator(*, separator: str = ",") -> str:
+def _escape_separator(*, separator: str = DEFAULT_SEPARATOR) -> str:
     return f"\\{separator}"
 
 
@@ -373,6 +396,10 @@ def strip_and_dedent(text: str, /, *, trailing: bool = False) -> str:
 
 
 __all__ = [
+    "BRACKETS",
+    "DEFAULT_SEPARATOR",
+    "LIST_SEPARATOR",
+    "PAIR_SEPARATOR",
     "ParseBoolError",
     "ParseNoneError",
     "SplitKeyValuePairsError",

utilities/types.py

@@ -232,6 +232,7 @@ class SupportsRound(Protocol[_T_co]):
 
 # parse
 type ParseObjectExtra = Mapping[Any, Callable[[str], Any]]
+type SerializeObjectExtra = Mapping[type[Any], Callable[[Any], str]]
 
 
 # pathlib
@@ -288,6 +289,7 @@ __all__ = [
     "PathLikeOrCallable",
     "RoundMode",
     "Seed",
+    "SerializeObjectExtra",
     "StrMapping",
     "StrStrMapping",
     "SupportsAbs",