plugins_api.data_plugins
Data plugins.
This module contains plugin classes for data management operations.
Classes
| Name | Description |
|---|---|
DataPlugin | Abstract 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) -> strDownload 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
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
| Name | Type | Description |
|---|---|---|
object_id | str | ID 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) -> PluginDataObjectReturn the detailed information of a data object.
Parameters
| Name | Type | Description |
|---|---|---|
object_id | str | ID 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
| Name | Type | Description |
|---|---|---|
parent_id | str | ID 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
| Name | Type | Description |
|---|---|---|
object_id | str | ID 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() -> strReturn the unique identifier of the root data object.
Returns
str- Unique identifier of the root data object.
get_root_namemethodabstractstaticmethod#
def get_root_name() -> strReturn the name of the root data object.
Returns
str- Name of the root data object.
Inherited from plugins_api.base.ConnectionPlugin
closemethod#
plugins_api.base.ConnectionPluginView sourcedef close() -> NoneRelease 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#
plugins_api.base.ConnectionPluginView sourcedef 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#
plugins_api.base.ConnectionPluginView sourcedef get_instance_name() -> strReturn the instance name of the connection plugin.
Returns
str- Instance name.
get_shared_parametersmethodabstract#
plugins_api.base.ConnectionPluginView sourcedef get_shared_parameters() -> dict[str, Any]Return all shared parameters in a cleaned form.
Returns
dict- Shared parameters cleaned.
is_sandboxmethodclassmethod#
plugins_api.base.ConnectionPluginView sourcedef is_sandbox(shared_parameters: dict[str, Any]) -> boolReturn whether the shared parameters are for a sandbox connection or not.
Parameters
| Name | Type | Description |
|---|---|---|
shared_parameters | dict | The shared parameters to check. |
Returns
bool- Plugin is sandbox.
on_before_store_credentialsmethodclassmethod#
plugins_api.base.ConnectionPluginView sourcedef on_before_store_credentials(shared_params: dict, private_params: dict) -> dictHook 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#
plugins_api.base.ConnectionPluginView sourcedef on_delete_credentials(shared_params: dict, vault_secret: dict) -> NoneHook 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#
plugins_api.base.MadbotPluginView sourcedef get_author() -> strReturn plugin author.
Returns
str- Plugin author.
get_colormethodabstractclassmethod#
plugins_api.base.MadbotPluginView sourcedef get_color() -> strReturn the color of the plugin.
Typically a hex value such as "#3B82F6".
Returns
str- Plugin color.
get_descriptionmethodabstractclassmethod#
plugins_api.base.MadbotPluginView sourcedef get_description() -> strReturn plugin description.
Returns
str- Plugin description.
get_idmethodclassmethod#
plugins_api.base.MadbotPluginView sourcedef get_id() -> strReturn the unique identifier of the plugin.
Returns
str- Unique identifier in the format ‘module.class’.
get_logomethodabstractclassmethod#
plugins_api.base.MadbotPluginView sourcedef get_logo() -> strReturn 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#
plugins_api.base.MadbotPluginView sourcedef get_name() -> strReturn the plugin name.
Returns
str- Plugin name.
get_slugmethodabstractclassmethod#
plugins_api.base.MadbotPluginView sourcedef get_slug() -> strReturn 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#
plugins_api.base.MadbotPluginView sourcedef 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#
plugins_api.base.MadbotPluginView sourcedef get_types() -> list[str]Return the list of the plugin types in snake_case.
Returns
list- List of plugin types.

