MNT/DOC: Deprecate anchor in Axes3D.set_aspect

Aaratrika-Shelly · Aaratrika-Shelly · commit 83b8e42bf848 · 2025-09-02T19:32:06.000Z
diff --git a/doc/api/next_api_changes/deprecations/30364-AS.rst b/doc/api/next_api_changes/deprecations/30364-AS.rst
@@ -0,0 +1,4 @@
+Parameters ``Axes3D.set_aspect(..., anchor=..., share=...)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The parameters *anchor* and *share* of `.Axes3D.set_aspect` are deprecated.
+They had no effect on 3D axes and will be removed in a future version.
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -244,6 +244,8 @@ def _transformed_cube(self, vals):
                 (minx, maxy, maxz)]
         return proj3d._proj_points(xyzs, self.M)
 
+    @_api.delete_parameter("3.11", "share")
+    @_api.delete_parameter("3.11", "anchor")
     def set_aspect(self, aspect, adjustable=None, anchor=None, share=False):
         """
         Set the aspect ratios.
@@ -263,39 +265,31 @@ def set_aspect(self, aspect, adjustable=None, anchor=None, share=False):
             'equalyz'   adapt the y and z axes to have equal aspect ratios.
             =========   ==================================================
 
-        adjustable : None or {'box', 'datalim'}, optional
-            If not *None*, this defines which parameter will be adjusted to
-            meet the required aspect. See `.set_adjustable` for further
-            details.
+        adjustable : {'box', 'datalim'}, default: 'box'
+            Defines which parameter to adjust to meet the aspect ratio.
+
+            - 'box': Change the physical dimensions of the axes bounding box.
+            - 'datalim': Change the x, y, or z data limits.
 
         anchor : None or str or 2-tuple of float, optional
-            If not *None*, this defines where the Axes will be drawn if there
-            is extra space due to aspect constraints. The most common way to
-            specify the anchor are abbreviations of cardinal directions:
-
-            =====   =====================
-            value   description
-            =====   =====================
-            'C'     centered
-            'SW'    lower left corner
-            'S'     middle of bottom edge
-            'SE'    lower right corner
-            etc.
-            =====   =====================
-
-            See `~.Axes.set_anchor` for further details.
+            .. deprecated:: 3.11
+                This parameter has no effect.
 
         share : bool, default: False
-            If ``True``, apply the settings to all shared Axes.
+            .. deprecated:: 3.11
+                This parameter has no effect.
 
         See Also
         --------
         mpl_toolkits.mplot3d.axes3d.Axes3D.set_box_aspect
         """
+        if adjustable is None:
+            adjustable = 'box'
+        _api.check_in_list(['box', 'datalim'], adjustable=adjustable)
         _api.check_in_list(('auto', 'equal', 'equalxy', 'equalyz', 'equalxz'),
                            aspect=aspect)
-        super().set_aspect(
-            aspect='auto', adjustable=adjustable, anchor=anchor, share=share)
+
+        self.set_adjustable(adjustable)
         self._aspect = aspect
 
         if aspect in ('equal', 'equalxy', 'equalxz', 'equalyz'):
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py b/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py
@@ -17,6 +17,7 @@
 from matplotlib.patches import Circle, PathPatch
 from matplotlib.path import Path
 from matplotlib.text import Text
+from matplotlib import  _api
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -2711,3 +2712,31 @@ def test_line3dcollection_autolim_ragged():
     assert np.allclose(ax.get_xlim3d(), (-0.08333333333333333, 4.083333333333333))
     assert np.allclose(ax.get_ylim3d(), (-0.0625, 3.0625))
     assert np.allclose(ax.get_zlim3d(), (-0.08333333333333333, 4.083333333333333))
+
+
+def test_axes3d_set_aspect_deperecated_params():
+    """
+    Test that using the deprecated 'anchor' and 'share' kwargs in
+    set_aspect raises the correct warning.
+    """
+    fig = plt.figure()
+    ax = fig.add_subplot(projection='3d')
+
+    # Test that providing the `anchor` parameter raises a deprecation warning.
+    with pytest.warns(_api.MatplotlibDeprecationWarning, match="'anchor' parameter"):
+        ax.set_aspect('equal', anchor='C')
+
+    # Test that using the 'share' parameter is now deprecated.
+    with pytest.warns(_api.MatplotlibDeprecationWarning, match="'share' parameter"):
+        ax.set_aspect('equal', share=True)
+
+    # Test that the `adjustable` parameter is correctly processed to satisfy
+    # code coverage.
+    ax.set_aspect('equal', adjustable='box')
+    assert ax.get_adjustable() == 'box'
+
+    ax.set_aspect('equal', adjustable='datalim')
+    assert ax.get_adjustable() == 'datalim'
+
+    with pytest.raises(ValueError, match="adjustable"):
+        ax.set_aspect('equal', adjustable='invalid_value')
