Skip to content
Reference of plugins_api 3.0.0.

plugins_api.dtos

Data Transfer Objects (DTOs) for plugins.

This module contains all DTOs used in the plugin system.

Classes

NameDescription
AccessTypeEnum for supported access types for external data objects.
AssociationRolePossible roles of an object within a submission association.
ConnectionFieldDTO representing a connection field.
ExternalAccessDTO for how to access an external data object.
ExternalIdentifierDTO for an identifier assigned by an external repository for submission plugins.
ExternalIdentifierTypeType of external identifier.
FieldRepresentationDTO for a metadata field defined by a plugin.
MadbotMetadataDTO for metadata attached to a madbot object, provided by madbot core to plugins.
MadbotMetadataObjectDTO for a metadata object instance provided by madbot core to plugins.
MetadataFieldIDDTO for metadata field.
MetadataFieldMappingDTO for metadata mapping.
MetadataGroupNodeDTODTO representing a node in a metadata groups navigation tree.
MetadataObjectDTO for a metadata object instance returned by a submission plugin.
MetadataObjectMetadataDTO for one metadata field on a metadata object.
MetadataObjectTypeDTO representing a type of metadata object in the submission plugin.
MetadataValueDTO for a metadata value.
PluginDataAssociationDTO representing a data association returned by data plugins.
PluginDataObjectDTO for an external data object returned by a data plugin.
PluginMetadataDTO for metadata returned by a plugin.
PluginStatusMaturity status of a plugin for a given capability type.
SchemaRepresentationDTO for the JSON schema of a metadata or connection field.
SettingFieldDTO for a submission setting schema, returned by get_settings_fields().
SettingsDTO for a submission setting value passed to the plugin constructor.
SourceAbstract base DTO for a madbot object that is the source of a metadata value.
SourceAssociationDataDTO for a data association that is the source of a metadata value.
SourceDataDTO for a madbot data object that is the source of a metadata value.
SourceNodeDTO for a madbot node that is the source of a metadata value.
SourceSampleDTO for a madbot sample that is the source of a metadata value.
SubmissionDTO for a submission.
SubmissionAssociationDTO representing an association (a group of related objects).
SubmissionAssociationObjectDTO representing an object within a submission association.
SubmissionDataDTO for a data object included in a submission, provided by madbot core.
SubmissionMemberDTO for a submission member.
SubmissionMetadataValueDTO for a metadata value on a submission.

AccessTypeclass#

class AccessType(StrEnum)

Bases: StrEnum

Enum for supported access types for external data objects.

SHELLattributeclass attributeinstance attribute#

SHELL = 'shell'

URLattributeclass attributeinstance attribute#

URL = 'url'

AssociationRoleclass#

class AssociationRole(StrEnum)

Bases: StrEnum

Possible roles of an object within a submission association.

SOURCEattributeclass attributeinstance attribute#

SOURCE = 'source'

TARGETattributeclass attributeinstance attribute#

TARGET = 'target'

ConnectionFieldclass#

class ConnectionField(BaseModel)

Bases: BaseModel

DTO representing a connection field.

schema_contentattributeinstance attribute#

schema_content: dict[str, Any]

slugattributeinstance attribute#

slug: str

uischemaattributeclass attributeinstance attribute#

uischema: dict[str, Any] | None = None

ExternalAccessclass#

class ExternalAccess(BaseModel)

Bases: BaseModel

DTO for how to access an external data object.

Attributes

NameTypeDescription
access_typeAccessTypeType of access to the external data object.
detailsstrFor AccessType.URL: a URL string. For AccessType.SHELL: a command string. Stored as a string of at most 1000 characters.

access_typeattributeinstance attribute#

access_type: AccessType

detailsattributeinstance attribute#

details: Any

ExternalIdentifierclass#

class ExternalIdentifier(BaseModel)

Bases: BaseModel

DTO for an identifier assigned by an external repository for submission plugins.

Attributes

NameTypeDescription
identifierstrThe identifier string itself (DOI, accession, …).
typeExternalIdentifierTypeKind of identifier. Must be one of the enum values.
url(str, optional)URL for the identifier, if any.

identifierattributeinstance attribute#

identifier: str

typeattributeclass attributeinstance attribute#

type: ExternalIdentifierType = Field(..., description='Type of identifier')

urlattributeclass attributeinstance attribute#

url: str | None = None

ExternalIdentifierTypeclass#

class ExternalIdentifierType(StrEnum)

