FIX: Disallow twinx/twiny on Axes3D

timhoffm · timhoffm · commit f8a68b706c94 · 2026-04-20T02:07:48.000+02:00
Closes #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/lib/matplotlib/_api/__init__.py b/lib/matplotlib/_api/__init__.py
@@ -35,6 +35,54 @@ def __repr__(self):
 UNSET = _Unset()
 
 
+class UnsupportedError(RuntimeError):
+    """
+    Raised on inherited methods if the child class does not support the functionality
+    of the base class.
+
+    See `.unsupported_method` for details.
+    """
+
+
+class unsupported_method:
+    """
+    Descriptor that creates a method raising `.UnsupportedError`.
+
+    Historically, we have quite a few cases of inheritance hierarchies that do not
+    fully respect the Liskov Substitution Principle, e.g. Axes and Artist. Some of
+    the methods of a base class may not be implemented in the child class. In that case,
+    we override the method in the child class to raise `.UnsupportedError`.
+
+    Use in a class body to mark inherited methods as unsupported::
+
+        class Axes3D(Axes):
+            twinx = _api.unsupported_method()
+
+    Calling ``Axes3D().twinx()`` will raise
+    "UnsupportedError: Axes3D does not support 'twinx'."
+
+    Parameters
+    ----------
+    append_message : str
+        Optional additional text to be appended to the error message.
+    """
+    def __init__(self, *, append_message=None):
+        self.append_message = append_message
+
+    def __set_name__(self, owner, name):
+        message = f"{owner.__name__} does not support '{name}'."
+        if self.append_message:
+            message += ' ' + self.append_message
+
+        def method(self, *args, **kwargs):
+            raise UnsupportedError(message)
+
+        method.__name__ = name
+        method.__qualname__ = f"{owner.__qualname__}.{name}"
+        method.__module__ = owner.__module__
+        setattr(owner, name, method)
+
+
 class classproperty:
     """
     Like `property`, but also triggers on access via the class, and it is the
diff --git a/lib/matplotlib/tests/test_api.py b/lib/matplotlib/tests/test_api.py
@@ -18,6 +18,27 @@
 T = TypeVar('T')
 
 
+def test_unsupported_method():
+    class Base:
+        def method_1(self):
+            pass
+
+        def method_2(self):
+            pass
+
+    class Child(Base):
+        method_1 = _api.unsupported_method()
+        method_2 = _api.unsupported_method(append_message="Sorry!")
+
+    child = Child()
+    with pytest.raises(_api.UnsupportedError,
+                       match=r"^Child does not support 'method_1'\.$"):
+        child.method_1()
+    with pytest.raises(_api.UnsupportedError,
+                       match=r"^Child does not support 'method_2'\. Sorry!$"):
+        child.method_2()
+
+
 @pytest.mark.parametrize('target,shape_repr,test_shape',
                          [((None, ), "(N,)", (1, 3)),
                           ((None, 3), "(N, 3)", (1,)),
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -31,7 +31,6 @@
 """
 
 from collections import defaultdict
-from functools import partialmethod
 import itertools
 import math
 import textwrap
@@ -71,6 +70,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 +1201,16 @@ 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."
-        )
+    twinx = _api.unsupported_method()
+    twiny = _api.unsupported_method()
+    secondary_xaxis = _api.unsupported_method()
+    secondary_yaxis = _api.unsupported_method()
 
-    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")
+    _msg = "Use ax.set_xscale/set_yscale/set_zscale and ax.plot(...) instead."
+    semilogx = _api.unsupported_method(append_message=_msg)
+    semilogy = _api.unsupported_method(append_message=_msg)
+    semilogz = _api.unsupported_method(append_message=_msg)
+    loglog = _api.unsupported_method(append_message=_msg)
 
     get_zticks = _axis_method_wrapper("zaxis", "get_ticklocs")
     set_zticks = _axis_method_wrapper("zaxis", "set_ticks")
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py b/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py
@@ -3164,15 +3164,6 @@ def test_scale3d_autoscale_with_log():
         assert lim[1] > 0, f"{name} upper limit should be positive"
 
 
-@pytest.mark.parametrize("method", ["semilogx", "semilogy", "semilogz", "loglog"])
-def test_semilog_loglog_not_implemented(method):
-    """semilogx/y/z and loglog should raise NotImplementedError on Axes3D."""
-    fig = plt.figure()
-    ax = fig.add_subplot(projection='3d')
-    with pytest.raises(NotImplementedError, match="Axes3D does not support"):
-        getattr(ax, method)([1, 10, 100], [1, 2, 3])
-
-
 def test_scale3d_calc_coord():
     """_calc_coord should return data coordinates with correct pane values."""
     fig = plt.figure()
