Rationalise artist get_figure; make figure attribute a property

rcomer · rcomer · commit 21a68c0c2d09 · 2024-05-06T18:04:12.000+01:00
diff --git a/ci/mypy-stubtest-allowlist.txt b/ci/mypy-stubtest-allowlist.txt
@@ -46,3 +46,6 @@ matplotlib.tri.*TriInterpolator.gradient
 matplotlib.backend_bases.FigureCanvasBase._T
 matplotlib.backend_managers.ToolManager._T
 matplotlib.spines.Spine._T
+
+# Parameter inconsistency due to 3.10 deprecation
+matplotlib.figure.SubFigure.get_figure
diff --git a/doc/api/next_api_changes/behavior/28177-REC.rst b/doc/api/next_api_changes/behavior/28177-REC.rst
@@ -0,0 +1,6 @@
+SubFigure.get_figure
+~~~~~~~~~~~~~~~~~~~~
+
+...in future will by default return the direct parent figure, which may be a SubFigure.
+This will make the default behavior consistent with the ``get_figure`` method of other
+artists.  To control the behavior, use the *root* parameter.
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
@@ -251,7 +251,7 @@ def remove(self):
             if self.figure:
                 if not _ax_flag:
                     self.figure.stale = True
-                self.figure = None
+                self._figure = None
 
         else:
             raise NotImplementedError('cannot remove artist')
@@ -720,9 +720,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):
         """
@@ -740,14 +751,16 @@ def set_figure(self, fig):
         # trying to change the figure an artist is associated with which
         # is not allowed for the same reason as adding the same instance
         # to more than one Axes
-        if self.figure is not None:
+        if self._figure is not None:
             raise RuntimeError("Can not put single artist in "
                                "more than one figure")
-        self.figure = fig
-        if self.figure and self.figure is not self:
+        self._figure = fig
+        if self._figure and self._figure is not self:
             self.pchanged()
         self.stale = True
 
+    figure = property(get_figure, set_figure)
+
     def set_clip_box(self, clipbox):
         """
         Set the artist's clip `.Bbox`.
diff --git a/lib/matplotlib/artist.pyi b/lib/matplotlib/artist.pyi
@@ -87,7 +87,7 @@ class Artist:
     ) -> None: ...
     def set_path_effects(self, path_effects: list[AbstractPathEffect]) -> None: ...
     def get_path_effects(self) -> list[AbstractPathEffect]: ...
-    def get_figure(self) -> Figure | None: ...
+    def get_figure(self, root: bool = ...) -> Figure | SubFigure | None: ...
     def set_figure(self, fig: Figure) -> None: ...
     def set_clip_box(self, clipbox: BboxBase | None) -> None: ...
     def set_clip_path(
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1295,7 +1295,7 @@ def __clear(self):
         self._gridOn = mpl.rcParams['axes.grid']
         old_children, self._children = self._children, []
         for chld in old_children:
-            chld.axes = chld.figure = None
+            chld.axes = chld._figure = None
         self._mouseover_set = _OrderedSet()
         self.child_axes = []
         self._current_image = None  # strictly for pyplot via _sci, _gci
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2215,7 +2215,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 +2239,20 @@ def __init__(self, parent, subplotspec, *,
         self._set_artist_props(self.patch)
         self.patch.set_antialiased(False)
 
+    def get_figure(self, root=None):
+        if root is None:
+            _api.warn_deprecated(
+                '3.10',
+                message=('From Matplotlib 3.12 SubFigure.get_figure will by default '
+                         'return the direct parent figure, which may be a SubFigure. '
+                         'To suppress this warning, pass the root parameter.'))
+            root = True
+
+        if root:
+            return self.figure
+
+        return self._parent
+
     @property
     def dpi(self):
         return self._parent.dpi
@@ -2493,7 +2507,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:
diff --git a/lib/matplotlib/tests/test_artist.py b/lib/matplotlib/tests/test_artist.py
@@ -562,3 +562,24 @@ def draw(self, renderer, extra):
 
     assert 'aardvark' == art.draw(renderer, 'aardvark')
     assert 'aardvark' == art.draw(renderer, extra='aardvark')
+
+
+def test_get_figure():
+    fig = plt.figure()
+    sfig1 = fig.subfigures()
+    sfig2 = sfig1.subfigures()
+    ax = sfig2.subplots()
+
+    assert fig.get_figure() == fig
+
+    assert ax.get_figure() == sfig2
+    assert ax.get_figure(root=False) == sfig2
+    assert ax.get_figure(root=True) == fig
+
+    # SubFigure.get_figure has separate implementation but should give consistent
+    # results to other artists.
+    assert sfig2.get_figure(root=False) == sfig1
+    assert sfig2.get_figure(root=True) == fig
+    # Currently different results by default.
+    with pytest.warns(mpl.MatplotlibDeprecationWarning):
+        assert sfig2.get_figure() == fig
