Backends API

BackendProtocol

BackendProtocol

Bases: Protocol[FigureT]

Structural protocol that every cplots backend must satisfy.

A backend translates a :class:~cplots.core.spec.PlotSpec or :class:~cplots.core.spec.FigureSpec into a native figure object. Any class that implements these methods is a valid backend — no inheritance required.

Styling: the spec's style (a :class:~cplots.core.theme.Style, possibly None or with unset fields) applies to the figure being rendered only. A backend must not change process-wide state such as matplotlib's rcParams beyond the render (use matplotlib.rc_context).

Attributes:

Name	Type	Description
name	str	Unique backend identifier (e.g. "matplotlib").

Methods:

render

render(spec: PlotSpec) -> FigureT

Render a single-panel plot.

Parameters:

Name	Type	Description	Default
spec	PlotSpec	Backend-agnostic plot specification.	required

Returns:

Type	Description
FigureT	Native figure object.

render_figure

render_figure(spec: FigureSpec) -> FigureT

Render a multi-panel figure.

Parameters:

Name	Type	Description	Default
spec	FigureSpec	Backend-agnostic multi-panel figure specification.	required

Returns:

Type	Description
FigureT	Native figure object.

show

show(fig: FigureT, **kwargs: Any) -> None

Display the native figure interactively.

Parameters:

Name	Type	Description	Default
fig	FigureT	Native figure returned by :meth:render or :meth:render_figure.	required
**kwargs	Any	Backend-specific display options.	{}

save

save(fig: FigureT, path: str | PathLike[str], **kwargs: Any) -> None

Save the native figure to disk.

Parameters:

Name	Type	Description	Default
fig	FigureT	Native figure returned by :meth:render or :meth:render_figure.	required
path	str | PathLike[str]	Destination file path.	required
**kwargs	Any	Backend-specific save options (e.g. dpi=300).	{}

BaseBackend

BaseBackend

Optional base class for backends that want automatic registration.

Subclass with the name keyword to self-register on class creation::

class MyBackend(BaseBackend, name="mybackend"):
    def render(self, spec): ...
    ...

The name keyword triggers :func:~cplots.core.registry.register_backend at class-definition time so no manual registration call is required.

Trace dispatch: :meth:_dispatch calls self._draw_<snake_case_type>(trace, ctx) (e.g. _draw_band_trace for a :class:~cplots.core.spec.BandTrace) and raises a uniform NotImplementedError for trace types the backend has no method for. Backends that don't draw trace by trace can check up front with :meth:_require.

Presentation features: :attr:capabilities lists the features of :data:cplots.core.features.FEATURES the backend renders; :meth:_check_features warns once about any other feature a spec asks for.

Methods:

render_figure

render_figure(spec: Any) -> Any

Render a multi-panel FigureSpec.

Raises:

Type	Description
NotImplementedError	Subclasses that support multi-panel layouts must override this method.

MatplotlibBackend

MatplotlibBackend

MatplotlibBackend()

Bases: BaseBackend

Matplotlib backend for cplots.

Produces matplotlib.figure.Figure objects. Registered automatically under the name "matplotlib".

Requires: pip install cplots[matplotlib]

Methods:

render

render(spec: PlotSpec) -> matplotlib.figure.Figure

Render a single PlotSpec to a matplotlib Figure.

Parameters:

Name	Type	Description	Default
spec	PlotSpec	Backend-agnostic plot specification.	required

Returns:

Type	Description
Figure	A matplotlib.figure.Figure. Call show() to display it.

render_figure

render_figure(spec: FigureSpec) -> matplotlib.figure.Figure

Render a multi-panel FigureSpec to a matplotlib Figure.

Parameters:

Name	Type	Description	Default
spec	FigureSpec	Backend-agnostic multi-panel figure specification.	required

Returns:

Type	Description
Figure	A matplotlib.figure.Figure.

Raises:

Type	Description
NotImplementedError	For 3D panels or TrianglePlot panels.

save

save(fig: Figure, path: str | PathLike[str], **kwargs: Any) -> None

Write fig to path and close it (save() renders a fresh figure each time, so keeping it open would only accumulate figures in batch scripts).

PlotlyBackend

PlotlyBackend

PlotlyBackend()

Bases: BaseBackend

Plotly backend for cplots.

Produces plotly.graph_objects.Figure objects. Registered automatically under the name "plotly".

When latex_labels=True on the spec, axis labels and titles are passed through unchanged so MathJax can render them in HTML export.

Requires: pip install cplots[plotly]

Methods:

render

render(spec: PlotSpec) -> go.Figure

Render a single PlotSpec to a Plotly Figure.

Parameters:

Name	Type	Description	Default
spec	PlotSpec	Backend-agnostic plot specification.	required

Returns:

Type	Description
Figure	A plotly.graph_objects.Figure.

render_figure

render_figure(spec: FigureSpec) -> go.Figure

Render a multi-panel FigureSpec to a Plotly Figure with subplots.

Parameters:

Name	Type	Description	Default
spec	FigureSpec	Backend-agnostic multi-panel figure specification.	required

Returns:

Type	Description
Figure	A plotly.graph_objects.Figure with subplot layout.

save

save(fig: Figure, path: str | PathLike[str], **kwargs: Any) -> None

Write fig: .html/.htm as interactive HTML, anything else as an image.

Images need kaleido; HTML does not.

AltairBackend

AltairBackend

AltairBackend()

Bases: BaseBackend

Altair (Vega-Lite) backend for cplots.

Produces altair.Chart objects. Registered automatically under the name "altair".

Note

Rowspan > 1 in multi-panel layouts is not supported; use the matplotlib or plotly backend for spanning layouts. Traces with typed styling (alpha, line width/style, markers, error bars) are drawn as separate layers without a legend entry; plain traces share one legend.

Requires: pip install cplots[altair]

Methods:

render

render(spec: PlotSpec, *, interactive: bool = True) -> alt.Chart

Render a single PlotSpec to an Altair Chart.

Parameters:

Name	Type	Description	Default
spec	PlotSpec	Backend-agnostic plot specification.	required
interactive	bool	Whether to call .interactive() on the chart, enabling pan and zoom in Jupyter notebooks.	True

Returns:

Type	Description
Chart	An altair.Chart (or layered chart for multi-trace plots).

render_figure

render_figure(spec: FigureSpec) -> Any

Render a multi-panel FigureSpec as an Altair hconcat/vconcat chart.

Parameters:

Name	Type	Description	Default
spec	FigureSpec	Backend-agnostic multi-panel figure specification.	required

Returns:

Type	Description
Any	An altair.Chart, altair.HConcatChart, or
Any	altair.VConcatChart depending on layout.

Raises:

Type	Description
NotImplementedError	If any panel has rowspan > 1.

UltraplotBackend

UltraplotBackend

UltraplotBackend()

Bases: BaseBackend

Ultraplot backend: x/y traces, bands and text only.