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

static write_data(filename: str, data: ndarray) → None[source]#

Write data to file

Parameters:
  • filename – File name

  • data – Image array data

write_with_options(filename: str, obj: ImageObj, writer_options: dict[str, object]) → None[source]#

Write classic image data with validated format-specific options.

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

to_rst_table_row() → str[source]#

Return reStructuredText table row for format info (table .. list-table:: format, with 5 columns)

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 (None for packaged ones)

classmethod get_plugin_id() → str[source]#

Return the stable plugin ID or a deterministic legacy fallback.

property plugin_id: str#

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_LAUNCHERS replaces the generic interaction of start_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 in last_example_data, so that recipes started on these objects reuse the example’s parameter values (see example_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 its PluginInfo. 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

show_warning(message: str)[source]#

Show warning message

show_error(message: str)[source]#

Show error message

show_info(message: str)[source]#

Show info message

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)

is_registered()[source]#

Return True if plugin is registered

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

unregister()[source]#

Unregister plugin

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.main and self.proxy are already set. Raising here rolls back the whole registration (the plugin stays unregistered).

unregister_hooks()[source]#

Unregister plugin hooks.

Called by unregister(); must undo register_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

name#

Plugin display name

Type:

str

version#

Plugin version

Type:

str

description#

Plugin description

Type:

str

icon#

Plugin icon: package:relative/path resource, module:filename image registered with guidata, or DataLab icon file name

Type:

str

id#

Stable, namespaced plugin ID (e.g. "org.example.my-plugin")

Type:

str | None

capabilities#

Plugin capabilities (PluginCapability values)

Type:

collections.abc.Collection[datalab.plugins.base.PluginCapability]

documentation_url#

HTTP or HTTPS URL of the plugin documentation, opened by the Documentation action of the Applications panel

Type:

str | None

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 unregister_all_plugins()[source]#

Unregister all plugins

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 clear_discovery_errors() → None[source]#

Clear recorded discovery errors.

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)

classmethod clear_failed_plugins() → None[source]#

Clear recorded failed plugin info.

classmethod get_plugin_info(html: bool = True) → str[source]#

Return plugin information (names, versions, descriptions) in html format

Parameters:

html – return html formatted text (default: True)

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

read(filename: str, worker: CallbackWorkerProtocol | None = None) → Sequence[SignalObj][source]#

Read list of signal objects from file

Parameters:
  • filename – File name

  • worker – Callback worker object

Returns:

List of signal objects

read_xydata(filename: str) → ndarray[source]#

Read data and metadata from file, write metadata to object, return xydata

Parameters:

filename – File name

Returns:

XY data

datalab.plugins.discover_plugins() → list[ModuleType][source]#

Discover plugins through package entry points and naming convention.

Installed packages may expose a PluginBase subclass through the datalab.plugins entry-point group. This function also reloads or imports modules and packages matching the historical "{MOD_NAME}_*" naming scheme, as well as the adapters.desktop module of such packages, which defines the plugin class of packages laid out by datalab-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 PluginRegistry class attributes so that callers (e.g. the main window) can replay them into the internal console once it is ready.

This function mutates sys.modules and 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_class declares a parameterless recipe whose run callable receives None as its second argument. Otherwise, that argument must be an instance of the declared DataSet subclass.

suggest_bindings receives 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_inputs receives 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.

property plugin_id: str#

Return the owning plugin ID encoded in the recipe ID.

property local_id: str#

Return the recipe-local ID encoded in the recipe ID.

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.

property is_cancelled: bool#

Return whether cancellation has been requested.

raise_if_cancelled() → None[source]#

Raise RecipeCancellationError when cancellation is requested.

report_progress(progress: float, message: str | None = None) → None[source]#

Report normalized progress between zero and one.

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 id if empty)

  • description – what the objects must represent and how they are acquired

  • min_count – minimum number of objects of a non-empty MANY slot

  • metadata – metadata entries expected on every bound object

property display_title: str#

Return the declared title, or one derived from the slot ID.

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 the RECIPE_RUN_RECORD_OPTION metadata option of every output object, so external consumers (DataLab-Web, HDF5 workspaces, tooling) can rely on the following schema (version 1):

  • schema_version (int): always RECIPE_RUN_RECORD_SCHEMA_VERSION

  • run_id (str): UUID shared by all outputs of one recipe invocation

  • plugin_id / plugin_version (str): owning plugin and its version

  • recipe_id / recipe_version (str): recipe (<plugin_id>:<name>) and its contract version

  • parameters_json (str): guidata DataSet serialized with dataset_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-trips

  • output_uuids (dict[str, str]): object UUID produced per output ID

  • datalab_version / sigima_version (str): environment versions

  • status (str): a RecipeRunStatus value

  • started_at / finished_at (str): timezone-aware ISO 8601

Compatibility policy: readers must reject records whose schema_version they do not know (as from_dict() does); any field addition, removal, or semantic change requires bumping RECIPE_RUN_RECORD_SCHEMA_VERSION and providing an explicit migration path for persisted workspaces.

to_dict() → dict[str, object][source]#

Return a representation composed only of JSON-compatible values.

classmethod from_dict(data: Mapping[str, Any]) → RecipeRunRecord[source]#

Restore a recipe run record from persisted metadata.

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.

details holds what hosts need to phrase the problem: count and min_count (TOO_FEW), count (TOO_MANY), key, count and titles of the objects lacking it (MISSING_METADATA), count and titles (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.

property can_run: bool#

Return True if the recipe can run with the assessed bindings.

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 bindings is None

  • parameters – 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.

property package: str#

Return the importable package containing the example resource.

property resource_path: str#

Return the POSIX-style path relative to the resource package.

resolve() → Traversable[source]#

Resolve the declared resource without requiring a filesystem path.

as_file() → Iterator[Path][source]#

Materialize the resource for APIs that require a filesystem path.

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

values_for(recipe_id: str) → Mapping[str, object][source]#

Return the parameter values suited to one recipe (empty if none).

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:path resource (SVG or bitmap) or DataLab icon file name; None falls back to the plugin icon

  • launcher – name of the plugin method called when the tile is clicked; None shows the plugin page in the Applications panel

property is_package_icon: bool#

Return True if the icon is a package:path resource

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 launcher method, called without arguments, or by an instrument method returning a datalab.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:path resource (SVG or bitmap) or DataLab icon file name; None falls back to the plugin icon

  • instrument – 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_type only

  • menu – 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 settings before calling preview() or acquire(). Both methods raise ValueError with 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 and close() when it closes (including when the plugin is reloaded or DataLab quits). It calls these methods, preview() and acquire() one at a time, outside the GUI thread, even when the window is closed and opened again while a call is running, and writes settings only 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 next preview() or acquire() call.

Parameters:

settings – instrument settings, edited by DataLab

live_interval_ms: int = 500#

Interval between two frames in live mode, in milliseconds

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 ValueError with a user-facing message if the instrument cannot be used: DataLab shows this message, and does not call preview() or acquire() 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:path resource 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.resources traversable, also valid for zipped packages

Raises:
datalab.plugins.resources.split_package_resource(resource: str, label: str = 'Plugin resource') → tuple[str, str][source]#

Validate a package:path resource 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.