dycw-utilities 0.112.14__py3-none-any.whl → 0.113.1__py3-none-any.whl

{dycw_utilities-0.112.14.dist-info → dycw_utilities-0.113.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.112.14
+Version: 0.113.1
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -137,7 +137,6 @@ Provides-Extra: zzz-test-pickle
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-pickle'
 Provides-Extra: zzz-test-platform
 Provides-Extra: zzz-test-polars
-Requires-Dist: dacite<1.10,>=1.9.2; extra == 'zzz-test-polars'
 Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-polars'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-polars'
 Provides-Extra: zzz-test-pqdm

{dycw_utilities-0.112.14.dist-info → dycw_utilities-0.113.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=CIhTEeq-pbU3Wh1aAi3xUU9ERIQ-sVu7LwD2EjBeNps,61
+utilities/__init__.py,sha256=jYMM0M9M6TZGpXyYU7Rwr3r3k0NY3IhjcbJz_O8C9oM,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=2BloGVlH85tNZjFQiKXNk00Qwe9aovoV7cwxqFRG2l8,32598
+utilities/dataclasses.py,sha256=iiC1wpGXWhaocIikzwBt8bbLWyImoUlOlcDZJGejaIg,33011
 utilities/datetime.py,sha256=OF7jZE702UecnwAbq9D3N-GINpp9gSGoidki1RhimCE,35752
 utilities/enum.py,sha256=HoRwVCWzsnH0vpO9ZEcAAIZLMv0Sn2vJxxA4sYMQgDs,5793
 utilities/errors.py,sha256=BtSNP0JC3ik536ddPyTerLomCRJV9f6kdMe6POz0QHM,361
@@ -26,13 +26,13 @@ utilities/hashlib.py,sha256=SVTgtguur0P4elppvzOBbLEjVM3Pea0eWB61yg2ilxo,309
 utilities/http.py,sha256=WcahTcKYRtZ04WXQoWt5EGCgFPcyHD3EJdlMfxvDt-0,946
 utilities/hypothesis.py,sha256=OpZhPdPmsYWvqMytFDc-G196eODosUzxQSuo-LfMYmM,46262
 utilities/ipython.py,sha256=V2oMYHvEKvlNBzxDXdLvKi48oUq2SclRg5xasjaXStw,763
-utilities/iterables.py,sha256=2Yy9gZ7BR4LXR4nlX7outFAjd4dpb3lgUo7ji_sdylY,45076
+utilities/iterables.py,sha256=prKXBdF5QfLTGC-q4567DwO8xzUng_Z-2a4wBkMqyDo,45360
 utilities/jupyter.py,sha256=ft5JA7fBxXKzP-L9W8f2-wbF0QeYc_2uLQNFDVk4Z-M,2917
 utilities/lightweight_charts.py,sha256=vyVOzarYhBIOZj2xDhqdbP85qbSKUjdc6Au91rc1W4M,2814
 utilities/logging.py,sha256=55LVJYd2BKzeTTQr4tG7uSNMDVEgUO56wK4s-rldjrM,25326
 utilities/loguru.py,sha256=MEMQVWrdECxk1e3FxGzmOf21vWT9j8CAir98SEXFKPA,3809
 utilities/luigi.py,sha256=fpH9MbxJDuo6-k9iCXRayFRtiVbUtibCJKugf7ygpv0,5988
-utilities/math.py,sha256=TexfvLCI12d9Sw5_W4pKVBZ3nRr3zk2iPkcEU7xdEWU,26771
+utilities/math.py,sha256=-mQgbah-dPJwOEWf3SonrFoVZ2AVxMgpeQ3dfVa-oJA,26764
 utilities/memory_profiler.py,sha256=tf2C51P2lCujPGvRt2Rfc7VEw5LDXmVPCG3z_AvBmbU,962
 utilities/modules.py,sha256=iuvLluJya-hvl1Q25-Jk3dLgx2Es3ck4SjJiEkAlVTs,3195
 utilities/more_itertools.py,sha256=6T0225gBFZtv47-B0JRFOKMz836Wg3Hct79ePPLGpuo,5827
@@ -46,7 +46,7 @@ utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=RWfcNVoNlW07RNdU47g_zuLZMKbtgfK4bE6G-9tVjY8,11024
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
 utilities/platform.py,sha256=NU7ycTvAXAG-fdYmDXaM1m4EOml2cGiaYwaUzfzSqyU,1767
-utilities/polars.py,sha256=bo2Rhukk2eXxe1RMfu2uvEjTQTd9SmOi8mGW4BRG82c,67288
+utilities/polars.py,sha256=fxfSm4xVHwKvRxu50IhYNKCKOagp12FdwsVf04ARKpk,63692
 utilities/polars_ols.py,sha256=efhXf0gjrHUpQrvS6a7g8yJQJWf_ATKtJnqqF2inCOU,5680
 utilities/pqdm.py,sha256=foRytQybmOQ05pjt5LF7ANyzrIa--4ScDE3T2wd31a4,3118
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -77,7 +77,7 @@ utilities/text.py,sha256=Fo12N4aA7k2rnb4W4vH9iiDh88Q5_nvRssTkfNsvVM8,10965
 utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=Rkc49KSpHuC8s7vUxGO9DU55U9I6yDKnchsQqrUCVBs,4075
 utilities/traceback.py,sha256=secexUnBsecfWV4ZuqP1W4pGF3prOeO1CRyJK-8zQDU,27402
-utilities/types.py,sha256=kVY71hZkcnyYNIlYSse0mLm8yeP3OBkzhDPMME6jXxo,18126
+utilities/types.py,sha256=B5slv6Vdj6uRmE1xnEBEJfWJmK_0odEwIUCVC9KHikw,18168
 utilities/typing.py,sha256=H6ysJkI830aRwLsMKz0SZIw4cpcsm7d6KhQOwr-SDh0,13817
 utilities/tzdata.py,sha256=yCf70NICwAeazN3_JcXhWvRqCy06XJNQ42j7r6gw3HY,1217
 utilities/tzlocal.py,sha256=3upDNFBvGh1l9njmLR2z2S6K6VxQSb7QizYGUbAH3JU,960
@@ -87,7 +87,7 @@ utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
 utilities/whenever.py,sha256=iLRP_-8CZtBpHKbGZGu-kjSMg1ZubJ-VSmgSy7Eudxw,17787
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-Xm57PMMwDTYpxJdkiJG13wnbwK--I7XItBh5WVhD-o,1874
-dycw_utilities-0.112.14.dist-info/METADATA,sha256=j1h-dnkoSmxpcQeVqNPWmJynfitGt61YQFT3liw1LuU,13005
-dycw_utilities-0.112.14.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.112.14.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.112.14.dist-info/RECORD,,
+dycw_utilities-0.113.1.dist-info/METADATA,sha256=yaeQ1FFLx3bZShYnRwFit1bF6k9iieYw8kInaN6kQ2w,12941
+dycw_utilities-0.113.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.113.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.113.1.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.112.14"
+__version__ = "0.113.1"

utilities/dataclasses.py

@@ -20,7 +20,12 @@ from utilities.functions import (
     is_dataclass_class,
     is_dataclass_instance,
 )
-from utilities.iterables import OneStrEmptyError, OneStrNonUniqueError, one_str
+from utilities.iterables import (
+    OneStrEmptyError,
+    OneStrNonUniqueError,
+    cmp_nullable,
+    one_str,
+)
 from utilities.operator import is_equal
 from utilities.parse import (
     _ParseObjectExtraNonUniqueError,
@@ -43,6 +48,7 @@ from utilities.types import (
     SerializeObjectExtra,
     StrStrMapping,
     TDataclass,
+    TSupportsLT,
 )
 from utilities.typing import get_type_hints
 
@@ -215,6 +221,22 @@ def dataclass_to_dict(
 ##
 
 
+def is_nullable_lt(x: TSupportsLT | None, y: TSupportsLT | None, /) -> bool | None:
+    """Compare two nullable fields."""
+    match cmp_nullable(x, y):
+        case 1:
+            return False
+        case -1:
+            return True
+        case 0:
+            return None
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
 def mapping_to_dataclass(
     cls: type[TDataclass],
     mapping: StrMapping,
@@ -1056,6 +1078,7 @@ __all__ = [
     "YieldFieldsError",
     "dataclass_repr",
     "dataclass_to_dict",
+    "is_nullable_lt",
     "mapping_to_dataclass",
     "one_field",
     "parse_dataclass",

utilities/iterables.py

@@ -45,7 +45,7 @@ from utilities.math import (
 )
 from utilities.reprlib import get_repr
 from utilities.sentinel import Sentinel, sentinel
-from utilities.types import THashable, THashable2, TSupportsAdd
+from utilities.types import Sign, THashable, THashable2, TSupportsAdd, TSupportsLT
 from utilities.zoneinfo import UTC
 
 if TYPE_CHECKING:
@@ -696,6 +696,24 @@ class _CheckUniqueModuloCaseDuplicateLowerCaseStringsError(CheckUniqueModuloCase
 ##
 
 
+def cmp_nullable(x: TSupportsLT | None, y: TSupportsLT | None, /) -> Sign:
+    """Compare two nullable objects."""
+    match x, y:
+        case None, None:
+            return 0
+        case None, _:
+            return -1
+        case _, None:
+            return 1
+        case _, _:
+            return cast("Sign", (x > y) - (x < y))
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
 def chunked(iterable: Iterable[_T], n: int, /) -> Iterator[Sequence[_T]]:
     """Break an iterable into lists of length n."""
     return iter(partial(take, n, iter(iterable)), [])
@@ -1293,7 +1311,7 @@ def sort_iterable(iterable: Iterable[_T], /) -> list[_T]:
     return sorted(iterable, key=cmp_to_key(_sort_iterable_cmp))
 
 
-def _sort_iterable_cmp(x: Any, y: Any, /) -> Literal[-1, 0, 1]:
+def _sort_iterable_cmp(x: Any, y: Any, /) -> Sign:
     """Compare two quantities."""
     if type(x) is not type(y):
         x_qualname = type(x).__qualname__
@@ -1318,7 +1336,7 @@ def _sort_iterable_cmp(x: Any, y: Any, /) -> Literal[-1, 0, 1]:
         return _sort_iterable_cmp_floats(x, y)
     if isinstance(x, str):  # else Sequence
         y = cast("str", y)
-        return cast("Literal[-1, 0, 1]", (x > y) - (x < y))
+        return cast("Sign", (x > y) - (x < y))
 
     # collections
     if isinstance(x, Sized):
@@ -1333,14 +1351,14 @@ def _sort_iterable_cmp(x: Any, y: Any, /) -> Literal[-1, 0, 1]:
         return _sort_iterable_cmp(sort_iterable(x), sort_iterable(y))
     if isinstance(x, Sequence):
         y = cast("Sequence[Any]", y)
-        it: Iterable[Literal[-1, 0, 1]] = (
+        it: Iterable[Sign] = (
             _sort_iterable_cmp(x_i, y_i) for x_i, y_i in zip(x, y, strict=True)
         )
         with suppress(StopIteration):
             return next(r for r in it if r != 0)
 
     try:
-        return cast("Literal[-1, 0, 1]", (x > y) - (x < y))
+        return cast("Sign", (x > y) - (x < y))
     except TypeError:
         raise SortIterableError(x=x, y=y) from None
 
@@ -1355,13 +1373,11 @@ class SortIterableError(Exception):
         return f"Unable to sort {get_repr(self.x)} and {get_repr(self.y)}"
 
 
-def _sort_iterable_cmp_datetimes(
-    x: dt.datetime, y: dt.datetime, /
-) -> Literal[-1, 0, 1]:
+def _sort_iterable_cmp_datetimes(x: dt.datetime, y: dt.datetime, /) -> Sign:
     """Compare two datetimes."""
     match x.tzinfo, y.tzinfo:
         case None, None:
-            return cast("Literal[-1, 0, 1]", (x > y) - (x < y))
+            return cast("Sign", (x > y) - (x < y))
         case dt.tzinfo(), None:
             return 1
         case None, dt.tzinfo():
@@ -1369,20 +1385,19 @@ def _sort_iterable_cmp_datetimes(
         case dt.tzinfo(), dt.tzinfo():
             x_utc = x.astimezone(tz=UTC)
             y_utc = y.astimezone(tz=UTC)
-            result = cast("Literal[-1, 0, 1]", (x_utc > y_utc) - (x_utc < y_utc))
+            result = cast("Sign", (x_utc > y_utc) - (x_utc < y_utc))
             if result != 0:
                 return result
             x_time_zone = ensure_not_none(ensure_not_none(x.tzinfo).tzname(x))
             y_time_zone = ensure_not_none(ensure_not_none(y.tzinfo).tzname(y))
             return cast(
-                "Literal[-1, 0, 1]",
-                (x_time_zone > y_time_zone) - (x_time_zone < y_time_zone),
+                "Sign", (x_time_zone > y_time_zone) - (x_time_zone < y_time_zone)
             )
         case _ as never:
             assert_never(never)
 
 
-def _sort_iterable_cmp_floats(x: float, y: float, /) -> Literal[-1, 0, 1]:
+def _sort_iterable_cmp_floats(x: float, y: float, /) -> Sign:
     """Compare two floats."""
     x_nan, y_nan = map(isnan, [x, y])
     match x_nan, y_nan:
@@ -1393,7 +1408,7 @@ def _sort_iterable_cmp_floats(x: float, y: float, /) -> Literal[-1, 0, 1]:
         case False, True:
             return -1
         case False, False:
-            return cast("Literal[-1, 0, 1]", (x > y) - (x < y))
+            return cast("Sign", (x > y) - (x < y))
         case _ as never:
             assert_never(never)
 
@@ -1517,6 +1532,7 @@ __all__ = [
     "check_superset",
     "check_unique_modulo_case",
     "chunked",
+    "cmp_nullable",
     "ensure_hashables",
     "ensure_iterable",
     "ensure_iterable_not_str",

utilities/math.py

@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 from utilities.errors import ImpossibleCaseError
 
 if TYPE_CHECKING:
-    from utilities.types import Number, RoundMode
+    from utilities.types import Number, RoundMode, Sign
 
 
 MIN_FLOAT32, MAX_FLOAT32 = -3.4028234663852886e38, 3.4028234663852886e38
@@ -860,7 +860,7 @@ class SafeRoundError(Exception):
 
 def sign(
     x: float, /, *, rel_tol: float | None = None, abs_tol: float | None = None
-) -> Literal[-1, 0, 1]:
+) -> Sign:
     """Get the sign of an integer/float."""
     match x:
         case int():

utilities/polars.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import datetime as dt
 import enum
-from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
+from collections.abc import Callable, Iterator, Sequence
 from collections.abc import Set as AbstractSet
 from contextlib import suppress
 from dataclasses import asdict, dataclass
@@ -15,7 +15,6 @@ from typing import (
     Any,
     Generic,
     Literal,
-    TypeGuard,
     TypeVar,
     assert_never,
     cast,
@@ -109,10 +108,9 @@ from utilities.warnings import suppress_warnings
 from utilities.zoneinfo import UTC, ensure_time_zone, get_time_zone_name
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator, Sequence
+    from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
     from collections.abc import Set as AbstractSet
 
-    from dacite.data import Data
     from polars._typing import (
         IntoExpr,  # pyright: ignore[reportPrivateImportUsage]
         IntoExprColumn,  # pyright: ignore[reportPrivateImportUsage]
@@ -126,13 +124,7 @@ if TYPE_CHECKING:
 
     from utilities.numpy import NDArrayB, NDArrayF
     from utilities.statsmodels import ACFMissing
-    from utilities.types import (
-        Dataclass,
-        MaybeIterable,
-        StrMapping,
-        TDataclass,
-        TimeZoneLike,
-    )
+    from utilities.types import Dataclass, MaybeIterable, StrMapping, TimeZoneLike
 
 
 _T = TypeVar("_T")
@@ -2134,116 +2126,6 @@ def week_num(column: IntoExprColumn, /, *, start: WeekDay = "mon") -> Expr | Ser
 ##
 
 
-@overload
-def yield_struct_series_elements(
-    series: Series, /, *, strict: Literal[True]
-) -> Iterator[Mapping[str, Any]]: ...
-@overload
-def yield_struct_series_elements(
-    series: Series, /, *, strict: Literal[False]
-) -> Iterator[Mapping[str, Any] | None]: ...
-@overload
-def yield_struct_series_elements(
-    series: Series, /, *, strict: bool = False
-) -> Iterator[Mapping[str, Any] | None]: ...
-def yield_struct_series_elements(
-    series: Series, /, *, strict: bool = False
-) -> Iterator[Mapping[str, Any] | None]:
-    """Yield the elements of a struct-dtype Series as optional mappings."""
-    if not isinstance(series.dtype, Struct):
-        raise _YieldStructSeriesElementsDTypeError(series=series)
-    if strict and series.is_null().any():
-        raise _YieldStructSeriesElementsNullElementsError(series=series)
-    for value in series:
-        yield _yield_struct_series_element_remove_nulls(value)
-
-
-def _yield_struct_series_element_remove_nulls(obj: Any, /) -> Any:
-    if not _yield_struct_series_element_is_mapping_of_str(obj):
-        return obj
-    if any(_yield_struct_series_element_is_mapping_of_str(v) for v in obj.values()):
-        result = {
-            k: _yield_struct_series_element_remove_nulls(v) for k, v in obj.items()
-        }
-        if result == obj:
-            return result
-        return _yield_struct_series_element_remove_nulls(result)
-    return None if all(v is None for v in obj.values()) else obj
-
-
-def _yield_struct_series_element_is_mapping_of_str(
-    obj: Any, /
-) -> TypeGuard[Mapping[str, Any]]:
-    return isinstance(obj, Mapping) and is_iterable_of(obj, str)
-
-
-@dataclass(kw_only=True, slots=True)
-class YieldStructSeriesElementsError(Exception):
-    series: Series
-
-
-@dataclass(kw_only=True, slots=True)
-class _YieldStructSeriesElementsDTypeError(YieldStructSeriesElementsError):
-    @override
-    def __str__(self) -> str:
-        return f"Series must have Struct-dtype; got {self.series.dtype}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _YieldStructSeriesElementsNullElementsError(YieldStructSeriesElementsError):
-    @override
-    def __str__(self) -> str:
-        return f"Series must not have nulls; got {self.series}"
-
-
-##
-
-
-@overload
-def yield_struct_series_dataclasses(
-    series: Series,
-    cls: type[TDataclass],
-    /,
-    *,
-    forward_references: dict[str, Any] | None = None,
-    check_types: bool = True,
-    strict: Literal[True],
-) -> Iterator[TDataclass]: ...
-@overload
-def yield_struct_series_dataclasses(
-    series: Series,
-    cls: type[TDataclass],
-    /,
-    *,
-    forward_references: dict[str, Any] | None = None,
-    check_types: bool = True,
-    strict: bool = False,
-) -> Iterator[TDataclass | None]: ...
-def yield_struct_series_dataclasses(
-    series: Series,
-    cls: type[TDataclass],
-    /,
-    *,
-    forward_references: dict[str, Any] | None = None,
-    check_types: bool = True,
-    strict: bool = False,
-) -> Iterator[TDataclass | None]:
-    """Yield the elements of a struct-dtype Series as dataclasses."""
-    from dacite import Config, from_dict
-
-    config = Config(
-        forward_references=forward_references, check_types=check_types, strict=True
-    )
-    for value in yield_struct_series_elements(series, strict=strict):
-        if value is None:
-            yield None
-        else:
-            yield from_dict(cls, cast("Data", value), config=config)
-
-
-##
-
-
 def zoned_datetime(
     *, time_unit: TimeUnit = "us", time_zone: TimeZoneLike = UTC
 ) -> Datetime:
@@ -2272,7 +2154,6 @@ __all__ = [
     "IsNullStructSeriesError",
     "SetFirstRowAsColumnsError",
     "StructFromDataClassError",
-    "YieldStructSeriesElementsError",
     "acf",
     "adjust_frequencies",
     "append_dataclass",
@@ -2319,7 +2200,5 @@ __all__ = [
     "try_reify_expr",
     "uniform",
     "unique_element",
-    "yield_struct_series_dataclasses",
-    "yield_struct_series_elements",
     "zoned_datetime",
 ]

utilities/types.py

@@ -140,6 +140,7 @@ type RoundMode = Literal[
     "standard-tie-toward-zero",
     "standard-tie-away-zero",
 ]
+type Sign = Literal[-1, 0, 1]
 
 
 # operator
@@ -291,6 +292,7 @@ __all__ = [
     "RoundMode",
     "Seed",
     "SerializeObjectExtra",
+    "Sign",
     "StrMapping",
     "StrStrMapping",
     "SupportsAbs",