dycw-utilities 0.108.3__tar.gz → 0.108.4__tar.gz

{dycw_utilities-0.108.3 → dycw_utilities-0.108.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.108.3
+Version: 0.108.4
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -82,7 +82,7 @@ Requires-Dist: asyncpg<0.31,>=0.30.0; extra == 'zzz-test-hypothesis'
 Requires-Dist: greenlet<3.3,>=3.2.0; extra == 'zzz-test-hypothesis'
 Requires-Dist: hypothesis<6.132,>=6.131.6; extra == 'zzz-test-hypothesis'
 Requires-Dist: luigi<3.7,>=3.6.0; extra == 'zzz-test-hypothesis'
-Requires-Dist: numpy<2.3,>=2.2.4; extra == 'zzz-test-hypothesis'
+Requires-Dist: numpy<2.3,>=2.2.5; extra == 'zzz-test-hypothesis'
 Requires-Dist: pathvalidate<3.3,>=3.2.3; extra == 'zzz-test-hypothesis'
 Requires-Dist: redis<5.3,>=5.2.1; extra == 'zzz-test-hypothesis'
 Requires-Dist: sqlalchemy<2.1,>=2.0.40; extra == 'zzz-test-hypothesis'
@@ -112,14 +112,14 @@ Provides-Extra: zzz-test-luigi
 Requires-Dist: luigi<3.7,>=3.6.0; extra == 'zzz-test-luigi'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-luigi'
 Provides-Extra: zzz-test-math
-Requires-Dist: numpy<2.3,>=2.2.4; extra == 'zzz-test-math'
+Requires-Dist: numpy<2.3,>=2.2.5; extra == 'zzz-test-math'
 Provides-Extra: zzz-test-memory-profiler
 Requires-Dist: memory-profiler<0.62,>=0.61.0; extra == 'zzz-test-memory-profiler'
 Provides-Extra: zzz-test-modules
 Provides-Extra: zzz-test-more-itertools
 Requires-Dist: more-itertools<10.7,>=10.6.0; extra == 'zzz-test-more-itertools'
 Provides-Extra: zzz-test-numpy
-Requires-Dist: numpy<2.3,>=2.2.4; extra == 'zzz-test-numpy'
+Requires-Dist: numpy<2.3,>=2.2.5; extra == 'zzz-test-numpy'
 Provides-Extra: zzz-test-operator
 Requires-Dist: polars-lts-cpu<1.28,>=1.27.1; extra == 'zzz-test-operator'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-operator'
@@ -177,7 +177,7 @@ Requires-Dist: scipy<1.16,>=1.15.2; extra == 'zzz-test-scipy'
 Provides-Extra: zzz-test-sentinel
 Provides-Extra: zzz-test-shelve
 Provides-Extra: zzz-test-slack-sdk
-Requires-Dist: aiohttp<3.12,>=3.11.16; extra == 'zzz-test-slack-sdk'
+Requires-Dist: aiohttp<3.12,>=3.11.17; extra == 'zzz-test-slack-sdk'
 Requires-Dist: slack-sdk<3.36,>=3.35.0; extra == 'zzz-test-slack-sdk'
 Provides-Extra: zzz-test-socket
 Provides-Extra: zzz-test-sqlalchemy

{dycw_utilities-0.108.3 → dycw_utilities-0.108.4}/pyproject.toml

@@ -8,7 +8,7 @@ requires = ["hatchling"]
 # dependency groups
 [dependency-groups]
 dev = [
-  "aiohttp >= 3.11.16, < 3.12",  # for slack
+  "aiohttp >= 3.11.17, < 3.12",  # for slack
   "aiosqlite >= 0.21.0, < 0.22",
   "altair >= 5.5.0, < 5.6",
   "astor >= 0.8.1, < 0.9",
@@ -35,7 +35,7 @@ dev = [
   "more-itertools >= 10.6.0, < 10.7",
   "nest-asyncio >= 1.6.0, < 1.7",  # for sqlalchemy async
   "nox >= 2025.2.9, < 2025.3",
-  "numpy >= 2.2.4, < 2.3",
+  "numpy >= 2.2.5, < 2.3",
   "optuna >= 4.3.0, < 4.4",
   "orjson >= 3.10.16, < 3.11",
   "pathvalidate >= 3.2.3, < 3.3",
@@ -89,7 +89,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.108.3"
+version = "0.108.4"
 
 [project.optional-dependencies]
 test = [
@@ -173,7 +173,7 @@ zzz-test-hypothesis = [
   "greenlet >= 3.2.0, < 3.3",  # for sqlalchemy async
   "hypothesis >= 6.131.6, < 6.132",
   "luigi >= 3.6.0, < 3.7",
-  "numpy >= 2.2.4, < 2.3",
+  "numpy >= 2.2.5, < 2.3",
   "pathvalidate >= 3.2.3, < 3.3",
   "redis >= 5.2.1, < 5.3",
   "sqlalchemy >= 2.0.40, < 2.1",
@@ -205,11 +205,11 @@ zzz-test-luigi = [
   "luigi >= 3.6.0, < 3.7",
   "whenever >= 0.7.3, < 0.8",
 ]
-zzz-test-math = ["numpy >= 2.2.4, < 2.3"]
+zzz-test-math = ["numpy >= 2.2.5, < 2.3"]
 zzz-test-memory-profiler = ["memory-profiler >= 0.61.0, < 0.62"]
 zzz-test-modules = []
 zzz-test-more-itertools = ["more-itertools >= 10.6.0, < 10.7"]
-zzz-test-numpy = ["numpy >= 2.2.4, < 2.3"]
+zzz-test-numpy = ["numpy >= 2.2.5, < 2.3"]
 zzz-test-operator = [
   "polars-lts-cpu >= 1.27.1, < 1.28",
   "whenever >= 0.7.3, < 0.8",
@@ -268,7 +268,7 @@ zzz-test-scipy = ["scipy >= 1.15.2, < 1.16"]
 zzz-test-sentinel = []
 zzz-test-shelve = []
 zzz-test-slack-sdk = [
-  "aiohttp >= 3.11.16, < 3.12",  # for slack
+  "aiohttp >= 3.11.17, < 3.12",  # for slack
   "slack-sdk >= 3.35.0, < 3.36",
 ]
 zzz-test-socket = []
@@ -332,7 +332,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.108.3"
+current_version = "0.108.4"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.108.3 → dycw_utilities-0.108.4}/src/tests/test_dataclasses.py

@@ -45,12 +45,17 @@ from utilities.dataclasses import (
     YieldFieldsError,
     _MappingToDataclassCaseInsensitiveNonUniqueError,
     _MappingToDataclassEmptyError,
+    _TextToDataClassGetFieldEmptyError,
+    _TextToDataClassGetFieldNonUniqueError,
+    _TextToDataClassParseValueError,
+    _TextToDataClassSplitKeyValuePairError,
     _YieldFieldsClass,
     _YieldFieldsInstance,
     dataclass_repr,
     dataclass_to_dict,
     mapping_to_dataclass,
     replace_non_sentinel,
+    text_to_dataclass,
     yield_fields,
 )
 from utilities.functions import get_class_name
@@ -65,6 +70,43 @@ from utilities.typing import get_args, is_list_type, is_literal_type, is_optiona
 TruthLit = Literal["true", "false"]  # in 3.12, use type TruthLit = ...
 
 
+class TestDataClassRepr:
+    def test_overriding_repr(self) -> None:
+        @dataclass(kw_only=True, slots=True)
+        class Example(DataClassFutureIntDefault):
+            @override
+            def __repr__(self) -> str:
+                return dataclass_repr(self)
+
+        obj = Example()
+        result = repr(obj)
+        expected = "Example()"
+        assert result == expected
+
+    def test_overriding_repr_defaults(self) -> None:
+        @dataclass(kw_only=True)
+        class Example(DataClassFutureIntDefault):
+            @override
+            def __repr__(self) -> str:
+                return dataclass_repr(self, defaults=True)
+
+        obj = Example()
+        result = repr(obj)
+        expected = "Example(int_=0)"
+        assert result == expected
+
+    @given(x=integers())
+    def test_non_repr_field(self, *, x: int) -> None:
+        @dataclass(kw_only=True, slots=True)
+        class Example:
+            x: int = field(default=0, repr=False)
+
+        obj = Example(x=x)
+        result = dataclass_repr(obj)
+        expected = "Example()"
+        assert result == expected
+
+
 class TestDataclassToDictAndDataclassRepr:
     @given(x=integers(), defaults=booleans())
     def test_field_without_defaults(self, *, x: int, defaults: bool) -> None:
@@ -328,31 +370,51 @@ class TestReplaceNonSentinel:
         assert obj.int_ == 1
 
 
-class TestReprWithoutDefaults:
-    def test_overriding_repr(self) -> None:
-        @dataclass(kw_only=True, slots=True)
-        class Example:
-            x: int = 0
-
-            @override
-            def __repr__(self) -> str:
-                return dataclass_repr(self)
+class TestTextToDataClass:
+    @given(int_=integers())
+    def test_main_text(self, *, int_: int) -> None:
+        result = text_to_dataclass(f"int_={int_}", DataClassFutureInt)
+        expected = DataClassFutureInt(int_=int_)
+        assert result == expected
 
-        obj = Example()
-        result = repr(obj)
-        expected = "Example()"
+    @given(int_=integers())
+    def test_main_mapping(self, *, int_: int) -> None:
+        result = text_to_dataclass({"int_": str(int_)}, DataClassFutureInt)
+        expected = DataClassFutureInt(int_=int_)
         assert result == expected
 
-    @given(x=integers())
-    def test_non_repr_field(self, *, x: int) -> None:
-        @dataclass(kw_only=True, slots=True)
+    def test_error_split_key_value_pair(self) -> None:
+        with raises(
+            _TextToDataClassSplitKeyValuePairError,
+            match="Unable to construct 'DataClassFutureInt'; failed to split key-value pair 'keyvalue'",
+        ):
+            _ = text_to_dataclass("keyvalue", DataClassFutureInt)
+
+    def test_error_get_field_empty(self) -> None:
+        with raises(
+            _TextToDataClassGetFieldEmptyError,
+            match=r"Dataclass 'DataClassFutureInt' does not contain any field starting with 'k' \(modulo case\)",
+        ):
+            _ = text_to_dataclass("k=value", DataClassFutureInt)
+
+    def test_error_get_field_non_unique(self) -> None:
+        @dataclass(order=True, unsafe_hash=True, kw_only=True)
         class Example:
-            x: int = field(default=0, repr=False)
+            int1: int
+            int2: int
 
-        obj = Example(x=x)
-        result = dataclass_repr(obj)
-        expected = "Example()"
-        assert result == expected
+        with raises(
+            _TextToDataClassGetFieldNonUniqueError,
+            match=r"Dataclass 'Example' must contain exactly one field starting with 'int' \(modulo case\); got 'int1', 'int2' and perhaps more",
+        ):
+            _ = text_to_dataclass("int=value", Example)
+
+    def test_error_parse_value(self) -> None:
+        with raises(
+            _TextToDataClassParseValueError,
+            match="Unable to construct 'DataClassFutureInt'; unable to parse field 'int_' of type <class 'int'>; got 'invalid'",
+        ):
+            _ = text_to_dataclass("int_=invalid", DataClassFutureInt)
 
 
 class TestYieldFields:

{dycw_utilities-0.108.3 → dycw_utilities-0.108.4}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.108.3"
+__version__ = "0.108.4"

{dycw_utilities-0.108.3 → dycw_utilities-0.108.4}/src/utilities/dataclasses.py

@@ -1,7 +1,17 @@
 from __future__ import annotations
 
+from collections.abc import Mapping
 from dataclasses import MISSING, dataclass, field, fields, replace
-from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, overload, override
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Literal,
+    TypeVar,
+    assert_never,
+    overload,
+    override,
+)
 
 from utilities.errors import ImpossibleCaseError
 from utilities.functions import (
@@ -11,14 +21,16 @@ 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.reprlib import get_repr
 from utilities.sentinel import Sentinel, sentinel
+from utilities.types import TDataclass
 from utilities.typing import get_type_hints
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Iterator, Mapping
+    from collections.abc import Callable, Iterable, Iterator
 
-    from utilities.types import Dataclass, StrMapping, TDataclass
+    from utilities.types import Dataclass, StrMapping
 
 
 _T = TypeVar("_T")
@@ -118,7 +130,7 @@ def dataclass_to_dict(
     recursive: bool = False,
 ) -> StrMapping:
     """Convert a dataclass to a dictionary."""
-    out: dict[str, Any] = {}
+    out: StrMapping = {}
     for fld in yield_fields(obj, globalns=globalns, localns=localns):
         if fld.keep(
             include=include,
@@ -233,9 +245,7 @@ class _MappingToDataclassEmptyError(MappingToDataclassError):
     @override
     def __str__(self) -> str:
         desc = f"Mapping {get_repr(self.mapping)} does not contain {self.field!r}"
-        if not self.case_sensitive:
-            desc += " (modulo case)"
-        return desc
+        return desc if self.case_sensitive else f"{desc} (modulo case)"
 
 
 @dataclass(kw_only=True, slots=True)
@@ -280,6 +290,142 @@ def replace_non_sentinel(
 ##
 
 
+def text_to_dataclass(
+    text_or_mapping: str | Mapping[str, str],
+    cls: type[TDataclass],
+    /,
+    *,
+    globalns: StrMapping | None = None,
+    localns: StrMapping | None = None,
+    case_sensitive: bool = False,
+) -> TDataclass:
+    """Construct a dataclass from a string or a mapping or strings."""
+    fields = list(yield_fields(cls, globalns=globalns, localns=localns))
+    match text_or_mapping:
+        case str() as text:
+            text_mapping = _text_to_dataclass_split_text(text, cls)
+        case Mapping() as text_mapping:
+            ...
+        case _ as never:
+            assert_never(never)
+    value_mapping = dict(
+        _text_to_dataclass_get_and_parse(
+            fields, key, value, cls, case_sensitive=case_sensitive
+        )
+        for key, value in text_mapping.items()
+    )
+    return mapping_to_dataclass(
+        cls,
+        value_mapping,
+        globalns=globalns,
+        localns=localns,
+        case_sensitive=case_sensitive,
+    )
+
+
+def _text_to_dataclass_split_text(
+    text: str, cls: type[TDataclass], /
+) -> Mapping[str, str]:
+    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]:
+    try:
+        key, value = text.split("=")
+    except ValueError:
+        raise _TextToDataClassSplitKeyValuePairError(cls=cls, text=text) from None
+    return key, value
+
+
+def _text_to_dataclass_get_and_parse(
+    fields: Iterable[_YieldFieldsClass[Any]],
+    key: str,
+    value: str,
+    cls: type[Dataclass],
+    /,
+    *,
+    case_sensitive: bool = False,
+) -> tuple[str, Any]:
+    mapping = {f.name: f for f in fields}
+    try:
+        name = one_str(mapping, key, head=True, case_sensitive=case_sensitive)
+    except OneStrEmptyError:
+        raise _TextToDataClassGetFieldEmptyError(
+            cls=cls, key=key, case_sensitive=case_sensitive
+        ) from None
+    except OneStrNonUniqueError as error:
+        raise _TextToDataClassGetFieldNonUniqueError(
+            cls=cls,
+            key=key,
+            case_sensitive=case_sensitive,
+            first=error.first,
+            second=error.second,
+        ) from None
+    field = mapping[name]
+    try:
+        parsed = parse_text(field.type_, value, case_sensitive=case_sensitive)
+    except ParseTextError:
+        raise _TextToDataClassParseValueError(
+            cls=cls, field=field, text=value
+        ) from None
+    return key, parsed
+
+
+@dataclass(kw_only=True, slots=True)
+class TextToDataClassError(Exception, Generic[TDataclass]):
+    cls: type[TDataclass]
+
+
+@dataclass(kw_only=True, slots=True)
+class _TextToDataClassSplitKeyValuePairError(TextToDataClassError):
+    text: str
+
+    @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 _TextToDataClassGetFieldEmptyError(TextToDataClassError[TDataclass]):
+    key: str
+    case_sensitive: bool = False
+
+    @override
+    def __str__(self) -> str:
+        desc = f"Dataclass {get_class_name(self.cls)!r} does not contain any field starting with {self.key!r}"
+        return desc if self.case_sensitive else f"{desc} (modulo case)"
+
+
+@dataclass(kw_only=True, slots=True)
+class _TextToDataClassGetFieldNonUniqueError(TextToDataClassError[TDataclass]):
+    key: str
+    case_sensitive: bool = False
+    first: str
+    second: str
+
+    @override
+    def __str__(self) -> str:
+        head = f"Dataclass {get_class_name(self.cls)!r} must contain exactly one field starting with {self.key!r}"
+        mid = "" if self.case_sensitive else " (modulo case)"
+        return f"{head}{mid}; got {self.first!r}, {self.second!r} and perhaps more"
+
+
+@dataclass(kw_only=True, slots=True)
+class _TextToDataClassParseValueError(TextToDataClassError[TDataclass]):
+    field: _YieldFieldsClass[Any]
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to construct {get_class_name(self.cls)!r}; unable to parse field {self.field.name!r} of type {self.field.type_!r}; got {self.text!r}"
+
+
+##
+
+
 @overload
 def yield_fields(
     obj: Dataclass,
@@ -346,18 +492,18 @@ def yield_fields(
         raise YieldFieldsError(obj=obj)
 
 
-@dataclass(kw_only=True, slots=True)
+@dataclass(order=True, unsafe_hash=True, kw_only=True, slots=True)
 class _YieldFieldsInstance(Generic[_T]):
     name: str
-    value: _T
-    type_: Any
-    default: _T | Sentinel = sentinel
-    default_factory: Callable[[], _T] | Sentinel = sentinel
+    value: _T = field(hash=False)
+    type_: Any = field(hash=False)
+    default: _T | Sentinel = field(default=sentinel, hash=False)
+    default_factory: Callable[[], _T] | Sentinel = field(default=sentinel, hash=False)
     repr: bool = True
     hash_: bool | None = None
     init: bool = True
     compare: bool = True
-    metadata: StrMapping = field(default_factory=dict)
+    metadata: StrMapping = field(default_factory=dict, hash=False)
     kw_only: bool | Sentinel = sentinel
 
     def equals_default(
@@ -407,17 +553,17 @@ class _YieldFieldsInstance(Generic[_T]):
         return (defaults and equal) or not equal
 
 
-@dataclass(kw_only=True, slots=True)
+@dataclass(order=True, unsafe_hash=True, kw_only=True, slots=True)
 class _YieldFieldsClass(Generic[_T]):
     name: str
-    type_: Any
-    default: _T | Sentinel = sentinel
-    default_factory: Callable[[], _T] | Sentinel = sentinel
+    type_: Any = field(hash=False)
+    default: _T | Sentinel = field(default=sentinel, hash=False)
+    default_factory: Callable[[], _T] | Sentinel = field(default=sentinel, hash=False)
     repr: bool = True
     hash_: bool | None = None
     init: bool = True
     compare: bool = True
-    metadata: StrMapping = field(default_factory=dict)
+    metadata: StrMapping = field(default_factory=dict, hash=False)
     kw_only: bool | Sentinel = sentinel
 
 
@@ -434,10 +580,12 @@ class YieldFieldsError(Exception):
 
 __all__ = [
     "MappingToDataclassError",
+    "TextToDataClassError",
     "YieldFieldsError",
     "dataclass_repr",
     "dataclass_to_dict",
     "mapping_to_dataclass",
     "replace_non_sentinel",
+    "text_to_dataclass",
     "yield_fields",
 ]