Skip to content
Reference of plugins_api 2.0.1, an older major version. See this page for plugins_api 3.0.0.

plugins_api.data_plugins

Data plugins.

This module contains plugin classes for data management operations.

Classes

NameDescription
DataPluginAbstract class defining the minimum API for a data plugin.

DataPluginclass#

class DataPlugin(connection_parameters: dict[str, Any])

Bases: ConnectionPlugin

Abstract class defining the minimum API for a data plugin.

Data plugins connect to external data sources and provide access to files and directories. They are used to browse, list, and download data from external systems.

download_datamethodabstract#

def download_data(external_dataobject_id: str, destination_path: str) -> str

Download a data object to local storage and returns an download report.

It is strongly recommended to implement data integrity verification in this method. This may include, but is not limited to:

  • Checksum validation (e.g., MD5, SHA256) if available.
  • File size comparison with the source.
  • Any other consistency checks relevant to the data source.

Implementing integrity checks helps prevent data corruption or incomplete downloads, ensuring reliable processing of the imported data.

Parameters

NameTypeDescription
external_dataobject_idstrUnique identifier of the data object in the external system.
destination_pathstrLocal path where the file should be saved.

Returns

str
Path to the local file.

Raises

NotImplementedError
This method must be implemented in a subclass.

get_data_associations_for_data_objectmethod#

def get_data_associations_for_data_object(object_id: str) -> list[PluginDataAssociation]

Return list of data associations for a data object.

Each association represents a group of data objects that should be associated together. A data object can participate in multiple associations, each returned as a separate PluginDataAssociation.

This method should return associations bidirectionally - if data objects A, B, and C are associated together, then when querying A, B, or C, they should all return the same association group containing all three.

Parameters

NameTypeDescription
object_idstrID of the data object.

Returns

list[PluginDataAssociation]
List of data associations. Each association contains a list of external_id values for data objects that should be grouped together. Returns empty list if no associations exist or method not implemented.

Examples

If data object A is associated with B and C in one group:

>>> [PluginDataAssociation(associated_external_ids=["A", "B", "C"])]

If data object A has two separate associations (one with B, one with C):

>>> [
... PluginDataAssociation(associated_external_ids=["A", "B"]),
... PluginDataAssociation(associated_external_ids=["A", "C"]),
... ]

With metadata:

>>> [
... PluginDataAssociation(
... associated_external_ids=["A", "B", "C"],
... metadata=[
... PluginMetadata(
... field=MetadataFieldID(slug="association_type", source="referential", name="Association Type"),
... value=MetadataValue(value="paired")
... )
... ]
... ),
... ]

get_data_objectmethodabstract#

def get_data_object(object_id: str) -> PluginDataObject

Return the detailed information of a data object.

Parameters

NameTypeDescription
object_idstrID of the data object.

Returns

PluginDataObject
An object containing detailed information about the data object.

get_data_objectsmethodabstract#

def get_data_objects(parent_id: str) -> list[PluginDataObject]

Return list of all mappable objects from a given parent.

Parameters

NameTypeDescription
parent_idstrID of the parent object, or the value of get_root_id() for the top level.

Returns

List[PluginDataObject]
Direct children of parent_id.

get_metadata_for_data_objectmethod#

def get_metadata_for_data_object(object_id: str) -> list[PluginMetadata]

Return the metadata for a data object.

Parameters

NameTypeDescription
object_idstrID of the data object.

Returns

list[PluginMetadata]
A list of metadata about the data object. Returns empty list if no metadata exists or method not implemented.

get_root_idmethodabstractstaticmethod#

def get_root_id() -> str

Return the unique identifier of the root data object.

Returns

str
Unique identifier of the root data object.

get_root_namemethodabstractstaticmethod#

def get_root_name() -> str

Return the name of the root data object.

Returns

str
Name of the root data object.
Inherited from plugins_api.base.ConnectionPlugin

