Calculate correct stack level for deprecation warnings to show them to the user.

Generating deprecation warnings with the correct stacklevel is tricky to get right. Up to now, users have not been seeing these deprecation warnigns because they had incorrect stacklevels. See python/cpython#68493 and python/cpython#67998 for good discussions, as well as ipython/ipython#8478 (comment) and ipython/ipython#8480 (comment) for more context.

We see these issues directly. Normally stacklevel=2 might be enough to target the caller of a function. However, in our deprecation warning in the __init__ method, each level of subclasses adds one stack frame, so depending on the subclass, the appropriate stacklevel is different. Thus this PR implements a trick from a discussion in Python to calculate the first stack frame that is external to the ipywidgets library, and use that as the target stack frame for the deprecation warning.

Author: jasongrout

python/ipywidgets/ipywidgets/widgets/utils.py

@@ -0,0 +1,35 @@
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import sys
+import warnings
+
+# This function is from https://github.com/python/cpython/issues/67998
+# (https://bugs.python.org/file39550/deprecated_module_stacklevel.diff) and
+# calculates the appropriate stacklevel for deprecations to target the
+# deprecation for the caller, no matter how many internal stack frames we have
+# added in the process. For example, with the deprecation warning in the
+# __init__ below, the appropriate stacklevel will change depending on how deep
+# the inheritance hierarchy is.
+def external_stacklevel(internal):
+    """Find the first frame that doesn't any of the given internal strings
+
+    The depth will be 2 at minimum in order to start checking at the caller of
+    the function that called this utility method.
+    """
+    level = 2
+    frame = sys._getframe(level)
+    while frame and any(s in frame.f_code.co_filename for s in internal):
+        level +=1
+        frame = frame.f_back
+    return level
+
+def deprecation(message, internal=None):
+    """Generate a deprecation warning targeting the first external frame
+    
+    internal is a list of strings, which if they appear in filenames in the
+    frames, the frames will also be considered internal.
+    """
+    if internal is None:
+        internal = []
+    warnings.warn(message, DeprecationWarning, stacklevel=external_stacklevel(internal+['ipywidgets/widgets/']))

python/ipywidgets/ipywidgets/widgets/widget_button.py

@@ -7,14 +7,14 @@
 click events on the button and trigger backend code when the clicks are fired.
 """
 
+from .utils import deprecation
 from .domwidget import DOMWidget
 from .widget import CallbackDispatcher, register, widget_serialization
 from .widget_core import CoreWidget
 from .widget_style import Style
 from .trait_types import Color, InstanceDict
 
 from traitlets import Unicode, Bool, CaselessStrEnum, Instance, validate, default
-import warnings
 
 
 @register
@@ -70,8 +70,9 @@ def _validate_icon(self, proposal):
         """Strip 'fa-' if necessary'"""
         value = proposal['value']
         if 'fa-' in value:
-            warnings.warn("icons names no longer need 'fa-', "
-            "just use the class names themselves (for example, 'gear spin' instead of 'fa-gear fa-spin')", DeprecationWarning)
+            deprecation("icons names no longer need 'fa-', "
+            "just use the class names themselves (for example, 'gear spin' instead of 'fa-gear fa-spin')",
+            internal=['traitlets/traitlets.py', '/contextlib.py'])
             value = value.replace('fa-', '')
         return value
 

python/ipywidgets/ipywidgets/widgets/widget_description.py

@@ -9,6 +9,8 @@
 from .widget_style import Style
 from .widget_core import CoreWidget
 from .domwidget import DOMWidget
+from .utils import deprecation
+
 import warnings
 
 @register
@@ -27,7 +29,7 @@ class DescriptionWidget(DOMWidget, CoreWidget):
 
     def __init__(self, *args, **kwargs):
         if 'description_tooltip' in kwargs:
-            warnings.warn("the description_tooltip argument is deprecated, use tooltip instead", DeprecationWarning)
+            deprecation("the description_tooltip argument is deprecated, use tooltip instead")
             kwargs.setdefault('tooltip', kwargs['description_tooltip'])
             del kwargs['description_tooltip']
         super().__init__(*args, **kwargs)
@@ -47,10 +49,10 @@ def description_tooltip(self):
         .. deprecated :: 8.0.0
            Use tooltip attribute instead.
         """
-        warnings.warn(".description_tooltip is deprecated, use .tooltip instead", DeprecationWarning)
+        deprecation(".description_tooltip is deprecated, use .tooltip instead")
         return self.tooltip
 
     @description_tooltip.setter
     def description_tooltip(self, tooltip):
-        warnings.warn(".description_tooltip is deprecated, use .tooltip instead", DeprecationWarning)
+        deprecation(".description_tooltip is deprecated, use .tooltip instead")
         self.tooltip = tooltip

python/ipywidgets/ipywidgets/widgets/widget_string.py

@@ -11,8 +11,8 @@
 from .widget import CallbackDispatcher, register, widget_serialization
 from .widget_core import CoreWidget
 from .trait_types import Color, InstanceDict, TypedTuple
+from .utils import deprecation
 from traitlets import Unicode, Bool, Int
-from warnings import warn
 
 
 class _StringStyle(DescriptionStyle, CoreWidget):
@@ -142,8 +142,7 @@ def on_submit(self, callback, remove=False):
         remove: bool (optional)
             Whether to unregister the callback
         """
-        import warnings
-        warnings.warn("on_submit is deprecated. Instead, set the .continuous_update attribute to False and observe the value changing with: mywidget.observe(callback, 'value').", DeprecationWarning)
+        deprecation("on_submit is deprecated. Instead, set the .continuous_update attribute to False and observe the value changing with: mywidget.observe(callback, 'value').")
         self._submission_callbacks.register_callback(callback, remove=remove)