Problem Description

At present the plotting functions accept a parameter show which defaults to True, which calls plt.show(). I suggest changing the default behaviour to not call plt.show, and deprecating the show parameter.

Rationale

Overall I think this parameter creates needless complexity for no added value.

• It's not needed. In typical notebook environments (e.g. VS Code, jupyter, jupyterlab), matplotlib plots are rendered automatically without needing to call plt.show().
• It can be frustrating, as plots can displaying twice (once by plt.show, and again by the notebook environment).
• It makes the API more complex. Other common plotting libraries (e.g. seaborn) do not have this parameter, as far as I know. Our plotting modules are already complicated enough as is!

API complexity

We generally want to return ax to fit with matplotlib's recommended signature, but this is only workable before plt.show() is called. At present we have to return the ax only if show=False, and otherwise return None.

This means the type signatures need to be quite complex:

@overload
def plot(..., show: Literal[True]) -> None: ...
@overload
def plot(..., show: Literal[False]) -> plt.Axes: ...
def plot(..., show: bool) -> plt.Axes | None: ...

The simpler API could just be:

def plot(...) -> plt.Axes

Suggested implementation plan

• Change the default behaviour to not call plt.show(), and raise a deprecation warning if show is passed (whilst still being backwards-compatible).
• In a several releases' time, remove the show argument. To be tracked on [Meta-issue] deprecation tracker for upcoming releases #3507