Description
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:
- 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:b. Items decorated with-@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", ...)
@_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.,c. Items decorated with-@_api.rename_parameter("3.7", "old_name", "new_name") def foo(new_name): ...
@_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).d. Items decorated with-@_api.make_keyword_only("3.7", "arg3") -def foo(arg1, arg2, arg3, arg4): +def foo(arg1, arg2, *, arg3, arg4): ...
@_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): ...
- The corresponding type stub in the related
*.pyi
file. - Any tests for only deprecated behaviour.
- 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,
- Removed code may be aliased by importing in another location, so those imports will have to be removed.
- Documentation may link to the removed API; these should be kept in code style. For example,
should be changed to:
This is some text referencing :class:`.RemovedClass`.
(Please expand the API into the full import name.)This is some text referencing ``matplotlib.submodule.RemovedClass``.
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):
-
lib/matplotlib/animation.py
- 2 deprecations Deprecated code removed in animation.py #26872 -
lib/matplotlib/axis.py
- 1 deprecation Removed the deprecated code fromaxis.py
#26871 -
lib/matplotlib/backends/*.py
- 3 deprecations andsrc/_backend_agg_wrapper.cpp
- 2 deprecations Remove backend 3.7-deprecated API #26962 -
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 -
lib/matplotlib/contour.py
- 5 deprecations Removal of deprecations for Contour #26907 -
lib/matplotlib/collections.py
- 2 deprecations Cleaned up the span_where class method from Polycollections. #26874 -
lib/matplotlib/_fontconfig_patterns.py
- 1 deprecation Remove deprecated code from _fontconfig_patterns #26884 -
lib/matplotlib/gridspec.py
- 1 deprecation Removed deprecated code from gridspec.py #26885 (!) -
lib/matplotlib/lines.py
- 2 deprecations Fixed deprecated APIs in lines.py #26902 -
lib/matplotlib/offsetbox.py
- 3 deprecations Removed the deprecated code from offsetbox.py #26910Updated offsetbox.py #26880 -
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 (!) -
lib/matplotlib/quiver.py
- 2 deprecations 26865 Removed deprecations from quiver.py #26918 -
lib/matplotlib/tri/*.py
- 8 deprecations deprecated api tri #26909 -
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.