DEPR: Styler.where possible deprecation (pandas-dev#40821)

pandas/io/formats/style.py

@@ -611,7 +611,6 @@ def apply(
 
         See Also
         --------
-        Styler.where: Apply CSS-styles based on a conditional function elementwise.
         Styler.applymap: Apply a CSS-styling function elementwise.
 
         Notes
@@ -669,7 +668,6 @@ def applymap(self, func: Callable, subset=None, **kwargs) -> Styler:
 
         See Also
         --------
-        Styler.where: Apply CSS-styles based on a conditional function elementwise.
         Styler.apply: Apply a CSS-styling function column-wise, row-wise, or table-wise.
 
         Notes
@@ -701,6 +699,8 @@ def where(
         """
         Apply CSS-styles based on a conditional function elementwise.
 
+        .. deprecated:: 1.3.0
+
         Updates the HTML representation with a style which is
         selected in accordance with the return value of a function.
 
@@ -728,13 +728,31 @@ def where(
         Styler.applymap: Apply a CSS-styling function elementwise.
         Styler.apply: Apply a CSS-styling function column-wise, row-wise, or table-wise.
 
-        Examples
-        --------
-        >>> def cond(v):
-        ...     return v > 1 and v != 4
+        Notes
+        -----
+        This method is deprecated.
+
+        This method is a convenience wrapper for :meth:`Styler.applymap`, which we
+        recommend using instead.
+
+        The example:
         >>> df = pd.DataFrame([[1, 2], [3, 4]])
-        >>> df.style.where(cond, value='color:red;', other='font-size:2em;')
+        >>> def cond(v, limit=4):
+        ...     return v > 1 and v != limit
+        >>> df.style.where(cond, value='color:green;', other='color:red;')
+
+        should be refactored to:
+        >>> def style_func(v, value, other, limit=4):
+        ...     cond = v > 1 and v != limit
+        ...     return value if cond else other
+        >>> df.style.applymap(style_func, value='color:green;', other='color:red;')
         """
+        warnings.warn(
+            "this method is deprecated in favour of `Styler.applymap()`",
+            FutureWarning,
+            stacklevel=2,
+        )
+
         if other is None:
             other = ""
 

pandas/tests/io/formats/style/test_style.py

@@ -541,7 +541,8 @@ def f(x):
 
         style1 = "foo: bar"
 
-        result = self.df.style.where(f, style1)._compute().ctx
+        with tm.assert_produces_warning(FutureWarning):
+            result = self.df.style.where(f, style1)._compute().ctx
         expected = {
             (r, c): [("foo", "bar")]
             for r, row in enumerate(self.df.index)
@@ -568,14 +569,15 @@ def f(x):
         style1 = "foo: bar"
         style2 = "baz: foo"
 
-        result = self.df.style.where(f, style1, style2, subset=slice_)._compute().ctx
+        with tm.assert_produces_warning(FutureWarning):
+            res = self.df.style.where(f, style1, style2, subset=slice_)._compute().ctx
         expected = {
             (r, c): [("foo", "bar") if f(self.df.loc[row, col]) else ("baz", "foo")]
             for r, row in enumerate(self.df.index)
             for c, col in enumerate(self.df.columns)
             if row in self.df.loc[slice_].index and col in self.df.loc[slice_].columns
         }
-        assert result == expected
+        assert res == expected
 
     def test_where_subset_compare_with_applymap(self):
         # GH 17474
@@ -597,9 +599,10 @@ def g(x):
         ]
 
         for slice_ in slices:
-            result = (
-                self.df.style.where(f, style1, style2, subset=slice_)._compute().ctx
-            )
+            with tm.assert_produces_warning(FutureWarning):
+                result = (
+                    self.df.style.where(f, style1, style2, subset=slice_)._compute().ctx
+                )
             expected = self.df.style.applymap(g, subset=slice_)._compute().ctx
             assert result == expected
 
@@ -609,14 +612,15 @@ def test_where_kwargs(self):
         def f(x, val):
             return x > val
 
-        result = df.style.where(f, "color:green;", "color:red;", val=2)._compute().ctx
+        with tm.assert_produces_warning(FutureWarning):
+            res = df.style.where(f, "color:green;", "color:red;", val=2)._compute().ctx
         expected = {
             (0, 0): [("color", "red")],
             (0, 1): [("color", "red")],
             (1, 0): [("color", "green")],
             (1, 1): [("color", "green")],
         }
-        assert result == expected
+        assert res == expected
 
     def test_empty(self):
         df = DataFrame({"A": [1, 0]})