Bases: StrEnum

Type of external identifier.

ACCESSIONattributeclass attributeinstance attribute#

ACCESSION = 'ACCESSION'

ARKattributeclass attributeinstance attribute#

ARK = 'ARK'

BIOPROJECTattributeclass attributeinstance attribute#

BIOPROJECT = 'BIOPROJECT'

BIOSAMPLEattributeclass attributeinstance attribute#

BIOSAMPLE = 'BIOSAMPLE'

DOIattributeclass attributeinstance attribute#

DOI = 'DOI'

ENA_EXPERIMENTattributeclass attributeinstance attribute#

ENA_EXPERIMENT = 'ENA EXPERIMENT'

ENA_PROJECTattributeclass attributeinstance attribute#

ENA_PROJECT = 'ENA PROJECT'

ENA_RUNattributeclass attributeinstance attribute#

ENA_RUN = 'ENA RUN'

ENA_SAMPLEattributeclass attributeinstance attribute#

ENA_SAMPLE = 'ENA SAMPLE'

IDattributeclass attributeinstance attribute#

ID = 'ID'

PURLattributeclass attributeinstance attribute#

PURL = 'PURL'

FieldRepresentationclass#

class FieldRepresentation(BaseModel)

Bases: BaseModel

DTO for a metadata field defined by a plugin.

Attributes

NameTypeDescription
slugstrField slug: plugin__field or plugin__mot__field.
schema_repSchemaRepresentationSchema for this field. schema_rep.slug should match slug.
titlestrDisplay name.
descriptionstrHuman-readable description. May be empty.
external_urlstrDocumentation URL for the field. Use "" if none.
madbot_fieldslist[str]Slugs of mapped madbot fields. Empty list if unmapped.
hiddenboolIf True, the field should be hidden in the UI.
standard(str, optional)Metadata standard this field belongs to, or None.

descriptionattributeinstance attribute#

description: str

external_urlattributeinstance attribute#

external_url: str

hiddenattributeinstance attribute#

hidden: bool

madbot_fieldsattributeinstance attribute#

madbot_fields: list[str]

schema_repattributeinstance attribute#

schema_rep: SchemaRepresentation

slugattributeinstance attribute#

slug: str

standardattributeclass attributeinstance attribute#

standard: str | None = None

titleattributeinstance attribute#

title: str

MadbotMetadataclass#

class MadbotMetadata(BaseModel)

Bases: BaseModel

DTO for metadata attached to a madbot object, provided by madbot core to plugins.

Attributes

NameTypeDescription
fieldMetadataFieldIDField this value belongs to.
metadata_value(MetadataValue, optional)Selected value. Named metadata_value here (not value).
inherited_valueslist[MetadataValue]Candidate values inherited from ancestors. Same role as MetadataObjectMetadata.candidate_values.

fieldattributeinstance attribute#

field: MetadataFieldID

inherited_valuesattributeclass attributeinstance attribute#

inherited_values: list[MetadataValue] = []

metadata_valueattributeclass attributeinstance attribute#

metadata_value: MetadataValue | None = None

MadbotMetadataObjectclass#

class MadbotMetadataObject(BaseModel)

Bases: BaseModel

DTO for a metadata object instance provided by madbot core to plugins.

Distinct from MetadataObject, which plugins return from create_metadata_objects().

Attributes

NameTypeDescription
idUUIDMadbot identifier of the metadata object.
typestrMetadata object type slug (e.g. "sample").
metadatalist[MetadataObjectMetadata]Field values on this object.
cross_validationdict[str, Any]Cross-field validation errors, keyed by field slug. Empty dict if valid.
external_identifierslist[ExternalIdentifier]Identifiers assigned after submission, if any.

cross_validationattributeinstance attribute#

cross_validation: dict[str, Any]

external_identifiersattributeclass attributeinstance attribute#

external_identifiers: list[ExternalIdentifier] = []

idattributeclass attributeinstance attribute#

id: UUID = Field(default_factory=uuid4)

metadataattributeinstance attribute#

metadata: list[MetadataObjectMetadata]

typeattributeinstance attribute#

type: str

MetadataFieldIDclass#

class MetadataFieldID(BaseModel)

Bases: BaseModel

DTO for metadata field.

Attributes

NameTypeDescription
slugstrUnique identifier for the metadata field. For plugin fields: plugin__field or plugin__mot__field. For madbot fields: the madbot field slug.
namestrDisplay name of the metadata field.
sourcestr"referential" for a madbot field, or the plugin slug for a plugin field.

