I agree about the most appropriate exception to raise, but it's not critical, and probably best to defer that sort of API-breaking cleanup. I approve, and will merge this as-is.

Is it cheaper to check if self.axes is not empty than creating a new axes instance with gca if there is no axes exist?

@lkjell Are you referring to plt.delaxes() when the figure does not have an axes? That's indeed an unnecessary axes creation and deletion. However, you'll most likely not trying to delete axes from empty figures a lot, so the performance penality is negligible. I've not changed the algorithmic behavior in this PR, just code and docstring cleanup.

I do. Not sure why implicit deletion does not return the deleted axes. With plt.delaxes there is no guard to undo the deletion.

Figure.del_axes does not return the deleted axes. So i removed the return value to not make any false promises. It has always been None anyway.

That said, a concept of "undo" is quite uncommon in programming, even if it's interactive. I wouldn't have expected this to be possible.

I would not worry about the speed in the case where someone is using plt.delaxes(), it is probably interactive usage where they are typing and the speed difference will be tiny compared to the speed at which they are typing.

If the user passes in the axes to delete they are already holding it. If it is implicit, then the assumption is the user is interactive and does not care.