matplotlib · jklymak · May 10, 2021 · Dec 23, 2020
diff --git a/doc/api/next_api_changes/behavior/20046-BB.rst b/doc/api/next_api_changes/behavior/20046-BB.rst
@@ -0,0 +1,25 @@
+``MatplotlibDeprecationWarning`` now subclasses ``DeprecationWarning``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Historically, it has not been possible to filter
+``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 DeprecationWarnings 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:
+
+.. code:: python
+
+	warnings.filterwarnings("ignore", category=DeprecationWarning)
+
+Library authors must now enable ``DeprecationWarning``\s explicitly in order
+for (non-interactive) CI/CD pipelines to report back these warnings, as is
+standard for the rest of the Python ecosystem:
+
+.. code:: python
+
+	warnings.filterwarnings("always", DeprecationWarning)
diff --git a/doc/conf.py b/doc/conf.py
@@ -17,7 +17,6 @@
 import warnings
 
 import matplotlib
-from matplotlib._api import MatplotlibDeprecationWarning
 import sphinx
 
 from datetime import datetime
@@ -117,7 +116,7 @@ def _check_dependencies():
 
 # we should ignore warnings coming from importing deprecated modules for
 # autodoc purposes, as this will disappear automatically when they are removed
-warnings.filterwarnings('ignore', category=MatplotlibDeprecationWarning,
+warnings.filterwarnings('ignore', category=DeprecationWarning,
                         module='importlib',  # used by sphinx.autodoc.importer
                         message=r'(\n|.)*module was deprecated.*')
 
@@ -126,7 +125,7 @@ def _check_dependencies():
 
 # make sure to ignore warnings that stem from simply inspecting deprecated
 # class-level attributes
-warnings.filterwarnings('ignore', category=MatplotlibDeprecationWarning,
+warnings.filterwarnings('ignore', category=DeprecationWarning,
                         module='sphinx.util.inspect')
 
 # missing-references names matches sphinx>=3 behavior, so we can't be nitpicky

diff --git a/lib/matplotlib/_api/deprecation.py b/lib/matplotlib/_api/deprecation.py
@@ -17,7 +17,7 @@
 import warnings
 
 
-class MatplotlibDeprecationWarning(UserWarning):
+class MatplotlibDeprecationWarning(DeprecationWarning):
     """
     A class for issuing deprecation warnings for Matplotlib users.
 

diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -8,14 +8,14 @@
 
 import matplotlib as mpl
 from matplotlib import cbook, rcParams
+from matplotlib._api.deprecation import MatplotlibDeprecationWarning
 from matplotlib.testing.decorators import image_comparison, check_figures_equal
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 from matplotlib.ticker import AutoMinorLocator, FixedFormatter, ScalarFormatter
 import matplotlib.pyplot as plt
 import matplotlib.dates as mdates
 import matplotlib.gridspec as gridspec
-from matplotlib.cbook import MatplotlibDeprecationWarning
 import numpy as np
 import pytest
 
@@ -150,7 +150,7 @@ def test_figure_legend():
 def test_gca():
     fig = plt.figure()
 
-    with pytest.warns(UserWarning):
+    with pytest.warns(MatplotlibDeprecationWarning):
         # empty call to add_axes() will throw deprecation warning
         assert fig.add_axes() is None