From f8c35e0727376b0e87857014c7ad5d240d3861cd Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Mon, 9 Mar 2026 16:12:44 +0100
Subject: [PATCH] DOC: Document that set_aspect applies the aspect lazily

Makes the effect in #31232 easier to understand.
Helps a bit clarifying the original vs. active position concept #31254.
---
 lib/matplotlib/axes/_base.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
index baab0e930bbc..bb975e585ad0 100644
--- 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