Backends API

BackendProtocol

BackendProtocol

Bases: Protocol[FigureT_co]

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.

Attributes:

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

Methods:

render

render(spec: PlotSpec) -> FigureT_co

Render a single-panel plot.

Parameters:

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

Returns:

Type	Description
FigureT_co	Native figure object.

render_figure

render_figure(spec: FigureSpec) -> FigureT_co

Render a multi-panel figure.

Parameters:

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

Returns:

Type	Description
FigureT_co	Native figure object.

show

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

Display the native figure interactively.

Parameters:

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

save

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

Save the native figure to disk.

Parameters:

Name	Type	Description	Default
fig	FigureT_co	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).	{}

apply_theme

apply_theme(theme: ThemeSpec) -> None

Apply a :class:~cplots.core.theme.ThemeSpec globally to this backend.

Parameters:

Name	Type	Description	Default
theme	ThemeSpec	Theme to apply. For matplotlib this mutates rcParams; for altair it registers a custom Vega theme.	required

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.

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 closed matplotlib.figure.Figure (call show() to display).

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 closed matplotlib.figure.Figure.

apply_theme

apply_theme(theme: ThemeSpec) -> None

Apply a ThemeSpec to matplotlib's global rcParams.

Parameters:

Name	Type	Description	Default
theme	ThemeSpec	Theme to apply. theme.extra keys are applied directly to mpl.rcParams. rcParams are reset to defaults first so previous theme settings do not bleed into the current render.	required

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.

apply_theme

apply_theme(theme: ThemeSpec) -> None

No-op: Plotly themes are applied per-render via layout kwargs.

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.

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.

apply_theme

apply_theme(theme: ThemeSpec) -> None

Register and enable a custom Vega-Lite theme from a ThemeSpec.

Parameters:

Name	Type	Description	Default
theme	ThemeSpec	Theme to apply. Sets background color, font family, and axis label font sizes via the Vega-Lite theme config.	required