Deprecate the keyword what of .param.watch_values (#1073)

Author: maximlt

doc/reference/deprecations.md

@@ -4,6 +4,7 @@ List of currently deprecated APIs:
 
 | Warning | Description |
 |-|-|
+| `ParamFutureWarning` since `2.3.0` | Parameterized `.param` namespace / `.param.watch_values`: the keyword `what` is deprecated |
 | `ParamPendingDeprecationWarning` since `2.3.0` | `param.parameterized` module / Setting a parameter value before full instance initialization |
 | `ParamFutureWarning` since `2.2.0`, `ParamDeprecationWarning` since `2.0.0` | Parameter slots / `List._class`: use instead `item_type` |
 | `ParamFutureWarning` since `2.2.0`, `ParamDeprecationWarning` since `2.0.0` | Parameter slots / `Number.set_hook`: no replacement |

param/parameterized.py

@@ -4114,6 +4114,8 @@ def watch_values(
             name, a list of parameter names, or a tuple of parameter names.
         what : str, optional
             The type of change to watch for. Must be 'value'. Default is 'value'.
+
+            .. deprecated:: 2.3.0
         onlychanged : bool, optional
             If True (default), the callback is only invoked when the parameter value
             changes. If False, the callback is invoked even when the parameter is
@@ -4179,6 +4181,13 @@ def watch_values(
             raise ValueError("User-defined watch callbacks must declare "
                              "a positive precedence. Negative precedences "
                              "are reserved for internal Watchers.")
+        if what != 'value':
+            warnings.warn(
+                'The keyword "what" is deprecated and will be removed in a '
+                'future version.',
+                category=_ParamFutureWarning,
+                stacklevel=3,
+            )
         assert what == 'value'
         if isinstance(parameter_names, list):
             parameter_names = tuple(parameter_names)

tests/testdeprecations.py

@@ -107,6 +107,17 @@ def __init__(self, **params):
         with pytest.raises(param._utils.ParamPendingDeprecationWarning):
             P()
 
+    def test_deprecate_watch_values_keyword_what(self):
+        class P(param.Parameterized):
+            x = param.Parameter()
+
+            def __init__(self, **params):
+                super().__init__(**params)
+                self.param.watch_values(lambda _: None, ['x'], 'doc')
+
+        with pytest.raises(param._utils.ParamFutureWarning):
+            P()
+
 
 class TestDeprecateParameters: