diff --git a/doc/api/next_api_changes/deprecations/23629-TH.rst b/doc/api/next_api_changes/deprecations/23629-TH.rst new file mode 100644 index 000000000000..5b7a36436663 --- /dev/null +++ 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 index db72bbdff020..00fd185836ca 100644 --- a/lib/matplotlib/_tight_bbox.py +++ b/lib/matplotlib/_tight_bbox.py @@ -30,20 +30,20 @@ def adjust_bbox(fig, bbox_inches, fixed_dpi=None): 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 index 980ef2f51c94..36393891f5cb 100644 --- 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 index 3fabf49ebb38..0e66951db0c9 100644 --- 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 index 0a0ff01a2571..021efa12ab7e 100644 --- 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 index dd37d3d8ee80..610c13a0d71c 100644 --- 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 index 2a2b5957e844..ce4df1f0d4eb 100644 --- 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 index c7ce4ba30a8c..e50ffa79bf69 100644 --- 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()