dycw-utilities 0.109.2__tar.gz → 0.109.4__tar.gz

{dycw_utilities-0.109.2 → dycw_utilities-0.109.4}/PKG-INFO

@@ -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 → dycw_utilities-0.109.4}/pyproject.toml

@@ -89,7 +89,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.109.2"
+version = "0.109.4"
 
 [project.optional-dependencies]
 test = [
@@ -332,7 +332,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.109.2"
+current_version = "0.109.4"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.109.2 → dycw_utilities-0.109.4}/src/tests/test_parse.py

@@ -13,6 +13,7 @@ from pytest import raises
 
 from tests.test_operator import TruthEnum
 from tests.test_typing_funcs.with_future import (
+    DataClassFutureInt,
     TrueOrFalseFutureLit,
     TrueOrFalseFutureTypeLit,
 )
@@ -26,7 +27,11 @@ from utilities.hypothesis import (
     zoned_datetimes,
 )
 from utilities.math import is_equal
-from utilities.parse import ParseTextError, parse_text
+from utilities.parse import (
+    _ParseTextExtraNonUniqueError,
+    _ParseTextParseError,
+    parse_text,
+)
 from utilities.sentinel import Sentinel, sentinel
 from utilities.version import Version
 from utilities.whenever import (
@@ -62,6 +67,17 @@ class TestParseText:
         result = parse_text(TruthEnum, text)
         assert result is truth
 
+    @given(value=integers())
+    def test_extra(self, *, value: int) -> None:
+        text = str(value)
+        result = parse_text(
+            DataClassFutureInt,
+            text,
+            extra={DataClassFutureInt: lambda text: DataClassFutureInt(int_=int(text))},
+        )
+        expected = DataClassFutureInt(int_=value)
+        assert result == expected
+
     @given(value=floats())
     def test_float(self, *, value: float) -> None:
         text = str(value)
@@ -135,6 +151,12 @@ class TestParseText:
         result = parse_text(dt.timedelta, text)
         assert result == timedelta
 
+    @given(x=integers(), y=integers())
+    def test_tuple(self, *, x: int, y: int) -> None:
+        text = f"({x}, {y})"
+        result = parse_text(tuple[int, int], text)
+        assert result == (x, y)
+
     @given(truth=sampled_from(["true", "false"]))
     def test_type_literal(self, *, truth: Literal["true", "false"]) -> None:
         result = parse_text(TrueOrFalseFutureTypeLit, truth)
@@ -148,88 +170,139 @@ class TestParseText:
 
     def test_error_bool(self) -> None:
         with raises(
-            ParseTextError, match="Unable to parse <class 'bool'>; got 'invalid'"
+            _ParseTextParseError, match="Unable to parse <class 'bool'>; got 'invalid'"
         ):
             _ = parse_text(bool, "invalid")
 
     def test_error_date(self) -> None:
         with raises(
-            ParseTextError,
+            _ParseTextParseError,
             match=r"Unable to parse <class 'datetime\.date'>; got 'invalid'",
         ):
             _ = parse_text(dt.date, "invalid")
 
     def test_error_datetime(self) -> None:
         with raises(
-            ParseTextError,
+            _ParseTextParseError,
             match=r"Unable to parse <class 'datetime\.datetime'>; got 'invalid'",
         ):
             _ = parse_text(dt.datetime, "invalid")
 
     def test_error_enum(self) -> None:
         with raises(
-            ParseTextError, match="Unable to parse <enum 'TruthEnum'>; got 'invalid'"
+            _ParseTextParseError,
+            match="Unable to parse <enum 'TruthEnum'>; got 'invalid'",
         ):
             _ = parse_text(TruthEnum, "invalid")
 
+    def test_error_extra_empty(self) -> None:
+        with raises(
+            _ParseTextParseError,
+            match="Unable to parse <class 'tests.test_typing_funcs.with_future.DataClassFutureInt'>; got 'invalid'",
+        ):
+            _ = parse_text(DataClassFutureInt, "invalid", extra={})
+
+    @given(value=integers())
+    def test_error_extra_non_unique(self, *, value: int) -> None:
+        @dataclass(kw_only=True)
+        class Parent1:
+            x: int = 0
+
+        @dataclass(kw_only=True)
+        class Parent2:
+            y: int = 0
+
+        @dataclass(kw_only=True)
+        class Child(Parent1, Parent2): ...
+
+        with raises(
+            _ParseTextExtraNonUniqueError,
+            match="Unable to parse <class '.*'> since `extra` must contain exactly one parent class; got <function .*>, <function .*> and perhaps more",
+        ):
+            _ = parse_text(
+                Child,
+                str(value),
+                extra={
+                    Parent1: lambda text: Child(x=int(text)),
+                    Parent2: lambda text: Child(y=int(text)),
+                },
+            )
+
     def test_error_float(self) -> None:
         with raises(
-            ParseTextError, match="Unable to parse <class 'float'>; got 'invalid'"
+            _ParseTextParseError, match="Unable to parse <class 'float'>; got 'invalid'"
         ):
             _ = parse_text(float, "invalid")
 
     def test_error_int(self) -> None:
         with raises(
-            ParseTextError, match="Unable to parse <class 'int'>; got 'invalid'"
+            _ParseTextParseError, match="Unable to parse <class 'int'>; got 'invalid'"
         ):
             _ = parse_text(int, "invalid")
 
     def test_error_none(self) -> None:
-        with raises(ParseTextError, match="Unable to parse None; got 'invalid'"):
+        with raises(_ParseTextParseError, match="Unable to parse None; got 'invalid'"):
             _ = parse_text(None, "invalid")
 
     def test_error_none_type(self) -> None:
         with raises(
-            ParseTextError, match="Unable to parse <class 'NoneType'>; got 'invalid'"
+            _ParseTextParseError,
+            match="Unable to parse <class 'NoneType'>; got 'invalid'",
         ):
             _ = parse_text(NoneType, "invalid")
 
     def test_error_nullable_int(self) -> None:
         with raises(
-            ParseTextError, match=r"Unable to parse int \| None; got 'invalid'"
+            _ParseTextParseError, match=r"Unable to parse int \| None; got 'invalid'"
         ):
             _ = parse_text(int | None, "invalid")
 
     def test_error_nullable_not_type(self) -> None:
         with raises(
-            ParseTextError,
+            _ParseTextParseError,
             match=r"Unable to parse collections\.abc\.Iterable\[None\] \| None; got 'invalid'",
         ):
             _ = parse_text(Iterable[None] | None, "invalid")
 
     def test_error_sentinel(self) -> None:
         with raises(
-            ParseTextError,
+            _ParseTextParseError,
             match=r"Unable to parse <class 'utilities\.sentinel\.Sentinel'>; got 'invalid'",
         ):
             _ = parse_text(Sentinel, "invalid")
 
     def test_error_time(self) -> None:
         with raises(
-            ParseTextError,
+            _ParseTextParseError,
             match=r"Unable to parse <class 'datetime\.time'>; got 'invalid'",
         ):
             _ = parse_text(dt.time, "invalid")
 
     def test_error_timedelta(self) -> None:
         with raises(
-            ParseTextError,
+            _ParseTextParseError,
             match=r"Unable to parse <class 'datetime\.timedelta'>; got 'invalid'",
         ):
             _ = parse_text(dt.timedelta, "invalid")
 
+    def test_error_tuple_invalid_text(self) -> None:
+        with raises(
+            _ParseTextParseError,
+            match=r"Unable to parse tuple\[int, int\]; got 'invalid'",
+        ):
+            _ = parse_text(tuple[int, int], "invalid")
+
+    def test_error_tuple_inconsistent_args_and_texts(self) -> None:
+        with raises(
+            _ParseTextParseError,
+            match=r"Unable to parse tuple\[int, int\]; got '\(text1, text2, text3\)'",
+        ):
+            _ = parse_text(tuple[int, int], "(text1, text2, text3)")
+
     def test_error_unknown_annotation(self) -> None:
-        with raises(ParseTextError, match=r"Unable to parse int \| str; got 'invalid'"):
+        with raises(
+            _ParseTextParseError, match=r"Unable to parse int \| str; got 'invalid'"
+        ):
             _ = parse_text(int | str, "invalid")
 
     def test_error_unknown_type(self) -> None:
@@ -238,14 +311,14 @@ class TestParseText:
             pass
 
         with raises(
-            ParseTextError,
+            _ParseTextParseError,
             match=r"Unable to parse <class 'tests\.test_parse\.TestParseText\.test_error_unknown_type\.<locals>\.Example'>; got 'invalid'",
         ):
             _ = parse_text(Example, "invalid")
 
     def test_error_version(self) -> None:
         with raises(
-            ParseTextError,
+            _ParseTextParseError,
             match=r"Unable to parse <class 'utilities\.version\.Version'>; got 'invalid'",
         ):
             _ = parse_text(Version, "invalid")

{dycw_utilities-0.109.2 → dycw_utilities-0.109.4}/src/tests/test_typing.py

@@ -55,6 +55,7 @@ from utilities.typing import (
     is_optional_type,
     is_sequence_type,
     is_set_type,
+    is_tuple_type,
     is_union_type,
 )
 
@@ -338,25 +339,63 @@ class TestIsAnnotationOfType:
     @mark.parametrize(
         ("func", "obj", "expected"),
         [
+            param(is_dict_type, Mapping[int, int], False),
+            param(is_dict_type, Sequence[int], False),
             param(is_dict_type, dict[int, int], True),
+            param(is_dict_type, frozenset[int], False),
             param(is_dict_type, list[int], False),
+            param(is_dict_type, set[int], False),
+            param(is_dict_type, tuple[int, int], False),
+            param(is_frozenset_type, Mapping[int, int], False),
+            param(is_frozenset_type, Sequence[int], False),
+            param(is_frozenset_type, dict[int, int], False),
             param(is_frozenset_type, frozenset[int], True),
             param(is_frozenset_type, list[int], False),
+            param(is_frozenset_type, set[int], False),
+            param(is_frozenset_type, tuple[int, int], False),
+            param(is_list_type, Mapping[int, int], False),
+            param(is_list_type, Sequence[int], False),
+            param(is_list_type, dict[int, int], False),
+            param(is_list_type, frozenset[int], False),
             param(is_list_type, list[int], True),
             param(is_list_type, set[int], False),
-            param(is_mapping_type, Mapping[int, int], True),
-            param(is_mapping_type, list[int], False),
+            param(is_list_type, tuple[int, int], False),
             param(is_literal_type, Literal["a", "b", "c"], True),
             param(is_literal_type, list[int], False),
+            param(is_mapping_type, Mapping[int, int], True),
+            param(is_mapping_type, Sequence[int], False),
+            param(is_mapping_type, dict[int, int], False),
+            param(is_mapping_type, frozenset[int], False),
+            param(is_mapping_type, list[int], False),
+            param(is_mapping_type, set[int], False),
+            param(is_mapping_type, tuple[int, int], False),
+            param(is_optional_type, Literal["a", "b", "c"] | None, True),
+            param(is_optional_type, Literal["a", "b", "c"], False),
             param(is_optional_type, int | None, True),
             param(is_optional_type, int | str, False),
-            param(is_optional_type, list[int], False),
             param(is_optional_type, list[int] | None, True),
-            param(is_optional_type, Literal["a", "b", "c"], False),
-            param(is_optional_type, Literal["a", "b", "c"] | None, True),
+            param(is_optional_type, list[int], False),
+            param(is_sequence_type, Mapping[int, int], False),
             param(is_sequence_type, Sequence[int], True),
+            param(is_sequence_type, dict[int, int], False),
+            param(is_sequence_type, frozenset[int], False),
             param(is_sequence_type, list[int], False),
+            param(is_sequence_type, set[int], False),
+            param(is_sequence_type, tuple[int, int], False),
+            param(is_set_type, Mapping[int, int], False),
+            param(is_set_type, Sequence[int], False),
+            param(is_set_type, dict[int, int], False),
+            param(is_set_type, frozenset[int], False),
             param(is_set_type, list[int], False),
+            param(is_set_type, set[int], True),
+            param(is_set_type, tuple[int, int], False),
+            param(is_tuple_type, Mapping[int, int], False),
+            param(is_tuple_type, Sequence[int], False),
+            param(is_tuple_type, dict[int, int], False),
+            param(is_tuple_type, frozenset[int], False),
+            param(is_tuple_type, list[int], False),
+            param(is_tuple_type, set[int], False),
+            param(is_tuple_type, tuple[int, int], True),
             param(is_union_type, int | str, True),
             param(is_union_type, list[int], False),
         ],

{dycw_utilities-0.109.2 → dycw_utilities-0.109.4}/src/utilities/__init__.py

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

{dycw_utilities-0.109.2 → dycw_utilities-0.109.4}/src/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"

{dycw_utilities-0.109.2 → dycw_utilities-0.109.4}/src/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",
 ]