dycw-utilities 0.165.3__py3-none-any.whl → 0.166.1__py3-none-any.whl

{dycw_utilities-0.165.3.dist-info → dycw_utilities-0.166.1.dist-info}/METADATA

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

{dycw_utilities-0.165.3.dist-info → dycw_utilities-0.166.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=dGyOX1Z3m0mhIPCR1cqAXlybAWUxvEasnTNSAfT9Fh8,60
+utilities/__init__.py,sha256=pk8s8uyCf9TfamkXymCVi1C6C_xH9yc5UV3b1hbP1Nk,60
 utilities/aeventkit.py,sha256=ddoleSwW9zdc2tjX5Ge0pMKtYwV_JMxhHYOxnWX2AGM,12609
 utilities/altair.py,sha256=92E2lCdyHY4Zb-vCw6rEJIsWdKipuu-Tu2ab1ufUfAk,9079
 utilities/asyncio.py,sha256=PUedzQ5deqlSECQ33sam9cRzI9TnygHz3FdOqWJWPTM,15288
@@ -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=6_k8cU7LePQ942Qfqe5l_tR8ND0M0bLlpnaMvDbRCM8,81754
+utilities/polars.py,sha256=FehlIHgHP-kvicBPSE6o-tswqUpRysA6epmkPrgHkGE,83239
 utilities/polars_ols.py,sha256=LNTFNLPuYW7fcAHymlbnams_DhitToblYvib3mhKbwI,5615
 utilities/postgres.py,sha256=ynCTTaF-bVEOSW-KEAR-dlLh_hYjeVVjm__-4pEU8Zk,12269
 utilities/pottery.py,sha256=ggMN72Y7wx7Js8VN6eyNyodpm8TIYqZHGghkDPXIVWk,3949
@@ -88,8 +88,8 @@ utilities/zoneinfo.py,sha256=tdIScrTB2-B-LH0ukb1HUXKooLknOfJNwHk10MuMYvA,3619
 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.165.3.dist-info/METADATA,sha256=pkTtRCmg_YK5SUclEGBHKWThH6nFfAdR3vn_EJZjGO8,1696
-dycw_utilities-0.165.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.165.3.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
-dycw_utilities-0.165.3.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.165.3.dist-info/RECORD,,
+dycw_utilities-0.166.1.dist-info/METADATA,sha256=tFhmfKrHbWlljJMUoGWMcLeXSJiVMMXbAAqlqwE6rTQ,1696
+dycw_utilities-0.166.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.166.1.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
+dycw_utilities-0.166.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.166.1.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.165.3"
+__version__ = "0.166.1"

utilities/polars.py

@@ -61,14 +61,12 @@ from utilities.gzip import read_binary
 from utilities.iterables import (
     CheckIterablesEqualError,
     CheckMappingsEqualError,
-    CheckSubSetError,
     CheckSuperMappingError,
     OneEmptyError,
     OneNonUniqueError,
     always_iterable,
     check_iterables_equal,
     check_mappings_equal,
-    check_subset,
     check_supermapping,
     is_iterable_not_str,
     one,
@@ -301,29 +299,77 @@ def any_series(series: Series, /, *columns: ExprOrSeries) -> Series:
 ##
 
 
-def append_dataclass(df: DataFrame, obj: Dataclass, /) -> DataFrame:
-    """Append a dataclass object to a DataFrame."""
-    non_null_fields = {k: v for k, v in asdict(obj).items() if v is not None}
-    try:
-        check_subset(non_null_fields, df.columns)
-    except CheckSubSetError as error:
-        raise AppendDataClassError(
-            left=error.left, right=error.right, extra=error.extra
-        ) from None
-    row_cols = set(df.columns) & set(non_null_fields)
-    row = dataclass_to_dataframe(obj).select(*row_cols)
-    return concat([df, row], how="diagonal")
+def append_row(
+    df: DataFrame,
+    row: StrMapping,
+    /,
+    *,
+    predicate: Callable[[StrMapping], bool] | None = None,
+    disallow_extra: bool = False,
+    disallow_missing: bool | MaybeIterable[str] = False,
+    disallow_null: bool | MaybeIterable[str] = False,
+    in_place: bool = False,
+) -> DataFrame:
+    """Append a row to a DataFrame."""
+    if (predicate is not None) and not predicate(row):
+        raise _AppendRowPredicateError(df=df, row=row)
+    if disallow_extra and (len(extra := set(row) - set(df.columns)) >= 1):
+        raise _AppendRowExtraKeysError(df=df, row=row, extra=extra)
+    if disallow_missing is not False:
+        missing = set(df.columns) - set(row)
+        if disallow_missing is not True:
+            missing &= set(always_iterable(disallow_missing))
+        if len(missing) >= 1:
+            raise _AppendRowMissingKeysError(df=df, row=row, missing=missing)
+    other = DataFrame(data=[row], schema=df.schema)
+    if disallow_null:
+        other_null = other.select(col(c).is_null().any() for c in other.columns)
+        null = {k for k, v in other_null.row(0, named=True).items() if v}
+        if disallow_null is not True:
+            null &= set(always_iterable(disallow_null))
+        if len(null) >= 1:
+            raise _AppendRowNullColumnsError(df=df, row=row, columns=null)
+    return df.extend(other) if in_place else df.vstack(other)
+
+
+@dataclass(kw_only=True, slots=True)
+class AppendRowError(Exception):
+    df: DataFrame
+    row: StrMapping
+
+
+@dataclass(kw_only=True, slots=True)
+class _AppendRowPredicateError(AppendRowError):
+    @override
+    def __str__(self) -> str:
+        return f"Predicate failed; got {get_repr(self.row)}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _AppendRowExtraKeysError(AppendRowError):
+    extra: AbstractSet[str]
+
+    @override
+    def __str__(self) -> str:
+        return f"Extra key(s) found; got {get_repr(self.extra)}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _AppendRowMissingKeysError(AppendRowError):
+    missing: AbstractSet[str]
+
+    @override
+    def __str__(self) -> str:
+        return f"Missing key(s) found; got {get_repr(self.missing)}"
 
 
 @dataclass(kw_only=True, slots=True)
-class AppendDataClassError[T](Exception):
-    left: AbstractSet[T]
-    right: AbstractSet[T]
-    extra: AbstractSet[T]
+class _AppendRowNullColumnsError(AppendRowError):
+    columns: AbstractSet[str]
 
     @override
     def __str__(self) -> str:
-        return f"Dataclass fields {get_repr(self.left)} must be a subset of DataFrame columns {get_repr(self.right)}; dataclass had extra items {get_repr(self.extra)}"
+        return f"Null column(s) found; got {get_repr(self.columns)}"
 
 
 ##
@@ -784,13 +830,15 @@ def choice(
 ##
 
 
-def columns_to_dict(df: DataFrame, key: str, value: str, /) -> dict[Any, Any]:
+def columns_to_dict(
+    df: DataFrame, key: IntoExprColumn, value: IntoExprColumn, /
+) -> dict[Any, Any]:
     """Map a pair of columns into a dictionary. Must be unique on `key`."""
-    col_key = df[key]
-    if col_key.is_duplicated().any():
-        raise ColumnsToDictError(df=df, key=key)
-    col_value = df[value]
-    return dict(zip(col_key, col_value, strict=True))
+    df = df.select(key, value)
+    key_col, value_col = [df[get_expr_name(df, expr)] for expr in [key, value]]
+    if key_col.is_duplicated().any():
+        raise ColumnsToDictError(df=df, key=key_col.name)
+    return dict(zip(key_col, value_col, strict=True))
 
 
 @dataclass(kw_only=True, slots=True)
@@ -2469,7 +2517,7 @@ def search_period(
     start_or_end: Literal["start", "end"] = "end",
 ) -> int | None:
     """Search a series of periods for the one containing a given date-time."""
-    start, end = [series.struct[k] for k in ["start", "end"]]
+    end = series.struct["end"]
     py_date_time = date_time.py_datetime()
     match start_or_end:
         case "start":
@@ -2701,6 +2749,7 @@ def zoned_date_time_period_dtype(
 
 
 __all__ = [
+    "AppendRowError",
     "BooleanValueCountsError",
     "CheckPolarsDataFrameError",
     "ColumnsToDictError",
@@ -2731,7 +2780,7 @@ __all__ = [
     "all_series",
     "any_dataframe_columns",
     "any_series",
-    "append_dataclass",
+    "append_row",
     "are_frames_equal",
     "bernoulli",
     "boolean_value_counts",