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

Submission plugins.

This module contains plugin classes for submission operations.

Classes

NameDescription
SubmissionPluginAbstract class defining the minimum API for a submission plugin.

SubmissionPluginclass#

class SubmissionPlugin(connection_parameters: dict[str, Any], settings: dict[str, Settings])

Bases: 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.

create_metadata_objectsmethodabstract#

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

NameTypeDefaultDescription
submissionSubmissionrequiredThe submission object.
metadata_objectsDict[str, List[MetadataObject]]NoneDictionary of already existing metadataObjects sorted by type.
dataList[SubmissionData]NoneList of data objects to create metadata objects for.
associationsList[SubmissionAssociation]NoneExisting 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.

get_connection_documentation_urlmethodabstractclassmethod#

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.

get_max_file_sizemethodclassmethod#

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)

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

get_max_files_per_submissionmethodclassmethod#

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.

get_max_submission_sizemethodclassmethod#

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)

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

get_metadata_fields_groupsmethodabstractclassmethod#

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

NameTypeDefaultDescription
parentstrNoneParent 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.

get_settings_fieldsmethodabstractclassmethod#

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.

get_supported_file_extensionsmethodabstractclassmethod#

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

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

Supports all types of files

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

prepare_depositionmethod#

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

NameTypeDefaultDescription
submissionSubmissionrequiredThe submission object.
metadata_objectsDict[str, List[MetadataObject]]NoneDictionary 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).

submitmethodabstract#

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

NameTypeDefaultDescription
submissionSubmissionrequiredThe submission object.
metadata_objectsDict[str, List[MetadataObject]]NoneDictionary of already existing metadataObjects sorted by type.
dataList[SubmissionData]NoneList of data objects to submit.
associationsList[SubmissionAssociation]NoneList of associations between metadata objects.
data_transfer_resultList[dict[str, Any]]NoneResult 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_paramsdict[str, Any] | NoneNoneParameters 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.

submit_datamethodabstract#

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

NameTypeDefaultDescription
deposition_idstr | NonerequiredThe deposition ID. May be None for plugins that don’t require a deposition before data submission.
filedict[str, Any]requiredThe file to submit. Contains keys: ‘name’, ‘size’, ‘data’, ‘md5_hash’, ‘submission_data_id’, ‘source_path’.
data_submission_urlstr | NoneNoneOptional 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.
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.