spacr.plugins

Versioned extension SDK for third-party spaCR plugins.

Plugins are ordinary Python distributions exposing one entry point in the spacr.plugins group. The entry point may resolve to a SpacrPlugin, a mapping accepted by plugin_from_mapping(), or a zero-argument factory returning either. Discovery is lazy, deterministic and failure-isolated: one malformed plugin is recorded in diagnostics() without preventing spaCR or the remaining plugins from loading.

For editable/local development, SPACR_PLUGIN_MODULES may contain a comma-separated list of module or module:attribute references. Installed plugins should always use package entry points instead.

Plugins and assay recipes can also be installed from a catalogue, a JSON file listing each entry’s version, author and licence. A catalogue plugin is installed into its own folder under ~/.spacr/plugins (or SPACR_PLUGIN_HOME), together with the libraries it asks for, so it never replaces or upgrades a package spaCR itself uses; it is discovered like any other plugin until it is uninstalled.

Setting SPACR_DISABLE_PLUGINS to 1, true, yes or on (case-insensitively) skips discovery entirely, so no plugin loads from either source.

Two locks guard the registry: registry readers hold _LOCK only for snapshot access and publication, while _CATALOGUE_MUTATION_LOCK serializes filesystem and module changes without blocking cached registry reads.

Classes

AppContribution	One runnable GUI/headless application contributed by a plugin.
ModelProviderContribution	Immutable record naming a plugin's model-zoo provider.
PluginDiagnostic	One discovery or contribution error visible to users and logs.
ReportContext	Read-only inputs passed to plugin report-section builders.
ReportSectionContribution	Immutable record naming a builder that adds one report section.
SpacrPlugin	Validated plugin manifest returned by a spacr.plugins entry point.

Functions

