Deprecate globals using module-level __getattr__.

This PR is mostly just to propose a pattern for defining module-level
`__getattr__`s for deprecating globals.

Relying on lru_cache rather than defining variables as `global` (see
change in `__init__.py`) avoids having to repeat *twice* the variable
name, and allows immediately returning its value without assigning it.
It means later accesses will be very slightly slower (because they'll
still go through the lru_cache layer), but that should hopefully be
negligible, and will mostly concern deprecated variables anyways.

One *could* consider adding a helper API in `_api.deprecation` that just
provides the decoration with `@lru_cache` and generates the
AttributeError message when needed, but that seems rather overkill.

The change in deprecation.py allows one to skip `obj_name` and get a
message like "foo is deprecated..." rather than "The foo  is
deprecated...".

Author: anntzer

lib/matplotlib/__init__.py

@@ -176,13 +176,15 @@ def _get_version():
         return _version.version
 
 
+@functools.lru_cache(None)
 def __getattr__(name):
-    if name in ("__version__", "__version_info__"):
-        global __version__  # cache it.
-        __version__ = _get_version()
-        global __version__info__  # cache it.
-        __version_info__ = _parse_to_version_info(__version__)
-        return __version__ if name == "__version__" else __version_info__
+    if name == "__version__":
+        return _get_version()
+    elif name == "__version_info__":
+        return _parse_to_version_info(__getattr__("__version__"))
+    elif name == "URL_REGEX":  # module-level deprecation.
+        _api.warn_deprecated("3.5", name=name)
+        return re.compile(r'^http://|^https://|^ftp://|^file:')
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
@@ -714,14 +716,10 @@ def rc_params(fail_on_error=False):
     return rc_params_from_file(matplotlib_fname(), fail_on_error)
 
 
-# Deprecated in Matplotlib 3.5.
-URL_REGEX = re.compile(r'^http://|^https://|^ftp://|^file:')
-
-
 @_api.deprecated("3.5")
 def is_url(filename):
     """Return whether *filename* is an http, https, ftp, or file URL path."""
-    return URL_REGEX.match(filename) is not None
+    return __getattr__("URL_REGEX").match(filename) is not None
 
 
 @functools.lru_cache()

lib/matplotlib/_api/deprecation.py

@@ -37,13 +37,11 @@ def _generate_deprecation_warning(
         removal = f"in {removal}" if removal else "two minor releases later"
     if not message:
         message = (
-            "\nThe %(name)s %(obj_type)s"
+            ("\nThe %(name)s %(obj_type)s" if obj_type else "%(name)s")
             + (" will be deprecated in a future version"
                if pending else
                (" was deprecated in Matplotlib %(since)s"
-                + (" and will be removed %(removal)s"
-                   if removal else
-                   "")))
+                + (" and will be removed %(removal)s" if removal else "")))
             + "."
             + (" Use %(alternative)s instead." if alternative else "")
             + (" %(addendum)s" if addendum else ""))

lib/matplotlib/backends/backend_gtk3.py

@@ -36,17 +36,27 @@
 backend_version = "%s.%s.%s" % (
     Gtk.get_major_version(), Gtk.get_minor_version(), Gtk.get_micro_version())
 
-try:
-    _display = Gdk.Display.get_default()
-    cursord = {  # deprecated in Matplotlib 3.5.
-        Cursors.MOVE:          Gdk.Cursor.new_from_name(_display, "move"),
-        Cursors.HAND:          Gdk.Cursor.new_from_name(_display, "pointer"),
-        Cursors.POINTER:       Gdk.Cursor.new_from_name(_display, "default"),
-        Cursors.SELECT_REGION: Gdk.Cursor.new_from_name(_display, "crosshair"),
-        Cursors.WAIT:          Gdk.Cursor.new_from_name(_display, "wait"),
-    }
-except TypeError as exc:
-    cursord = {}  # deprecated in Matplotlib 3.5.
+
+# module-level deprecations.
+@functools.lru_cache(None)
+def __getattr__(name):
+    if name == "cursord":
+        _api.warn_deprecated("3.5", name=name)
+        try:
+            new_cursor = functools.partial(
+                Gdk.Cursor.new_from_name, Gdk.Display.get_default())
+            return {
+                Cursors.MOVE:          new_cursor("move"),
+                Cursors.HAND:          new_cursor("pointer"),
+                Cursors.POINTER:       new_cursor("default"),
+                Cursors.SELECT_REGION: new_cursor("crosshair"),
+                Cursors.WAIT:          new_cursor("wait"),
+            }
+        except TypeError as exc:
+            return {}
+    else:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 # Placeholder
 _application = None