nameattributeinstance attribute#

name: str

slugattributeinstance attribute#

slug: str

sourceattributeinstance attribute#

source: str

MetadataFieldMappingclass#

class MetadataFieldMapping(BaseModel)

Bases: BaseModel

DTO for metadata mapping.

This DTO is used to map a metadata field from the plugin to a metadata field in madbot. It represents a bidirectional mapping between fields in the madbot referential and fields in a plugin referential, along with transformation functions for converting data between the two systems.

Attributes

NameTypeDescription
plugin_fieldslist[str]Plugin field slugs involved in this mapping. Keys of the dict passed to transform_plugin_to_madbot must be a subset of these slugs.
madbot_fieldslist[str]Madbot field slugs involved in this mapping. Keys of the dict passed to transform_madbot_to_plugin must be a subset of these slugs.
transform_madbot_to_pluginCallabledict[madbot_slug, value] -> dict[plugin_slug, value].
transform_plugin_to_madbotCallabledict[plugin_slug, value] -> dict[madbot_slug, value].
mapping_idOptional[str]Unique identifier for this mapping rule. Useful for distinguishing between multiple mappings for the same field (e.g., different checklists).

madbot_fieldsattributeinstance attribute#

madbot_fields: list[str]

mapping_idattributeclass attributeinstance attribute#

mapping_id: str | None = None

model_configattributeclass attributeinstance attribute#

model_config = ConfigDict(extra='allow')

plugin_fieldsattributeinstance attribute#

plugin_fields: list[str]

transform_madbot_to_pluginattributeinstance attribute#

transform_madbot_to_plugin: Callable[[dict[str, Any]], dict[str, Any]]

transform_plugin_to_madbotattributeinstance attribute#

transform_plugin_to_madbot: Callable[[dict[str, Any]], dict[str, Any]]

MetadataGroupNodeDTOclass#

class MetadataGroupNodeDTO(BaseModel)

Bases: BaseModel

DTO representing a node in a metadata groups navigation tree.

This tree is for UI navigation only. It is complementary to get_all_metadata_object_types() / get_contextual_metadata_object_types(), which define what each metadata object type (MOT) contains (fields, levels, occurrences). Groups only organize those fields for browsing.

Attributes

NameTypeDescription
slugstrUnique slug for the group node. For type="mot", use the MOT slug.
namestrDisplay name of the group node.
descriptionstrHuman-readable description of the group node.
typeLiteral['mot', 'subgroup'] | None"mot" for a metadata object type node, "subgroup" for nested groups.
has_groupsboolTrue when this node has child group nodes.
fieldslist[str | dict]

Field slugs attached to this node (usually on subgroups, not on MOT nodes that have children). Each field can be either:

  • a plain slug string, or
  • a dict with:
    • slug: field slug
    • level: one of “mandatory”, “recommended”, “optional”
childrenlist[MetadataGroupNodeDTO]Child group nodes.

Examples

A single MOT with subgroups (Zenodo-style):

>>> MetadataGroupNodeDTO(
... slug="general",
... name="General",
... description="Deposition metadata",
... type="mot",
... has_groups=True,
... fields=[],
... children=[
... MetadataGroupNodeDTO(
... slug="core_identification",
... name="Core identification",
... description="Essential identifying information",
... type="subgroup",
... has_groups=False,
... fields=["plugin__title", "plugin__description"],
... children=[],
... )
... ],
... )

Two MOTs:

>>> [
... MetadataGroupNodeDTO(
... slug="general",
... name="General",
... description="General metadata object",
... type="mot",
... has_groups=False,
... fields=["plugin__a", "plugin__b"],
... children=[],
... ),
... MetadataGroupNodeDTO(
... slug="complementary",
... name="Complementary",
... description="Complementary metadata object",
... type="mot",
... has_groups=False,
... fields=["plugin__d", "plugin__e"],
... children=[],
... ),
... ]

A subgroup with checklist-specific levels:

>>> MetadataGroupNodeDTO(
... slug="sample_environment",
... name="Environment",
... description="Environmental metadata for the sample",
... type="subgroup",
... has_groups=False,
... fields=[
... {"slug": "ena__sample__environmental_sample", "level": "optional"},
... {"slug": "ena__sample__geographical_location", "level": "mandatory"},
... ],
... children=[],
... )

childrenattributeclass attributeinstance attribute#

children: list[MetadataGroupNodeDTO] = Field(default_factory=list)

descriptionattributeinstance attribute#

description: str

fieldsattributeclass attributeinstance attribute#

fields: list[
  str | dict[Literal['slug', 'level'], str | Literal['mandatory', 'recommended', 'optional'] | None]
] = Field(default_factory=list)

has_groupsattributeclass attributeinstance attribute#

has_groups: bool = False

nameattributeinstance attribute#

name: str

slugattributeinstance attribute#

slug: str

typeattributeclass attributeinstance attribute#

type: Literal['mot', 'subgroup'] | None = None

MetadataObjectclass#

class MetadataObject(BaseModel)

Bases: BaseModel

DTO for a metadata object instance returned by a submission plugin.

Distinct from MadbotMetadataObject, which madbot core sends to plugins. Return these from create_metadata_objects(), keyed by type slug.

Attributes

NameTypeDescription
id(UUID, optional)Existing madbot ID when updating, or a new UUID when creating.
typeMetadataObjectTypeFull type definition, not a slug.
metadatalist[MetadataObjectMetadata]Field values on this object.
cross_validationdict[str, Any]Cross-field validation errors, keyed by field slug. Empty dict if valid.
external_identifierslist[ExternalIdentifier]Identifiers assigned after submission, if any.

cross_validationattributeinstance attribute#

cross_validation: dict[str, Any]

external_identifiersattributeclass attributeinstance attribute#

external_identifiers: list[ExternalIdentifier] = []

idattributeclass attributeinstance attribute#

id: UUID | None = Field(default_factory=uuid4)

metadataattributeinstance attribute#

metadata: list[MetadataObjectMetadata]

typeattributeinstance attribute#

type: MetadataObjectType

MetadataObjectMetadataclass#

class MetadataObjectMetadata(BaseModel)

Bases: BaseModel

DTO for one metadata field on a metadata object.

Attributes

NameTypeDescription
fieldMetadataFieldIDField this value belongs to.
metadata_value(MetadataValue or SubmissionMetadataValue, optional)Selected value.
candidate_valueslist[MetadataValue | SubmissionMetadataValue]Alternative values the user may pick. Same role as MadbotMetadata.inherited_values.

candidate_valuesattributeclass attributeinstance attribute#

candidate_values: list[MetadataValue | SubmissionMetadataValue] = []

fieldattributeinstance attribute#

field: MetadataFieldID

metadata_valueattributeclass attributeinstance attribute#

metadata_value: MetadataValue | SubmissionMetadataValue | None = None

from_metadatamethodclassmethod#

def from_metadata(metadata: MadbotMetadata) -> MetadataObjectMetadata

Convert a Metadata to a MetadataObjectMetadata.

to_metadatamethod#

def to_metadata() -> MadbotMetadata

Convert a MetadataObjectMetadata to a Metadata.

MetadataObjectTypeclass#

class MetadataObjectType(BaseModel)

Bases: BaseModel

DTO representing a type of metadata object in the submission plugin.

This class defines the structure and requirements for a metadata object type in the system. It specifies what fields are required, recommended, or optional, along with their validation rules.

Attributes

NameTypeDescription
namestrThe display name of the metadata object type (e.g., ‘Sample’, ‘Experiment’, ‘Dataset’).
slugstrA unique identifier for the metadata object type, used in URLs and API endpoints. Should be lowercase with hyphens (e.g., ‘sample’, ‘experiment’, ‘dataset’).
summary_fieldsList[str]List of field names that should be displayed in summary views or lists. These fields provide a quick overview of the metadata object.
priorityList[str]Ordered list of field names indicating their display priority. Fields listed first will be displayed before fields listed later.
descriptionstrA detailed description of what this metadata object type represents and how it should be used in the system.
additional_information(str, optional)Additional contextual information displayed as an informational alert in the submission UI tabs. Intended to provide guidance or warnings specific to this metadata object type, such as instructions for configuring paired data. If None, no alert is displayed.
show_additional_information_on_data_tabboolWhether the additional_information message should also be displayed in the Data tab of the submission UI, in addition to the metadata object type’s own tab. Useful when the guidance is relevant to data configuration, such as paired file setup. Defaults to False.
minimal_occurrenceintThe minimum number of instances of this metadata object type that must be provided in a submission. For example, if set to 1, at least one instance is required.
maximal_occurrenceOptional[int]The maximum number of instances of this metadata object type allowed in a submission. If None, there is no upper limit to the number of instances.
mandatory_fields_schemaslist[FieldRepresentation]List of field schemas that are required for this metadata object type. These fields must be provided for the submission to be valid.
recommended_fields_schemaslist[FieldRepresentation]List of field schemas that are recommended but not required for this metadata object type. These fields should be provided when possible but their absence won’t invalidate the submission.
optional_fields_schemaslist[FieldRepresentation]List of field schemas that are optional for this metadata object type. These fields can be provided but are not required or recommended.

additional_informationattributeclass attributeinstance attribute#

additional_information: str | None = None

descriptionattributeinstance attribute#

description: str

mandatory_fields_schemasattributeinstance attribute#

mandatory_fields_schemas: list[FieldRepresentation]

maximal_occurrenceattributeclass attributeinstance attribute#

maximal_occurrence: int | None = None

minimal_occurrenceattributeinstance attribute#

minimal_occurrence: int

nameattributeinstance attribute#

name: str

optional_fields_schemasattributeinstance attribute#

optional_fields_schemas: list[FieldRepresentation]

priorityattributeinstance attribute#

priority: list[str]

recommended_fields_schemasattributeinstance attribute#

recommended_fields_schemas: list[FieldRepresentation]

show_additional_information_on_data_tabattributeclass attributeinstance attribute#

show_additional_information_on_data_tab: bool = False

slugattributeinstance attribute#

slug: str

summary_fieldsattributeinstance attribute#

summary_fields: list[str]

MetadataValueclass#

class MetadataValue(BaseModel)

Bases: BaseModel

DTO for a metadata value.

Attributes

NameTypeDescription
value(Any, optional)The value. Must match the field’s JSON schema. None means that the value is not set.
source_id(UUID, optional)Madbot Metadata record UUID this value comes from. Plugins building values should leave this None.

source_idattributeclass attributeinstance attribute#

source_id: UUID | None = None

valueattributeclass attributeinstance attribute#

value: Any | None = None

PluginDataAssociationclass#

class PluginDataAssociation(BaseModel)

Bases: BaseModel

DTO representing a data association returned by data plugins.

A data association represents a relationship between multiple data objects. Each association contains a list of external_id values that should be grouped together in a single DataAssociation in madbot, and optionally metadata that should be attached to the association.

Attributes

NameTypeDescription
associated_external_idslist[str]List of external_id values for data objects that should be associated together.
metadata(list[PluginMetadata], optional)List of metadata that should be attached to the DataAssociation. Defaults to empty list if not provided.

Examples

If data objects A, B, and C should be associated together:

>>> 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=["B", "C"],
... metadata=[
... PluginMetadata(
... field=MetadataFieldID(slug="association_type", source="referential", name="Association Type"),
... value=MetadataValue(value="paired")
... )
... ]
... )

associated_external_idsattributeinstance attribute#

associated_external_ids: list[str]

metadataattributeclass attributeinstance attribute#

metadata: list[PluginMetadata] = []

PluginDataObjectclass#

class PluginDataObject(BaseModel)

Bases: BaseModel

DTO for an external data object returned by a data plugin.

Attributes

NameTypeDescription
idstrStable identifier in the external system. Becomes madbot external_id.
namestrDisplay name.
type(str, optional)Free-form kind of object (e.g. "file", "directory", "project").
description(str, optional)Human-readable description, or None.
media_type(str, optional)MIME type (e.g. "application/gzip"), or None.
file_extension(str, optional)Extension without the leading dot (e.g. "fastq" or "fastq.gz"), or None.
size(int, optional)Size in bytes, or None.
icon(str, optional)Nerd Font class from get_icon() (e.g. "nf nf-fa-folder"), or None.
has_childrenboolTrue if browse_data_objects(this id) will return items.
linkableboolWhether the object can be linked into a madbot node.
childrenlist[PluginDataObject]List of child external data objects. Defaults to None.
accesseslist[ExternalAccess]Ways to open or download the object.

accessesattributeclass attributeinstance attribute#

accesses: list[ExternalAccess] = []

childrenattributeclass attributeinstance attribute#

children: list[PluginDataObject] = []

descriptionattributeclass attributeinstance attribute#

description: str | None = None

file_extensionattributeclass attributeinstance attribute#

file_extension: str | None = None

has_childrenattributeclass attributeinstance attribute#

has_children: bool = False

iconattributeclass attributeinstance attribute#

icon: str | None = None

