Merge pull request matplotlib#19162 from timhoffm/change-warn_deprecated-usage

Deprecate cbook.warn_deprecated and move internal calls to _api.warn_deprecated

Author: timhoffm

doc/api/next_api_changes/deprecations/18657-TH.rst

@@ -1,3 +1,12 @@
-``matplotlib.cbook.deprecation`` is deprecated
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The module is considered internal and will be removed from the public API.
+Deprecation-related functionality is considered internal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The module ``matplotlib.cbook.deprecation`` is considered internal and will be
+removed from the public API. This also holds for deprecation-related re-imports
+in ``matplotlib.cbook``, i.e. ``matplotlib.cbook.deprecated()``,
+``matplotlib.cbook.warn_deprecated()``,
+``matplotlib.cbook.MatplotlibDeprecationWarning`` and
+``matplotlib.cbook.mplDeprecation``.
+
+If needed, external users may import ``MatplotlibDeprecationWarning`` directly
+from the ``matplotlib`` namespace. ``mplDeprecation`` is only an alias of
+``MatplotlibDeprecationWarning`` and should not be used anymore.

lib/matplotlib/__init__.py

@@ -472,7 +472,7 @@ def get_cachedir():
 def get_data_path(*, _from_rc=None):
     """Return the path to Matplotlib data."""
     if _from_rc is not None:
