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

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

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

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

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=slpwNiDikjtNehM2JREvjZjOsOKdf-wqmlj9BocXPYI,61
+utilities/__init__.py,sha256=AIZiPdrHMOKkgJqoeU29sMxSZXZMURdyCYzqvmBulyI,61
 utilities/altair.py,sha256=Gpja-flOo-Db0PIPJLJsgzAlXWoKUjPU1qY-DQ829ek,9156
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
 utilities/asyncio.py,sha256=41oQUurWMvadFK5gFnaG21hMM0Vmfn2WS6OpC0R9mas,14757
@@ -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=D1rqqrULV1FkjnCZS6804Io26_AZbMrsEILf-pZGNzw,7192
+utilities/parse.py,sha256=l8W5ik1CvmPEsas-dB7cS5gCKpeyr0hQDtjZqI-9azI,16283
 utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=ikHXsWtDLr553cfH6p9mMaiCnIAP69B7q84ckWV3HaA,10884
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
@@ -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.27.dist-info/METADATA,sha256=w37gHaQA-n4cnvJvqkxAoWdEsIbL6Ycj_IgjBhds7G0,13005
-dycw_utilities-0.109.27.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.109.27.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.109.27.dist-info/RECORD,,
+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,,

utilities/__init__.py

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

utilities/parse.py

@@ -7,71 +7,138 @@ from enum import Enum
 from pathlib import Path
 from re import DOTALL
 from types import NoneType
-from typing import Any, override
+from typing import TYPE_CHECKING, Any, override
 
-from utilities.datetime import is_subclass_date_not_datetime
+from utilities.datetime import (
+    is_instance_date_not_datetime,
+    is_subclass_date_not_datetime,
+)
 from utilities.enum import ParseEnumError, parse_enum
 from utilities.functions import is_subclass_int_not_bool
 from utilities.iterables import OneEmptyError, OneNonUniqueError, one, one_str
 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 ParseBoolError, ParseNoneError, parse_bool, parse_none
+from utilities.text import (
+    ParseBoolError,
+    ParseNoneError,
+    join_strs,
+    parse_bool,
+    parse_none,
+    split_key_value_pairs,
+    split_str,
+)
 from utilities.types import Duration, Number, ParseTextExtra
 from utilities.typing import (
     get_args,
+    is_dict_type,
+    is_frozenset_type,
+    is_list_type,
     is_literal_type,
     is_optional_type,
+    is_set_type,
     is_tuple_type,
     is_union_type,
 )
 from utilities.version import ParseVersionError, Version, parse_version
 
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from collections.abc import Set as AbstractSet
+
 
 def parse_text(
-    obj: Any,
+    type_: Any,
     text: str,
     /,
     *,
+    list_separator: str = ",",
+    pair_separator: str = "=",
     head: bool = False,
     case_sensitive: bool = False,
     extra: ParseTextExtra | None = None,
 ) -> Any:
     """Parse text."""
-    if obj is None:
+    if type_ is None:
         try:
             return parse_none(text)
         except ParseNoneError:
-            raise _ParseTextParseError(obj=obj, text=text) from None
-    if isinstance(obj, type):
-        return _parse_text_type(obj, text, case_sensitive=case_sensitive, extra=extra)
-    if is_literal_type(obj):
-        return one_str(get_args(obj), text, head=head, case_sensitive=case_sensitive)
-    if is_optional_type(obj):
+            raise _ParseTextParseError(type_=type_, text=text) from None
+    if isinstance(type_, type):
+        return _parse_text_type(type_, text, case_sensitive=case_sensitive, extra=extra)
+    if is_dict_type(type_):
+        return _parse_text_dict_type(
+            type_,
+            text,
+            list_separator=list_separator,
+            pair_separator=pair_separator,
+            head=head,
+            case_sensitive=case_sensitive,
+            extra=extra,
+        )
+    if is_frozenset_type(type_):
+        return frozenset(
+            _parse_text_set_type(
+                type_,
+                text,
+                list_separator=list_separator,
+                pair_separator=pair_separator,
+                head=head,
+                case_sensitive=case_sensitive,
+                extra=extra,
+            )
+        )
+    if is_list_type(type_):
+        return _parse_text_list_type(
+            type_,
+            text,
+            list_separator=list_separator,
+            pair_separator=pair_separator,
+            head=head,
+            case_sensitive=case_sensitive,
+            extra=extra,
+        )
+    if is_literal_type(type_):
+        return one_str(get_args(type_), text, head=head, case_sensitive=case_sensitive)
+    if is_optional_type(type_):
         with suppress(ParseNoneError):
             return parse_none(text)
