Merge pull request matplotlib#23722 from QuLogic/restore-mplDeprecation

Restore deprecation class aliases in cbook

Author: timhoffm

doc/api/matplotlib_configuration_api.rst

@@ -69,4 +69,6 @@ Colormaps and color sequences
 Miscellaneous
 =============
 
+.. autoclass:: MatplotlibDeprecationWarning
+
 .. autofunction:: get_cachedir

doc/api/next_api_changes/deprecations/23720-RS.rst

@@ -0,0 +1,13 @@
+Deprecation aliases in cbook
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The module ``matplotlib.cbook.deprecation`` was previously deprecated in
+Matplotlib 3.4, along with deprecation-related API in ``matplotlib.cbook``. Due
+to technical issues, ``matplotlib.cbook.MatplotlibDeprecationWarning`` and
+``matplotlib.cbook.mplDeprecation`` did not raise deprecation warnings on use.
+Changes in Python have now made it possible to warn when these aliases are
+being used.
+
+In order to avoid downstream breakage, these aliases will now warn, and their
+removal has been pushed from 3.6 to 3.8 to give time to notice said warnings.
+As replacement, please use `matplotlib.MatplotlibDeprecationWarning`.

doc/api/next_api_changes/removals/22514-OG.rst

@@ -3,5 +3,4 @@ Removal of deprecations in ``cbook``
 
 The module ``cbook.deprecation`` is removed from the public API as it is
 considered internal. This also holds for deprecation-related re-imports in
-``cbook``: ``deprecated``, ``MatplotlibDeprecationWarning``,
-``mplDeprecation``, and ``warn_deprecated``.
+``cbook``: ``deprecated``, and ``warn_deprecated``.

doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst

@@ -47,16 +47,16 @@ corresponding ``Axes.add_*`` method.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Historically, it has not been possible to filter
-`.MatplotlibDeprecationWarning`\s by checking for `DeprecationWarning`, since we
-subclass `UserWarning` directly.
+`~matplotlib.MatplotlibDeprecationWarning`\s by checking for
+`DeprecationWarning`, since we subclass `UserWarning` directly.
 
 The decision to not subclass `DeprecationWarning` has to do with a decision
 from core Python in the 2.x days to not show `DeprecationWarning`\s to users.
 However, there is now a more sophisticated filter in place (see
 https://www.python.org/dev/peps/pep-0565/).
 
-Users will now see `.MatplotlibDeprecationWarning` only during interactive
-sessions, and these can be silenced by the standard mechanism:
+Users will now see `~matplotlib.MatplotlibDeprecationWarning` only during
+interactive sessions, and these can be silenced by the standard mechanism:
 
 .. code:: python
 

doc/devel/contributing.rst

@@ -322,8 +322,8 @@ Introducing
 1. Announce the deprecation in a new file
    :file:`doc/api/next_api_changes/deprecations/99999-ABC.rst` where ``99999``
    is the pull request number and ``ABC`` are the contributor's initials.
-2. If possible, issue a `.MatplotlibDeprecationWarning` when the deprecated
-   API is used. There are a number of helper tools for this:
+2. If possible, issue a `~matplotlib.MatplotlibDeprecationWarning` when the
+   deprecated API is used. There are a number of helper tools for this:
 
    - Use ``_api.warn_deprecated()`` for general deprecation warnings
    - Use the decorator ``@_api.deprecated`` to deprecate classes, functions,

lib/matplotlib/cbook/__init__.py

@@ -30,6 +30,19 @@
 from matplotlib import _api, _c_internal_utils
 
 
+@_api.caching_module_getattr
+class __getattr__:
+    # module-level deprecations
+    MatplotlibDeprecationWarning = _api.deprecated(
+        "3.6", obj_type="",
+        alternative="matplotlib.MatplotlibDeprecationWarning")(
+        property(lambda self: _api.deprecation.MatplotlibDeprecationWarning))
+    mplDeprecation = _api.deprecated(
+        "3.6", obj_type="",
+        alternative="matplotlib.MatplotlibDeprecationWarning")(
+        property(lambda self: _api.deprecation.MatplotlibDeprecationWarning))
+
+
 def _get_running_interactive_framework():
     """
     Return the interactive framework whose event loop is currently running, if