Add a fill_null method to dataframe and column

Follow-up to gh-167, which added `fill_nan`, and closes gh-142.

Author: rgommers

spec/API_specification/dataframe_api/column_object.py

@@ -641,3 +641,16 @@ def fill_nan(self, value: float | 'null', /) -> Column:
 
         """
         ...
+
+    def fill_null(self, value: Scalar, /) -> Column:
+        """
+        Fill null values with the given fill value.
+
+        Parameters
+        ----------
+        value : Scalar
+            Value used to replace any ``null`` values in the column with.
+            Must be of the Python scalar type matching the dtype of the column.
+
+        """
+        ...

spec/API_specification/dataframe_api/dataframe_object.py

@@ -774,3 +774,36 @@ def fill_nan(self, value: float | 'null', /) -> DataFrame:
 
         """
         ...
+
+    def fill_null(
+        self, value: Scalar, /, *, column_names : list[str] | None = None
+    ) -> DataFrame:
+        """
+        Fill null values with the given fill value.
+
+        This method can only be used if all columns that are to be filled are
+        of the same dtype kind (e.g., all floating-point, all integer, all
+        string or all datetime dtypes). If that is not the case, it is not
+        possible to use a single Python scalar type that matches the dtype of
+        all columns to which ``fill_null`` is being applied, and hence an
+        exception will be raised.
+
+        Parameters
+        ----------
+        value : Scalar
+            Value used to replace any ``null`` values in the dataframe with.
+            Must be of the Python scalar type matching the dtype(s) of the dataframe.
+        column_names : list[str] | None
+            A list of column names for which to replace nulls with the given
+            scalar value.
+
+        Raises
+        ------
+        TypeError
+            If the columns of the dataframe are not all of the same kind.
+        KeyError
+            If ``column_names`` contains a column name that is not present in
+            the dataframe.
+
+        """
+        ...