-        inner = one(arg for arg in get_args(obj) if arg is not NoneType)
+        inner = one(arg for arg in get_args(type_) if arg is not NoneType)
         try:
             return parse_text(
-                inner, text, head=head, case_sensitive=case_sensitive, extra=extra
+                inner,
+                text,
+                list_separator=list_separator,
+                pair_separator=pair_separator,
+                head=head,
+                case_sensitive=case_sensitive,
+                extra=extra,
             )
         except _ParseTextParseError:
-            raise _ParseTextParseError(obj=obj, text=text) from None
-    if is_tuple_type(obj):
-        args = get_args(obj)
-        try:
-            texts = extract_group(r"^\((.*)\)$", text, flags=DOTALL).split(", ")
-        except ExtractGroupError:
-            raise _ParseTextParseError(obj=obj, text=text) from None
-        if len(args) != len(texts):
-            raise _ParseTextParseError(obj=obj, text=text)
-        return tuple(
-            parse_text(arg, text, head=head, case_sensitive=case_sensitive, extra=extra)
-            for arg, text in zip(args, texts, strict=True)
+            raise _ParseTextParseError(type_=type_, text=text) from None
+    if is_set_type(type_):
+        return _parse_text_set_type(
+            type_,
+            text,
+            list_separator=list_separator,
+            pair_separator=pair_separator,
+            head=head,
+            case_sensitive=case_sensitive,
+            extra=extra,
         )
-    if is_union_type(obj):
-        return _parse_text_union_type(obj, text, extra=extra)
-    raise _ParseTextParseError(obj=obj, text=text) from None
+    if is_tuple_type(type_):
+        return _parse_text_tuple_type(
+            type_,
+            text,
+            list_separator=list_separator,
+            pair_separator=pair_separator,
+            head=head,
+            case_sensitive=case_sensitive,
+            extra=extra,
+        )
+    if is_union_type(type_):
+        return _parse_text_union_type(type_, text, extra=extra)
+    raise _ParseTextParseError(type_=type_, text=text) from None
 
 
 def _parse_text_type(
@@ -87,69 +154,69 @@ def _parse_text_type(
         try:
             return parse_none(text)
         except ParseNoneError:
-            raise _ParseTextParseError(obj=cls, text=text) from None
+            raise _ParseTextParseError(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(obj=cls, text=text) from None
+            raise _ParseTextParseError(type_=cls, text=text) from None
     if is_subclass_int_not_bool(cls):
         try:
             return int(text)
         except ValueError:
-            raise _ParseTextParseError(obj=cls, text=text) from None
+            raise _ParseTextParseError(type_=cls, text=text) from None
     if issubclass(cls, float):
         try:
             return float(text)
         except ValueError:
-            raise _ParseTextParseError(obj=cls, text=text) from None
+            raise _ParseTextParseError(type_=cls, text=text) from None
     if issubclass(cls, Enum):
         try:
             return parse_enum(text, cls, case_sensitive=case_sensitive)
         except ParseEnumError:
-            raise _ParseTextParseError(obj=cls, text=text) from None
+            raise _ParseTextParseError(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(obj=cls, text=text) from None
+            raise _ParseTextParseError(type_=cls, text=text) from None
     if issubclass(cls, Version):
         try:
             return parse_version(text)
         except ParseVersionError:
-            raise _ParseTextParseError(obj=cls, text=text) from None
+            raise _ParseTextParseError(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(obj=cls, text=text) from None
+            raise _ParseTextParseError(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(obj=cls, text=text) from None
+            raise _ParseTextParseError(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(obj=cls, text=text) from None
+            raise _ParseTextParseError(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(obj=cls, text=text) from None
+            raise _ParseTextParseError(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))
@@ -157,41 +224,197 @@ def _parse_text_type(
             pass
         except OneNonUniqueError as error:
             raise _ParseTextExtraNonUniqueError(
-                obj=cls, text=text, first=error.first, second=error.second
+                type_=cls, text=text, first=error.first, second=error.second
             ) from None
         else:
             return parser(text)
-    raise _ParseTextParseError(obj=cls, text=text) from None
+    raise _ParseTextParseError(type_=cls, text=text) from None
+
+
+def _parse_text_dict_type(
+    type_: Any,
+    text: str,
+    /,
+    *,
+    list_separator: str = ",",
+    pair_separator: str = "=",
+    head: bool = False,
+    case_sensitive: bool = False,
+    extra: ParseTextExtra | 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
+    pairs = split_key_value_pairs(
+        inner_text,
+        list_separator=list_separator,
+        pair_separator=pair_separator,
+        mapping=True,
+    )
+    keys = (
+        parse_text(
+            key_type,
+            k,
+            list_separator=list_separator,
+            pair_separator=pair_separator,
+            head=head,
+            case_sensitive=case_sensitive,
+            extra=extra,
+        )
+        for k in pairs
+    )
+    values = (
+        parse_text(
+            value_type,
+            v,
+            list_separator=list_separator,
+            pair_separator=pair_separator,
+            head=head,
+            case_sensitive=case_sensitive,
+            extra=extra,
+        )
+        for v in pairs.values()
+    )
+    try:
+        return dict(zip(keys, values, strict=True))
+    except _ParseTextParseError:
+        raise _ParseTextParseError(type_=type_, text=text) from None
+
+
+def _parse_text_list_type(
+    type_: Any,
+    text: str,
+    /,
+    *,
+    list_separator: str = ",",
+    pair_separator: str = "=",
+    head: bool = False,
+    case_sensitive: bool = False,
+    extra: ParseTextExtra | 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
+    texts = split_str(inner_text, separator=list_separator)
+    try:
+        return [
+            parse_text(
+                inner_type,
+                t,
+                list_separator=list_separator,
+                pair_separator=pair_separator,
+                head=head,
+                case_sensitive=case_sensitive,
+                extra=extra,
+            )
+            for t in texts
+        ]
+    except _ParseTextParseError:
+        raise _ParseTextParseError(type_=type_, text=text) from None
+
+
+def _parse_text_set_type(
+    type_: Any,
+    text: str,
+    /,
+    *,
+    list_separator: str = ",",
+    pair_separator: str = "=",
+    head: bool = False,
+    case_sensitive: bool = False,
+    extra: ParseTextExtra | 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
+    texts = split_str(inner_text, separator=list_separator)
+    try:
+        return {
+            parse_text(
+                inner_type,
+                t,
+                list_separator=list_separator,
+                pair_separator=pair_separator,
+                head=head,
+                case_sensitive=case_sensitive,
+                extra=extra,
+            )
+            for t in texts
+        }
+    except _ParseTextParseError:
+        raise _ParseTextParseError(type_=type_, text=text) from None
 
 
 def _parse_text_union_type(
-    obj: Any, text: str, /, *, extra: ParseTextExtra | None = None
+    type_: Any, text: str, /, *, extra: ParseTextExtra | None = None
 ) -> Any:
-    if obj is Number:
+    if type_ is Number:
         try:
             return parse_number(text)
         except ParseNumberError:
-            raise _ParseTextParseError(obj=obj, text=text) from None
-    if obj is Duration:
+            raise _ParseTextParseError(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(obj=obj, text=text) from None
+            raise _ParseTextParseError(type_=type_, text=text) from None
     if extra is not None:
         try:
-            parser = one(p for c, p in extra.items() if c is obj)
+            parser = one(p for c, p in extra.items() if c is type_)
         except OneEmptyError:
             pass
         else:
             return parser(text)
-    raise _ParseTextParseError(obj=obj, text=text) from None
+    raise _ParseTextParseError(type_=type_, text=text) from None
+
+
+def _parse_text_tuple_type(
+    type_: Any,
+    text: str,
+    /,
+    *,
+    list_separator: str = ",",
+    pair_separator: str = "=",
+    head: bool = False,
+    case_sensitive: bool = False,
+    extra: ParseTextExtra | 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(",")
+    if len(args) != len(texts):
+        raise _ParseTextParseError(type_=type_, text=text)
+    try:
+        return tuple(
+            parse_text(
+                arg,
+                text,
+                list_separator=list_separator,
+                pair_separator=pair_separator,
+                head=head,
+                case_sensitive=case_sensitive,
+                extra=extra,
+            )
+            for arg, text in zip(args, texts, strict=True)
+        )
+    except _ParseTextParseError:
+        raise _ParseTextParseError(type_=type_, text=text) from None
 
 
 @dataclass
 class ParseTextError(Exception):
-    obj: Any
+    type_: Any
     text: str
 
 
@@ -199,7 +422,7 @@ class ParseTextError(Exception):
 class _ParseTextParseError(ParseTextError):
     @override
     def __str__(self) -> str:
-        return f"Unable to parse {self.obj!r}; got {self.text!r}"
+        return f"Unable to parse {self.type_!r}; got {self.text!r}"
 
 
 @dataclass
@@ -209,4 +432,105 @@ class _ParseTextExtraNonUniqueError(ParseTextError):
 
     @override
     def __str__(self) -> str:
-        return f"Unable to parse {self.obj!r} since `extra` must contain exactly one parent class; got {self.first!r}, {self.second!r} and perhaps more"
+        return f"Unable to parse {self.type_!r} since `extra` must contain exactly one parent class; got {self.first!r}, {self.second!r} and perhaps more"
+
+
+##
+
+
+def to_text(
+    obj: Any, /, *, list_separator: str = ",", pair_separator: str = "="
+) -> str:
+    """Convert an object to text."""
+    if (obj is None) or isinstance(
+        obj, bool | int | float | str | Path | Sentinel | Version
+    ):
+        return str(obj)
+    if is_instance_date_not_datetime(obj):
+        from utilities.whenever import serialize_date
+
+        return serialize_date(obj)
+    if isinstance(obj, dt.datetime):
+        from utilities.whenever import serialize_datetime
+
+        return serialize_datetime(obj)
+    if isinstance(obj, dt.time):
+        from utilities.whenever import serialize_time
+
+        return serialize_time(obj)
+    if isinstance(obj, dt.timedelta):
+        from utilities.whenever import serialize_timedelta
+
+        return serialize_timedelta(obj)
+    if isinstance(obj, Enum):
+        return obj.name
+    if isinstance(obj, dict):
+        return _to_text_dict(
+            obj, list_separator=list_separator, pair_separator=pair_separator
+        )
+    if isinstance(obj, list):
+        return _to_text_list(
+            obj, list_separator=list_separator, pair_separator=pair_separator
+        )
+    if isinstance(obj, tuple):
+        return _to_text_tuple(
+            obj, list_separator=list_separator, pair_separator=pair_separator
+        )
+    if isinstance(obj, set | frozenset):
+        return _to_text_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 = "="
+) -> str:
+    keys = (
+        to_text(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)
+        for v in obj.values()
+    )
+    items = zip(keys, values, strict=True)
+    joined_items = (join_strs(item, separator=pair_separator) for item in items)
+    joined = join_strs(joined_items, separator=list_separator)
+    return f"{{{joined}}}"
+
+
+def _to_text_list(
+    obj: Sequence[Any], /, *, list_separator: str = ",", pair_separator: str = "="
+) -> str:
+    items = (
+        to_text(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 = "="
+) -> str:
+    items = (
+        to_text(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 = "="
+) -> str:
+    items = (
+        to_text(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"]