# plugins_api.submission_plugins

*module*

Submission plugins.

This module contains plugin classes for submission operations.

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

## plugins_api.submission_plugins.SubmissionPlugin

*class*

```python
class SubmissionPlugin(ConnectionPlugin)
```

Bases: `plugins_api.base.ConnectionPlugin`

Abstract class defining the minimum API for a submission plugin.

Submission plugins handle the submission of data and metadata to external repositories and services.
They manage the entire submission process, from metadata creation to the final publication.

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

### plugins_api.submission_plugins.SubmissionPlugin.create_metadata_objects

*method* · *abstract*

```python
def create_metadata_objects(submission: Submission, metadata_objects: dict[str, list[MetadataObject]] | None = None, data: list[SubmissionData] | None = None, associations: list[SubmissionAssociation] | None = None) -> tuple[dict[str, list[MetadataObject]], list[SubmissionAssociation] | None]
```

Create metadata objects (and optionally associations) for a submission.

**Parameters**

- `submission` (`Submission`) — The submission object.
- `metadata_objects` (`Dict[str, List[MetadataObject]]`) (default: `None`) — Dictionary of already existing metadataObjects sorted by type.
- `data` (`List[SubmissionData]`) (default: `None`) — List of data objects to create metadata objects for.
- `associations` (`List[SubmissionAssociation]`) (default: `None`) — Existing submission associations between metadata objects and data objects.

**Returns**

- (`Tuple[Dict[str, List[MetadataObject]], Optional[List[SubmissionAssociation]]]`) — First element: Dictionary of metadata objects to create, sorted by type. Second element: Optional list of associations (SubmissionAssociation DTOs) to create. If no associations are created, the second element can be None.

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

### plugins_api.submission_plugins.SubmissionPlugin.get_connection_documentation_url

*method* · *abstract* · *classmethod*

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

Retrieve the documentation URL for the submission plugin.

This method should be implemented by subclasses to provide
the appropriate URL that points to the documentation for
the specific plugin.

**Returns**

- (`str`) — A string containing the documentation URL.

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

### plugins_api.submission_plugins.SubmissionPlugin.get_max_file_size

*method* · *classmethod*

```python
def get_max_file_size() -> int | None
```

Return the maximum file size in bytes allowed by the plugin.

Returns None if there is no file size limit.

**Returns**

- (`int | None`) — Maximum file size in bytes, or None if no limit.

**Examples**

Using raw bytes for a 100MB file size limit (decimal conversion)

```pycon
>>> print(self.get_max_file_size())
100000000
```

> **Notes**
>
> Use the size_to_bytes helper to convert human-readable units to raw bytes.
> 
> Using the size_to_bytes helper for a 100MB file size limit (decimal/SI conversion)
> 
> >>> from plugins_api import size_to_bytes
> >>> return size_to_bytes(100, "MB")
> 100000000
> 
> Using binary conversion for a 100MiB file size limit (IEC units)
> 
> >>> from plugins_api import size_to_bytes
> >>> return size_to_bytes(100, "MiB")
> 104857600

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

### plugins_api.submission_plugins.SubmissionPlugin.get_max_files_per_submission

*method* · *classmethod*

```python
def get_max_files_per_submission() -> int | None
```

Return the maximum number of files allowed per submission for the plugin.

Returns None if there is no limit.

**Returns**

- (`int | None`) — Maximum number of files per submission, or None if no limit.

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

### plugins_api.submission_plugins.SubmissionPlugin.get_max_submission_size

*method* · *classmethod*

```python
def get_max_submission_size() -> int | None
```

Return the maximum total submission size in bytes allowed by the plugin.

This is the cumulative size limit for all files in a single submission.
Returns None if there is no submission size limit.

**Returns**

- (`int | None`) — Maximum total submission size in bytes, or None if no limit.

**Examples**

Using raw bytes for a 50GB submission size limit (decimal conversion)

```pycon
>>> print(self.get_max_submission_size())
50000000000
```

> **Notes**
>
> Use the size_to_bytes helper to convert human-readable units to raw bytes.
> 
> Using the size_to_bytes helper for a 50GB submission size limit (decimal/SI conversion)
> 
> >>> from plugins_api import size_to_bytes
> >>> return size_to_bytes(50, "GB")
> 50000000000
> 
> Using binary conversion for a 50GiB submission size limit (IEC units)
> 
> >>> from plugins_api import size_to_bytes
> >>> return size_to_bytes(50, "GiB")
> 53687091200

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

### plugins_api.submission_plugins.SubmissionPlugin.get_metadata_fields_groups

*method* · *abstract* · *classmethod*

```python
def get_metadata_fields_groups(parent: str | None = None) -> list[MetadataGroupNodeDTO]
```

Return metadata groups for UI navigation.

Same contract as
``MetadataFieldDefinitionPlugin.get_metadata_fields_groups``.
Required when the plugin also implements
``MetadataFieldDefinitionPlugin`` (madbot core only calls this on
that plugin type). See ``MetadataGroupNodeDTO``.

