matplotlib · timhoffm · Aug 15, 2022 · Jun 3, 2024
diff --git a/doc/api/next_api_changes/deprecations/23629-TH.rst b/doc/api/next_api_changes/deprecations/23629-TH.rst
@@ -0,0 +1,3 @@
+The parameter *position* in ``Axes.apply_aspect()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... is deprecated. It is considered internal API and no public use case is known.
diff --git a/lib/matplotlib/_tight_bbox.py b/lib/matplotlib/_tight_bbox.py
@@ -30,20 +30,20 @@
         current_pos = ax.get_position(original=False).frozen()
         ax.set_axes_locator(lambda a, r, _pos=current_pos: _pos)
         # override the method that enforces the aspect ratio on the Axes
-        if 'apply_aspect' in ax.__dict__:
-            old_aspect.append(ax.apply_aspect)
+        if '_apply_aspect' in ax.__dict__:
+            old_aspect.append(ax._apply_aspect)
         else:
             old_aspect.append(sentinel)
-        ax.apply_aspect = lambda pos=None: None
+        ax._apply_aspect = lambda pos=None: None
 
     def restore_bbox():
         for ax, loc, aspect in zip(fig.axes, locator_list, old_aspect):
             ax.set_axes_locator(loc)
             if aspect is sentinel:
                 # delete our no-op function which un-hides the original method
-                del ax.apply_aspect
+                del ax._apply_aspect
             else:
-                ax.apply_aspect = aspect
+                ax._apply_aspect = aspect
 
         fig.bbox = origBbox
         fig.bbox_inches = origBboxInches

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1870,6 +1870,7 @@ def get_data_ratio(self):
         ysize = max(abs(tymax - tymin), 1e-30)
         return ysize / xsize
 
+    @_api.delete_parameter("3.10", "position")
     def apply_aspect(self, position=None):
         """
         Adjust the Axes for a specified data aspect ratio.
@@ -1885,6 +1886,12 @@ def apply_aspect(self, position=None):
             Axes within the figure as a Bbox. See `~.Axes.get_position`
             for further details.
 
+            .. deprecated:: 3.10
+
+                Changing the *position* through ``apply_aspect`` is
+                considered internal API. This parameter will be removed
+                in the future.
+
         Notes
         -----
         This is called automatically when each Axes is drawn.  You may need
@@ -1900,6 +1907,36 @@ def apply_aspect(self, position=None):
         matplotlib.axes.Axes.set_anchor
             Set the position in case of extra space.
         """
+        # Note: This method is a thin wrapper that only exists for the purpose
+        # of not exposing the position parameter as public API.
+        self._apply_aspect(position)
+
+    def _apply_aspect(self, position=None):
+        """
+        Adjust the Axes for a specified data aspect ratio.
+
+        See the docstring of the public `apply_aspect` method.
+
+        .. note::
+
+            It is somewhat surprising that "_apply_aspect" takes an optional
+            position as input, which seems more functionality than what the
+            name suggests.
+
+            Generally, applying an aspect will modify the size and position
+            of an Axes. I haven't been able to reconstruct the history but
+            assume, the fact that position is updated anyway was used to
+            funnel additional position constraints into the already existing
+            code. Likely, this function should better be called
+            _update_geometry() nowadays.
+
+        Parameters
+        ----------
+        position : None or .Bbox
+            If not ``None``, this defines the position of the
+            Axes within the figure as a Bbox. See `~.Axes.get_position`
+            for further details.
+        """
         if position is None:
             position = self.get_position(original=True)
 
@@ -2998,7 +3035,7 @@ def _update_title_position(self, renderer):
 
         for ax in self.child_axes:  # Child positions must be updated first.
             locator = ax.get_axes_locator()
-            ax.apply_aspect(locator(self, renderer) if locator else None)
+            ax._apply_aspect(locator(self, renderer) if locator else None)
 
         top = -np.inf
         for ax in axs:
@@ -3061,7 +3098,7 @@ def draw(self, renderer):
 
         # loop over self and child Axes...
         locator = self.get_axes_locator()
-        self.apply_aspect(locator(self, renderer) if locator else None)
+        self._apply_aspect(locator(self, renderer) if locator else None)
 
         artists = self.get_children()
         artists.remove(self.patch)
