bencher.plugins

Plot plugin infrastructure for bencher.

The public surface a plugin author depends on:

• BenchData: frozen value handed to render(), defines what plugins receive.

• PlotPlugin: protocol all plugins satisfy.

• plot_plugin: decorator for the function form.

• register_plugin / unregister_plugin / get_registry: explicit registration API.

• PlotFilter / VarRange (re-exported): for declaring match rules.

Bencher’s internal call sites do not yet depend on this package. Migration of the built-in chart types onto the plugin mechanism happens in subsequent PRs.

Submodules

• bencher.plugins.bench_data
• bencher.plugins.builtins
• bencher.plugins.plugin
• bencher.plugins.registry

Attributes

ENTRY_POINT_GROUP

Classes

PlotFilter	A class for representing the types of results a plot is able to represent.
VarRange	A VarRange represents the bounded and unbounded ranges of integers. This class is used to define filters for various variable types. For example by defining cat_var = VarRange(0,0), calling matches(0) will return true, but any other integer will not match. You can also have unbounded ranges for example VarRange(2,None) will match to 2,3,4... up to infinity. for By default the lower and upper bounds are set to -1 so so that no matter what value is passed to matches() will return false. Matches only takes 0 and positive integers.
BenchData	Frozen value type handed to plot plugins. The stable public contract surface for
CacheHandle	Plugin-accessible memoization surface. Bencher core supplies a concrete handle;
RunMeta
PlotPlugin	Stable public contract for plot plugins.
PluginRegistry	In-process registry of plot plugins, keyed by (name, backend).

Functions

plot_plugin(...)	Wrap a function as a plot plugin and (by default) register it with the global
get_registry(→ PluginRegistry)
register_plugin(→ bencher.plugins.plugin.PlotPlugin)
unregister_plugin(→ None)

Package Contents

class bencher.plugins.PlotFilter

A class for representing the types of results a plot is able to represent.

float_range: VarRange

cat_range: VarRange

vector_len: VarRange

result_vars: VarRange

panel_range: VarRange

repeats_range: VarRange

input_range: VarRange

classmethod match_all() → PlotFilter

A filter that matches every sweep shape.

The default PlotFilter() ranges are restrictive (VarRange() matches nothing), which suits plots that opt in to specific shapes. Plugins that do their own internal shape handling should use this instead.

matches_result(plt_cnt_cfg: bencher.plotting.plt_cnt_cfg.PltCntCfg, plot_name: str, override: bool) → PlotMatchesResult

Checks if the result data signature matches the type of data the plot is able to display.

Parameters:

• plt_cnt_cfg (PltCntCfg) – Configuration containing counts of different plot elements

• plot_name (str) – Name of the plot being checked

• override (bool) – Whether to override filter matching rules

Returns:

Object containing match results and information

Return type:

PlotMatchesResult

class bencher.plugins.VarRange(lower_bound: int = 0, upper_bound: int = -1)

A VarRange represents the bounded and unbounded ranges of integers. This class is used to define filters for various variable types. For example by defining cat_var = VarRange(0,0), calling matches(0) will return true, but any other integer will not match. You can also have unbounded ranges for example VarRange(2,None) will match to 2,3,4… up to infinity. for By default the lower and upper bounds are set to -1 so so that no matter what value is passed to matches() will return false. Matches only takes 0 and positive integers.

lower_bound = 0

upper_bound = -1

matches(val: int) → bool

Checks that a value is within the variable range. lower_bound and upper_bound are inclusive (lower_bound<=val<=upper_bound )

Parameters:

val (int) – A positive integer representing a number of items

Returns:

True if the items is within the range, False otherwise.

Return type:

bool

Raises:

ValueError – If val < 0

matches_info(val: int, name: str) → tuple[bool, str]

Get matching info for a value with a descriptive name.

Parameters:

• val (int) – A positive integer to check against the range

• name (str) – A descriptive name for the value being checked, used in the output string

Returns:

A tuple containing:

• bool: True if the value matches the range, False otherwise

• str: A formatted string describing the match result

Return type:

tuple[bool, str]

__str__() → str

class bencher.plugins.BenchData

Frozen value type handed to plot plugins. The stable public contract surface for plugin authors — internal bencher refactors must preserve this shape.

dataset: xarray.Dataset

input_vars: tuple = ()

result_vars: tuple = ()

plt_cnt_cfg: bencher.plotting.plt_cnt_cfg.PltCntCfg | None = None

run_meta: RunMeta

optimizer_study: Any | None = None

baseline_runs: tuple[BenchData, Ellipsis] = ()

cache: CacheHandle | None = None

legacy_result: Any | None = None

render_kwargs: dict

has(capability: str) → bool

True when an optional context field is populated.

Used by PlotFilter.requires to gate plugins that need fields beyond dataset+vars.

with_changes(**kwargs) → BenchData

