BackendPolicy#

class scikitplot.corpus.BackendPolicy(name='resilient', order=(), include_unlisted=True, allow_fallback=True, require_ready=False, allow_network=True, allow_download=True, on_exhausted=ErrorPolicy.COLLECT)[source]#

Policy for selecting and exhausting optional backend chains.

The policy controls orchestration, not backend implementation details. Readers continue to decide what counts as a usable result and which exceptions are safe to fall back from.

Parameters:
namestr

Stable policy label used in diagnostics.

ordertuple[str, …], optional

Preferred backend names. Unlisted candidates follow in their declared order unless include_unlisted is false.

include_unlistedbool, optional

Append candidates absent from order. Default: True.

allow_fallbackbool, optional

When false, only the first selected candidate is attempted.

require_readybool, optional

Skip candidates whose registered capability is not definitely ready. This is useful for deterministic/offline runs; the default resilient policy may attempt components whose model readiness is unknowable until first use.

allow_networkbool, optional

Permit candidates declaring a network requirement.

allow_downloadbool, optional

Permit candidates that may download assets on first use. Backends that declare offline_capable=True may still run when downloads are forbidden, but they must enforce a local-only execution mode.

on_exhaustedErrorPolicy, optional

Public operation behavior after every backend fails. The generic runner records the policy but does not raise; readers apply it because only the reader knows the correct exception/message contract.

Parameters:
allow_download: bool = True#
allow_fallback: bool = True#
allow_network: bool = True#
classmethod first_available()[source]#

Attempt only the first selected candidate; do not cascade.

Return type:

BackendPolicy

classmethod from_config(config)[source]#

Build a policy from JSON/YAML-shaped configuration.

The optional preset key selects resilient (default), strict, offline or first first; remaining fields explicitly override the preset. Unknown fields are rejected so misspelled policy controls never look applied while doing nothing.

Parameters:

config (Mapping[str, Any])

Return type:

BackendPolicy

include_unlisted: bool = True#
name: str = 'resilient'#
classmethod offline()[source]#

Use only local components and forbid network/download side effects.

Readiness may be UNKNOWN for model-backed engines whose cache can only be proven by attempting a local-only load. Such engines are eligible only when their candidate declares offline_capable=True.

Return type:

BackendPolicy

on_exhausted: ErrorPolicy = 'collect'[source]#
order: tuple[str, ...] = ()#
property raise_on_exhausted: bool#

Whether the operation should raise after chain exhaustion.

require_ready: bool = False#
classmethod resilient()[source]#

Fallback through declared candidates and collect final failure.

Return type:

BackendPolicy

classmethod strict()[source]#

Fallback through candidates, then require the caller to raise.

Return type:

BackendPolicy

to_dict()[source]#

Return a JSON-compatible policy representation.

Return type:

dict[str, Any]

with_order(*names, include_unlisted=None)[source]#

Return a copy with explicit backend preference order.

Parameters:
  • names (str)

  • include_unlisted (bool | None)

Return type:

BackendPolicy