DOC: Document that set_aspect applies the aspect lazily

timhoffm · timhoffm · commit f8c35e072737 · 2026-03-09T16:12:44.000+01:00
Makes the effect in #31232 easier to understand. Helps a bit clarifying the original vs. active position concept #31254.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1700,12 +1700,21 @@ def set_aspect(self, aspect, adjustable=None, anchor=None, share=False):
         share : bool, default: False
             If ``True``, apply the settings to all shared Axes.
 
+        Notes
+        -----
+        The aspect will require an update of the Axes position or limits (which
+        one depends on *adjustable*). This update is applied lazily, the latest
+        when the figure is drawn. Use `.apply_aspect` to force an update.
+
         See Also
         --------
         matplotlib.axes.Axes.set_adjustable
             Set how the Axes adjusts to achieve the required aspect ratio.
         matplotlib.axes.Axes.set_anchor
             Set the position in case of extra space.
+        matplotlib.axes.Axes.apply_aspect
+            Force the update required to meet the aspect ratio to happen
+            immediately.
         """
         if cbook._str_equal(aspect, 'equal'):
             aspect = 1
