Public API#
This page is the reference of the classes and functions available to plugins. See Developing plugins for their use, and Application plugins for the declarations of application plugins.
DataLab plugin system#
DataLab plugin system provides a way to extend the application with new functionalities.
Plugins are Python modules that relies on two classes:
PluginInfo, which stores information about the plugin
PluginBase, which is the base class for all plugins
Plugins may also extends DataLab I/O features by providing new image or
signal formats. To do so, they must provide a subclass of ImageFormatBase
or SignalFormatBase, in which format information is defined using the
FormatInfo class.
- class datalab.plugins.ClassicsImageFormat[source]#
Object representing classic image file types
- static read_data(filename: str) ndarray[source]#
Read data and return it
- Parameters:
filename – File name
- Returns:
Image array data
- class datalab.plugins.FailedPluginInfo(name: str, filepath: str, traceback: str, source: str = '')[source]#
Information about a plugin that failed to load or instantiate.
- class datalab.plugins.FormatInfo(name: str = None, extensions: str = None, readable: bool = False, writeable: bool = False, requires: list[str] = None)[source]#
Format info
- class datalab.plugins.ImageFormatBase[source]#
Base image format object.
This class is used to define the interface for image I/O formats. It is an abstract base class that defines the methods that must be implemented by any image format class.
- validate_read_param(param: DataSet | None) None[source]#
Reject read parameters for formats that do not support them.
- abstractmethod read(filename: str, worker: CallbackWorkerProtocol | None = None, *, param: DataSet | None = None) Sequence[ImageObj][source]#
Read list of image objects from file
- Parameters:
filename – File name
worker – Callback worker object
param – Optional format-specific read parameters
- Returns:
List of image objects
- abstractmethod write(filename: str, obj: ImageObj) None[source]#
Write data to file
- Parameters:
filename – file name
obj – native object (signal or image)
- Raises:
NotImplementedError – if format is not supported
- write_with_options(filename: str, obj: ImageObj, writer_options: dict[str, object]) None[source]#
Write an image with format-specific options.
- Parameters:
filename – File name
obj – Image object
writer_options – Format-specific writer options
- Raises:
ValueError – If this format does not support writer options
- class datalab.plugins.PluginBase[source]#
Plugin base class
- last_example_data: PluginExampleData | None = None#
Data of the last opened generated example (
Nonefor packaged ones)
- classmethod get_plugin_id() str[source]#
Return the stable plugin ID or a deterministic legacy fallback.
- classmethod get_recipes() tuple[RecipeDescriptor, ...][source]#
Return validated recipe descriptors exposed by this plugin.
- classmethod get_recipe(recipe_id: str) RecipeDescriptor[source]#
Return one recipe descriptor by its namespaced ID.
- classmethod get_recipe_launchers() Mapping[str, str][source]#
Return validated recipe-to-method bindings overriding the Desktop UI.
- launch_recipe(recipe_id: str) RecipeOutcome | None[source]#
Launch a recipe on the current selection.
A plugin method declared in
RECIPE_LAUNCHERSreplaces the generic interaction ofstart_recipe().
- get_selected_objects() list[SignalObj | ImageObj][source]#
Return the objects selected in the current signal or image panel.
- example_parameter_values(recipe_id: str, objects: Sequence[SignalObj | ImageObj]) Mapping[str, object][source]#
Return the last example’s parameter values for a recipe and objects.
Values are returned only when all objects come from the last opened generated example: they are suited to that data only.
- assess_recipe(recipe_id: str, objects: Sequence[SignalObj | ImageObj] | None = None) RecipeReadiness[source]#
Assess whether a recipe can run on objects (default: selection).
- start_recipe(recipe_id: str, objects: Sequence[SignalObj | ImageObj] | None = None, parameter_values: Mapping[str, object] | None = None) RecipeOutcome | None[source]#
Run a recipe through the generic DataLab interaction.
DataLab assigns the objects (default: selection) to the recipe inputs, asking the user when needed, checks them, edits the parameters, then runs the recipe.
- Parameters:
recipe_id – namespaced recipe ID
objects – candidate objects (default: current selection)
parameter_values – initial parameter values (default: those of the last opened example, when the objects come from it)
- Returns:
Recipe outcome, or None if cancelled or failed
- try_example(example_id: str, recipe_id: str) RecipeOutcome | None[source]#
Open an example, then start one of the recipes it was designed for.
- classmethod get_tools() tuple[PluginTool, ...][source]#
Return validated tools listed in the Applications panel.
- classmethod get_tool(tool_id: str) PluginTool[source]#
Return one tool by its plugin-local ID.
- assess_tool(tool_id: str, objects: Sequence[SignalObj | ImageObj] | None = None) str | None[source]#
Return why a tool cannot be opened on objects (default: selection).
- Returns:
Message telling which objects to select, or None if the tool can be opened
- launch_tool(tool_id: str) object[source]#
Open a plugin tool: call its launcher, or show its instrument.
- Raises:
ValueError – if the selection does not allow opening the tool
- get_instrument(tool_id: str) PluginInstrument[source]#
Return the instrument of a tool, created once per registration.
- classmethod get_examples() tuple[PluginExample, ...][source]#
Return validated packaged examples exposed by this plugin.
- classmethod get_example(example_id: str) PluginExample[source]#
Return one packaged example by its plugin-local ID.
- classmethod materialize_example(example_id: str) PluginExampleData | None[source]#
Generate one example in memory, or defer to its package resource.
- launch_example(example_id: str) PluginExample | None[source]#
Confirm and open a generated or packaged example, then select it.
- open_example(example_id: str, reset_all: bool = True) PluginExample[source]#
Open a generated or packaged HDF5 example in the Desktop workspace.
Generated examples (
materialize_example()returning data) are loaded directly into the signal/image panels; packaged examples are opened through their native HDF5 resource. The materialized data is kept inlast_example_data, so that recipes started on these objects reuse the example’s parameter values (seeexample_parameter_values()).
- classmethod get_welcome_tiles() tuple[WelcomeTile, ...][source]#
Return validated welcome page tiles exposed by this application plugin.
Without declared
WELCOME_TILES, an application plugin exposes one default tile built from itsPluginInfo. Declared tiles without icon inherit the plugin icon.
- launch_welcome_tile(tile_id: str) object[source]#
Launch a welcome page tile.
A tile without launcher shows the plugin page in the Applications panel; otherwise, its plugin method is called without arguments.
- Returns:
Value returned by the launcher method (None for the Applications panel)
- property signalpanel: SignalPanel#
Return signal panel
- property imagepanel: ImagePanel#
Return image panel
- ask_yesno(message: str, title: str | None = None, cancelable: bool = False) bool[source]#
Ask yes/no question
- edit_new_signal_parameters(title: str | None = None, size: int | None = None) NewSignalParam[source]#
Create and edit new signal parameter dataset
- Parameters:
title – title of the new signal
size – size of the new signal (default: None, get from current signal)
- Returns:
New signal parameter dataset (or None if canceled)
- edit_new_image_parameters(title: str | None = None, shape: tuple[int, int] | None = None, hide_height: bool = False, hide_width: bool = False, hide_type: bool = True, hide_dtype: bool = False) NewImageParam | None[source]#
Create and edit new image parameter dataset
- Parameters:
title – title of the new image
shape – shape of the new image (default: None, get from current image)
hide_height – hide image heigth parameter (default: False)
hide_width – hide image width parameter (default: False)
hide_type – hide image type parameter (default: True)
hide_dtype – hide image data type parameter (default: False)
- Returns:
New image parameter dataset (or None if canceled)
- register(main: main.DLMainWindow) None[source]#
Register plugin
The declarations of the plugin (recipes, examples, tools, welcome tiles) are validated first: an invalid plugin is not registered, so that the Applications panel, the welcome page and the menus only get valid declarations.
- Raises:
TypeError – if a declaration has the wrong type
ValueError – if a declaration is invalid or the plugin ID is already used
- remove_owned_features() None[source]#
Remove this plugin’s computing features from available processors.
- register_hooks()[source]#
Register plugin hooks.
Called by
register()during application startup or plugin reload, before the panels’ PLUGINS action category exists: use this for non-GUI side effects only (I/O format registration, listeners).self.mainandself.proxyare already set. Raising here rolls back the whole registration (the plugin stays unregistered).
- unregister_hooks()[source]#
Unregister plugin hooks.
Called by
unregister(); must undoregister_hooks(). Owned computing features are removed automatically afterwards.
- register_computations() None[source]#
Register owned computations after signal and image panels exist.
Called once per registered plugin, right before
create_actions(); raising here removes the plugin’s owned features but keeps the plugin registered.
- abstractmethod create_actions()[source]#
Create actions.
Called immediately after
register_computations(), inside the panels’ PLUGINS action category: actions created here populate the Plugins menu.
- class datalab.plugins.PluginBaseMeta(name, bases, namespace, /, **kwargs)[source]#
Mixed metaclass to avoid conflicts
- class datalab.plugins.PluginCapability(value)[source]#
Capability exposed by a plugin to DataLab consumers.
- class datalab.plugins.PluginInfo(name: str = None, version: str = '0.0.0', description: str = '', icon: str = None, id: str | None = None, capabilities: Collection[PluginCapability] = <factory>, documentation_url: str | None = None)[source]#
Plugin info
- icon#
Plugin icon:
package:relative/pathresource,module:filenameimage registered with guidata, or DataLab icon file name- Type:
- capabilities#
Plugin capabilities (
PluginCapabilityvalues)
- class datalab.plugins.PluginRegistry(name, bases, attrs)[source]#
Metaclass for registering plugins
- classmethod get_plugin_classes() list[type[PluginBase]][source]#
Return plugin classes
- classmethod get_plugins() list[PluginBase][source]#
Return plugin instances
- classmethod get_plugin(name_or_class: str | type[PluginBase]) PluginBase | None[source]#
Return a plugin by stable ID, legacy name, or class.
Legacy display names are accepted only when they identify a single plugin.
- classmethod register_plugin(plugin: PluginBase)[source]#
Register plugin
- classmethod unregister_plugin(plugin: PluginBase)[source]#
Unregister plugin
- classmethod clear_plugin_classes() None[source]#
Clear registered plugin classes.
This is mainly useful when reloading plugin modules at runtime.
- classmethod add_discovery_error(tb_text: str) None[source]#
Record an error traceback that occurred during plugin discovery.
- Parameters:
tb_text – Formatted traceback string
- classmethod get_discovery_errors() list[str][source]#
Return error tracebacks collected during plugin discovery.
- Returns:
List of formatted traceback strings (may be empty)
- classmethod add_failed_plugin(name: str, filepath: str, tb_text: str, source: str = '') None[source]#
Record a plugin that failed to load or instantiate.
- Parameters:
name – Module or plugin class name
filepath – File path of the plugin module
tb_text – Formatted traceback string
source – Discovery source description
- classmethod get_failed_plugins() list[FailedPluginInfo][source]#
Return structured info about plugins that failed to load.
- Returns:
List of FailedPluginInfo objects (may be empty)
- class datalab.plugins.SignalFormatBase[source]#
Class representing a signal file type
- static create_object(filename: str, index: int | None = None) SignalObj[source]#
Create empty object
- Parameters:
filename – File name
index – Index of object in file
- Returns:
Signal object
- create_signal(xydata: ndarray, filename: str, index: int | None = None) SignalObj[source]#
Create signal object from xydata and filename.
- Parameters:
xydata – XY data
filename – File name
index – Index of object in file
- Returns:
Signal object
- create_signals_from(xydata: ndarray, filename: str) list[SignalObj][source]#
Create signal objects from xydata and filename
- Parameters:
xydata – XY data
filename – File name
- Returns:
List of signal objects
- datalab.plugins.discover_plugins() list[ModuleType][source]#
Discover plugins through package entry points and naming convention.
Installed packages may expose a
PluginBasesubclass through thedatalab.pluginsentry-point group. This function also reloads or imports modules and packages matching the historical"{MOD_NAME}_*"naming scheme, as well as theadapters.desktopmodule of such packages, which defines the plugin class of packages laid out bydatalab-plugin create.Import errors for individual plugins are captured and logged so that one broken plugin does not prevent the others from loading. Error tracebacks are accumulated in
PluginRegistryclass attributes so that callers (e.g. the main window) can replay them into the internal console once it is ready.This function mutates
sys.modulesand the plugin registry without synchronization: call it from the Qt main thread only.- Returns:
Imported/reloaded modules containing discovered plugins
- datalab.plugins.discover_v020_plugins() list[tuple[str, str]][source]#
Discover v0.20 plugins (with
cdl_prefix) without importing them- Returns:
List of tuples (plugin_name, directory_path) for discovered v0.20 plugins
- datalab.plugins.format_tool_requirement(tool: PluginTool) str[source]#
Return the message telling which objects to select to open a tool.
- datalab.plugins.get_available_plugins() list[PluginBase][source]#
Instantiate and get available plugins
- Returns:
List of available plugins (as instances)
- datalab.plugins.migrate_enabled_plugin_ids(enabled_plugins: list[str] | None, plugin_classes: list[type[PluginBase]] | None = None) list[str] | None[source]#
Migrate enabled plugin display names to stable IDs.
Unknown entries are retained so temporarily unavailable plugins do not lose their activation state. A legacy name shared by multiple plugins enables all matching IDs because the old setting cannot distinguish between them.
- Parameters:
enabled_plugins – Configured stable IDs or legacy display names
plugin_classes – Classes available for migration (registry by default)
- Returns:
Enabled stable IDs and retained unknown entries, or None for all plugins
- datalab.plugins.reload_plugin_modules() None[source]#
Reload plugin modules and reset plugin classes.
This helper is intended for hot-reloading plugins at runtime. It:
Updates the plugin search path
Clears the plugin class registry
Reloads or imports all modules matching the plugin naming convention
Like
discover_plugins(), this is not thread-safe: call it from the Qt main thread only.
datalab.plugins.PLUGIN_ENTRY_POINT_GROUP is the entry-point group of DataLab Desktop plugin classes ("datalab.plugins"); DataLab-Web plugin classes use the datalab.web_plugins group (see Plugins and DataLab-Web). The other names exported by datalab.plugins, such as PluginRegistry or discover_plugins, are used by DataLab to load and manage plugins, and are not described here.
Headless contracts for plugin-provided scientific recipes.
- exception datalab.plugins.recipes.RecipeCancellationError[source]#
Raised when recipe execution observes a cancellation request.
- class datalab.plugins.recipes.RecipeCardinality(value)[source]#
Number of objects accepted by a recipe input slot.
- class datalab.plugins.recipes.RecipeDescriptor(recipe_id: str, plugin_version: str, title: str, version: str, run: Callable[[Mapping[str, tuple[SignalObj | ImageObj, ...]], DataSet | None, RecipeExecutionContext], RecipeOutcome], description: str = '', inputs: Sequence[RecipeInputSlot] = (), parameter_class: type[DataSet] | None = None, suggest_bindings: Callable[[tuple[SignalObj | ImageObj, ...]], Mapping[str, Sequence[SignalObj | ImageObj]]] | None = None, check_inputs: Callable[[Mapping[str, tuple[SignalObj | ImageObj, ...]], DataSet | None], Sequence[RecipeDiagnostic]] | None = None)[source]#
Versioned, typed declaration of a plugin-provided headless recipe.
A missing
parameter_classdeclares a parameterless recipe whose run callable receivesNoneas its second argument. Otherwise, that argument must be an instance of the declaredDataSetsubclass.suggest_bindingsreceives the candidate objects and returns a proposed assignment of some of them to input slots (e.g. from metadata). Hosts use it to bind inputs without asking the user.check_inputsreceives complete inputs and parameters (defaults when assessing a selection) and returns diagnostics: errors block the run, warnings are shown. It must stay fast (metadata, shapes, counts) because hosts call it whenever the selection changes.- get_input(slot_id: str) RecipeInputSlot[source]#
Return one declared input slot by its ID.
- class datalab.plugins.recipes.RecipeDiagnostic(level: RecipeDiagnosticLevel, code: str, message: str, details: Mapping[str, object]=<factory>)[source]#
Structured, machine-identifiable diagnostic emitted by a recipe.
- class datalab.plugins.recipes.RecipeDiagnosticLevel(value)[source]#
Severity of a structured recipe diagnostic.
- class datalab.plugins.recipes.RecipeExecutionContext(progress_callback: Callable[[float, str | None], None] | None = None, cancellation_callback: Callable[[], bool] | None = None)[source]#
Technology-neutral progress and cancellation callbacks for a recipe.
- raise_if_cancelled() None[source]#
Raise
RecipeCancellationErrorwhen cancellation is requested.
- class datalab.plugins.recipes.RecipeInputSlot(id: str, object_type: RecipeObjectType, cardinality: RecipeCardinality, required: bool = True, title: str = '', description: str = '', min_count: int = 1, metadata: Sequence[RecipeMetadataRequirement] = ())[source]#
Typed input slot declared by a recipe.
- Parameters:
id – slot ID, local to the recipe
object_type – type of the accepted objects
cardinality – one object, or several objects
required – True if the slot cannot be left empty
title – human-readable slot name (derived from
idif empty)description – what the objects must represent and how they are acquired
min_count – minimum number of objects of a non-empty
MANYslotmetadata – metadata entries expected on every bound object
- class datalab.plugins.recipes.RecipeMetadataRequirement(key: str, description: str = '', required: bool = True)[source]#
Metadata entry expected on the objects bound to a recipe input slot.
- Parameters:
key – metadata key
description – meaning of the value (unit, allowed values…)
required – True if objects lacking the key cannot be analyzed; False documents an optional hint, e.g. used to assign objects to slots
- class datalab.plugins.recipes.RecipeObjectOutput(id: str, value: SignalObj | ImageObj)[source]#
Named signal or image produced by a recipe.
- class datalab.plugins.recipes.RecipeObjectType(value)[source]#
Scientific object type accepted by a recipe input slot.
- class datalab.plugins.recipes.RecipeOutcome(objects: Sequence[RecipeObjectOutput] = (), results: Sequence[RecipeResultOutput] = (), diagnostics: Sequence[RecipeDiagnostic] = ())[source]#
Objects, anchored scalar results, and diagnostics produced by a recipe.
- class datalab.plugins.recipes.RecipeResultOutput(id: str, value: TableResult | GeometryResult, anchor_id: str)[source]#
Named scalar result attached to a named object output.
- class datalab.plugins.recipes.RecipeRunRecord(run_id: str, plugin_id: str, plugin_version: str, recipe_id: str, recipe_version: str, parameters_json: str, input_uuids: Mapping[str, Sequence[str]], output_uuids: Mapping[str, str], datalab_version: str, sigima_version: str, status: RecipeRunStatus, started_at: str, finished_at: str, schema_version: int = 1)[source]#
Versioned local provenance shared by every output of a recipe run.
The record is persisted as JSON metadata (see
to_dict()) under theRECIPE_RUN_RECORD_OPTIONmetadata option of every output object, so external consumers (DataLab-Web, HDF5 workspaces, tooling) can rely on the following schema (version1):schema_version(int): alwaysRECIPE_RUN_RECORD_SCHEMA_VERSIONrun_id(str): UUID shared by all outputs of one recipe invocationplugin_id/plugin_version(str): owning plugin and its versionrecipe_id/recipe_version(str): recipe (<plugin_id>:<name>) and its contract versionparameters_json(str): guidata DataSet serialized withdataset_to_json("null"for parameterless recipes)input_uuids(dict[str, list[str]]): object UUIDs consumed per input slot — a mapping (not a flat list) so slot roles survive round-tripsoutput_uuids(dict[str, str]): object UUID produced per output IDdatalab_version/sigima_version(str): environment versionsstatus(str): aRecipeRunStatusvaluestarted_at/finished_at(str): timezone-aware ISO 8601
Compatibility policy: readers must reject records whose
schema_versionthey do not know (asfrom_dict()does); any field addition, removal, or semantic change requires bumpingRECIPE_RUN_RECORD_SCHEMA_VERSIONand providing an explicit migration path for persisted workspaces.
- class datalab.plugins.recipes.RecipeRunStatus(value)[source]#
Terminal status persisted on successful recipe outputs.
- exception datalab.plugins.recipes.RecipeValidationError[source]#
Raised when recipe inputs or parameters violate their descriptor.
Host-independent assignment of objects to recipe inputs, and readiness.
DataLab Desktop and DataLab-Web share this module: both propose bindings from the selected objects, assess whether a recipe can run on them, and phrase the returned issues in their own user interface.
- datalab.plugins.recipe_binding.INPUT_CHECK_FAILED_CODE = 'input-check-failed'#
Diagnostic code of an exception raised by a recipe input check
- class datalab.plugins.recipe_binding.RecipeBindingProposal(bindings: Mapping[str, tuple[SignalObj | ImageObj, ...]], ambiguous_slots: tuple[str, ...] = ())[source]#
Objects proposed for each recipe input slot.
- class datalab.plugins.recipe_binding.RecipeInputIssue(code: RecipeInputIssueCode, slot_id: str, details: Mapping[str, object]=<factory>)[source]#
Generic problem found on one recipe input slot.
detailsholds what hosts need to phrase the problem:countandmin_count(TOO_FEW),count(TOO_MANY),key,countandtitlesof the objects lacking it (MISSING_METADATA),countandtitles(WRONG_TYPE,DUPLICATE).
- class datalab.plugins.recipe_binding.RecipeInputIssueCode(value)[source]#
Generic reason why objects cannot be bound to a recipe input slot.
- class datalab.plugins.recipe_binding.RecipeReadiness(status: RecipeReadinessStatus, bindings: Mapping[str, tuple[SignalObj | ImageObj, ...]], issues: tuple[RecipeInputIssue, ...] = (), diagnostics: tuple[RecipeDiagnostic, ...] = ())[source]#
Result of the assessment of recipe inputs.
- class datalab.plugins.recipe_binding.RecipeReadinessStatus(value)[source]#
Whether a recipe can run on a set of candidate objects.
- NO_INPUT = 'no_input'#
No candidate object has a type accepted by the recipe
- NEEDS_ASSIGNMENT = 'needs_assignment'#
Inputs are available but must be assigned to slots by the user
- NOT_READY = 'not_ready'#
Inputs violate the slot declarations or the recipe input checks
- WARNINGS = 'warnings'#
The recipe can run, but its input checks returned warnings
- READY = 'ready'#
The recipe can run
- datalab.plugins.recipe_binding.assess_recipe_inputs(descriptor: RecipeDescriptor, candidates: Sequence[SignalObj | ImageObj] = (), parameters: DataSet | None = None, bindings: Mapping[str, Sequence[SignalObj | ImageObj]] | None = None) RecipeReadiness[source]#
Assess whether a recipe can run on candidate objects or bindings.
- Parameters:
descriptor – recipe descriptor
candidates – candidate objects, used when
bindingsis Noneparameters – parameters passed to the recipe input checks
bindings – explicit bindings (e.g. edited by the user)
- Returns:
Readiness status, bindings, generic issues, and recipe diagnostics
- datalab.plugins.recipe_binding.check_recipe_inputs(descriptor: RecipeDescriptor, inputs: Mapping[str, tuple[SignalObj | ImageObj, ...]], parameters: DataSet | None) tuple[RecipeDiagnostic, ...][source]#
Run the input checks of a recipe on complete inputs.
An exception raised by the checks (e.g. by a validation function reused from the recipe) is reported as an error diagnostic.
- Parameters:
descriptor – recipe descriptor
inputs – objects bound to each slot
parameters – recipe parameters, or None for a parameterless recipe
- Returns:
Diagnostics returned by the recipe
- datalab.plugins.recipe_binding.create_recipe_parameters(descriptor: RecipeDescriptor, values: Mapping[str, object] | None = None) DataSet | None[source]#
Create default recipe parameters, updated with known values.
- Parameters:
descriptor – recipe descriptor
values – parameter values, e.g. suited to an example
- Returns:
Parameters, or None for a parameterless recipe
- Raises:
RecipeValidationError – a value does not match a recipe parameter
- datalab.plugins.recipe_binding.find_input_issues(descriptor: RecipeDescriptor, bindings: Mapping[str, Sequence[SignalObj | ImageObj]], ambiguous_slots: Sequence[str] = ()) tuple[RecipeInputIssue, ...][source]#
Check bindings against the declaration of the recipe input slots.
- Parameters:
descriptor – recipe descriptor
bindings – objects bound to each slot
ambiguous_slots – unbound slots awaiting a user assignment
- Returns:
Problems found, in slot declaration order
- datalab.plugins.recipe_binding.is_compatible(slot: RecipeInputSlot, obj: object) bool[source]#
Return True if an object has the type accepted by an input slot.
- datalab.plugins.recipe_binding.propose_bindings(descriptor: RecipeDescriptor, candidates: Sequence[SignalObj | ImageObj]) RecipeBindingProposal[source]#
Propose objects for each input slot of a recipe.
The recipe’s binding suggestions come first. Otherwise, all compatible candidates go to the only slot accepting their type; slots sharing a type with others are left to the user (ambiguous slots).
- Parameters:
descriptor – recipe descriptor
candidates – candidate objects, e.g. the current selection
- Returns:
Proposed bindings and the slots requiring a user decision
Portable declarations for plugin-provided example workspaces.
- class datalab.plugins.examples.PluginExample(id: str, title: str, resource: str | None = None, description: str = '', recipe_ids: Sequence[str] = (), expected_checks: Sequence[str] = ())[source]#
Packaged or generated example, and the recipes it was designed for.
An example without recipe is presented as a plain dataset.
- class datalab.plugins.examples.PluginExampleData(objects: ~collections.abc.Sequence[~sigima.objects.signal.object.SignalObj | ~sigima.objects.image.object.ImageObj], parameter_values: ~collections.abc.Mapping[str, ~collections.abc.Mapping[str, object]] = <factory>)[source]#
Scientific objects and per-recipe defaults generated by a plugin.
- Parameters:
objects – generated signals and images
parameter_values – recipe ID to parameter values suited to these objects
Portable declarations for plugin-provided welcome page tiles.
- class datalab.plugins.tiles.WelcomeTile(id: str, title: str, description: str = '', icon: str | None = None, launcher: str | None = None)[source]#
Welcome page tile exposed by an application plugin
- Parameters:
id – plugin-local tile ID (lowercase letters, digits,
.,_,-)title – tile title
description – short description shown below the title
icon –
package:pathresource (SVG or bitmap) or DataLab icon file name;Nonefalls back to the plugin iconlauncher – name of the plugin method called when the tile is clicked;
Noneshows the plugin page in the Applications panel
Declarations of plugin-owned tools listed in the Applications catalog.
DataLab Desktop and DataLab-Web share this module.
- class datalab.plugins.tools.PluginTool(id: str, title: str, launcher: str | None = None, description: str = '', icon: str | None = None, instrument: str | None = None, object_type: RecipeObjectType | None = None, selection: ToolSelection = ToolSelection.NONE, menu: bool = True)[source]#
Tool with its own user interface, exposed by an application plugin
Recipes cover headless analyses run by DataLab; a tool covers any other interaction owned by the plugin (wizard, interactive editor, data preparation, instrument…). DataLab lists tools in the Applications catalog and in the plugin’s submenu of the Plugins menu.
A tool is opened either by a
launchermethod, called without arguments, or by aninstrumentmethod returning adatalab.plugins.instruments.PluginInstrument, which DataLab shows in a window with a live view and the instrument settings.- Parameters:
id – plugin-local tool ID (lowercase letters, digits,
.,_,-)title – tool title
launcher – name of the plugin method called, without arguments, to open the tool
description – short description of what the tool does
icon –
package:pathresource (SVG or bitmap) or DataLab icon file name;Nonefalls back to the plugin iconinstrument – name of the plugin method returning the instrument shown by DataLab (exclusive with
launcher)object_type – type of the objects the tool works on or creates; the tool is listed in the menu of that panel (
None: both panels)selection – selection needed to open the tool, counting objects of
object_typeonlymenu – if False, DataLab does not add the tool to the plugin’s submenu of the Plugins menu (e.g. because the plugin already places it in one of its own submenus); it is still listed in the Applications catalog
- class datalab.plugins.tools.ToolSelection(value)[source]#
Selection a tool needs to be opened (names follow DataLab’s conditions).
- datalab.plugins.tools.tool_accepts_selection(tool: PluginTool, objects: Sequence[SignalObj | ImageObj]) bool[source]#
Return True if the selected objects allow opening the tool.
- Parameters:
tool – tool to open
objects – selected objects
- Returns:
True if the number of selected objects of the tool’s object type matches the tool’s selection
Instruments exposed by application plugins as tools.
An instrument is a headless object: it holds settings (a guidata DataSet), returns a live frame for these settings, and acquires objects. DataLab shows it in a window with the live view on the left and the settings on the right. DataLab Desktop and DataLab-Web share this module.
- class datalab.plugins.instruments.InstrumentAcquisition(group_title: str, objects: Sequence[SignalObj | ImageObj])[source]#
Objects acquired by an instrument, added by DataLab to the workspace.
DataLab adds them to a new group, or to the current group of the panel when the user turns off the New group option of the instrument window (see
PluginInstrument.new_group).- Parameters:
group_title – title of the group created for the acquisition, if any
objects – acquired signals, or acquired images
- class datalab.plugins.instruments.InstrumentFrame(objects: Sequence[SignalObj | ImageObj], summary: str = '', value_range: tuple[float, float] | None = None)[source]#
Live frame shown by DataLab for the current instrument settings.
- Parameters:
objects – signals drawn together, or a single image
summary – short text shown below the view (e.g. measured levels)
value_range – fixed Y range of signals, or color range of the image (
None: automatic)
- class datalab.plugins.instruments.PluginInstrument(settings: DataSet)[source]#
Instrument opened by a plugin tool.
DataLab writes the edited values into
settingsbefore callingpreview()oracquire(). Both methods raiseValueErrorwith a user-facing message when the settings cannot be used. The plugin keeps one instance per tool during the session, so settings are kept from one opening to the next.DataLab calls
open()when the instrument window opens andclose()when it closes (including when the plugin is reloaded or DataLab quits). It calls these methods,preview()andacquire()one at a time, outside the GUI thread, even when the window is closed and opened again while a call is running, and writessettingsonly between two calls: a slow instrument does not freeze DataLab. Data received by the instrument in its own threads (e.g. device events) must be stored for the nextpreview()oracquire()call.- Parameters:
settings – instrument settings, edited by DataLab
- new_group: bool = True#
Default state of the New group option of the instrument window (if True, each acquisition is added to a new group, otherwise to the current group of the panel). The choice of the user, once made, prevails.
- open() None[source]#
Prepare the instrument when its window opens (e.g. connect to it).
Raises
ValueErrorwith a user-facing message if the instrument cannot be used: DataLab shows this message, and does not callpreview()oracquire()until a new request (e.g. after a settings change) opens the instrument successfully. Does nothing by default.
- close() None[source]#
Release the instrument when its window closes (e.g. disconnect).
Called even if
open()failed, and possibly several times: it must release only what is still held. Does nothing by default.
- abstractmethod preview() InstrumentFrame[source]#
Return a live frame for the current settings.
- abstractmethod acquire() InstrumentAcquisition[source]#
Acquire objects with the current settings.
Package resources declared by plugins with the package:path syntax.
- datalab.plugins.resources.LOCAL_ID_PATTERN = re.compile('^[a-z0-9]+(?:[._-][a-z0-9]+)*$')#
Plugin-local identifier syntax (examples, welcome page tiles)
- datalab.plugins.resources.resolve_package_resource(resource: str, label: str = 'Plugin resource') Traversable[source]#
Resolve a
package:pathresource without requiring a filesystem path- Parameters:
resource – resource declaration, e.g.
"my_plugin:icons/logo.svg"label – resource description used in error messages
- Returns:
importlib.resourcestraversable, also valid for zipped packages- Raises:
ValueError – if the declaration is malformed
FileNotFoundError – if the package does not contain the resource
- datalab.plugins.resources.split_package_resource(resource: str, label: str = 'Plugin resource') tuple[str, str][source]#
Validate a
package:pathresource and return its two parts- Parameters:
resource – resource declaration, e.g.
"my_plugin:icons/logo.svg"label – resource description used in error messages
- Returns:
Importable package name and POSIX path relative to this package
- Raises:
ValueError – if the declaration is malformed
Transactional Desktop runner for plugin-provided scientific recipes.
- exception datalab.gui.plugins.recipe_runner.RecipeCommitError(message: str, rollback_error: Exception | None = None)[source]#
Raised after a failed recipe workspace commit has been rolled back.
- rollback_error#
Exception raised by the rollback itself, or None when the workspace was successfully restored.
- class datalab.gui.plugins.recipe_runner.RecipeRunner(mainwindow: DLMainWindow)[source]#
Validate, execute, and transactionally commit a recipe on Desktop.
- run(descriptor: RecipeDescriptor, inputs: Mapping[str, Sequence[SignalObj | ImageObj]], parameters: DataSet | None = None, context: RecipeExecutionContext | None = None, group_title: str | None = None) RecipeOutcome[source]#
Validate, execute, and atomically commit one recipe invocation.