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

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

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

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

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=BFspQsIuZJOmuE31YyhwkR4P62-Ad5dFurosyyABzLA,60
+utilities/__init__.py,sha256=TfQi7UYijWAmuZ8wsQ7kQKbgWiSQWgaXE80fBUn8qx8,60
 utilities/altair.py,sha256=NSyDsm8QlkAGmsGdxVwCkHnPxt_35yJBa9Lg7bz9Ays,9054
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
 utilities/asyncio.py,sha256=41oQUurWMvadFK5gFnaG21hMM0Vmfn2WS6OpC0R9mas,14757
@@ -40,7 +40,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=yLLH51VNwmcWbEvwqh6M-weWt7NIayd7No67Oe80S3k,4585
+utilities/parse.py,sha256=q1A1-bsXltdAh8We5Acy-lPuVIClWTxsRXQWq5wYyKk,6382
 utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=ikHXsWtDLr553cfH6p9mMaiCnIAP69B7q84ckWV3HaA,10884
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
@@ -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=h1vt82GUs-3ww7yFbZ3BWjdUM4NBPHaptcJHSKuRa5E,5341
+utilities/typing.py,sha256=gLg4EbE1FX52fJ1d3ji4i08qolwu9qgWt8w_w_Y5DTk,5512
 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.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,,
+dycw_utilities-0.109.4.dist-info/METADATA,sha256=-fU_tSw6cCv59Fg6s0I0pUlV3YzXeuq15kfirsKUmik,13004
+dycw_utilities-0.109.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.109.4.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.109.4.dist-info/RECORD,,

utilities/__init__.py

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

utilities/parse.py

@@ -5,30 +5,44 @@ from contextlib import suppress
 from dataclasses import dataclass
 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, TypeVar, override
 
 from utilities.datetime import 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 one, one_str
+from utilities.iterables import OneEmptyError, OneNonUniqueError, one, one_str
+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.typing import get_args, is_literal_type, is_optional_type
+from utilities.typing import get_args, is_literal_type, is_optional_type, is_tuple_type
 from utilities.version import ParseVersionError, Version, parse_version
 
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+
+_T = TypeVar("_T")
+
 
 def parse_text(
-    obj: Any, text: str, /, *, case_sensitive: bool = False, head: bool = False
+    obj: Any,
+    text: str,
+    /,
+    *,
+    case_sensitive: bool = False,
+    head: bool = False,
+    extra: Mapping[type[_T], Callable[[str], _T]] | None = None,
 ) -> Any:
     """Parse text."""
     if obj is None:
         try:
             return parse_none(text)
         except ParseNoneError:
-            raise ParseTextError(obj=obj, text=text) from None
+            raise _ParseTextParseError(obj=obj, text=text) from None
     if isinstance(obj, type):
-        return _parse_text_type(obj, text, case_sensitive=case_sensitive)
+        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):
@@ -40,83 +54,111 @@ def parse_text(
         ):
             try:
                 return _parse_text_type(inner, text, case_sensitive=case_sensitive)
-            except ParseTextError:
-                raise ParseTextError(obj=obj, text=text) from None
-    raise ParseTextError(obj=obj, text=text) from None
+            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, case_sensitive=case_sensitive, head=head)
+            for arg, text in zip(args, texts, strict=True)
+        )
+    raise _ParseTextParseError(obj=obj, text=text) from None
 
 
 def _parse_text_type(
-    cls: type[Any], text: str, /, *, case_sensitive: bool = False
+    cls: type[Any],
+    text: str,
+    /,
+    *,
+    case_sensitive: bool = False,
+    extra: Mapping[type[_T], Callable[[str], _T]] | None = None,
 ) -> Any:
     """Parse text."""
     if issubclass(cls, NoneType):
         try:
             return parse_none(text)
         except ParseNoneError:
-            raise ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=cls, text=text) from None
     if issubclass(cls, str):
         return text
     if issubclass(cls, bool):
         try:
             return parse_bool(text)
         except ParseBoolError:
-            raise ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=cls, text=text) from None
     if is_subclass_int_not_bool(cls):
         try:
             return int(text)
         except ValueError:
-            raise ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=cls, text=text) from None
     if issubclass(cls, float):
         try:
             return float(text)
         except ValueError:
-            raise ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=cls, text=text) from None
     if issubclass(cls, Enum):
         try:
             return parse_enum(text, cls, case_sensitive=case_sensitive)
         except ParseEnumError:
-            raise ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=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 ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=cls, text=text) from None
     if issubclass(cls, Version):
         try:
             return parse_version(text)
         except ParseVersionError:
-            raise ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=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 ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=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 ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=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 ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=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 ParseTextError(obj=cls, text=text) from None
-    raise ParseTextError(obj=cls, text=text) from None
+            raise _ParseTextParseError(obj=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(
+                obj=cls, text=text, first=error.first, second=error.second
+            ) from None
+        else:
+            return parser(text)
+    raise _ParseTextParseError(obj=cls, text=text) from None
 
 
 @dataclass
@@ -124,6 +166,19 @@ class ParseTextError(Exception):
     obj: Any
     text: str
 
+
+@dataclass
+class _ParseTextParseError(ParseTextError):
     @override
     def __str__(self) -> str:
         return f"Unable to parse {self.obj!r}; got {self.text!r}"
+
+
+@dataclass
+class _ParseTextExtraNonUniqueError(ParseTextError):
+    first: type[Any]
+    second: type[Any]
+
+    @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"

utilities/typing.py

@@ -182,6 +182,14 @@ def is_set_type(obj: Any, /) -> bool:
 ##
 
 
+def is_tuple_type(obj: Any, /) -> bool:
+    """Check if an object is a tuple type annotation."""
+    return _is_annotation_of_type(obj, tuple)
+
+
+##
+
+
 def is_union_type(obj: Any, /) -> bool:
     """Check if an object is a union type annotation."""
     is_old_union = _is_annotation_of_type(obj, Union)  # pyright: ignore[reportDeprecated]
@@ -212,5 +220,6 @@ __all__ = [
     "is_optional_type",
     "is_sequence_type",
     "is_set_type",
+    "is_tuple_type",
     "is_union_type",
 ]