dycw-utilities 0.159.0__tar.gz → 0.159.2__tar.gz

{dycw_utilities-0.159.0 → dycw_utilities-0.159.2}/PKG-INFO

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

{dycw_utilities-0.159.0 → dycw_utilities-0.159.2}/pyproject.toml

@@ -118,7 +118,7 @@ orjson-test = [
   "polars",
 ]
 polars = [
-  "polars >=1.32.2, <1.33",
+  "polars >=1.32.3, <1.33",
 ]
 polars-ols = [
   "polars-ols >=0.3.5, <0.4",
@@ -227,7 +227,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.159.0"
+version = "0.159.2"
 
 [project.entry-points.pytest11]
 pytest-randomly = "utilities.pytest_plugins.pytest_randomly"
@@ -259,7 +259,7 @@ test = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.159.0"
+current_version = "0.159.2"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.159.0 → dycw_utilities-0.159.2}/src/tests/test_polars.py

@@ -94,6 +94,8 @@ from utilities.polars import (
     FiniteEWMMeanError,
     InsertAfterError,
     InsertBeforeError,
+    OneColumnEmptyError,
+    OneColumnNonUniqueError,
     SetFirstRowAsColumnsError,
     TimePeriodDType,
     _check_polars_dataframe_predicates,
@@ -147,7 +149,6 @@ from utilities.polars import (
     boolean_value_counts,
     check_polars_dataframe,
     choice,
-    collect_series,
     columns_to_dict,
     concat_series,
     convert_time_zone,
@@ -161,7 +162,9 @@ from utilities.polars import (
     ensure_data_type,
     ensure_expr_or_series,
     ensure_expr_or_series_many,
+    expr_to_series,
     finite_ewm_mean,
+    first_true_horizontal,
     get_data_type_or_series_time_zone,
     get_expr_name,
     get_frequency_spectrum,
@@ -180,6 +183,7 @@ from utilities.polars import (
     nan_sum_cols,
     normal,
     offset_datetime,
+    one_column,
     order_of_magnitude,
     period_range,
     read_dataframe,
@@ -827,14 +831,6 @@ class TestChoice:
         assert series.is_in(list(elements)).all()
 
 
-class TestCollectSeries:
-    def test_main(self) -> None:
-        expr = int_range(end=10)
-        series = collect_series(expr)
-        expected = int_range(end=10, eager=True)
-        assert_series_equal(series, expected)
-
-
 class TestColumnsToDict:
     def test_main(self) -> None:
         df = DataFrame(
@@ -1470,6 +1466,14 @@ class TestEnsureExprOrSeriesMany:
             assert isinstance(r, Expr | Series)
 
 
+class TestExprToSeries:
+    def test_main(self) -> None:
+        expr = int_range(end=10)
+        series = expr_to_series(expr)
+        expected = int_range(end=10, eager=True)
+        assert_series_equal(series, expected)
+
+
 class TestFiniteEWMMean:
     alpha_0_75_values: ClassVar[list[float]] = [
         -8.269850726503885,
@@ -1555,6 +1559,22 @@ class TestFiniteEWMWeights:
             _ = _finite_ewm_weights(min_weight=1.0)
 
 
+class TestFirstTrueHorizontal:
+    @mark.parametrize(
+        ("row", "expected"),
+        [
+            param([True, True, True], 0),
+            param([False, True, True], 1),
+            param([False, False, True], 2),
+            param([False, False, False], None),
+        ],
+    )
+    def test_main(self, *, row: list[bool], expected: int | None) -> None:
+        df = DataFrame([row], schema={str(i): Boolean for i in range(3)}, orient="row")
+        result = first_true_horizontal(df)
+        assert result.item() == expected
+
+
 class TestGetDataTypeOrSeriesTimeZone:
     @given(
         time_zone=sampled_from([HongKong, UTC]),
@@ -2239,6 +2259,27 @@ class TestOffsetDateTime:
         assert result == expected
 
 
+class TestOneColumn:
+    def test_main(self) -> None:
+        series = int_range(end=10, eager=True).alias("x")
+        df = series.to_frame()
+        result = one_column(df)
+        assert_series_equal(result, series)
+
+    def test_error_empty(self) -> None:
+        with raises(OneColumnEmptyError, match="DataFrame must not be empty"):
+            _ = one_column(DataFrame())
+
+    def test_error_non_unique(self) -> None:
+        x, y = [int_range(end=10, eager=True).alias(name) for name in ["x", "y"]]
+        df = concat_series(x, y)
+        with raises(
+            OneColumnNonUniqueError,
+            match="DataFrame must contain exactly one column; got 'x', 'y' and perhaps more",
+        ):
+            _ = one_column(df)
+
+
 class TestOrderOfMagnitude:
     @given(
         sign=sampled_from([1, -1]),

{dycw_utilities-0.159.0 → dycw_utilities-0.159.2}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.159.0"
+__version__ = "0.159.2"

{dycw_utilities-0.159.0 → dycw_utilities-0.159.2}/src/utilities/polars.py

@@ -32,6 +32,7 @@ from polars import (
     any_horizontal,
     col,
     concat,
+    concat_list,
     datetime_range,
     int_range,
     lit,
@@ -42,9 +43,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
@@ -337,8 +338,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."""
@@ -350,8 +351,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:
@@ -783,15 +784,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]
@@ -1044,7 +1036,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)
@@ -1219,6 +1213,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,
@@ -1322,6 +1324,15 @@ class _FiniteEWMWeightsError(Exception):
 ##
 
 
+def first_true_horizontal(df: DataFrame, /) -> Series:
+    """Get the index of the first true in each row."""
+    expr = when(any_horizontal(pl.all())).then(concat_list(pl.all()).list.arg_max())
+    return one_column(df.select(expr))
+
+
+##
+
+
 def get_data_type_or_series_time_zone(
     dtype_or_series: PolarsDataType | Series, /
 ) -> ZoneInfo:
@@ -1393,8 +1404,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)
 
@@ -1989,6 +1999,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
@@ -2110,13 +2157,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)
@@ -2519,6 +2563,9 @@ __all__ = [
     "InsertBeforeError",
     "InsertBetweenError",
     "IsNearEventError",
+    "OneColumnEmptyError",
+    "OneColumnError",
+    "OneColumnNonUniqueError",
     "SetFirstRowAsColumnsError",
     "TimePeriodDType",
     "acf",
@@ -2533,7 +2580,6 @@ __all__ = [
     "boolean_value_counts",
     "check_polars_dataframe",
     "choice",
-    "collect_series",
     "columns_to_dict",
     "concat_series",
     "convert_time_zone",
@@ -2545,7 +2591,9 @@ __all__ = [
     "ensure_data_type",
     "ensure_expr_or_series",
     "ensure_expr_or_series_many",
+    "expr_to_series",
     "finite_ewm_mean",
+    "first_true_horizontal",
     "get_data_type_or_series_time_zone",
     "get_expr_name",
     "get_frequency_spectrum",
@@ -2565,6 +2613,7 @@ __all__ = [
     "nan_sum_cols",
     "normal",
     "offset_datetime",
+    "one_column",
     "order_of_magnitude",
     "period_range",
     "read_dataframe",

{dycw_utilities-0.159.0 → dycw_utilities-0.159.2}/src/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(