lib/matplotlib/backends/backend_wx.py

@@ -40,8 +40,26 @@
 # for some info about screen dpi
 PIXELS_PER_INCH = 75
 
-# Delay time for idle checks
-IDLE_DELAY = 5  # Documented as deprecated as of Matplotlib 3.1.
+
+# module-level deprecations.
+@functools.lru_cache(None)
+def __getattr__(name):
+    if name == "IDLE_DELAY":
+        _api.warn_deprecated("3.1", name=name)
+        return 5
+    elif name == "cursord":
+        _api.warn_deprecated("3.5", name=name)
+        return {  # deprecated in Matplotlib 3.5.
+            cursors.MOVE: wx.CURSOR_HAND,
+            cursors.HAND: wx.CURSOR_HAND,
+            cursors.POINTER: wx.CURSOR_ARROW,
+            cursors.SELECT_REGION: wx.CURSOR_CROSS,
+            cursors.WAIT: wx.CURSOR_WAIT,
+            cursors.RESIZE_HORIZONTAL: wx.CURSOR_SIZEWE,
+            cursors.RESIZE_VERTICAL: wx.CURSOR_SIZENS,
+        }
+    else:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 def error_msg_wx(msg, parent=None):
@@ -721,7 +739,15 @@ def _onKeyUp(self, event):
 
     def set_cursor(self, cursor):
         # docstring inherited
-        cursor = wx.Cursor(_api.check_getitem(cursord, cursor=cursor))
+        cursor = wx.Cursor(_api.check_getitem({
+            cursors.MOVE: wx.CURSOR_HAND,
+            cursors.HAND: wx.CURSOR_HAND,
+            cursors.POINTER: wx.CURSOR_ARROW,
+            cursors.SELECT_REGION: wx.CURSOR_CROSS,
+            cursors.WAIT: wx.CURSOR_WAIT,
+            cursors.RESIZE_HORIZONTAL: wx.CURSOR_SIZEWE,
+            cursors.RESIZE_VERTICAL: wx.CURSOR_SIZENS,
+        }, cursor=cursor))
         self.SetCursor(cursor)
         self.Update()
 
@@ -1049,17 +1075,6 @@ def _set_frame_icon(frame):
     frame.SetIcons(bundle)
 
 
-cursord = {  # deprecated in Matplotlib 3.5.
-    cursors.MOVE: wx.CURSOR_HAND,
-    cursors.HAND: wx.CURSOR_HAND,
-    cursors.POINTER: wx.CURSOR_ARROW,
-    cursors.SELECT_REGION: wx.CURSOR_CROSS,
-    cursors.WAIT: wx.CURSOR_WAIT,
-    cursors.RESIZE_HORIZONTAL: wx.CURSOR_SIZEWE,
-    cursors.RESIZE_VERTICAL: wx.CURSOR_SIZENS,
-}
-
-
 class NavigationToolbar2Wx(NavigationToolbar2, wx.ToolBar):
     def __init__(self, canvas, coordinates=True):
         wx.ToolBar.__init__(self, canvas.GetParent(), -1)

lib/matplotlib/colorbar.py

@@ -12,6 +12,7 @@
 """
 
 import copy
+import functools
 import logging
 import textwrap
 
@@ -193,10 +194,21 @@
        textwrap.indent(_make_axes_other_param_doc, "    "),
        _colormap_kw_doc))
 
-# Deprecated since 3.4.
-colorbar_doc = docstring.interpd.params["colorbar_doc"]
-colormap_kw_doc = _colormap_kw_doc
-make_axes_kw_doc = _make_axes_param_doc + _make_axes_other_param_doc
+
+# module-level deprecations.
+@functools.lru_cache(None)
+def __getattr__(name):
+    if name == "colorbar_doc":
+        _api.warn_deprecated("3.4", name=name)
+        return docstring.interpd.params["colorbar_doc"]
+    elif name == "colormap_kw_doc":
+        _api.warn_deprecated("3.4", name=name)
+        return _colormap_kw_doc
+    elif name == "make_axes_kw_doc":
+        _api.warn_deprecated("3.4", name=name)
+        return _make_axes_param_doc + _make_axes_other_param_doc
+    else:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 def _set_ticks_on_axis_warn(*args, **kw):