Merge pull request #31314 from rcomer/set_position-active-doc

QuLogic · web-flow · commit b5d2c9ee0a38 · 2026-04-16T22:24:40.000-04:00
DOC: setting active axes position is ineffective
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1179,6 +1179,15 @@ def set_position(self, pos, which='both'):
         which : {'both', 'active', 'original'}, default: 'both'
             Determines which position variables to change.
 
+            .. note::
+                This parameter is considered internal. End users should not use it.
+
+                For native Matplotlib `.Axes`, the active position is
+                determined by a combination of the original position and the
+                aspect ratio.  Any active position set by the user will therefore be
+                overwritten by internal handling.  This option is retained as it may be
+                relevant for some third party `.Axes` subclasses.
+
         See Also
         --------
         matplotlib.transforms.Bbox.from_bounds
