FIX: Disallow twinx/twiny on Axes3D

[timhoffm]

Closes #31523.

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.

[rcomer]

From the note in the NotImplementedError docs, I think we should actually be setting these methods to None.
https://docs.python.org/3/library/exceptions.html#NotImplementedError

[timhoffm]

I acknowledge the Python reference docs. However, setting to None has a non-helpful runtime behavior: "TypeError: 'NoneType' object is not callable".

I've followed the pattern of the semilog errors right below, because I think that's decent. You may debate whether NotImplementedError is exactly the right type, and we could change to something else like RuntimeError if you feel stongly. But I think NotImplementedError is bearable given the docs also state "indicate that the real implementation still needs to be added." - in theory we could add that functionality even though its not planned.

[buddy0452004]

I tested both approaches and wanted to share a finding that might be useful for this discussion.
The None approach has a hidden UX problem. Axes3D already uses = None for get_frame_on and set_frame_on so @rcomer suggestion is consistent with the existing codebase pattern. However, when a user actually calls a None overridden method, they still get a cryptic error:

ax.get_frame_on()
# TypeError: 'NoneType' object is not callable

This is essentially the same problem we're trying to fix just a different cryptic error. Setting twinx = None would give users TypeError: 'NoneType' object is not callable instead of the current AttributeError: 'YAxis' object has no attribute 'tick_left'. Neither tells the user why it failed.

The NotImplementedError approach is better UX it gives a clear, actionable message. The Python docs note about NotImplementedError is about abstract base classes specifically, not a general recommendation against using it to signal unsupported operations.

My suggestion: If we go with None for consistency with the existing pattern, we should also fix get_frame_on and set_frame_on to use NotImplementedError in a follow-up otherwise we're perpetuating the same bad UX pattern. If we go with NotImplementedError here, it becomes the new standard for unsupported methods in Axes3D going forward.

Either way, this PR is a clear improvement over the current behaviour. Just wanted to surface this so the decision is made intentionally.

[buddy0452004]

I also noticed get_frame_on and set_frame_on in Axes3D are currently set to None would it make sense to migrate those to the new partialmethod pattern in a follow-up PR for consistency?

[rcomer]

Ah OK, I admit I didn’t actually try it 🐑, just assumed that the documented recommendation would give something useful.

A more specific error might be good: something like SubclassUnsupportedError, but I don’t feel strongly.

[rcomer]

In the issue, @buddy0452004 noted that Polar has a similar problem, so I’m wondering if the exception should be defined somewhere more general that both subclass modules can import from.

Or is toolkits considered sufficiently separate that it makes sense to have its own exceptions?

[buddy0452004]

Since mpl_toolkits and matplotlib are separate packages (different install roots), defining UnsupportedError inside mpl_toolkits.mplot3d and importing it from matplotlib.projections.polar would create a cross-package dependency which feels wrong architecturally.

The natural shared home would be matplotlib.axes._base (or a new matplotlib.exceptions module), since both Axes3D and PolarAxes inherit from _AxesBase. That way:

• Axes3D imports from matplotlib.axes._base (already does this heavily)
• PolarAxes imports from matplotlib.axes._base (same)
• No cross-toolkit dependency
• The exception is co-located with the base class that defines the contract

I confirmed polar has the same issue ax.twinx() on a polar axes raises ValueError: Cannot set Axes adjustable to 'datalim' for Axes which override 'get_data_ratio' another cryptic internal error. So the fix would benefit both projections.

If it's useful, I'm happy to look into adding UnsupportedError to _AxesBase and applying the partialmethod pattern to PolarAxes in a follow-up PR.

[timhoffm]

Ok, since this is needed more often, it should live in matplotlib._api. I've also created a descriptor so that it's easier to mark functions as unsupported:

twinx = _api.unsupported_method()

Note: I've removed the explicit tests for the unsupported log functions, since the descriptor itself is tested and we therefore don't need to test every application.

[buddy0452004]

Great solution placing it in matplotlib._api makes it reusable across the whole codebase. Thanks for the thorough fix

[rcomer]

Nice! I didn’t know about __set_name__ 👀