# plugins_api.data_plugins

*module*

Data plugins.

This module contains plugin classes for data management operations.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/data_plugins.py#L1-1)

## plugins_api.data_plugins.DataPlugin

*class*

```python
class DataPlugin(ConnectionPlugin)
```

Bases: `plugins_api.base.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.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/data_plugins.py#L15-246)

### plugins_api.data_plugins.DataPlugin.download_data

*method* · *abstract*

```python
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**

- `external_dataobject_id` (`str`) — Unique identifier of the data object in the external system.
- `destination_path` (`str`) — Local path where the file should be saved.

**Returns**

- (`str`) — Path to the local file.

**Raises**

- `NotImplementedError` — This method must be implemented in a subclass.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/data_plugins.py#L214-246)

### plugins_api.data_plugins.DataPlugin.get_data_associations_for_data_object

*method*

```python
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**

- `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.

> **Notes**
>
> This method has a default implementation that returns an empty list,
> making it optional for plugins to implement. Plugins that support data
> associations should override this method to return the appropriate
> association groups.

**Examples**

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

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

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

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

With metadata:

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

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/data_plugins.py#L154-212)

### plugins_api.data_plugins.DataPlugin.get_data_object

*method* · *abstract*

```python
def get_data_object(object_id: str) -> PluginDataObject
```

Return the detailed information of a data object.

**Parameters**

- `object_id` (`str`) — ID of the data object.

**Returns**

- (`PluginDataObject`) — An object containing detailed information about the data object.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/data_plugins.py#L112-128)

### plugins_api.data_plugins.DataPlugin.get_data_objects

*method* · *abstract*

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

Return list of all mappable objects from a given parent.

**Parameters**

- `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``.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/data_plugins.py#L93-110)

### plugins_api.data_plugins.DataPlugin.get_metadata_for_data_object

*method*

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

Return the metadata for a data object.

**Parameters**

- `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.

> **Notes**
>
> This method has a default implementation that returns an empty list,
> making it optional for plugins to implement. Plugins that support metadata
> should override this method to return ``PluginMetadata`` instances.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/data_plugins.py#L130-152)

### plugins_api.data_plugins.DataPlugin.get_root_id

*method* · *abstract* · *staticmethod*

```python
def get_root_id() -> str
```

Return the unique identifier of the root data object.

**Returns**

- (`str`) — Unique identifier of the root data object.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/data_plugins.py#L79-91)

### plugins_api.data_plugins.DataPlugin.get_root_name

*method* · *abstract* · *staticmethod*

```python
def get_root_name() -> str
```

Return the name of the root data object.

**Returns**

- (`str`) — Name of the root data object.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/data_plugins.py#L65-77)

### plugins_api.data_plugins.DataPlugin.close

*method*

```python
def close() -> None
```

Inherited from: `plugins_api.base.ConnectionPlugin`

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.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L232-244)

### plugins_api.data_plugins.DataPlugin.get_connection_fields

*method* · *abstract* · *classmethod*

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

Inherited from: `plugins_api.base.ConnectionPlugin`

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).

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L201-217)

### plugins_api.data_plugins.DataPlugin.get_instance_name

*method* · *abstract*

```python
def get_instance_name() -> str
```

Inherited from: `plugins_api.base.ConnectionPlugin`

Return the instance name of the connection plugin.

**Returns**

- (`str`) — Instance name.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L188-199)

### plugins_api.data_plugins.DataPlugin.get_shared_parameters

*method* · *abstract*

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

Inherited from: `plugins_api.base.ConnectionPlugin`

Return all shared parameters in a cleaned form.

**Returns**

- (`dict`) — Shared parameters cleaned.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L219-230)

### plugins_api.data_plugins.DataPlugin.is_sandbox

*method* · *classmethod*

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

Inherited from: `plugins_api.base.ConnectionPlugin`

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

**Parameters**

- `shared_parameters` (`dict`) — The shared parameters to check.

**Returns**

- (`bool`) — Plugin is sandbox.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L246-263)

### plugins_api.data_plugins.DataPlugin.on_before_store_credentials

*method* · *classmethod*

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

Inherited from: `plugins_api.base.ConnectionPlugin`

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

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L265-276)

### plugins_api.data_plugins.DataPlugin.on_delete_credentials

*method* · *classmethod*

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

Inherited from: `plugins_api.base.ConnectionPlugin`

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

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L278-289)

### plugins_api.data_plugins.DataPlugin.get_author

*method* · *abstract* · *classmethod*

```python
def get_author() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return plugin author.

**Returns**

- (`str`) — Plugin author.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L77-89)

### plugins_api.data_plugins.DataPlugin.get_color

*method* · *abstract* · *classmethod*

```python
def get_color() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the color of the plugin.

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

**Returns**

- (`str`) — Plugin color.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L108-122)

### plugins_api.data_plugins.DataPlugin.get_description

*method* · *abstract* · *classmethod*

```python
def get_description() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return plugin description.

**Returns**

- (`str`) — Plugin description.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L63-75)

### plugins_api.data_plugins.DataPlugin.get_id

*method* · *classmethod*

```python
def get_id() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the unique identifier of the plugin.

**Returns**

- (`str`) — Unique identifier in the format 'module.class'.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L19-30)

### plugins_api.data_plugins.DataPlugin.get_logo

*method* · *abstract* · *classmethod*

```python
def get_logo() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

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.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L91-106)

### plugins_api.data_plugins.DataPlugin.get_name

*method* · *abstract* · *classmethod*

```python
def get_name() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the plugin name.

**Returns**

- (`str`) — Plugin name.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L32-44)

### plugins_api.data_plugins.DataPlugin.get_slug

*method* · *abstract* · *classmethod*

```python
def get_slug() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

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.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L46-61)

### plugins_api.data_plugins.DataPlugin.get_status

*method* · *abstract* · *classmethod*

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

Inherited from: `plugins_api.base.MadbotPlugin`

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:

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

A plugin implementing several types at once:

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

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L124-157)

### plugins_api.data_plugins.DataPlugin.get_types

*method* · *classmethod*

```python
def get_types() -> list[str]
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the list of the plugin types in snake_case.

**Returns**

- (`list`) — List of plugin types.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/base.py#L159-176)
