nexusLIMS.exporters.base#

Base protocols and data structures for export destinations.

This module defines the core interfaces and data structures for the NexusLIMS export framework, which allows records to be exported to multiple repository destinations (CDCS, LabArchives, eLabFTW, etc.) using a plugin-based architecture.

Module Contents#

Classes#

ExportResult

Result of a single export attempt.

ExportContext

Context passed to export destination plugins.

ExportDestination

Protocol for export destination plugins.

API#

class nexusLIMS.exporters.base.ExportResult[source]#

Result of a single export attempt.

Parameters:

  • success – Whether the export succeeded

  • destination_name – Name of the destination plugin (e.g., “cdcs”)

  • record_id – Destination-specific record identifier (if successful)

  • record_url – Direct URL to view the exported record (if successful)

  • error_message – Error message if export failed

  • timestamp – When the export attempt occurred

  • metadata – Additional destination-specific metadata

success#

Type: bool

destination_name#

Type: str

record_id#

Type: str | None

record_url#

Type: str | None

error_message#

Type: str | None

timestamp#

‘field(…)’

Type: datetime.datetime

metadata#

‘field(…)’

Type: dict[str, typing.Any]

class nexusLIMS.exporters.base.ExportContext[source]#

Context passed to export destination plugins.

Provides all necessary information for a destination to export a record, including file path, session metadata, and results from previously-run higher-priority destinations (for inter-destination dependencies).

Parameters:

  • xml_file_path – Path to the XML record file to export

  • session_identifier – Unique identifier for this session

  • instrument_pid – Instrument identifier (e.g., “FEI-Titan-TEM-012345”)

  • dt_from – Session start datetime

  • dt_to – Session end datetime

  • user – Username associated with this session (if known)

  • metadata – Additional session metadata

  • previous_results – Results from higher-priority destinations that have already run. Destinations can access these to create inter-destination dependencies (e.g., LabArchives including a CDCS link).

xml_file_path#

Type: pathlib.Path

session_identifier#

Type: str

instrument_pid#

Type: str

dt_from#

Type: datetime.datetime

dt_to#

Type: datetime.datetime

user#

Type: str | None

metadata#

‘field(…)’

Type: dict[str, typing.Any]

previous_results#

‘field(…)’

Type: dict[str, nexusLIMS.exporters.base.ExportResult]

activities#

‘field(…)’

Type: list[nexusLIMS.schemas.activity.AcquisitionActivity]

reservation_event#

Type: nexusLIMS.harvesters.reservation_event.ReservationEvent | None

get_result(destination_name: str) → ExportResult | None[source]#

Get result from a specific destination, if it has already run.

Parameters:

destination_name – Name of the destination to query (e.g., “cdcs”)

Returns:

The result if the destination has run, None otherwise

Return type:

ExportResult | None

add_result(destination_name: str, result: ExportResult) → None[source]#

Add or update result from a destination.

Parameters:

  • destination_name – Name of the destination (e.g., “cdcs”, “elabftw”)

  • result – The export result to store

Examples:

>>> from nexusLIMS.exporters.base import ExportResult
>>> result = ExportResult(success=True, message="Uploaded successfully")
>>> context.add_result("cdcs", result)
has_successful_export(destination_name: str) → bool[source]#

Check if a destination successfully exported.

Parameters:

destination_name – Name of the destination to check (e.g., “cdcs”)

Returns:

True if the destination ran and succeeded, False otherwise

Return type:

bool

class nexusLIMS.exporters.base.ExportDestination[source]#

Bases: typing.Protocol

Protocol for export destination plugins.

Export destinations are discovered automatically by walking the exporters/destinations/ directory. Any class matching this protocol will be registered as an export destination.

Variables:

  • name (str) – Unique identifier for this destination (e.g., “cdcs”)

  • priority (int) – Selection priority (0-1000, higher runs first). Use priority to manage inter-destination dependencies: higher-priority destinations run first and their results are available to lower-priority destinations.

name#

Type: str

priority#

Type: int

property enabled: bool#

Whether this destination is enabled and configured.

Check if all required configuration is present (API keys, URLs, etc.) and the destination should be used for exports.

Returns:

True if destination is ready to use, False otherwise

Return type:

bool

validate_config() → tuple[bool, str | None][source]#

Validate configuration.

Perform startup-time validation of configuration (API keys, connectivity, etc.) and return detailed error information.

Returns:

(is_valid, error_message)

  • is_valid: True if configuration is valid

  • error_message: None if valid, descriptive error if invalid

Return type:

tuple[bool, str | None]

export(context: ExportContext) → ExportResult[source]#

Export record to this destination.

CRITICAL: This method MUST NOT raise exceptions. All errors must be caught and returned as ExportResult with success=False and error_message set.

Parameters:

context – Export context with file path, session metadata, and results from higher-priority destinations

Returns:

Result of the export attempt (success or failure)

Return type:

ExportResult