dycw-utilities 0.158.2__py3-none-any.whl → 0.159.1__py3-none-any.whl

{dycw_utilities-0.158.2.dist-info → dycw_utilities-0.159.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.158.2
+Version: 0.159.1
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -12,7 +12,7 @@ Provides-Extra: logging
 Requires-Dist: coloredlogs<15.1,>=15.0.1; extra == 'logging'
 Provides-Extra: test
 Requires-Dist: dycw-pytest-only<2.2,>=2.1.1; extra == 'test'
-Requires-Dist: hypothesis<6.138,>=6.137.1; extra == 'test'
+Requires-Dist: hypothesis<6.139,>=6.138.0; extra == 'test'
 Requires-Dist: pytest-asyncio<1.2,>=1.1.0; extra == 'test'
 Requires-Dist: pytest-cov<6.3,>=6.2.1; extra == 'test'
 Requires-Dist: pytest-instafail<0.6,>=0.5.0; extra == 'test'

{dycw_utilities-0.158.2.dist-info → dycw_utilities-0.159.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=jZQwkUNy9TN26VVw3BQw14Odj6HwpuCsgilpBwksDU4,60
+utilities/__init__.py,sha256=Sn6930zXuSe3WGJ5qrzIW92IebaarjXcUx0osmO7Hsk,60
 utilities/altair.py,sha256=92E2lCdyHY4Zb-vCw6rEJIsWdKipuu-Tu2ab1ufUfAk,9079
 utilities/asyncio.py,sha256=PUedzQ5deqlSECQ33sam9cRzI9TnygHz3FdOqWJWPTM,15288
 utilities/atomicwrites.py,sha256=tPo6r-Rypd9u99u66B9z86YBPpnLrlHtwox_8Z7T34Y,5790
@@ -45,7 +45,7 @@ utilities/parse.py,sha256=JcJn5yXKhIWXBCwgBdPsyu7Hvcuw6kyEdqvaebCaI9k,17951
 utilities/pathlib.py,sha256=qGuU8XPmdgGpy8tOMUgelfXx3kxI8h9IaV3TI_06QGE,8428
 utilities/pickle.py,sha256=MBT2xZCsv0pH868IXLGKnlcqNx2IRVKYNpRcqiQQqxw,653
 utilities/platform.py,sha256=pTn7gw6N4T6LdKrf0virwarof_mze9WtoQlrGMzhGVI,2798
-utilities/polars.py,sha256=JOZjSpj9jitDijX044mKc-N00C5N_On3TJYJKJRhdcE,78494
+utilities/polars.py,sha256=qgk9TXHrHodUsgevDbtglYtiZ8jZ-PT8y4EyfU4fk9U,76772
 utilities/polars_ols.py,sha256=Uc9V5kvlWZ5cU93lKZ-cfAKdVFFw81tqwLW9PxtUvMs,5618
 utilities/postgres.py,sha256=ynCTTaF-bVEOSW-KEAR-dlLh_hYjeVVjm__-4pEU8Zk,12269
 utilities/pottery.py,sha256=ggMN72Y7wx7Js8VN6eyNyodpm8TIYqZHGghkDPXIVWk,3949
@@ -54,7 +54,7 @@ utilities/psutil.py,sha256=KUlu4lrUw9Zg1V7ZGetpWpGb9DB8l_SSDWGbANFNCPU,2104
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 utilities/pyinstrument.py,sha256=NZCZz2nBo0BLJ9DTf7H_Q_KGxvsf2S2M3h0qYoYh2kw,804
 utilities/pytest.py,sha256=M-Om6b3hpF9W_bEB7UFY2IzBCubSxzVQleGrgRXHtxY,7741
-utilities/pytest_regressions.py,sha256=8by5DWEL89Y469TI5AzX1pMy3NJWVtjEg2xQdOOdYuM,4169
+utilities/pytest_regressions.py,sha256=ocjHTtfOeiGfQAKIei8pKNd61sxN9dawrJJ9gPt2wzA,4097
 utilities/random.py,sha256=hZlH4gnAtoaofWswuJYjcygejrY8db4CzP-z_adO2Mo,4165
 utilities/re.py,sha256=S4h-DLL6ScMPqjboZ_uQ1BVTJajrqV06r_81D--_HCE,4573
 utilities/redis.py,sha256=pqzl5A08vaRS4Gfjxob3LWWH9c-vwlsKbvVMTjWMSh8,28364
@@ -87,8 +87,8 @@ utilities/zoneinfo.py,sha256=FBMcUQ4662Aq8SsuCL1OAhDQiyANmVjtb-C30DRrWoE,1966
 utilities/pytest_plugins/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
 utilities/pytest_plugins/pytest_randomly.py,sha256=B1qYVlExGOxTywq2r1SMi5o7btHLk2PNdY_b1p98dkE,409
 utilities/pytest_plugins/pytest_regressions.py,sha256=9v8kAXDM2ycIXJBimoiF4EgrwbUvxTycFWJiGR_GHhM,1466
-dycw_utilities-0.158.2.dist-info/METADATA,sha256=obAnKM-ELyfwb4R4ujBYwTxLDgAgCQjFu5lQxUwri38,1643
-dycw_utilities-0.158.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.158.2.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
-dycw_utilities-0.158.2.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.158.2.dist-info/RECORD,,
+dycw_utilities-0.159.1.dist-info/METADATA,sha256=CxCbx_EE_zO3iemn0g8u__516dCh1gbwoQCSZZ7ZEcE,1643
+dycw_utilities-0.159.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.159.1.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
+dycw_utilities-0.159.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.159.1.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.158.2"
+__version__ = "0.159.1"

utilities/polars.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import enum
 from collections.abc import Callable, Iterator, Sequence
 from collections.abc import Set as AbstractSet
-from contextlib import suppress
 from dataclasses import asdict, dataclass
 from functools import partial, reduce
 from itertools import chain, pairwise, product
@@ -43,9 +42,9 @@ from polars import (
 from polars._typing import PolarsDataType
 from polars.datatypes import DataType, DataTypeClass
 from polars.exceptions import (
-    ColumnNotFoundError,  # pyright: ignore[reportAttributeAccessIssue]
+    ColumnNotFoundError,
     NoRowsReturnedError,
-    OutOfBoundsError,  # pyright: ignore[reportAttributeAccessIssue]
+    OutOfBoundsError,
     PolarsInefficientMapWarning,
 )
 from polars.schema import Schema
@@ -59,7 +58,6 @@ from utilities.functions import (
     ensure_int,
     is_dataclass_class,
     is_dataclass_instance,
-    is_iterable_of,
     make_isinstance,
 )
 from utilities.gzip import read_binary
@@ -91,7 +89,6 @@ from utilities.reprlib import get_repr
 from utilities.types import MaybeStr, Number, PathLike, WeekDay
 from utilities.typing import (
     get_args,
-    get_type_hints,
     is_frozenset_type,
     is_list_type,
     is_literal_type,
@@ -340,8 +337,8 @@ def are_frames_equal(
     check_column_order: bool = True,
     check_dtypes: bool = True,
     check_exact: bool = False,
-    rtol: float = 1e-5,
-    atol: float = 1e-8,
+    rel_tol: float = 1e-5,
+    abs_tol: float = 1e-8,
     categorical_as_str: bool = False,
 ) -> bool:
     """Check if two DataFrames are equal."""
@@ -353,8 +350,8 @@ def are_frames_equal(
             check_column_order=check_column_order,
             check_dtypes=check_dtypes,
             check_exact=check_exact,
-            rtol=rtol,
-            atol=atol,
+            rel_tol=rel_tol,
+            abs_tol=abs_tol,
             categorical_as_str=categorical_as_str,
         )
     except AssertionError:
@@ -786,15 +783,6 @@ def choice(
 ##
 
 
-def collect_series(expr: Expr, /) -> Series:
-    """Collect a column expression into a Series."""
-    data = DataFrame().with_columns(expr)
-    return data[one(data.columns)]
-
-
-##
-
-
 def columns_to_dict(df: DataFrame, key: str, value: str, /) -> dict[Any, Any]:
     """Map a pair of columns into a dictionary. Must be unique on `key`."""
     col_key = df[key]
@@ -1047,7 +1035,9 @@ def _dataclass_to_dataframe_cast(series: Series, /) -> Series:
     is_path = series.map_elements(make_isinstance(Path), return_dtype=Boolean).all()
     is_uuid = series.map_elements(make_isinstance(UUID), return_dtype=Boolean).all()
     if is_path or is_uuid:
-        with suppress_warnings(category=PolarsInefficientMapWarning):
+        with suppress_warnings(
+            category=cast("type[Warning]", PolarsInefficientMapWarning)
+        ):
             return series.map_elements(str, return_dtype=String)
     if series.map_elements(make_isinstance(whenever.Time), return_dtype=Boolean).all():
         return series.map_elements(lambda x: x.py_time(), return_dtype=pl.Time)
@@ -1188,27 +1178,6 @@ def _dataclass_to_schema_one(
 ##
 
 
-def drop_null_struct_series(series: Series, /) -> Series:
-    """Drop nulls in a struct-dtype Series as per the <= 1.1 definition."""
-    try:
-        is_not_null = is_not_null_struct_series(series)
-    except IsNotNullStructSeriesError as error:
-        raise DropNullStructSeriesError(series=error.series) from None
-    return series.filter(is_not_null)
-
-
-@dataclass(kw_only=True, slots=True)
-class DropNullStructSeriesError(Exception):
-    series: Series
-
-    @override
-    def __str__(self) -> str:
-        return f"Series must have Struct-dtype; got {self.series.dtype}"
-
-
-##
-
-
 def ensure_data_type(dtype: PolarsDataType, /) -> DataType:
     """Ensure a data type is returned."""
     return dtype if isinstance(dtype, DataType) else dtype()
@@ -1243,6 +1212,14 @@ def ensure_expr_or_series_many(
 ##
 
 
+def expr_to_series(expr: Expr, /) -> Series:
+    """Collect a column expression into a Series."""
+    return one_column(DataFrame().with_columns(expr))
+
+
+##
+
+
 @overload
 def finite_ewm_mean(
     column: ExprLike,
@@ -1417,8 +1394,7 @@ def get_expr_name(obj: Series | DataFrame, expr: IntoExprColumn, /) -> str:
         case Series() as series:
             return get_expr_name(series.to_frame(), expr)
         case DataFrame() as df:
-            selected = df.select(expr)
-            return one(selected.columns)
+            return one_column(df.select(expr)).name
         case never:
             assert_never(never)
 
@@ -1718,68 +1694,28 @@ class _IsNearEventAfterError(IsNearEventError):
 ##
 
 
-def is_not_null_struct_series(series: Series, /) -> Series:
-    """Check if a struct-dtype Series is not null as per the <= 1.1 definition."""
-    try:
-        return ~is_null_struct_series(series)
-    except IsNullStructSeriesError as error:
-        raise IsNotNullStructSeriesError(series=error.series) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class IsNotNullStructSeriesError(Exception):
-    series: Series
-
-    @override
-    def __str__(self) -> str:
-        return f"Series must have Struct-dtype; got {self.series.dtype}"
-
-
-##
-
-
-def is_null_struct_series(series: Series, /) -> Series:
-    """Check if a struct-dtype Series is null as per the <= 1.1 definition."""
-    if not isinstance(series.dtype, Struct):
-        raise IsNullStructSeriesError(series=series)
-    paths = _is_null_struct_series_one(series.dtype)
-    paths = list(paths)
-    exprs = map(_is_null_struct_to_expr, paths)
-    expr = all_horizontal(*exprs)
-    return (
-        series.struct.unnest().with_columns(_result=expr)["_result"].rename(series.name)
-    )
-
-
-def _is_null_struct_series_one(
-    dtype: Struct, /, *, root: Iterable[str] = ()
-) -> Iterator[Sequence[str]]:
-    for field in dtype.fields:
-        name = field.name
-        inner = field.dtype
-        path = list(chain(root, [name]))
-        if isinstance(inner, Struct):
-            yield from _is_null_struct_series_one(inner, root=path)
-        else:
-            yield path
-
-
-def _is_null_struct_to_expr(path: Iterable[str], /) -> Expr:
-    head, *tail = path
-    return reduce(_is_null_struct_to_expr_reducer, tail, col(head)).is_null()
-
-
-def _is_null_struct_to_expr_reducer(expr: Expr, path: str, /) -> Expr:
-    return expr.struct[path]
+@overload
+def is_true(column: ExprLike, /) -> Expr: ...
+@overload
+def is_true(column: Series, /) -> Series: ...
+@overload
+def is_true(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def is_true(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series is True."""
+    column = ensure_expr_or_series(column)
+    return (column.is_not_null()) & column
 
 
-@dataclass(kw_only=True, slots=True)
-class IsNullStructSeriesError(Exception):
-    series: Series
-
-    @override
-    def __str__(self) -> str:
-        return f"Series must have Struct-dtype; got {self.series.dtype}"
+@overload
+def is_false(column: ExprLike, /) -> Expr: ...
+@overload
+def is_false(column: Series, /) -> Series: ...
+@overload
+def is_false(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def is_false(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series is False."""
+    column = ensure_expr_or_series(column)
+    return (column.is_not_null()) & (~column)
 
 
 ##
@@ -2053,6 +1989,43 @@ def offset_datetime(
 ##
 
 
+def one_column(df: DataFrame, /) -> Series:
+    """Return the unique column in a DataFrame."""
+    try:
+        return df[one(df.columns)]
+    except OneEmptyError:
+        raise OneColumnEmptyError(df=df) from None
+    except OneNonUniqueError as error:
+        raise OneColumnNonUniqueError(
+            df=df, first=error.first, second=error.second
+        ) from None
+
+
+@dataclass(kw_only=True, slots=True)
+class OneColumnError(Exception):
+    df: DataFrame
+
+
+@dataclass(kw_only=True, slots=True)
+class OneColumnEmptyError(OneColumnError):
+    @override
+    def __str__(self) -> str:
+        return "DataFrame must not be empty"
+
+
+@dataclass(kw_only=True, slots=True)
+class OneColumnNonUniqueError(OneColumnError):
+    first: str
+    second: str
+
+    @override
+    def __str__(self) -> str:
+        return f"DataFrame must contain exactly one column; got {self.first!r}, {self.second!r} and perhaps more"
+
+
+##
+
+
 @overload
 def order_of_magnitude(column: ExprLike, /, *, round_: bool = False) -> Expr: ...
 @overload
@@ -2174,13 +2147,10 @@ def reify_exprs(
         .with_columns(*all_exprs)
         .drop("_index")
     )
-    match len(df.columns):
-        case 0:
-            raise ImpossibleCaseError(case=[f"{df.columns=}"])  # pragma: no cover
-        case 1:
-            return df[one(df.columns)]
-        case _:
-            return df
+    try:
+        return one_column(df)
+    except OneColumnNonUniqueError:
+        return df
 
 
 @dataclass(kw_only=True, slots=True)
@@ -2408,74 +2378,52 @@ def struct_dtype(**kwargs: PolarsDataType) -> Struct:
 ##
 
 
-def struct_from_dataclass(
-    cls: type[Dataclass],
-    /,
-    *,
-    globalns: StrMapping | None = None,
-    localns: StrMapping | None = None,
-    warn_name_errors: bool = False,
-    time_zone: TimeZoneLike | None = None,
-) -> Struct:
-    """Construct the Struct data type for a dataclass."""
-    if not is_dataclass_class(cls):
-        raise _StructFromDataClassNotADataclassError(cls=cls)
-    anns = get_type_hints(
-        cls, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
-    )
-    data_types = {
-        k: _struct_from_dataclass_one(v, time_zone=time_zone) for k, v in anns.items()
-    }
-    return Struct(data_types)
-
-
-def _struct_from_dataclass_one(
-    ann: Any, /, *, time_zone: TimeZoneLike | None = None
-) -> PolarsDataType:
-    mapping = {
-        bool: Boolean,
-        whenever.Date: pl.Date,
-        float: Float64,
-        int: Int64,
-        str: String,
-    }
-    with suppress(KeyError):
-        return mapping[ann]
-    if is_dataclass_class(ann):
-        return struct_from_dataclass(ann, time_zone=time_zone)
-    if (isinstance(ann, type) and issubclass(ann, enum.Enum)) or (
-        is_literal_type(ann) and is_iterable_of(get_args(ann), str)
-    ):
-        return String
-    if is_optional_type(ann):
-        return _struct_from_dataclass_one(
-            one(get_args(ann, optional_drop_none=True)), time_zone=time_zone
-        )
-    if is_frozenset_type(ann) or is_list_type(ann) or is_set_type(ann):
-        return List(_struct_from_dataclass_one(one(get_args(ann)), time_zone=time_zone))
-    raise _StructFromDataClassTypeError(ann=ann)
-
-
-@dataclass(kw_only=True, slots=True)
-class StructFromDataClassError(Exception): ...
+@overload
+def to_true(column: ExprLike, /) -> Expr: ...
+@overload
+def to_true(column: Series, /) -> Series: ...
+@overload
+def to_true(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def to_true(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series turns True."""
+    t = is_true(column)
+    return ((~t).shift() & t).fill_null(value=False)
 
 
-@dataclass(kw_only=True, slots=True)
-class _StructFromDataClassNotADataclassError(StructFromDataClassError):
-    cls: type[Dataclass]
+@overload
+def to_not_true(column: ExprLike, /) -> Expr: ...
+@overload
+def to_not_true(column: Series, /) -> Series: ...
+@overload
+def to_not_true(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def to_not_true(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series turns non-True."""
+    t = is_true(column)
+    return (t.shift() & (~t)).fill_null(value=False)
 
-    @override
-    def __str__(self) -> str:
-        return f"Object must be a dataclass; got {self.cls}"
 
+@overload
+def to_false(column: ExprLike, /) -> Expr: ...
+@overload
+def to_false(column: Series, /) -> Series: ...
+@overload
+def to_false(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def to_false(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series turns False."""
+    f = is_false(column)
+    return ((~f).shift() & f).fill_null(value=False)
 
-@dataclass(kw_only=True, slots=True)
-class _StructFromDataClassTypeError(StructFromDataClassError):
-    ann: Any
 
-    @override
-    def __str__(self) -> str:
-        return f"Unsupported type: {self.ann}"
+@overload
+def to_not_false(column: ExprLike, /) -> Expr: ...
+@overload
+def to_not_false(column: Series, /) -> Series: ...
+@overload
+def to_not_false(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def to_not_false(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series turns non-False."""
+    f = is_false(column)
+    return (f.shift() & (~f)).fill_null(value=False)
 
 
 ##
@@ -2597,7 +2545,6 @@ __all__ = [
     "DatetimeUSCentral",
     "DatetimeUSEastern",
     "DatetimeUTC",
-    "DropNullStructSeriesError",
     "ExprOrSeries",
     "FiniteEWMMeanError",
     "GetDataTypeOrSeriesTimeZoneError",
@@ -2606,9 +2553,10 @@ __all__ = [
     "InsertBeforeError",
     "InsertBetweenError",
     "IsNearEventError",
-    "IsNullStructSeriesError",
+    "OneColumnEmptyError",
+    "OneColumnError",
+    "OneColumnNonUniqueError",
     "SetFirstRowAsColumnsError",
-    "StructFromDataClassError",
     "TimePeriodDType",
     "acf",
     "adjust_frequencies",
@@ -2622,7 +2570,6 @@ __all__ = [
     "boolean_value_counts",
     "check_polars_dataframe",
     "choice",
-    "collect_series",
     "columns_to_dict",
     "concat_series",
     "convert_time_zone",
@@ -2631,10 +2578,10 @@ __all__ = [
     "dataclass_to_schema",
     "decreasing_horizontal",
     "deserialize_dataframe",
-    "drop_null_struct_series",
     "ensure_data_type",
     "ensure_expr_or_series",
     "ensure_expr_or_series_many",
+    "expr_to_series",
     "finite_ewm_mean",
     "get_data_type_or_series_time_zone",
     "get_expr_name",
@@ -2645,9 +2592,9 @@ __all__ = [
     "insert_before",
     "insert_between",
     "integers",
+    "is_false",
     "is_near_event",
-    "is_not_null_struct_series",
-    "is_null_struct_series",
+    "is_true",
     "join",
     "join_into_periods",
     "map_over_columns",
@@ -2655,6 +2602,7 @@ __all__ = [
     "nan_sum_cols",
     "normal",
     "offset_datetime",
+    "one_column",
     "order_of_magnitude",
     "period_range",
     "read_dataframe",
@@ -2664,7 +2612,10 @@ __all__ = [
     "serialize_dataframe",
     "set_first_row_as_columns",
     "struct_dtype",
-    "struct_from_dataclass",
+    "to_false",
+    "to_not_false",
+    "to_not_true",
+    "to_true",
     "touch",
     "try_reify_expr",
     "uniform",

utilities/pytest_regressions.py

@@ -91,9 +91,7 @@ class PolarsRegressionFixture:
     def check(self, obj: Series | DataFrame, /, *, suffix: str | None = None) -> None:
         """Check the Series/DataFrame summary against the baseline."""
         from polars import DataFrame, Series, col
-        from polars.exceptions import (
-            InvalidOperationError,  # pyright: ignore[reportAttributeAccessIssue]
-        )
+        from polars.exceptions import InvalidOperationError
 
         data: StrMapping = {
             "describe": obj.describe(percentiles=[i / 10 for i in range(1, 10)]).rows(