closemethod#

def close() -> None

Release connection resources (optional).

Plugins that hold long-lived connections (e.g. SSH, persistent HTTP sessions) may override this method to close the underlying connection and release file descriptors. Callers (e.g. core) should call close() when done with the plugin instance.

The base implementation does nothing. Plugins that do not need to release resources need not override it.

get_connection_fieldsmethodabstractclassmethod#

def get_connection_fields() -> tuple[list[ConnectionField], list[ConnectionField]]

Retrieve the connection fields for the connection plugin.

Returns

tuple[list[ConnectionField], list[ConnectionField]]
(shared_fields, private_fields). Shared fields are instance-level (URL, host). Private fields are per-user secrets (token, password).

get_instance_namemethodabstract#

def get_instance_name() -> str

Return the instance name of the connection plugin.

Returns

str
Instance name.

get_shared_parametersmethodabstract#

def get_shared_parameters() -> dict[str, Any]

Return all shared parameters in a cleaned form.

Returns

dict
Shared parameters cleaned.

is_sandboxmethodclassmethod#

def is_sandbox(shared_parameters: dict[str, Any]) -> bool

Return whether the shared parameters are for a sandbox connection or not.

Parameters

NameTypeDescription
shared_parametersdictThe shared parameters to check.

Returns

bool
Plugin is sandbox.

on_before_store_credentialsmethodclassmethod#

def on_before_store_credentials(shared_params: dict, private_params: dict) -> dict

Hook called just before writing credentials to the Vault. Allows the plugin to transform/enrich the private_params. By default, returns the params unchanged.

on_delete_credentialsmethodclassmethod#

def on_delete_credentials(shared_params: dict, vault_secret: dict) -> None

Hook called just before deleting credentials from the Vault. Allows the plugin to perform cleanup on the remote server side. By default, does nothing.

Inherited from plugins_api.base.MadbotPlugin

get_authormethodabstractclassmethod#

def get_author() -> str

Return plugin author.

Returns

str
Plugin author.

get_colormethodabstractclassmethod#

def get_color() -> str

Return the color of the plugin.

Typically a hex value such as "#3B82F6".

Returns

str
Plugin color.

get_descriptionmethodabstractclassmethod#

def get_description() -> str

Return plugin description.

Returns

str
Plugin description.

get_idmethodclassmethod#

def get_id() -> str

Return the unique identifier of the plugin.

Returns

str
Unique identifier in the format ‘module.class’.
def get_logo() -> str

Return the static path of the plugin logo.

Path is relative to the plugin package static files. Example: "images/ena.png".

Returns

str
Plugin logo static path.

get_namemethodabstractclassmethod#

def get_name() -> str

Return the plugin name.

Returns

str
Plugin name.

get_slugmethodabstractclassmethod#

def get_slug() -> str

Return the plugin slug.

Lowercase, no spaces (e.g. "ena", "omero"). Used as MetadataFieldID.source and as the schema source at reload.

Returns

str
Plugin slug.

get_statusmethodabstractclassmethod#

def get_status() -> dict[str, PluginStatus]

Return the maturity status of the plugin, keyed by capability type.

A plugin implementing several capability types at once (e.g. a class inheriting from both SubmissionPlugin and MetadataFieldDefinitionPlugin) must return one entry per type it implements, using the same type strings as get_types().

Returns

dict[str, PluginStatus]
Mapping of plugin type (as returned by get_types()) to its maturity status.

Examples

A plugin implementing a single type:

>>> print(self.get_status())
{"data_plugin": PluginStatus.PREVIEW}

A plugin implementing several types at once:

>>> print(self.get_status())
{
"submission_plugin": PluginStatus.STABLE,
"metadata_field_definition_plugin": PluginStatus.STABLE,
}

get_typesmethodclassmethod#

def get_types() -> list[str]

Return the list of the plugin types in snake_case.

Returns

list
List of plugin types.