dycw-utilities 0.165.2__py3-none-any.whl → 0.166.0__py3-none-any.whl

{dycw_utilities-0.165.2.dist-info → dycw_utilities-0.166.0.dist-info}/METADATA

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

{dycw_utilities-0.165.2.dist-info → dycw_utilities-0.166.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=ZnsWqCnQBd7LRuMGzf7ent48hxqCg33kMckVmWtmXfo,60
+utilities/__init__.py,sha256=tOFl7wsUYIesJ9qprnlUN41VJOJseeW2CsZNgcZ0gng,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=X-TaklmHmyJazckJIRNMwwvgSp3q6EGGb0mVnwHEDrI,80811
+utilities/polars.py,sha256=hYgFfmpLG3Xc75SCzARkA2JLEIyIrD-AfcRwE8ABWAU,83139
 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.2.dist-info/METADATA,sha256=jw-a2WMCwJGXlvhvV3CVjpssOr7e-1QUnw-3i4WuM2k,1696
-dycw_utilities-0.165.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.165.2.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
-dycw_utilities-0.165.2.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.165.2.dist-info/RECORD,,
+dycw_utilities-0.166.0.dist-info/METADATA,sha256=0_1Nn-M65PH_lpHB1NUUiPxCylNpVd7B9948OxvL8kY,1696
+dycw_utilities-0.166.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.166.0.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
+dycw_utilities-0.166.0.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.166.0.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.165.2"
+__version__ = "0.166.0"

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,
@@ -105,6 +103,7 @@ from utilities.whenever import (
 from utilities.zoneinfo import UTC, to_time_zone_name
 
 if TYPE_CHECKING:
+    import datetime as dt
     from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
     from collections.abc import Set as AbstractSet
 
@@ -300,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)}"
 
 
 ##
@@ -2460,6 +2507,34 @@ class RoundToFloatError(Exception):
 ##
 
 
+def search_period(
+    series: Series,
+    date_time: ZonedDateTime,
+    /,
+    *,
+    start_or_end: Literal["start", "end"] = "end",
+) -> int | None:
+    """Search a series of periods for the one containing a given date-time."""
+    end = series.struct["end"]
+    py_date_time = date_time.py_datetime()
+    match start_or_end:
+        case "start":
+            index = end.search_sorted(py_date_time, side="right")
+            if index >= len(series):
+                return None
+            item: dt.datetime = series[index]["start"]
+            return index if py_date_time >= item else None
+        case "end":
+            index = end.search_sorted(py_date_time, side="left")
+            if index >= len(series):
+                return None
+            item: dt.datetime = series[index]["start"]
+            return index if py_date_time > item else None
+
+
+##
+
+
 def select_exact(
     df: DataFrame, /, *columns: IntoExprColumn, drop: MaybeIterable[str] | None = None
 ) -> DataFrame:
@@ -2672,6 +2747,7 @@ def zoned_date_time_period_dtype(
 
 
 __all__ = [
+    "AppendRowError",
     "BooleanValueCountsError",
     "CheckPolarsDataFrameError",
     "ColumnsToDictError",
@@ -2702,7 +2778,7 @@ __all__ = [
     "all_series",
     "any_dataframe_columns",
     "any_series",
-    "append_dataclass",
+    "append_row",
     "are_frames_equal",
     "bernoulli",
     "boolean_value_counts",
@@ -2750,6 +2826,7 @@ __all__ = [
     "read_series",
     "replace_time_zone",
     "round_to_float",
+    "search_period",
     "select_exact",
     "serialize_dataframe",
     "set_first_row_as_columns",