-        cbook.warn_deprecated(
+        _api.warn_deprecated(
             "3.2",
             message=("Setting the datapath via matplotlibrc is deprecated "
                      "%(since)s and will be removed %(removal)s."),
@@ -495,7 +495,7 @@ def _get_data_path():
     if path.is_dir():
         return str(path)
 
-    cbook.warn_deprecated(
+    _api.warn_deprecated(
         "3.2", message="Matplotlib installs where the data is not in the "
         "mpl-data subdirectory of the package are deprecated since %(since)s "
         "and support for them will be removed %(removal)s.")
@@ -617,17 +617,16 @@ def __setitem__(self, key, val):
         try:
             if key in _deprecated_map:
                 version, alt_key, alt_val, inverse_alt = _deprecated_map[key]
-                cbook.warn_deprecated(
+                _api.warn_deprecated(
                     version, name=key, obj_type="rcparam", alternative=alt_key)
                 key = alt_key
                 val = alt_val(val)
             elif key in _deprecated_remain_as_none and val is not None:
                 version, = _deprecated_remain_as_none[key]
-                cbook.warn_deprecated(
-                    version, name=key, obj_type="rcparam")
+                _api.warn_deprecated(version, name=key, obj_type="rcparam")
             elif key in _deprecated_ignore_map:
                 version, alt_key = _deprecated_ignore_map[key]
-                cbook.warn_deprecated(
+                _api.warn_deprecated(
                     version, name=key, obj_type="rcparam", alternative=alt_key)
                 return
             elif key == 'backend':
@@ -647,13 +646,13 @@ def __setitem__(self, key, val):
     def __getitem__(self, key):
         if key in _deprecated_map:
             version, alt_key, alt_val, inverse_alt = _deprecated_map[key]
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 version, name=key, obj_type="rcparam", alternative=alt_key)
             return inverse_alt(dict.__getitem__(self, alt_key))
 
         elif key in _deprecated_ignore_map:
             version, alt_key = _deprecated_ignore_map[key]
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 version, name=key, obj_type="rcparam", alternative=alt_key)
             return dict.__getitem__(self, alt_key) if alt_key else None
 
@@ -811,7 +810,7 @@ def _rc_params_in_file(fname, transform=lambda x: x, fail_on_error=False):
                                  fname, line_no, line.rstrip('\n'), msg)
         elif key in _deprecated_ignore_map:
             version, alt_key = _deprecated_ignore_map[key]
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 version, name=key, alternative=alt_key, obj_type='rcparam',
                 addendum="Please update your matplotlibrc.")
         else:

lib/matplotlib/animation.py

@@ -1719,7 +1719,7 @@ def gen():
                     except StopIteration:
                         pass
                     else:
-                        cbook.warn_deprecated(
+                        _api.warn_deprecated(
                             "2.2", message="FuncAnimation.save has truncated "
                             "your animation to 100 frames.  In the future, no "
                             "such truncation will occur; please pass "

lib/matplotlib/artist.py

@@ -1036,7 +1036,7 @@ def update(self, props):
         with cbook._setattr_cm(self, eventson=False):
             for k, v in props.items():
                 if k != k.lower():
-                    cbook.warn_deprecated(
+                    _api.warn_deprecated(
                         "3.3", message="Case-insensitive properties were "
                         "deprecated in %(since)s and support will be removed "
                         "%(removal)s")
@@ -1156,7 +1156,7 @@ def set(self, **kwargs):
                 i_other = keys.index(other)
                 if i_other < i_color:
                     move_color_to_start = True
-                    cbook.warn_deprecated(
+                    _api.warn_deprecated(
                         "3.3", message=f"You have passed the {other!r} kwarg "
                         "before the 'color' kwarg.  Artist.set() currently "
                         "reorders the properties to apply 'color' first, but "

lib/matplotlib/axes/_axes.py

@@ -3032,7 +3032,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
 
         if normalize is None:
             if sx < 1:
-                cbook.warn_deprecated(
+                _api.warn_deprecated(
                     "3.3", message="normalize=None does not normalize "
                     "if the sum is less than 1 but this behavior "
                     "is deprecated since %(since)s until %(removal)s. "
@@ -3062,15 +3062,15 @@ def get_next_color():
                 return next(color_cycle)
 
         if radius is None:
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 "3.3", message="Support for passing a radius of None to mean "
                 "1 is deprecated since %(since)s and will be removed "
                 "%(removal)s.")
             radius = 1
 
         # Starting theta1 is the start fraction of the circle
         if startangle is None:
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 "3.3", message="Support for passing a startangle of None to "
                 "mean 0 is deprecated since %(since)s and will be removed "
                 "%(removal)s.")
@@ -5636,7 +5636,7 @@ def _pcolorargs(self, funcname, *args, shading='flat', **kwargs):
                                 ' X (%d) and/or Y (%d); see help(%s)' % (
                                     C.shape, Nx, Ny, funcname))
             if (ncols == Nx or nrows == Ny):
-                cbook.warn_deprecated(
+                _api.warn_deprecated(
                     "3.3", message="shading='flat' when X and Y have the same "
                     "dimensions as C is deprecated since %(since)s.  Either "
                     "specify the corners of the quadrilaterals with X and Y, "

lib/matplotlib/axes/_base.py

@@ -2781,7 +2781,7 @@ def _update_title_position(self, renderer):
     def draw(self, renderer=None, inframe=False):
         # docstring inherited
         if renderer is None:
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 "3.3", message="Support for not passing the 'renderer' "
                 "parameter to Axes.draw() is deprecated since %(since)s and "
                 "will be removed %(removal)s.  Use axes.draw_artist(axes) "

lib/matplotlib/axes/_subplots.py

@@ -1,7 +1,7 @@
 import functools
 import uuid
 
-from matplotlib import _api, cbook, docstring
+from matplotlib import _api, docstring
 import matplotlib.artist as martist
 from matplotlib.axes._axes import Axes
 from matplotlib.gridspec import GridSpec, SubplotSpec
@@ -180,7 +180,7 @@ def subplot_class_factory(axes_class=None):
     not have to be created for every type of Axes.
     """
     if axes_class is None:
-        cbook.warn_deprecated(
+        _api.warn_deprecated(
             "3.3", message="Support for passing None to subplot_class_factory "
             "is deprecated since %(since)s; explicitly pass the default Axes "
             "class instead. This will become an error %(removal)s.")

lib/matplotlib/backend_bases.py

@@ -416,7 +416,7 @@ def _iter_collection(self, gc, master_transform, all_transforms,
         Nurls = len(urls)
 
         if offset_position == "data":
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 "3.3", message="Support for offset_position='data' is "
                 "deprecated since %(since)s and will be removed %(removal)s.")
 
@@ -1191,7 +1191,7 @@ def remove_callback(self, func, *args, **kwargs):
         pass it to `add_callback` as a `functools.partial` object.
         """
         if args or kwargs:
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 "3.1", message="In a future version, Timer.remove_callback "
                 "will not take *args, **kwargs anymore, but remove all "
                 "callbacks where the callable matches; to keep a specific "
@@ -1652,7 +1652,7 @@ def wrapper(*args, **kwargs):
         for arg in list(kwargs):
             if arg in accepted_kwargs:
                 continue
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 '3.3', name=name,
                 message='%(name)s() got unexpected keyword argument "'
                         + arg + '" which is no longer supported as of '
@@ -1967,7 +1967,7 @@ def enter_notify_event(self, guiEvent=None, xy=None):
         else:
             x = None
             y = None
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 '3.0', removal='3.5', name='enter_notify_event',
                 message='Since %(since)s, %(name)s expects a location but '
                 'your backend did not pass one. This will become an error '
@@ -2607,7 +2607,7 @@ def _get_uniform_gridstate(ticks):
         for a in canvas.figure.get_axes():
             if (event.x is not None and event.y is not None
                     and a.in_axes(event)):  # FIXME: Why only these?
-                cbook.warn_deprecated(
+                _api.warn_deprecated(
                     "3.3", message="Toggling axes navigation from the "
                     "keyboard is deprecated since %(since)s and will be "
                     "removed %(removal)s.")
@@ -2620,7 +2620,7 @@ def _get_uniform_gridstate(ticks):
             for i, a in enumerate(canvas.figure.get_axes()):
                 if (event.x is not None and event.y is not None
                         and a.in_axes(event)):  # FIXME: Why only these?
-                    cbook.warn_deprecated(
+                    _api.warn_deprecated(
                         "3.3", message="Toggling axes navigation from the "
                         "keyboard is deprecated since %(since)s and will be "
                         "removed %(removal)s.")

lib/matplotlib/backend_managers.py

@@ -199,7 +199,7 @@ def update_keymap(self, name, key, *args):
         self._remove_keys(name)
         for key in [key, *args]:
             if isinstance(key, str) and validate_stringlist(key) != [key]:
-                cbook.warn_deprecated(
+                _api.warn_deprecated(
                     "3.3", message="Passing a list of keys as a single "
                     "comma-separated string is deprecated since %(since)s and "
                     "support will be removed %(removal)s; pass keys as a list "

lib/matplotlib/backends/backend_agg.py

@@ -168,7 +168,7 @@ def draw_path_collection(self, gc, master_transform, paths, all_transforms,
                              linewidths, linestyles, antialiaseds, urls,
                              offset_position):
         if offset_position == "data":
-            cbook.warn_deprecated(
+            _api.warn_deprecated(
                 "3.3", message="Support for offset_position='data' is "
                 "deprecated since %(since)s and will be removed %(removal)s.")
         return self._renderer.draw_path_collection(
@@ -219,7 +219,7 @@ def get_text_width_height_descent(self, s, prop, ismath):
 
         if ismath in ["TeX", "TeX!"]:
             if ismath == "TeX!":
-                cbook._warn_deprecated(
+                _api.warn_deprecated(
                     "3.3", message="Support for ismath='TeX!' is deprecated "
                     "since %(since)s and will be removed %(removal)s; use "
                     "ismath='TeX' instead.")
@@ -573,7 +573,7 @@ def print_jpg(self, filename_or_obj, *args, pil_kwargs=None, **kwargs):
             quality = pil_kwargs["quality"] = \
                 dict.__getitem__(mpl.rcParams, "savefig.jpeg_quality")
             if quality not in [0, 75, 95]:  # default qualities.
-                cbook.warn_deprecated(
+                _api.warn_deprecated(
                     "3.3", name="savefig.jpeg_quality", obj_type="rcParam",
                     addendum="Set the quality using "
                     "`pil_kwargs={'quality': ...}`; the future default "