idattributeinstance attribute#

id: str

linkableattributeclass attributeinstance attribute#

linkable: bool = False

media_typeattributeclass attributeinstance attribute#

media_type: str | None = None

nameattributeinstance attribute#

name: str

sizeattributeclass attributeinstance attribute#

size: int | None = None

typeattributeclass attributeinstance attribute#

type: str | None = None

add_external_accessmethod#

def add_external_access(access_type: AccessType, access_details: str) -> None

Add external access information to the data object.

Parameters

NameTypeDescription
access_typeAccessTypeThe type of access being added (must be one of the supported access types).
access_detailsstrThe access details to be associated with the specified access type. For AccessType.URL: a URL. For AccessType.SHELL: a command.

Raises

ValueError
If the provided access_type is not supported.

PluginMetadataclass#

class PluginMetadata(BaseModel)

Bases: BaseModel

DTO for metadata returned by a plugin.

Attributes

NameTypeDescription
fieldMetadataFieldIDField this value belongs to.
value(MetadataValue, optional)The value.

fieldattributeinstance attribute#

field: MetadataFieldID

valueattributeclass attributeinstance attribute#

value: MetadataValue | None = None

PluginStatusclass#

class PluginStatus(StrEnum)

Bases: StrEnum

Maturity status of a plugin for a given capability type.

PREVIEWattributeclass attributeinstance attribute#

PREVIEW = 'preview'

STABLEattributeclass attributeinstance attribute#

STABLE = 'stable'

SchemaRepresentationclass#

class SchemaRepresentation(BaseModel)

Bases: BaseModel

DTO for the JSON schema of a metadata or connection field.

Attributes

NameTypeDescription
slugstrField slug. For metadata fields: plugin__field or plugin__mot__field.
schema_contentdict[str, Any]JSON Schema. originalTitle is read by madbot core as the original field name when title is a user-friendly label.
uischema(dict[str, Any], optional)JSON Forms UI schema, if any.
sourcestrPlugin slug.

schema_contentattributeinstance attribute#

schema_content: dict[str, Any]

slugattributeinstance attribute#

slug: str

sourceattributeinstance attribute#

source: str

uischemaattributeclass attributeinstance attribute#

uischema: dict[str, Any] | None = None

SettingFieldclass#

class SettingField(ConnectionField)

Bases: ConnectionField

DTO for a submission setting schema, returned by get_settings_fields().

The slug must match Settings.field in the plugin constructor.

Inherited from plugins_api.dtos.ConnectionField

schema_contentattributeinstance attribute#

schema_content: dict[str, Any]

slugattributeinstance attribute#

slug: str

uischemaattributeclass attributeinstance attribute#

uischema: dict[str, Any] | None = None

Settingsclass#

class Settings(BaseModel)

Bases: BaseModel

DTO for a submission setting value passed to the plugin constructor.

Distinct from SettingField, which describes the setting schema. Madbot core passes dict[str, Settings] keyed by setting slug.

Attributes

NameTypeDescription
fieldstrSetting slug, matching a SettingField.slug from get_settings_fields().
setting_valueAnyUser-provided value, validated against that setting’s JSON schema.

fieldattributeinstance attribute#

field: str

setting_valueattributeinstance attribute#

setting_value: Any

Sourceclass#

class Source(BaseModel, ABC)

Bases: BaseModel, ABC

Abstract base DTO for a madbot object that is the source of a metadata value.

Do not instantiate this class. Use SourceData, SourceNode, SourceSample, or SourceAssociationData.

Attributes

NameTypeDescription
madbot_idUUIDMadbot identifier of the source object.

madbot_idattributeclass attributeinstance attribute#

madbot_id: UUID = Field(default_factory=uuid4)

model_post_initmethod#

def model_post_init(__context: Any) -> None

Reject direct instantiation of the abstract base.

SourceAssociationDataclass#

class SourceAssociationData(Source)

Bases: Source

DTO for a data association that is the source of a metadata value.

Attributes

NameTypeDescription
source_datalist[SourceData]Data objects in the association.
metadatalist[MadbotMetadata]Metadata attached to the association.

metadataattributeclass attributeinstance attribute#

metadata: list[MadbotMetadata] = []

source_dataattributeinstance attribute#

source_data: list[SourceData]
Inherited from plugins_api.dtos.Source

madbot_idattributeclass attributeinstance attribute#

madbot_id: UUID = Field(default_factory=uuid4)

model_post_initmethod#

