Prepare inlining MovieWriter.cleanup() into MovieWriter.finish().

The docs only mention `finish()`; but the implementations of `finish()`
simply forwards themselves to `cleanup()` (and do a bit more).  One can
instead just put all the relevant logic in `finish()` and not expose a
separate (basically internal) API.

Author: anntzer

doc/api/next_api_changes/deprecations/19046-AL.rst

@@ -0,0 +1,5 @@
+``MovieWriter.cleanup`` is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Cleanup logic is now fully implemented in `.MovieWriter.finish`.  Third-party
+movie writers should likewise move the relevant cleanup logic there, as
+overridden ``cleanup``\s will no longer be called in the future.

doc/missing-references.json

@@ -251,15 +251,15 @@
     ],
     "matplotlib.axes._axes.Axes": [
       "doc/api/artist_api.rst:189",
-      "doc/api/axes_api.rst:617",
+      "doc/api/axes_api.rst:609",
       "lib/matplotlib/projections/polar.py:docstring of matplotlib.projections.polar.PolarAxes:1",
       "lib/mpl_toolkits/axes_grid1/mpl_axes.py:docstring of mpl_toolkits.axes_grid1.mpl_axes.Axes:1",
       "lib/mpl_toolkits/axisartist/axislines.py:docstring of mpl_toolkits.axisartist.axislines.Axes:1",
       "lib/mpl_toolkits/mplot3d/axes3d.py:docstring of mpl_toolkits.mplot3d.axes3d.Axes3D:1"
     ],
     "matplotlib.axes._base._AxesBase": [
       "doc/api/artist_api.rst:189",
-      "doc/api/axes_api.rst:617",
+      "doc/api/axes_api.rst:609",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes.Axes:1"
     ],
     "matplotlib.backend_bases.FigureCanvas": [
@@ -831,6 +831,7 @@
       "lib/matplotlib/image.py:docstring of matplotlib.image.composite_images:9"
     ],
     "cleanup": [
+      "lib/matplotlib/animation.py:docstring of matplotlib.animation.FileMovieWriter.setup:18",
       "lib/matplotlib/animation.py:docstring of matplotlib.animation.HTMLWriter.setup:18"
     ],
     "colorbar.ColorbarBase.outline": [
@@ -895,7 +896,7 @@
       "lib/mpl_toolkits/mplot3d/axes3d.py:docstring of mpl_toolkits.mplot3d.axes3d.Axes3D.get_ylim3d:24"
     ],
     "ipykernel.pylab.backend_inline": [
-      "doc/users/interactive.rst:256"
+      "doc/users/interactive.rst:257"
     ],
     "kde.covariance_factor": [
       "lib/matplotlib/mlab.py:docstring of matplotlib.mlab.GaussianKDE:41"
@@ -1102,16 +1103,19 @@
       "doc/api/_as_gen/matplotlib.animation.FFMpegWriter.rst:28:<autosummary>:1"
     ],
     "matplotlib.animation.FileMovieWriter.args_key": [
-      "lib/matplotlib/animation.py:docstring of matplotlib.animation.FileMovieWriter.cleanup:1:<autosummary>:1"
+      "lib/matplotlib/animation.py:docstring of matplotlib.animation.FileMovieWriter.clear_temp:1:<autosummary>:1"
     ],
     "matplotlib.animation.FileMovieWriter.bin_path": [
       "doc/api/_as_gen/matplotlib.animation.FileMovieWriter.rst:28:<autosummary>:1"
     ],
+    "matplotlib.animation.FileMovieWriter.cleanup": [
+      "doc/api/_as_gen/matplotlib.animation.FileMovieWriter.rst:28:<autosummary>:1"
+    ],
     "matplotlib.animation.FileMovieWriter.exec_key": [
-      "lib/matplotlib/animation.py:docstring of matplotlib.animation.FileMovieWriter.cleanup:1:<autosummary>:1"
+      "lib/matplotlib/animation.py:docstring of matplotlib.animation.FileMovieWriter.clear_temp:1:<autosummary>:1"
     ],
     "matplotlib.animation.FileMovieWriter.frame_size": [
-      "lib/matplotlib/animation.py:docstring of matplotlib.animation.FileMovieWriter.cleanup:1:<autosummary>:1"
+      "lib/matplotlib/animation.py:docstring of matplotlib.animation.FileMovieWriter.clear_temp:1:<autosummary>:1"
     ],
     "matplotlib.animation.FileMovieWriter.isAvailable": [
       "doc/api/_as_gen/matplotlib.animation.FileMovieWriter.rst:28:<autosummary>:1"

lib/matplotlib/animation.py

@@ -335,7 +335,12 @@ def _run(self):
 
     def finish(self):
         """Finish any processing for writing the movie."""
-        self.cleanup()
+        overridden_cleanup = cbook._deprecate_method_override(
+            __class__.cleanup, self, since="3.4", alternative="finish()")
+        if overridden_cleanup is not None:
+            overridden_cleanup()
+        else:
+            self._cleanup()  # Inline _cleanup() once cleanup() is removed.
 
     def grab_frame(self, **savefig_kwargs):
         # docstring inherited
@@ -355,7 +360,7 @@ def _args(self):
         """Assemble list of encoder-specific command-line arguments."""
         return NotImplementedError("args needs to be implemented by subclass.")
 
-    def cleanup(self):
+    def _cleanup(self):  # Inline to finish() once cleanup() is removed.
         """Clean-up and collect the process used to write the movie file."""
         out, err = self._proc.communicate()
         self._frame_sink().close()
@@ -374,6 +379,10 @@ def cleanup(self):
             raise subprocess.CalledProcessError(
                 self._proc.returncode, self._proc.args, out, err)
 
+    @_api.deprecated("3.4")
+    def cleanup(self):
+        self._cleanup()
+
     @classmethod
     def bin_path(cls):
         """
@@ -505,8 +514,8 @@ def finish(self):
         self._run()
         super().finish()  # Will call clean-up
 
-    def cleanup(self):
-        super().cleanup()
+    def _cleanup(self):  # Inline to finish() once cleanup() is removed.
+        super()._cleanup()
         if self._tmpdir:
             _log.debug('MovieWriter: clearing temporary path=%s', self._tmpdir)
             self._tmpdir.cleanup()