diff --git a/doc/api/next_api_changes/behavior/20046-BB.rst b/doc/api/next_api_changes/behavior/20046-BB.rst new file mode 100644 index 000000000000..717a42b84603 --- /dev/null +++ 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 index 87738a6ae5d1..bdcd0ac5023c 100644 --- 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 index 440a64f691d9..79b69dfe275c 100644 --- 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 index c0ebe79f33db..4eddf309474b 100644 --- a/lib/matplotlib/tests/test_figure.py +++ b/lib/matplotlib/tests/test_figure.py @@ -8,6 +8,7 @@ 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 @@ -15,7 +16,6 @@ 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