**Parameters**

- `parent` (`str`) (default: `None`) — Parent group slug. ``None`` returns root groups. Unknown parent values must raise ``ValueError``.

**Returns**

- (`list[MetadataGroupNodeDTO]`) — Metadata group nodes. MOT nodes use ``type="mot"``; UI folders use ``type="subgroup"``. Use ``children``, not a ``groups`` key.

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

### plugins_api.submission_plugins.SubmissionPlugin.get_settings_fields

*method* · *abstract* · *classmethod*

```python
def get_settings_fields() -> list[SettingField]
```

Retrieve the settings fields for the plugin.

**Returns**

- (`list[SettingField]`) — A list of SettingField DTOs, each containing a `slug` and its corresponding `schema_content`.

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

### plugins_api.submission_plugins.SubmissionPlugin.get_supported_file_extensions

*method* · *abstract* · *classmethod*

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

Return a list of supported file extensions for the plugin.

Returning an empty list implies that all file extensions are supported.

**Returns**

- (`list`) — List of file extensions supported by the plugin.

**Examples**

Supports fastq files

```pycon
>>> print(self.get_supported_file_extensions())
["fastq"]
```

Supports all types of files

```pycon
>>> print(self.get_supported_file_extensions())
[]
```

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

### plugins_api.submission_plugins.SubmissionPlugin.prepare_deposition

*method*

```python
def prepare_deposition(submission: Submission, metadata_objects: dict[str, list[MetadataObject]] | None = None) -> dict[str, Any] | None
```

Prepare a deposition/container before data submission (if needed).

Some plugins (like Zenodo) require creating a deposition/container first
before data can be submitted. This method allows the plugin to create
the deposition and return the necessary parameters for data submission
(e.g., deposition_id, bucket_url).

**Parameters**

- `submission` (`Submission`) — The submission object.
- `metadata_objects` (`Dict[str, List[MetadataObject]]`) (default: `None`) — Dictionary of already existing metadataObjects sorted by type.

**Returns**

- (`dict[str, Any] | None`) — A dictionary containing parameters needed for data submission. Common keys: 'deposition_id', 'data_submission_url', etc. Returns None if no preparation is needed (data-first workflow).

> **Notes**
>
> - For plugins that use data-first workflow (like ENA), this should return None.
> - For plugins that need deposition first (like Zenodo), this should create
>   the deposition and return the necessary parameters.
> - The returned dictionary will be passed to _submit_data_files() as kwargs.

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

### plugins_api.submission_plugins.SubmissionPlugin.submit

*method* · *abstract*

```python
def submit(submission: Submission, metadata_objects: dict[str, list[MetadataObject]] | None = None, data: list[SubmissionData] | None = None, associations: list[SubmissionAssociation] | None = None, data_transfer_result: list[dict[str, Any]] | None = None, deposition_params: dict[str, Any] | None = None) -> tuple[list[ExternalIdentifier], dict[str, list[MetadataObject]]]
```

Submit a submission to the repository.

**Parameters**

- `submission` (`Submission`) — The submission object.
- `metadata_objects` (`Dict[str, List[MetadataObject]]`) (default: `None`) — Dictionary of already existing metadataObjects sorted by type.
- `data` (`List[SubmissionData]`) (default: `None`) — List of data objects to submit.
- `associations` (`List[SubmissionAssociation]`) (default: `None`) — List of associations between metadata objects.
- `data_transfer_result` (`List[dict[str, Any]]`) (default: `None`) — Result from data file submission. Contains information about uploaded files including external identifiers. This is provided when data submission happens before metadata submission (imposed workflow).
- `deposition_params` (`dict[str, Any] | None`) (default: `None`) — Parameters returned from prepare_deposition() if the plugin needs a deposition/container created before data submission. Contains information like deposition_id that was created.

**Returns**

- (`tuple`) — (ExternalIdentifiers, updated_metadata_objects) - The external identifiers and updated metadata objects.

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

### plugins_api.submission_plugins.SubmissionPlugin.submit_data

*method* · *abstract*

```python
def submit_data(deposition_id: str, file: dict[str, Any], data_submission_url: str | None = None) -> dict[str, Any]
```

Submit a data file to the plugin.

**Parameters**

- `deposition_id` (`str | None`) — The deposition ID. May be None for plugins that don't require a deposition before data submission.
- `file` (`dict[str, Any]`) — The file to submit. Contains keys: 'name', 'size', 'data', 'md5_hash', 'submission_data_id', 'source_path'.
- `data_submission_url` (`str | None`) (default: `None`) — Optional endpoint URL for direct file upload (e.g., Zenodo bucket URL, FTP URL, etc.).

**Returns**

- (`dict[str, Any]`) — File information with optional 'external_identifiers' list containing ExternalIdentifier objects for the uploaded file.

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

### plugins_api.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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.submission_plugins.SubmissionPlugin.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)