def model_post_init(__context: Any) -> None

Reject direct instantiation of the abstract base.

SourceDataclass#

class SourceData(Source)

Bases: Source

DTO for a madbot data object that is the source of a metadata value.

Attributes

NameTypeDescription
namestrDisplay name of the data object.

nameattributeinstance attribute#

name: str
Inherited from plugins_api.dtos.Source

madbot_idattributeclass attributeinstance attribute#

madbot_id: UUID = Field(default_factory=uuid4)

model_post_initmethod#

def model_post_init(__context: Any) -> None

Reject direct instantiation of the abstract base.

SourceNodeclass#

class SourceNode(Source)

Bases: Source

DTO for a madbot node that is the source of a metadata value.

Attributes

NameTypeDescription
titlestrNode title.
description(str, optional)Node description as a JSON string of EditorJS content.
parent(SourceNode, optional)Parent node, or None for a root node.

descriptionattributeclass attributeinstance attribute#

description: str | None = None

parentattributeclass attributeinstance attribute#

parent: Optional[SourceNode] = None

titleattributeinstance attribute#

title: str

from_nodemethodclassmethod#

def from_node(values: Any) -> Any

Convert a generic node object into a SourceNode.

get_ancestorsmethod#

def get_ancestors() -> list[SourceNode]

Get all ancestors of this node, from root to the node itself.

Returns

List[SourceNode]
List of ancestors, ordered from root to this node
Inherited from plugins_api.dtos.Source

madbot_idattributeclass attributeinstance attribute#

madbot_id: UUID = Field(default_factory=uuid4)

model_post_initmethod#

def model_post_init(__context: Any) -> None

Reject direct instantiation of the abstract base.

SourceSampleclass#

class SourceSample(Source)

Bases: Source

DTO for a madbot sample that is the source of a metadata value.

Attributes

NameTypeDescription
titlestrSample title.
aliasstrSample alias.

aliasattributeinstance attribute#

alias: str

titleattributeinstance attribute#

title: str
Inherited from plugins_api.dtos.Source

madbot_idattributeclass attributeinstance attribute#

madbot_id: UUID = Field(default_factory=uuid4)

model_post_initmethod#

def model_post_init(__context: Any) -> None

Reject direct instantiation of the abstract base.

Submissionclass#

class Submission(BaseModel)

Bases: BaseModel

DTO for a submission.

idattributeclass attributeinstance attribute#

id: UUID = Field(default_factory=uuid4)

membersattributeinstance attribute#

members: list[SubmissionMember]

statusattributeinstance attribute#

status: str

titleattributeinstance attribute#

title: str

SubmissionAssociationclass#

class SubmissionAssociation(BaseModel)

Bases: BaseModel

DTO representing an association (a group of related objects).

Attributes

NameTypeDescription
idUUIDUnique identifier for the association.
submission_idUUIDIdentifier of the submission to which this association belongs.
association_namestrDescriptive name for the association, indicating the kind of relationship between objects (free-form, e.g. "paired_end").
objectslist[SubmissionAssociationObject]List of objects participating in the association. Each object may have a role (source/target) and can be either a metadata object or a data object.

association_nameattributeinstance attribute#

association_name: str

idattributeclass attributeinstance attribute#

id: UUID = Field(default_factory=uuid4)

objectsattributeinstance attribute#

objects: list[SubmissionAssociationObject]

submission_idattributeinstance attribute#

submission_id: UUID

SubmissionAssociationObjectclass#

class SubmissionAssociationObject(BaseModel)

Bases: BaseModel

DTO representing an object within a submission association.

Attributes

NameTypeDescription
idUUIDUnique identifier for the association object.
roleOptional[AssociationRole]

Role of this object in the association.

  • “source”: object initiating the association
  • “target”: object receiving the association
  • None: neutral, undirected membership (no orientation)
objectMadbotMetadataObject or SubmissionData or MetadataObject

The actual object participating in the association. Can be either:

  • a metadata object (incoming MadbotMetadataObject or outgoing MetadataObject)
  • a data object (SubmissionData)

idattributeinstance attribute#

id: UUID

objectattributeinstance attribute#

object: Union[MadbotMetadataObject, SubmissionData, MetadataObject]

roleattributeclass attributeinstance attribute#

role: AssociationRole | None = None

SubmissionDataclass#

class SubmissionData(BaseModel)

Bases: BaseModel

DTO for a data object included in a submission, provided by madbot core.

