Bug summary

Per the matplotlib.pyplot.subplot_tool documentation, the return value is suppose to be a matplotlib.widgets.SubplotTool instance.

In pyplot.py, the type hint also specifies that None can be returned:

def subplot_tool(targetfig: Figure | None = None) -> SubplotTool | None:
    """
    Launch a subplot tool window for a figure.

    Returns
    -------
    `matplotlib.widgets.SubplotTool`
    """

However, when using the qtagg backend, a SubplotToolQt instance is returned. Despite the name, it doesn't inherit from SubplotTool, only QtWidgets.QDialog.

I think there are multiple issues here:

1. The documentation should mention the None case
2. configure_subplot in backend_bases.pyi should have a type hint with a return value of widgets.SubplotTool | None.
3. qtagg should then return None from its configure_subplot method.

Alternatively, SubplotToolQt should inherit from both SubplotTool and QtWidgets.QDialog, but I'm not sure what all that would entail.

Code for reproduction

import matplotlib.pyplot as plt
import matplotlib
import numpy as np

x = np.linspace(0, 10, 100)
fig, ax = plt.subplots()
ax.plot(x, np.sin(x))

tool = plt.subplot_tool()
if tool:
    assert isinstance(tool, matplotlib.widgets.SubplotTool)

plt.show()

Actual outcome

AssertionError

Expected outcome

No assertion.

Additional information

No response

Operating system

No response

Matplotlib Version

3.11

Matplotlib Backend

qtagg

Python version

3.14.5

Jupyter version

No response

Installation

None