DEPR: null_color since color used everywhere else (pandas-dev#45907)

me-kbs · Mar 3, 2022 · e4162cd · e4162cd
1 parent e36db19
commit e4162cd
Show file tree

Hide file tree

Showing 5 changed files with 36 additions and 7 deletions.
diff --git a/doc/source/user_guide/style.ipynb b/doc/source/user_guide/style.ipynb
@@ -1131,7 +1131,7 @@
    "source": [
     "df2.iloc[0,2] = np.nan\n",
     "df2.iloc[4,3] = np.nan\n",
-    "df2.loc[:4].style.highlight_null(null_color='yellow')"
+    "df2.loc[:4].style.highlight_null(color='yellow')"
    ]
   },
   {

diff --git a/doc/source/whatsnew/v1.5.0.rst b/doc/source/whatsnew/v1.5.0.rst
@@ -22,6 +22,7 @@ Styler
   - New method :meth:`.Styler.to_string` for alternative customisable output methods (:issue:`44502`)
   - Added the ability to render ``border`` and ``border-{side}`` CSS properties in Excel (:issue:`42276`)
   - Added a new method :meth:`.Styler.concat` which allows adding customised footer rows to visualise additional calculations on the data, e.g. totals and counts etc. (:issue:`43875`, :issue:`46186`)
+  - :meth:`.Styler.highlight_null` now accepts ``color`` consistently with other builtin methods and deprecates ``null_color`` although this remains backwards compatible (:issue:`45907`)
 
 .. _whatsnew_150.enhancements.enhancement2:
 

diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py
@@ -19,6 +19,7 @@
 
 from pandas._config import get_option
 
+from pandas._libs import lib
 from pandas._typing import (
     Axis,
     FilePath,
@@ -3203,19 +3204,23 @@ def bar(
 
         return self
 
-    @Substitution(subset=subset, props=props)
+    @Substitution(subset=subset, props=props, color=color)
     def highlight_null(
         self,
-        null_color: str = "red",
+        color: str | None = None,
         subset: Subset | None = None,
         props: str | None = None,
+        null_color=lib.no_default,
     ) -> Styler:
         """
         Highlight missing values with a style.
 
         Parameters
         ----------
-        null_color : str, default 'red'
+        %(color)s
+
+            .. versionadded:: 1.5.0
+
         %(subset)s
 
             .. versionadded:: 1.1.0
@@ -3224,6 +3229,13 @@ def highlight_null(
 
             .. versionadded:: 1.3.0
 
+        null_color : str, default None
+            The background color for highlighting.
+
+            .. deprecated:: 1.5.0
+               Use ``color`` instead. If ``color`` is given ``null_color`` is
+               not used.
+
         Returns
         -------
         self : Styler
@@ -3239,8 +3251,19 @@ def highlight_null(
         def f(data: DataFrame, props: str) -> np.ndarray:
             return np.where(pd.isna(data).to_numpy(), props, "")
 
+        if null_color != lib.no_default:
+            warnings.warn(
+                "`null_color` is deprecated: use `color` instead",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        if color is None and null_color == lib.no_default:
+            color = "red"
+        elif color is None and null_color != lib.no_default:
+            color = null_color
         if props is None:
-            props = f"background-color: {null_color};"
+            props = f"background-color: {color};"
         return self.apply(f, axis=None, subset=subset, props=props)
 
     @Substitution(subset=subset, color=color, props=props)

diff --git a/pandas/tests/io/formats/style/test_deprecated.py b/pandas/tests/io/formats/style/test_deprecated.py
@@ -163,3 +163,8 @@ def test_precision(df):
 def test_render(df):
     with tm.assert_produces_warning(FutureWarning):
         df.style.render()
+
+
+def test_null_color(df):
+    with tm.assert_produces_warning(FutureWarning):
+        df.style.highlight_null(null_color="blue")
diff --git a/pandas/tests/io/formats/style/test_highlight.py b/pandas/tests/io/formats/style/test_highlight.py
@@ -37,8 +37,8 @@ def test_highlight_null(styler):
 def test_highlight_null_subset(styler):
     # GH 31345
     result = (
-        styler.highlight_null(null_color="red", subset=["A"])
-        .highlight_null(null_color="green", subset=["B"])
+        styler.highlight_null(color="red", subset=["A"])
+        .highlight_null(color="green", subset=["B"])
         ._compute()
         .ctx
     )