doc: documentation of the new parameters

narwhals-dev · Oct 7, 2024 · 38e5b7f · 38e5b7f
1 parent 4a62e91
commit 38e5b7f
Show file tree

Hide file tree

Showing 2 changed files with 66 additions and 5 deletions.
diff --git a/narwhals/expr.py b/narwhals/expr.py
@@ -1148,10 +1148,16 @@ def fill_null(
             >>> import polars as pl
             >>> import narwhals as nw
             >>> df_pd = pd.DataFrame(
-            ...     {"a": [2, 4, None, 3, 5], "b": [2.0, 4.0, float("nan"), 3.0, 5.0]}
+            ...     {
+            ...         "a": [2, 4, None, None, 3, 5],
+            ...         "b": [2.0, 4.0, float("nan"), float("nan"), 3.0, 5.0],
+            ...     }
             ... )
             >>> df_pl = pl.DataFrame(
-            ...     {"a": [2, 4, None, 3, 5], "b": [2.0, 4.0, float("nan"), 3.0, 5.0]}
+            ...     {
+            ...         "a": [2, 4, None, None, 3, 5],
+            ...         "b": [2.0, 4.0, float("nan"), float("nan"), 3.0, 5.0],
+            ...     }
             ... )
 
             Let's define a dataframe-agnostic function:
@@ -1167,11 +1173,12 @@ def fill_null(
             0  2.0  2.0
             1  4.0  4.0
             2  0.0  0.0
-            3  3.0  3.0
-            4  5.0  5.0
+            3  0.0  0.0
+            4  3.0  3.0
+            5  5.0  5.0
 
             >>> func(df_pl)  # nan != null for polars
-            shape: (5, 2)
+            shape: (6, 2)
             ┌─────┬─────┐
             │ a   ┆ b   │
             │ --- ┆ --- │
@@ -1180,9 +1187,42 @@ def fill_null(
             │ 2   ┆ 2.0 │
             │ 4   ┆ 4.0 │
             │ 0   ┆ NaN │
+            │ 0   ┆ NaN │
             │ 3   ┆ 3.0 │
             │ 5   ┆ 5.0 │
             └─────┴─────┘
+
+            Using a strategy:
+
+            >>> @nw.narwhalify
+            ... def func_strategies(df):
+            ...     return df.with_columns(
+            ...         nw.col("a", "b").fill_null(strategy="forward", limit=1)
+            ...     )
+
+            >>> func_strategies(df_pd)
+                 a    b
+            0  2.0  2.0
+            1  4.0  4.0
+            2  4.0  4.0
+            3  NaN  NaN
+            4  3.0  3.0
+            5  5.0  5.0
+
+            >>> func_strategies(df_pl)  # nan != null for polars
+            shape: (6, 2)
+            ┌──────┬─────┐
+            │ a    ┆ b   │
+            │ ---  ┆ --- │
+            │ i64  ┆ f64 │
+            ╞══════╪═════╡
+            │ 2    ┆ 2.0 │
+            │ 4    ┆ 4.0 │
+            │ 4    ┆ NaN │
+            │ null ┆ NaN │
+            │ 3    ┆ 3.0 │
+            │ 5    ┆ 5.0 │
+            └──────┴─────┘
         """
         return self.__class__(
             lambda plx: self._call(plx).fill_null(

diff --git a/narwhals/series.py b/narwhals/series.py
@@ -1433,6 +1433,27 @@ def fill_null(
                2
                5
             ]
+
+            Using a strategy:
+
+            >>> @nw.narwhalify
+            ... def func_strategies(s):
+            ...     return s.fill_null(strategy="forward", limit=1)
+
+            >>> func_strategy(s_pd)
+            0    1.0
+            1    2.0
+            2    2.0
+            dtype: float64
+
+            >>> func_strategy(s_pl)  # doctest: +NORMALIZE_WHITESPACE
+            shape: (3,)
+            Series: '' [i64]
+            [
+               1
+               2
+               2
+            ]
         """
         return self._from_compliant_series(
             self._compliant_series.fill_null(value=value, strategy=strategy, limit=limit)