diff --git a/doc/source/user_guide/style.ipynb b/doc/source/user_guide/style.ipynb index 96589b74fcf6b..85c552a7d596f 100644 --- 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 index 851cf201cae6a..3bc9a1ef1ca48 100644 --- 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 index 0502e2a2f4395..da578ebd624ea 100644 --- 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 index 9c96e3cf1ba81..863c31ed3cccd 100644 --- 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 index 89aa0686562a9..63138d87bc72f 100644 --- 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 )