phenotypic.abc_.figure

phenotypic.abc_.figure(*, title: str, section: str = 'default', controls: dict[str, Control] | None = None, description: Any = None, primary: bool = False) → Callable[[Callable[..., 'go.Figure']], Callable[..., 'go.Figure']]

Mark a method as a figure builder and auto-apply the house Plotly theme.

The decorated method returns a raw plotly.graph_objects.Figure, accepts each control as a keyword argument, and may accept a subject as its first positional parameter (any positional-or-keyword parameter that is not itself a control). The decorator:

• validates that every controls key names a real parameter,

• detects wants_subject / subject_param from the signature,

• stashes a FigureSpec on fn.__figure_spec__ (invisible to pydantic), and

• wraps the method so its returned figure is restyled via the "phenotypic" template (imported lazily, so this module stays UI-toolkit-free).

Parameters:

• title (str) – Figure title.

• section (str) – Flat grouping tag for collapsible cards.

• controls (dict[str, Control] | None) – {method-kwarg: Control} recompute inputs.

• description (Any) – Optional interpretive block.

• primary (bool) – Mark this as the inspect() figure.

Returns:

A decorator that returns the wrapped, theme-applying method.

Raises:

ValueError – If a controls key is not a parameter of the method.

Return type:

Callable[[Callable[…, ‘go.Figure’]], Callable[…, ‘go.Figure’]]