classmethod fake(*, dataset: xarray.Dataset | None = None, input_vars: tuple = (), result_vars: tuple = (), plt_cnt_cfg: bencher.plotting.plt_cnt_cfg.PltCntCfg | None = None, **overrides) → BenchData

Construct a minimal BenchData for plugin unit tests.

Defaults dataset to an empty xr.Dataset and plt_cnt_cfg to a zero-counted config so plugin authors can construct a usable handle in one line.

class bencher.plugins.CacheHandle

Bases: Protocol

Plugin-accessible memoization surface. Bencher core supplies a concrete handle; plugins treat it as opaque key/value storage.

get(key: str) → Any | None

set(key: str, value: Any) → None

class bencher.plugins.RunMeta

name: str = ''

timestamp: datetime.datetime

sweep_hash: str = ''

class bencher.plugins.PlotPlugin

Bases: Protocol

Stable public contract for plot plugins.

A plugin renders a BenchData handle into a Panel-embeddable view. The plugin owns internal composition (linked hv.Layout, plotly.subplots, full Rerun blueprints, …); bencher only does outer Panel-level composition over plugin outputs.

name: str

backend: str

match: bencher.plotting.plot_filter.PlotFilter

priority: int

requires: frozenset[str]

render(data: bencher.plugins.bench_data.BenchData) → panel.viewable.Viewable

bencher.plugins.plot_plugin(*, name: str, backend: str = 'user', match: bencher.plotting.plot_filter.PlotFilter | None = None, priority: int = 0, requires: frozenset[str] | set[str] | tuple[str, Ellipsis] | None = None, register: bool = True) → Callable[[Callable[[bencher.plugins.bench_data.BenchData], panel.viewable.Viewable]], _FunctionPlugin]

Wrap a function as a plot plugin and (by default) register it with the global registry. Returns the plugin object so callers can also register manually with register=False.

bencher.plugins.ENTRY_POINT_GROUP = 'bencher.plot_plugins'

class bencher.plugins.PluginRegistry

In-process registry of plot plugins, keyed by (name, backend).

name is the chart type (“line”, “heatmap”, …); backend is the rendering library namespace (“holoviews”, “rerun”, …). Several backends may implement the same chart type; selection resolves each chart type to one implementation — the preferred backend when given, otherwise the highest-priority one. Registering an existing (name, backend) pair replaces it, which is the documented override mechanism (a user plugin replaces a built-in by sharing its name and backend, or outranks it from a different backend via priority/preference).

_plugins: dict[tuple[str, str], bencher.plugins.plugin.PlotPlugin]

_entry_points_loaded = False

register(plugin: bencher.plugins.plugin.PlotPlugin) → None

unregister(name: str, backend: str | None = None) → None

Remove a plugin. With no backend, removes every backend’s implementation of that chart type.

clear() → None

mark_entry_points_loaded() → None

Skip the entry-point scan on next lookup. Test-only helper.

get(name: str, backend: str | None = None) → bencher.plugins.plugin.PlotPlugin | None

Resolve a chart type to one implementation.

With a backend, exact lookup. Without, the preferred implementation: highest priority among all backends providing name (ties broken by backend string for determinism).

implementations(name: str) → tuple[bencher.plugins.plugin.PlotPlugin, Ellipsis]

Every backend’s implementation of a chart type, highest priority first.

all() → tuple[bencher.plugins.plugin.PlotPlugin, Ellipsis]

_ensure_entry_points_loaded() → None

_register_loaded(ep_name: str, obj) → None

select(data: bencher.plugins.bench_data.BenchData, *, include: Iterable[str] | None = None, exclude: Iterable[str] | None = None, backend: str | None = None, only: str | None = None) → tuple[bencher.plugins.plugin.PlotPlugin, Ellipsis]

Return one matching implementation per chart type, by descending priority.

• only short-circuits to a single named chart type (no match-filter check; explicit opt-in by name implies the user knows what they want).

• include / exclude filter the candidate set by chart-type name.

• backend states the preferred backend: where a chart type is implemented by several backends, the preferred one is chosen when it matches; chart types the preferred backend does not provide still render through their best other implementation. This is what lets a config flag swap the rendering library under the same set of plotters.

render(data: bencher.plugins.bench_data.BenchData, *, include: Iterable[str] | None = None, exclude: Iterable[str] | None = None, backend: str | None = None, only: str | None = None, strict: bool = False) → tuple[tuple[str, panel.viewable.Viewable], Ellipsis]

Run every selected plugin, returning (name, pane) pairs in priority order.

With strict=False (default) a render exception is caught and replaced with a visible error pane so one broken plugin doesn’t kill the report. strict=True re-raises the first failure — intended for development.

bencher.plugins.get_registry() → PluginRegistry

bencher.plugins.register_plugin(plugin: bencher.plugins.plugin.PlotPlugin) → bencher.plugins.plugin.PlotPlugin

bencher.plugins.unregister_plugin(name: str, backend: str | None = None) → None