Summary

As old and unused API (classes, methods, functions) are found, they are marked deprecated with removal intended in a later release. These API are decorated or otherwise wrapped with the deprecation functions in _api (i.e., deprecated, warn_deprecated, rename_parameter, delete_parameter, make_keyword_only, deprecate_method_override, or deprecate_privatize_attribute).

Now that 3.8 is out and main targets 3.9, we can start the process of removing API that were deprecated in 3.7 (i.e., those with since="3.7" and without pending=True).

Proposed fix

Each part of the deprecated API should be removed:

1. The deprecated code itself:
   a. Items marked with _api.warn_deprecated, @_api.deprecated or @_api.deprecate_privatize_attribute are to be removed on expiry, i.e., any of the marked lines below:

   -@api.deprecated("3.7", ...)
   -def foo():
   -    pass
   
    def bar(x):
        if x is None:
   -        _api.warn_deprecated("3.7", message="x=None is deprecated")
   +        raise ValueError("x=None is not supported")
       ...
   
    class Baz:
         ...
   -     value = _api.deprecate_privatize_attribute("3.7", ...)

   b. Items decorated with @_api.rename_parameter should have this decorator removed, and no other changes will be necessary (the parameter rename should already have been made when the decorator was added.), i.e.,

   -@_api.rename_parameter("3.7", "old_name", "new_name")
    def foo(new_name):
       ...

   c. Items decorated with @_api.make_keyword_only should have the decorator removed, and the parameter named there should be made keyword-only (by adding a * before that point).

   -@_api.make_keyword_only("3.7", "arg3")
   -def foo(arg1, arg2, arg3, arg4):
   +def foo(arg1, arg2, *, arg3, arg4):
       ...

   d. Items decorated with @_api.delete_parameter will need to have the parameter deleted and all following parameters made keyword-only.

   -@_api.delete_parameter("3.7", "arg3")
   -def foo(arg1, arg2, arg3, arg4):
   +def foo(arg1, arg2, *, arg4):
       ...

2. The corresponding type stub in the related *.pyi file.
3. Any tests for only deprecated behaviour.
4. Any related exceptions in ci/mypy-stubtest-allowlist.txt, if there are any.

Additionally, the removal should be documented by placing a snippet in doc/api/next_api_changes/removals/ (see 00001-ABC.rst in that directory for a template). For writing these snippets, you may wish to copy the original deprecation notice, modifying it slightly to state that the API has been removed instead. Please ensure that any references to deleted API include a full path (as there may be many methods with the same name, but on different classes.)

NOTE: After removing the deprecated API, there may be some additional fallout that should be corrected. For example,

1. Removed code may be aliased by importing in another location, so those imports will have to be removed.
2. Documentation may link to the removed API; these should be kept in code style. For example,

   This is some text referencing :class:`.RemovedClass`.

   should be changed to:

   This is some text referencing ``matplotlib.submodule.RemovedClass``.

   (Please expand the API into the full import name.)

See also our documentation on removing deprecated API and #26853 for an example removing several types of deprecated API.

Task list

A quick search shows the following sets of possible parts to remove (for GHC OSD, please use Slack and/or Zoom to make sure someone else hasn't started working on the same set):

1. lib/matplotlib/animation.py - 2 deprecations Deprecated code removed in animation.py #26872
2. lib/matplotlib/axis.py - 1 deprecation Removed the deprecated code from axis.py #26871
3. lib/matplotlib/backends/*.py - 3 deprecations and src/_backend_agg_wrapper.cpp - 2 deprecations Remove backend 3.7-deprecated API  #26962
4. lib/matplotlib/cm.py - 2 deprecations (Note: the documentation for this removal may be a bit tricky to write.) Removal of deprecated API cm #26965
5. lib/matplotlib/contour.py - 5 deprecations Removal of deprecations for Contour #26907
6. lib/matplotlib/collections.py - 2 deprecations Cleaned up the span_where class method from Polycollections. #26874
7. lib/matplotlib/_fontconfig_patterns.py - 1 deprecation Remove deprecated code from _fontconfig_patterns #26884
8. lib/matplotlib/gridspec.py - 1 deprecation Removed deprecated code from gridspec.py #26885 (!)
9. lib/matplotlib/lines.py - 2 deprecations Fixed deprecated APIs in lines.py #26902
10. lib/matplotlib/offsetbox.py - 3 deprecations Removed the deprecated code from offsetbox.py #26910 Updated offsetbox.py #26880
11. lib/matplotlib/patches.py - 1 deprecation Removing deprecated api from patches #26890 issue: 26871 - Remove SimplePath class from patches.py #26876 #26865 removing deprecations to axislines.py #26900 (!)
12. lib/matplotlib/quiver.py - 2 deprecations 26865 Removed deprecations from quiver.py #26918
13. lib/matplotlib/tri/*.py - 8 deprecations deprecated api tri #26909
14. lib/mpl_toolkits/axisartist/axislines.py - 2 deprecations #26865 removing deprecations to axislines.py #26900

There may be some other items I've missed here, but note that we do not want to remove any with pending=True, or since="3.8" or higher.