* update "fill_null" docstrings with additional example (#2666)

polars/polars-io/src/avro.rs

@@ -7,7 +7,7 @@ use std::ops::Deref;
 
 use arrow::io::avro::{read, write};
 
-/// Read Appache Avro format into a DataFrame
+/// Read Apache Avro format into a DataFrame
 ///
 /// # Example
 /// ```
@@ -96,7 +96,7 @@ where
 
 pub use write::Compression as AvroCompression;
 
-/// Write a DataFrame to Appache Avro format
+/// Write a DataFrame to Apache Avro format
 ///
 /// # Example
 ///

polars/polars-lazy/src/physical_plan/expressions/window.rs

@@ -131,7 +131,7 @@ impl WindowExpr {
             (true, true, _) => Ok(MapStrategy::ExplodeLater),
             // Explode all the aggregated lists. Maybe add later?
             (true, false, _) => {
-                Err(PolarsError::ComputeError("This operation is likely not what you want. Please open an issue if you really want to do this".into()))
+                Err(PolarsError::ComputeError("This operation is likely not what you want (you may need '.list()'). Please open an issue if you really want to do this".into()))
             }
             // explicit list
             // `(col("x").sum() * col("y")).list().over("groups")`
@@ -203,12 +203,12 @@ impl PhysicalExpr for WindowExpr {
         //
         //      - 3.2 EXPLODE
         //          Explicit list aggregations that are followed by `over().flatten()`
-        //          # the fastest method to do things over groups when the groups are sorted
-        //          # note that it will require an excit `list()` call from now on.
+        //          # the fastest method to do things over groups when the groups are sorted.
+        //          # note that it will require an explicit `list()` call from now on.
         //              `(col("x").sum() * col("y")).list().over("groups").flatten()`
         //
         //      - 3.3. MAP to original locations
-        //          This will be done for list aggregation that are not excitly aggregated as list
+        //          This will be done for list aggregations that are not explicitly aggregated as list
         //              `(col("x").sum() * col("y")).over("groups")`
 
         // 4. select the final column and return

py-polars/polars/internals/expr.py

@@ -914,17 +914,18 @@ def shift_and_fill(
 
     def fill_null(self, fill_value: Union[int, float, bool, str, "Expr"]) -> "Expr":
         """
-        Fill none value with a fill value or strategy
+        Fill null values using a filling strategy, literal, or Expr.
 
         fill_value
-            Fill null strategy or a value
-                   * "backward"
-                   * "forward"
-                   * "min"
-                   * "max"
-                   * "mean"
-                   * "one"
-                   * "zero"
+            One of:
+            - "backward"
+            - "forward"
+            - "min"
+            - "max"
+            - "mean"
+            - "one"
+            - "zero"
+            Or an expression.
         """
         # we first must check if it is not an expr, as expr does not implement __bool__
         # and thus leads to a value error in the second comparisson.
@@ -3202,15 +3203,15 @@ def and_time_unit(self, tu: str, dtype: Type[DataType] = Datetime) -> Expr:
 
     def and_time_zone(self, tz: Optional[str]) -> Expr:
         """
-        Set time zone a Series of type Datetime
+        Set time zone for a Series of type Datetime.
 
         ..deprecated::
             Use `with_time_zone`
 
         Parameters
         ----------
         tz
-            Time zone for the `Datetime` Series: any of {"ns", "ms"}
+            Time zone for the `Datetime` Series
 
         """
         return wrap_expr(self._pyexpr).map(
@@ -3219,12 +3220,12 @@ def and_time_zone(self, tz: Optional[str]) -> Expr:
 
     def with_time_zone(self, tz: Optional[str]) -> Expr:
         """
-        Set time zone a Series of type Datetime
+        Set time zone for a Series of type Datetime.
 
         Parameters
         ----------
         tz
-            Time zone for the `Datetime` Series: any of {"ns", "ms"}
+            Time zone for the `Datetime` Series
 
         """
         return wrap_expr(self._pyexpr).map(

py-polars/polars/internals/frame.py

@@ -549,14 +549,14 @@ def _read_avro(
         file: Union[str, BinaryIO], n_rows: Optional[int] = None
     ) -> "DataFrame":
         """
-        Read into a DataFrame from Appache Avro format.
+        Read into a DataFrame from Apache Avro format.
 
         Parameters
         ----------
         file
             Path to a file or a file like object.
         n_rows
-            Stop reading from Appache Avro file after reading ``n_rows``.
+            Stop reading from Apache Avro file after reading ``n_rows``.
 
         Returns
         -------
@@ -916,7 +916,7 @@ def to_avro(
         compression: Literal["uncompressed", "snappy", "deflate"] = "uncompressed",
     ) -> None:
         """
-        Write to Appache Avro file.
+        Write to Apache Avro file.
 
         Parameters
         ----------
@@ -3343,7 +3343,7 @@ def get_column(self, name: str) -> "pli.Series":
 
     def fill_null(self, strategy: Union[str, "pli.Expr", Any]) -> "DataFrame":
         """
-        Fill None/missing values by a filling strategy or an Expression evaluation.
+        Fill null values using a filling strategy, literal, or Expr.
 
         Parameters
         ----------
@@ -3360,7 +3360,7 @@ def fill_null(self, strategy: Union[str, "pli.Expr", Any]) -> "DataFrame":
 
         Returns
         -------
-            DataFrame with None replaced with the filling strategy.
+            DataFrame with None values replaced by the filling strategy.
         """
         if isinstance(strategy, pli.Expr):
             return self.lazy().fill_null(strategy).collect(no_optimization=True)

py-polars/polars/internals/lazy_frame.py

@@ -1106,12 +1106,12 @@ def with_row_count(self, name: str = "row_nr", offset: int = 0) -> "LazyFrame":
 
     def fill_null(self, fill_value: Union[int, str, "pli.Expr"]) -> "LazyFrame":
         """
-        Fill missing values
+        Fill missing values with a literal or Expr.
 
         Parameters
         ----------
         fill_value
-            Value to fill the missing values with
+            Value to fill the missing values with.
         """
         if not isinstance(fill_value, pli.Expr):
             fill_value = pli.lit(fill_value)

py-polars/polars/internals/series.py

@@ -2178,7 +2178,7 @@ def fill_nan(
 
     def fill_null(self, strategy: Union[str, int, "pli.Expr"]) -> "Series":
         """
-        Fill null values with a filling strategy.
+        Fill null values using a filling strategy, literal, or Expr.
 
         Examples
         --------
@@ -2196,24 +2196,32 @@ def fill_null(self, strategy: Union[str, int, "pli.Expr"]) -> "Series":
         shape: (4,)
         Series: 'a' [i64]
         [
-                1
-                2
-                3
-                1
+            1
+            2
+            3
+            1
+        ]
+        >>> s = pl.Series("b", ["x", None, "z"])
+        >>> s.fill_null(pl.lit(""))
+        shape: (3,)
+        Series: 'b' [str]
+        [
+            "x"
+            ""
+            "z"
         ]
-
         Parameters
         ----------
         strategy
-
-        Fill null strategy or a value
-               * "backward"
-               * "forward"
-               * "min"
-               * "max"
-               * "mean"
-               * "one"
-               * "zero"
+            One of:
+            - "backward"
+            - "forward"
+            - "min"
+            - "max"
+            - "mean"
+            - "one"
+            - "zero"
+            Or an expression.
         """
         if not isinstance(strategy, str):
             return self.to_frame().select(pli.col(self.name).fill_null(strategy))[
@@ -3427,7 +3435,7 @@ def extend_constant(
     @property
     def time_unit(self) -> Optional[str]:
         """
-        Get the time unit of underlying Datetime Series as {"ns", "ms"}
+        Get the time unit of underlying Datetime Series as {"ns", "us", "ms"}
         """
         return self._s.time_unit()
 
@@ -4299,27 +4307,27 @@ def and_time_unit(self, tu: str) -> "Series":
 
     def and_time_zone(self, tz: Optional[str]) -> "Series":
         """
-        Set time zone a Series of type Datetime
+        Set time zone a Series of type Datetime.
 
         ..deprecated::
             Use `with_time_zone`
 
         Parameters
         ----------
         tz
-            Time zone for the `Datetime` Series: any of {"ns", "ms"}
+            Time zone for the `Datetime` Series
 
         """
         return wrap_s(self._s.and_time_zone(tz))
 
     def with_time_zone(self, tz: Optional[str]) -> "Series":
         """
-        Set time zone a Series of type Datetime
+        Set time zone a Series of type Datetime.
 
         Parameters
         ----------
         tz
-            Time zone for the `Datetime` Series: any of {"ns", "ms"}
+            Time zone for the `Datetime` Series
 
         """
         return wrap_s(self._s.and_time_zone(tz))

py-polars/polars/io.py

@@ -700,14 +700,14 @@ def read_avro(
     file: Union[str, Path, BytesIO, BinaryIO], n_rows: Optional[int] = None
 ) -> DataFrame:
     """
-    Read into a DataFrame from Appache Avro format.
+    Read into a DataFrame from Apache Avro format.
 
     Parameters
     ----------
     file
         Path to a file or a file like object.
     n_rows
-        Stop reading from Appache Avro file after reading ``n_rows``.
+        Stop reading from Apache Avro file after reading ``n_rows``.
 
     Returns
     -------