Rationalise artist get_figure

rcomer · rcomer · commit 5cc7449d71f8 · 2024-05-06T14:50:55.000+01:00
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -181,7 +181,7 @@ def __init__(self):
         self._stale = True
         self.stale_callback = None
         self._axes = None
-        self.figure = None
+        self._figure = None
 
         self._transform = None
         self._transformSet = False
@@ -290,6 +290,8 @@ def convert_yunits(self, y):
             return y
         return ax.yaxis.convert_units(y)
 
+    figure = _api.deprecate_privatize_attribute('3.10', 'get_figure or set_figure')
+
     @property
     def axes(self):
         """The `~.axes.Axes` instance the artist resides in, or *None*."""
@@ -720,9 +722,20 @@ def set_path_effects(self, path_effects):
     def get_path_effects(self):
         return self._path_effects
 
-    def get_figure(self):
-        """Return the `.Figure` instance the artist belongs to."""
-        return self.figure
+    def get_figure(self, root=False):
+        """
+        Return the `.Figure` or `.SubFigure` instance the artist belongs to.
+
+        Parameters
+        ----------
+        root : bool, default=False
+            If False, return the (Sub)Figure this artist is on.  If True,
+            return the root Figure for a nested tree of SubFigures.
+        """
+        if root:
+            return self._figure._figure
+
+        return self._figure
 
     def set_figure(self, fig):
         """
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -63,6 +63,7 @@
 
 
 def _stale_figure_callback(self, val):
+    """Callback used on non-figure artists."""
     if self.figure:
         self.figure.stale = val
 
@@ -1239,11 +1240,11 @@ def colorbar(
             if isinstance(mappable_host_fig, mpl.figure.SubFigure):
                 mappable_host_fig = mappable_host_fig.figure
             # Warn in case of mismatch
-            if mappable_host_fig is not self.figure:
+            if mappable_host_fig is not self._figure:
                 _api.warn_external(
                         f'Adding colorbar to a different Figure '
                         f'{repr(mappable.figure)} than '
-                        f'{repr(self.figure)} which '
+                        f'{repr(self._figure)} which '
                         f'fig.colorbar is called on.')
 
         NON_COLORBAR_KEYS = [  # remove kws that cannot be passed to Colorbar
@@ -1760,7 +1761,7 @@ def get_tightbbox(self, renderer=None, bbox_extra_artists=None):
         """
 
         if renderer is None:
-            renderer = self.figure._get_renderer()
+            renderer = self._figure._get_renderer()
 
         bb = []
         if bbox_extra_artists is None:
@@ -2215,7 +2216,7 @@ def __init__(self, parent, subplotspec, *,
 
         self._subplotspec = subplotspec
         self._parent = parent
-        self.figure = parent.figure
+        self._figure = parent._figure
 
         # subfigures use the parent axstack
         self._axstack = parent._axstack
@@ -2239,6 +2240,13 @@ def __init__(self, parent, subplotspec, *,
         self._set_artist_props(self.patch)
         self.patch.set_antialiased(False)
 
+    def get_figure(self, root=False):
+        # docstring inherited
+        if root:
+            return self._figure
+
+        return self._parent
+
     @property
     def dpi(self):
         return self._parent.dpi
@@ -2349,7 +2357,7 @@ def draw(self, renderer):
             renderer.open_group('subfigure', gid=self.get_gid())
             self.patch.draw(renderer)
             mimage._draw_list_compositing_images(
-                renderer, self, artists, self.figure.suppressComposite)
+                renderer, self, artists, self._figure.suppressComposite)
             renderer.close_group('subfigure')
 
         finally:
@@ -2493,7 +2501,7 @@ def __init__(self,
             %(Figure:kwdoc)s
         """
         super().__init__(**kwargs)
-        self.figure = self
+        self._figure = self
         self._layout_engine = None
 
         if layout is not None:
