FIX: Disallow twinx/twiny on Axes3D

timhoffm · timhoffm · commit c29bc0c84403 · 2026-04-18T23:41:11.000+02:00
Closes matplotlib#31522. The root cause is that Axes3D inherits a lot of functionality from Axes that does not work for 3D. This is a design flaw we cannot easily fix. With this PR we have at least a reasonable mechanism in place to flag not-supported methods. When we get aware of additional methods, we can easily add them.
diff --git a/doc/api/toolkits/mplot3d/axes3d.rst b/doc/api/toolkits/mplot3d/axes3d.rst
@@ -286,8 +286,8 @@ Aliases and deprecated methods
     text3D
 
 
-Other
------
+Other methods
+-------------
 
 .. autosummary::
    :toctree: ../../_as_gen
@@ -302,16 +302,16 @@ Other
 
 .. currentmodule:: mpl_toolkits.mplot3d
 
-Sample 3D data
---------------
+Other
+-----
 
 .. autosummary::
    :toctree: ../../_as_gen
    :template: autosummary.rst
    :nosignatures:
 
    axes3d.get_test_data
-
+   axes3d.UnsupportedError
 
 .. minigallery:: mpl_toolkits.mplot3d.axes3d.Axes3D
    :add-heading:
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -59,6 +59,12 @@
 from . import axis3d
 
 
+class UnsupportedError(RuntimeError):
+    """
+    Raised on Axes3D methods that are inherited from Axes, but not supported by Axes3D.
+    """
+
+
 @_docstring.interpd
 @_api.define_aliases({
     "xlim": ["xlim3d"], "ylim": ["ylim3d"], "zlim": ["zlim3d"]})
@@ -71,6 +77,11 @@ class Axes3D(Axes):
         As a user, you do not instantiate Axes directly, but use Axes creation
         methods instead; e.g. from `.pyplot` or `.Figure`:
         `~.pyplot.subplots`, `~.pyplot.subplot_mosaic` or `.Figure.add_axes`.
+
+    .. note::
+
+        Some of the inherited behavior of Axes is not applicable to 3d and will raise
+        an `.UnsupportedError`.
     """
     name = '3d'
 
@@ -1197,16 +1208,24 @@ def set_zscale(self, value, **kwargs):
         """
         self._set_axis_scale(self.zaxis, value, **kwargs)
 
-    def _raise_semilog_not_implemented(self, name, *args, **kwargs):
-        raise NotImplementedError(
-            f"Axes3D does not support {name}. Use ax.set_xscale/set_yscale/set_zscale "
-            "and ax.plot(...) instead."
+    def _raise_unsupported(self, name, *args, **kwargs):
+        raise UnsupportedError(f"Axes3D does not support '{name}'.")
+
+    twinx = partialmethod(_raise_unsupported, "twinx")
+    twiny = partialmethod(_raise_unsupported, "twiny")
+    secondary_xaxis = partialmethod(_raise_unsupported, "secondary_xaxis")
+    secondary_yaxis = partialmethod(_raise_unsupported, "secondary_yaxis")
+
+    def _raise_semilog_unsupported(self, name, *args, **kwargs):
+        raise UnsupportedError(
+            f"Axes3D does not support '{name}'. "
+            "Use ax.set_xscale/set_yscale/set_zscale and ax.plot(...) instead."
         )
 
-    semilogx = partialmethod(_raise_semilog_not_implemented, "semilogx")
-    semilogy = partialmethod(_raise_semilog_not_implemented, "semilogy")
-    semilogz = partialmethod(_raise_semilog_not_implemented, "semilogz")
-    loglog = partialmethod(_raise_semilog_not_implemented, "loglog")
+    semilogx = partialmethod(_raise_semilog_unsupported, "semilogx")
+    semilogy = partialmethod(_raise_semilog_unsupported, "semilogy")
+    semilogz = partialmethod(_raise_semilog_unsupported, "semilogz")
+    loglog = partialmethod(_raise_semilog_unsupported, "loglog")
 
     get_zticks = _axis_method_wrapper("zaxis", "get_ticklocs")
     set_zticks = _axis_method_wrapper("zaxis", "set_ticks")
