From cfb4dd54e66ba8e9b5fc53891677e15706306642 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Wed, 24 Aug 2022 13:49:43 +0200 Subject: [PATCH] Backport PR #23722: Restore deprecation class aliases in cbook --- doc/api/matplotlib_configuration_api.rst | 2 ++ doc/api/next_api_changes/deprecations/23720-RS.rst | 13 +++++++++++++ doc/api/next_api_changes/removals/22514-OG.rst | 3 +-- .../api_changes_3.5.0/behaviour.rst | 8 ++++---- doc/devel/contributing.rst | 4 ++-- lib/matplotlib/cbook/__init__.py | 13 +++++++++++++ 6 files changed, 35 insertions(+), 8 deletions(-) create mode 100644 doc/api/next_api_changes/deprecations/23720-RS.rst diff --git a/doc/api/matplotlib_configuration_api.rst b/doc/api/matplotlib_configuration_api.rst index 23e6b0d2220f..eb9cffb0f93f 100644 --- a/doc/api/matplotlib_configuration_api.rst +++ b/doc/api/matplotlib_configuration_api.rst @@ -69,4 +69,6 @@ Colormaps and color sequences Miscellaneous ============= +.. autoclass:: MatplotlibDeprecationWarning + .. autofunction:: get_cachedir diff --git a/doc/api/next_api_changes/deprecations/23720-RS.rst b/doc/api/next_api_changes/deprecations/23720-RS.rst new file mode 100644 index 000000000000..9e771009aa15 --- /dev/null +++ b/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`. diff --git a/doc/api/next_api_changes/removals/22514-OG.rst b/doc/api/next_api_changes/removals/22514-OG.rst index edce714555bd..c426dd4e5c27 100644 --- a/doc/api/next_api_changes/removals/22514-OG.rst +++ b/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``. diff --git a/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst index 1d6a5e15d2d3..69e38270ca76 100644 --- a/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst +++ b/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 diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 578cf8f28f58..dfdc03d0eeef 100644 --- a/doc/devel/contributing.rst +++ b/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, diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py index f364b8d178f2..17d1cad3a753 100644 --- a/lib/matplotlib/cbook/__init__.py +++ b/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