diagnostics(→ Tuple[PluginDiagnostic, ...])	Return discovery and runtime contribution failures.
discover_plugins(→ Tuple[SpacrPlugin, ...])	Return every valid discovered plugin in deterministic order.
get_app(→ Optional[AppContribution])	Return a contributed app by key, or None.
load_object(→ Any)	Import and return module:attribute (nested attributes supported).
model_providers(→ Tuple[Tuple[str, ...)	Return (plugin_name, provider) model-zoo contributions.
plugin_apps(→ Tuple[AppContribution, ...])	Return all contributed applications.
plugin_from_mapping(→ SpacrPlugin)	Validate a mapping and return its immutable SpacrPlugin.
record_diagnostic(→ None)	Record a model/report/runtime plugin failure without aborting spaCR.
reload_plugins(→ Tuple[SpacrPlugin, ...])	Clear the discovery cache and discover again (primarily for tests/dev).
report_sections(→ Tuple[Tuple[str, ...)	Return (plugin_name, section) report contributions.

Module Contents

class spacr.plugins.AppContribution

One runnable GUI/headless application contributed by a plugin.

Discovery rejects the contribution with ValueError when section, stage, kind or call_style falls outside the fixed vocabulary listed below, when key does not match ^[a-z][a-z0-9_]{1,63}$, or when any non-empty module:callable reference is malformed.

Variables:

• key – identifier the CLI accepts and the GUI registers under; must match ^[a-z][a-z0-9_]{1,63}$. Reusing another plugin’s key fails that plugin’s load; colliding with a built-in app skips the contribution and records a diagnostic.

• name – human-readable title shown in the sidebar and screen header; cannot be blank.

• description – one-line blurb used as the app intro and the spacr-run --list summary; cannot be blank.

• entrypoint – "module:callable" reference to the callable that does the work.

• defaults – "module:callable" reference to a helper returning the settings dictionary; called with {} and retried with no argument.

• section – sidebar group; one of "core", "data", "models", "results" or "toxo".

• stage – maturity annotation; one of "alpha", "beta" or "stable".

• kind – what the app is; one of "assay", "importer", "analysis" or "utility".

• categories – settings-screen tabs, mapping a tab name to the setting keys it holds; empty means the generic ungrouped layout.

• tooltips – hover text per setting key.

• labels – display label per setting key, overriding the generated one.

• docs_url – address the settings screen’s API link opens.

• aliases – extra names the CLI and spacr.validate resolve to key.

• validator – optional "module:callable" reference to a callable taking the settings dict and returning spacr.validate.Problem objects or equivalent mappings.

• screen_factory – optional "module:callable" reference to a factory returning a QWidget, replacing the generic settings screen; it is always invoked as factory(app_key=...) and so must accept that keyword.

• drop_handler – optional "module:callable" reference to a spacr.qt.dnd_handlers.DropHandler subclass.

• icon – absolute image path, or the name of a spaCR semantic icon; empty falls back to the puzzle-piece icon.

• requires – settings the user must supply, phrased for a human.

• writes – what the app leaves on disk.

• call_style – "settings" for fn(settings_dict); "folder" for a callable taking a bare path.

class spacr.plugins.ModelProviderContribution

Immutable record naming a plugin’s model-zoo provider.

Parameters:

• key – identifier for the provider; must match ^[a-z][a-z0-9_]{1,63}$ and be unique across all loaded plugins.

• provider – "module:callable" reference string – not the callable itself – resolved at catalogue time to a zero-argument callable returning model-zoo entries or entry mappings.

class spacr.plugins.PluginDiagnostic

One discovery or contribution error visible to users and logs.

Parameters:

• plugin – entry-point or manifest name identifying the plugin that could not be loaded.

• severity – diagnostic level, such as "error" or "warning".

• message – concise user-facing account of the failed operation.

• exception – captured exception text with the technical cause; empty when no exception accompanied the diagnostic.

class spacr.plugins.ReportContext

Read-only inputs passed to plugin report-section builders.

Parameters:

• src – source folder or object from which the core report is built.

• artifacts – named core report artifacts available for reuse by the plugin section.

• runs – immutable sequence of recorded run summaries associated with the report source.

• options – report-generation options supplied by the caller.

class spacr.plugins.ReportSectionContribution

Immutable record naming a builder that adds one report section.

spacr.report.collect_report() resolves and calls the builder, and substitutes a visible problem section if it fails.

Parameters:

• key – stable section identifier; plugin validation requires ^[a-z][a-z0-9_]{1,63}$ and discovery rejects duplicate contribution keys.

• title – fallback section heading used when the builder returns no title and when the builder fails; cannot be blank.

• builder – "module:callable" reference resolved at report collection to a callable taking ReportContext and returning a spacr.report.Section.

• after – existing section key after which this section is inserted; an unmatched key appends it to the report.

class spacr.plugins.SpacrPlugin

Validated plugin manifest returned by a spacr.plugins entry point.

Parameters:

• name – human-readable plugin name used in diagnostics and discovery output.

• version – version of the plugin distribution, reported to users without being interpreted by spaCR.

• api_version – plugin SDK version the manifest targets; its major version must match PLUGIN_API_VERSION.

• apps – runnable applications the plugin adds to the GUI and headless registry.

• model_providers – providers that extend the model-zoo catalogue.

• report_sections – builders that insert plugin-owned sections into generated reports.

• translations – locale-to-message mappings that translate the plugin’s own visible strings.

spacr.plugins.diagnostics() → Tuple[PluginDiagnostic, ...]

Return discovery and runtime contribution failures.

spacr.plugins.discover_plugins() → Tuple[SpacrPlugin, ...]

Return every valid discovered plugin in deterministic order.

Returns an empty tuple, with no diagnostic recorded, when SPACR_DISABLE_PLUGINS is set to 1, true, yes or on (case-insensitively): nothing is imported at all. The result is cached; reload_plugins() discards the cache and discovers again.

spacr.plugins.get_app(key: str) → AppContribution | None

Return a contributed app by key, or None.

Parameters:

key – key of an installed plugin’s AppContribution; converted with str() before the registry lookup.

spacr.plugins.load_object(reference: str) → Any

Import and return module:attribute (nested attributes supported).

Parameters:

reference – string of the form "package.module:attribute"; the attribute part may be dotted to reach nested objects. Anything else raises ValueError.

spacr.plugins.model_providers() → Tuple[Tuple[str, ModelProviderContribution], ...]

Return (plugin_name, provider) model-zoo contributions.

spacr.plugins.plugin_apps() → Tuple[AppContribution, ...]

Return all contributed applications.

spacr.plugins.plugin_from_mapping(value: Mapping[str, Any]) → SpacrPlugin

Validate a mapping and return its immutable SpacrPlugin.

Parameters:

value – manifest mapping whose keys are the SpacrPlugin fields; apps, model_providers and report_sections may hold mappings or contribution objects, and translations must map language codes to string mappings. A non-mapping raises TypeError.

spacr.plugins.record_diagnostic(plugin: str, message: str, exception: Any = '', severity: str = 'error') → None

Record a model/report/runtime plugin failure without aborting spaCR.

Parameters:

• plugin – name of the plugin that failed, stored on the PluginDiagnostic and written to the log.

• message – user-facing account of the failed operation.

spacr.plugins.reload_plugins() → Tuple[SpacrPlugin, ...]

Clear the discovery cache and discover again (primarily for tests/dev).

spacr.plugins.report_sections() → Tuple[Tuple[str, ReportSectionContribution], ...]

Return (plugin_name, section) report contributions.