Temporary: Do we really want this?

timhoffm · timhoffm · commit 57c4ddf3e653 · 2024-06-03T18:09:28.000+02:00
diff --git a/doc/api/next_api_changes/deprecations/23629-TH.rst b/doc/api/next_api_changes/deprecations/23629-TH.rst
@@ -1,3 +1,3 @@
 The parameter *position* in ``Axes.apply_aspect()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-... is deprecated. It is considered internal API and now public use case is known.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... is deprecated. It is considered internal API and no public use case is known.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -410,7 +410,7 @@ def inset_axes(self, bounds, *, transform=None, zorder=5, **kwargs):
         inset_ax = projection_class(self.figure, bounds, zorder=zorder, **pkw)
 
         # this locator lets the axes move if in data coordinates.
-        # it gets called in `ax._apply_aspect() (of all places)
+        # it gets called in `ax.apply_aspect() (of all places)
         inset_ax.set_axes_locator(inset_locator)
 
         self.add_child_axes(inset_ax)
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1736,7 +1736,7 @@ def set_adjustable(self, adjustable, share=False):
                 and any(getattr(ax.get_data_ratio, "__func__", None)
                         != _AxesBase.get_data_ratio
                         for ax in axs)):
-            # Limits adjustment by _apply_aspect assumes that the axes' aspect
+            # Limits adjustment by apply_aspect assumes that the axes' aspect
             # ratio can be computed from the data limits and scales.
             raise ValueError("Cannot set Axes adjustable to 'datalim' for "
                              "Axes which override 'get_data_ratio'")
@@ -1870,7 +1870,7 @@ def get_data_ratio(self):
         ysize = max(abs(tymax - tymin), 1e-30)
         return ysize / xsize
 
-    @_api.delete_parameter("3.6", "position")
+    @_api.delete_parameter("3.10", "position")
     def apply_aspect(self, position=None):
         """
         Adjust the Axes for a specified data aspect ratio.
@@ -1882,12 +1882,11 @@ def apply_aspect(self, position=None):
         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.
 
-            .. admonition:: Deprecated
+            .. deprecated:: 3.10
 
                 Changing the *position* through ``apply_aspect`` is
                 considered internal API. This parameter will be removed
@@ -1918,6 +1917,19 @@ def _apply_aspect(self, position=None):
 
         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
diff --git a/lib/matplotlib/axes/_secondary_axes.py b/lib/matplotlib/axes/_secondary_axes.py
@@ -139,10 +139,10 @@ def set_location(self, location, transform=None):
         # it gets called in ax._apply_aspect() (of all places)
         self.set_axes_locator(_TransformedBoundsLocator(bounds, transform))
 
-    def _apply_aspect(self, position=None):
+    def apply_aspect(self, position=None):
         # docstring inherited.
         self._set_lims()
-        super()._apply_aspect(position)
+        super().apply_aspect(position)
 
     @_docstring.copy(Axis.set_ticks)
     def set_ticks(self, ticks, labels=None, *, minor=False, **kwargs):