Attributes

NameTypeDescription
filenamestrFile name as stored in madbot.
sizeintFile size in bytes.
madbot_idUUIDIdentifier of the submission-data row (not the Data object).
data_madbot_idUUIDIdentifier of the Data object.
parent_node(SourceNode, optional)Node the data is linked to.
path(str, optional)Local path of the file, if already downloaded.
md5_hash(str, optional)MD5 checksum of the file.
file_type(str, optional)File type / extension.
metadatalist[MadbotMetadata]Metadata attached to this data object.
data_associationslist[SourceAssociationData]Associations this data object belongs to.
bound_sampleslist[dict]Samples bound to this data. Each dict has id (UUID string), title (str), and alias (str or None).

bound_samplesattributeclass attributeinstance attribute#

bound_samples: list[dict] = []

data_associationsattributeclass attributeinstance attribute#

data_associations: list[SourceAssociationData] = []

data_madbot_idattributeclass attributeinstance attribute#

data_madbot_id: UUID = Field(default_factory=uuid4)

file_typeattributeclass attributeinstance attribute#

file_type: str | None = None

filenameattributeinstance attribute#

filename: str

madbot_idattributeclass attributeinstance attribute#

madbot_id: UUID = Field(default_factory=uuid4)

md5_hashattributeclass attributeinstance attribute#

md5_hash: str | None = None

metadataattributeclass attributeinstance attribute#

metadata: list[MadbotMetadata] = []

parent_nodeattributeclass attributeinstance attribute#

parent_node: SourceNode | None = None

pathattributeclass attributeinstance attribute#

path: str | None = None

sizeattributeinstance attribute#

size: int

find_last_common_ancestormethodstaticmethod#

def find_last_common_ancestor(data_objects: list[SubmissionData]) -> list[SourceNode] | None

Find the last common ancestor of multiple data objects.

Parameters

NameTypeDescription
data_objectsList[SubmissionData]List of Data objects to find common ancestor for

Returns

Optional[List[SourceNode]]
The last common ancestor nodes, or None if no common ancestor exists

SubmissionMemberclass#

class SubmissionMember(BaseModel)

Bases: BaseModel

DTO for a submission member.

first_nameattributeinstance attribute#

first_name: str

last_nameattributeinstance attribute#

last_name: str

orcid_uriattributeclass attributeinstance attribute#

orcid_uri: str | None = None

roleattributeinstance attribute#

role: str

SubmissionMetadataValueclass#

class SubmissionMetadataValue(MetadataValue)

Bases: MetadataValue

DTO for a metadata value on a submission.

Inherits from MetadataValue and adds a list of source submission data IDs. This allows tracking which submission data objects are associated with each metadata value, enabling easier management (such as removal) of metadata values when related submission data objects are deleted.

Attributes

NameTypeDescription
sources_submission_datalist[UUID]Submission-data UUIDs this value was derived from. Used by madbot core to drop the value when those data objects are removed.

sources_submission_dataattributeclass attributeinstance attribute#

sources_submission_data: list[UUID] = Field(default_factory=list)

add_source_for_allmethodclassmethod#

def add_source_for_all(metadata_values: list[SubmissionMetadataValue], source_id: UUID) -> list[SubmissionMetadataValue]

Add the same submission data ID to all submission metadata values in the list.

Parameters

NameTypeDescription
metadata_valuesList[SubmissionMetadataValue]The list of SubmissionMetadataValue instances.
source_idUUIDThe source ID to add.

Returns

List[SubmissionMetadataValue]
The list of updated SubmissionMetadataValue instances.

add_sources_submission_datamethod#

def add_sources_submission_data(submission_data_ids: UUID | list[UUID]) -> None

Add one or more source submission data IDs to the metadata value.

Parameters

NameTypeDescription
submission_data_idsUUID or List[UUID]The ID(s) of the submission data to add as sources.

create_from_metadata_valuemethodclassmethod#

def create_from_metadata_value(metadata_value: MetadataValue) -> SubmissionMetadataValue

Create a SubmissionMetadataValue from a MetadataValue.

Parameters

NameTypeDescription
metadata_valueMetadataValueThe MetadataValue to convert.

Returns

SubmissionMetadataValue
The converted SubmissionMetadataValue instance.
Inherited from plugins_api.dtos.MetadataValue

source_idattributeclass attributeinstance attribute#

source_id: UUID | None = None

valueattributeclass attributeinstance attribute#

value: Any | None = None