@@ -4444,7 +4481,7 @@ def get_tightbbox(self, renderer=None, call_axes_locator=True,
             return None
 
         locator = self.get_axes_locator()
-        self.apply_aspect(
+        self._apply_aspect(
             locator(self, renderer) if locator and call_axes_locator else None)
 
         for axis in self._axis_map.values():

diff --git a/lib/matplotlib/axes/_secondary_axes.py b/lib/matplotlib/axes/_secondary_axes.py
@@ -136,7 +136,7 @@ def set_location(self, location, transform=None):
         # this locator lets the axes move in the parent axes coordinates.
         # so it never needs to know where the parent is explicitly in
         # figure coordinates.
-        # it gets called in ax.apply_aspect() (of all places)
+        # it gets called in ax._apply_aspect() (of all places)
         self.set_axes_locator(_TransformedBoundsLocator(bounds, transform))
 
     def apply_aspect(self, position=None):

diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -154,7 +154,7 @@ def __init__(self, **kwargs):
         self.set(**kwargs)
 
     def _get_draw_artists(self, renderer):
-        """Also runs apply_aspect"""
+        """Also runs _apply_aspect"""
         artists = self.get_children()
 
         artists.remove(self.patch)
@@ -163,12 +163,12 @@ def _get_draw_artists(self, renderer):
             key=lambda artist: artist.get_zorder())
         for ax in self._localaxes:
             locator = ax.get_axes_locator()
-            ax.apply_aspect(locator(ax, renderer) if locator else None)
+            ax._apply_aspect(locator(ax, renderer) if locator else None)
 
             for child in ax.get_children():
-                if hasattr(child, 'apply_aspect'):
+                if hasattr(child, '_apply_aspect'):
                     locator = child.get_axes_locator()
-                    child.apply_aspect(
+                    child._apply_aspect(
                         locator(child, renderer) if locator else None)
         return artists
 

diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -5700,7 +5700,7 @@ def test_shared_with_aspect_2():
     axs[0].set_aspect(2, share=True)
     axs[0].plot([1, 2], [3, 4])
     axs[1].plot([3, 4], [1, 2])
-    plt.draw()  # Trigger apply_aspect().
+    plt.draw()  # Trigger _apply_aspect().
     assert axs[0].get_xlim() == axs[1].get_xlim()
     assert axs[0].get_ylim() == axs[1].get_ylim()
 
@@ -5713,7 +5713,7 @@ def test_shared_with_aspect_3():
         axs[1].set_aspect(0.5, adjustable=adjustable)
         axs[0].plot([1, 2], [3, 4])
         axs[1].plot([3, 4], [1, 2])
-        plt.draw()  # Trigger apply_aspect().
+        plt.draw()  # Trigger _apply_aspect().
         assert axs[0].get_xlim() != axs[1].get_xlim()
         assert axs[0].get_ylim() == axs[1].get_ylim()
         fig_aspect = fig.bbox_inches.height / fig.bbox_inches.width

diff --git a/lib/mpl_toolkits/axes_grid1/parasite_axes.py b/lib/mpl_toolkits/axes_grid1/parasite_axes.py
@@ -126,13 +126,13 @@ def draw(self, renderer):
         if locator:
             pos = locator(self, renderer)
             self.set_position(pos, which="active")
-            self.apply_aspect(pos)
+            self._apply_aspect(pos)
         else:
-            self.apply_aspect()
+            self._apply_aspect()
 
         rect = self.get_position()
         for ax in self.parasites:
-            ax.apply_aspect(rect)
+            ax._apply_aspect(rect)
             self._children.extend(ax.get_children())
 
         super().draw(renderer)

diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -386,7 +386,7 @@ def set_box_aspect(self, aspect, *, zoom=1):
         self._box_aspect = self._roll_to_vertical(aspect, reverse=True)
         self.stale = True
 
-    def apply_aspect(self, position=None):
+    def _apply_aspect(self, position=None):
         if position is None:
             position = self.get_position(original=True)
 
@@ -419,7 +419,7 @@ def draw(self, renderer):
         # it adjusts the view limits and the size of the bounding box
         # of the Axes
         locator = self.get_axes_locator()
-        self.apply_aspect(locator(self, renderer) if locator else None)
+        self._apply_aspect(locator(self, renderer) if locator else None)
 
         # add the projection matrix to the renderer
         self.M = self.get_proj()