spacr.figure_sink

Save figures and optionally publish them to an attached viewer.

Publishing is independent of Matplotlib’s global pyplot registry, so figures constructed with matplotlib.figure.Figure are handled the same way as pyplot figures. Headless callers install no sink; files are still written and this module does not import Qt.

Functions

clear_sink(→ None)	Remove BOTH sinks. A run that has finished is not still publishing.
file_sink(→ Optional[Callable[..., Any]])	The installed file sink, or None. For a test that wants to assert it.
publish(fig[, path, fmt, dpi, close])	Save fig and send it to the installed display sink.
publish_file(path[, title])	Announce a figure FILE somebody else already wrote. Returns the path.
set_file_sink(sink)	Install the callable that receives published FILES.
set_sink(sink)	Install the callable that receives published figures.
sink(→ Optional[Callable[..., Any]])	The installed sink, or None. For a test that wants to assert it.

Module Contents

spacr.figure_sink.clear_sink() → None

Remove BOTH sinks. A run that has finished is not still publishing.

Both, because there are two routes into the gallery now and a run that left one of them installed would keep announcing into a screen that has moved on – which is worse than the missing tile it was added to fix.

spacr.figure_sink.file_sink() → Callable[..., Any] | None

The installed file sink, or None. For a test that wants to assert it.

spacr.figure_sink.publish(fig, path=None, *, fmt=None, dpi=None, close=False, **kwargs)

Save fig and send it to the installed display sink.

Parameters:

• fig – Matplotlib figure. None is accepted and returns None.

• path – output path. Omit it to publish without saving.

• fmt – explicit output format; otherwise inferred by spacr.plot.save_figure().

• dpi – explicit output resolution; otherwise use the figure setting.

• close – close the figure after the sink has received it.

Returns:

path written, or None when no file was requested or no figure was supplied.

Saving occurs before the best-effort sink notification, so a display-sink error cannot remove an output file that was written successfully.

spacr.figure_sink.publish_file(path, title=None)

Announce a figure FILE somebody else already wrote. Returns the path.

Parameters:

path – existing figure file to announce to the active sink.

The rule – saved and visible are the same event – with the half that publish() cannot cover. A pyqtgraph scene exported by FastPlot.export is a finished file and never was a matplotlib Figure, so there is nothing for the figure sink to render; without this, moving a generated plot to the screen’s renderer would silently take it out of the gallery, which is the exact bug 139 C was filed for.

A SINK THAT RAISES DOES NOT LOSE THE FILE, for the same reason as in publish(): the file is already on disk and the announcement is best-effort, so a GUI that has gone away must not take the run’s output with it.

spacr.figure_sink.set_file_sink(sink: Callable[..., Any] | None)

Install the callable that receives published FILES.

Parameters:

sink – called sink(path, title) on the thread that published. Like set_sink() it must not touch a widget.

Returns:

the sink that was installed before, so a caller can put it back.

spacr.figure_sink.set_sink(sink: Callable[..., Any] | None)

Install the callable that receives published figures.

Parameters:

sink – called sink(fig, path) on the thread that published. It must not touch a widget – the GUI side renders to a PNG and hands that over a signal.

Returns:

the sink that was installed before, so a caller can put it back.

spacr.figure_sink.sink() → Callable[..., Any] | None

The installed sink, or None. For a test that wants to assert it.