plugins_api.metadata_plugins
Metadata-related plugin classes.
This module contains classes for metadata field definition and mapping.
Classes
| Name | Description |
|---|---|
MetadataFieldDefinitionPlugin | Abstract class defining the minimum API for a MetadataFieldDefinition plugin. |
MetadataFieldDefinitionPluginWithStandardMapping | Abstract class defining the minimum API for a MetadataFieldDefinition plugin, while implementing a standard mapping system. |
StandardMetadataMapper | Class representing bidirectional mapping between plugin fields and madbot fields. |
MetadataFieldDefinitionPluginclass#
class MetadataFieldDefinitionPlugin(MadbotPlugin)Bases: MadbotPlugin
Abstract class defining the minimum API for a MetadataFieldDefinition plugin.
Metadata field definition plugins are interfaces used to import metadata fields from external sources. They provide a consistent way to fetch, parse and integrate metadata specifications from various standards bodies, repositories, or other external systems into the madbot metadata fields referential. For this purpose, they define the metadata fields, mappings between these fields and the metadata fields of the madbot referential. Finally, they provide methods to convert values from the plugin referential to the madbot referential and vice versa.
convert_madbot_to_pluginmethodabstractclassmethod#
def convert_madbot_to_plugin(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]Transform the values from the madbot referential to the plugin referential.
Parameters
Examples
Convert a full name from madbot to plugin format
>>> print(self.convert_madbot_to_plugin({"full_name": "John Doe"})){"first_name": "John", "last_name": "Doe"}convert_plugin_to_madbotmethodabstractclassmethod#
def convert_plugin_to_madbot(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]Transform the values from the plugin referential to the madbot referential.
Parameters
Examples
Convert a full name from plugin to madbot format
>>> print(self.convert_plugin_to_madbot({"first_name": "John", "last_name": "Doe"})){"full_name": "John Doe"}get_all_mappingsmethodabstractclassmethod#
def get_all_mappings(mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]Get all mappings for the plugin, optionally filtered.
Returns
List[MetadataFieldMapping]- List of all field mappings between both referential, optionally filtered.
get_all_metadata_object_typesmethodabstractclassmethod#
def get_all_metadata_object_types() -> dict[str, MetadataObjectType]Return a dictionary of metadata object types supported by the plugin.
Returns
Dict[str, MetadataObjectType]- Dictionary of metadata object types supported by the plugin, keyed by type slug.
get_contextual_metadata_object_typesmethodabstract#
def get_contextual_metadata_object_types() -> dict[str, MetadataObjectType]Return a filtered dictionary of metadata object types supported by the plugin.
The filter is applied based on the context of the plugin. For example, for the ENA plugin, the values returned for the contextual metadata object types include the sample metadata object type of the selected checklist.
Returns
dict[str, MetadataObjectType]- Dictionary of metadata object types supported by the plugin, filtered by the context of the plugin (e.g. the selected checklist).
get_madbot_field_mappingmethodabstractclassmethod#
def get_madbot_field_mapping(madbot_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]Get the mapping information for a specific field in the madbot referential.
Parameters
Returns
List[MetadataFieldMapping]- List of mapping information for the specified field.
get_metadata_fields_groupsmethodabstractclassmethod#
def get_metadata_fields_groups(parent: str | None = None) -> list[MetadataGroupNodeDTO]Return metadata groups for UI navigation.
Complementary to get_all_metadata_object_types(): MOT methods define
what each object type contains; this method only organizes those fields
for browsing. See MetadataGroupNodeDTO for the full contract.
Returns
list[MetadataGroupNodeDTO]- Metadata group nodes.
Examples
One MOT with subgroups (parent=None):
>>> cls.get_metadata_fields_groups(parent=None)[ MetadataGroupNodeDTO( slug="general", name="General", description="General metadata object", 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__identifier", "plugin__type"], children=[], ) ], ),]Expanding that MOT:
>>> cls.get_metadata_fields_groups(parent="general")[ MetadataGroupNodeDTO( slug="core_identification", name="Core identification", description="Essential identifying information", type="subgroup", has_groups=False, fields=["plugin__identifier", "plugin__type"], children=[], )]get_plugin_field_mappingmethodabstractclassmethod#
def get_plugin_field_mapping(plugin_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]Get the mapping information for a specific field in the plugin referential.
Parameters
Returns
List[MetadataFieldMapping]- List of mapping information for the specified field.
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.
MetadataFieldDefinitionPluginWithStandardMappingclass#
class MetadataFieldDefinitionPluginWithStandardMapping(MetadataFieldDefinitionPlugin)Bases: MetadataFieldDefinitionPlugin
Abstract class defining the minimum API for a MetadataFieldDefinition plugin, while implementing a standard mapping system.
Metadata field definition plugins are interfaces used to import metadata fields from external sources. They provide a consistent way to fetch, parse and integrate metadata specifications from various standards bodies, repositories, or other external systems into the Madbot metadata fields referential.
This class implements a standard mapping system, which allows to define a mapping between the metadata fields of the plugin and the metadata fields of the Madbot referential.
The mapping is defined by the user, by calling the set_mapper method or setting the
mapper attribute.
mapperattributeclass attributeinstance attribute#
mapper: StandardMetadataMapper | None = Noneconvert_madbot_to_pluginmethodclassmethod#
def convert_madbot_to_plugin(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]Transform the values from the madbot referential to the plugin referential.
This method delegates to the mapper if one is set, otherwise raises NotImplementedError.
Parameters
Raises
NotImplementedError- If no mapper is set.
Examples
Convert a full name from madbot to plugin format
>>> print(self.convert_madbot_to_plugin({"full_name": "John Doe"})){"first_name": "John", "last_name": "Doe"}Convert multiple fields
>>> print(self.convert_madbot_to_plugin({"title": "Hello World", "description": "A test"})){"name": "HELLO WORLD", "desc": "A test"}Convert with specific checklist filter
>>> print(self.convert_madbot_to_plugin({"name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"})){"sample_name": "Sample123"}convert_plugin_to_madbotmethodclassmethod#
def convert_plugin_to_madbot(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]Transform the values from the plugin referential to the madbot referential.
This method delegates to the mapper if one is set, otherwise raises NotImplementedError.
Parameters
Raises
NotImplementedError- If no mapper is set.
Examples
Convert a full name from plugin to madbot format
>>> print(self.convert_plugin_to_madbot({"first_name": "John", "last_name": "Doe"})){"full_name": "John Doe"}Convert multiple fields
>>> print(self.convert_plugin_to_madbot({"name": "Hello World", "desc": "A test"})){"title": "HELLO WORLD", "description": "A test"}Convert with specific checklist filter
>>> print(self.convert_plugin_to_madbot({"sample_name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"})){"name": "Sample123"}get_all_mappingsmethodclassmethod#
def get_all_mappings(mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]Get all mappings for the plugin, optionally filtered.
This method delegates to the mapper if one is set, otherwise raises NotImplementedError.
Parameters
Returns
List[MetadataFieldMapping]- List of all field mappings between both referential, optionally filtered.
Raises
NotImplementedError- If no mapper is set.
get_madbot_field_mappingmethodclassmethod#
def get_madbot_field_mapping(madbot_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]Get the mapping information for a specific field in the madbot referential.
Parameters
Returns
List[MetadataFieldMapping]- List of mapping information for the specified field.
Raises
NotImplementedError- If no mapper is set.
get_plugin_field_mappingmethodclassmethod#
def get_plugin_field_mapping(plugin_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]Get the mapping information for a specific field in the plugin referential.
Parameters
Returns
List[MetadataFieldMapping]- List of mapping information for the specified field.
Raises
NotImplementedError- If no mapper is set.
set_mappermethodclassmethod#
def set_mapper(mapper: StandardMetadataMapper) -> NoneSet the mapper for this plugin class.
This method sets the mapper that will be used by all instances of this class.
Parameters
| Name | Type | Description |
|---|---|---|
mapper | StandardMetadataMapper | The mapper to use for field transformations. |
Inherited from plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin
get_all_metadata_object_typesmethodabstractclassmethod#
def get_all_metadata_object_types() -> dict[str, MetadataObjectType]Return a dictionary of metadata object types supported by the plugin.
Returns
Dict[str, MetadataObjectType]- Dictionary of metadata object types supported by the plugin, keyed by type slug.
get_contextual_metadata_object_typesmethodabstract#
def get_contextual_metadata_object_types() -> dict[str, MetadataObjectType]Return a filtered dictionary of metadata object types supported by the plugin.
The filter is applied based on the context of the plugin. For example, for the ENA plugin, the values returned for the contextual metadata object types include the sample metadata object type of the selected checklist.
Returns
dict[str, MetadataObjectType]- Dictionary of metadata object types supported by the plugin, filtered by the context of the plugin (e.g. the selected checklist).
get_metadata_fields_groupsmethodabstractclassmethod#
def get_metadata_fields_groups(parent: str | None = None) -> list[MetadataGroupNodeDTO]Return metadata groups for UI navigation.
Complementary to get_all_metadata_object_types(): MOT methods define
what each object type contains; this method only organizes those fields
for browsing. See MetadataGroupNodeDTO for the full contract.
Returns
list[MetadataGroupNodeDTO]- Metadata group nodes.
Examples
One MOT with subgroups (parent=None):
>>> cls.get_metadata_fields_groups(parent=None)[ MetadataGroupNodeDTO( slug="general", name="General", description="General metadata object", 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__identifier", "plugin__type"], children=[], ) ], ),]Expanding that MOT:
>>> cls.get_metadata_fields_groups(parent="general")[ MetadataGroupNodeDTO( slug="core_identification", name="Core identification", description="Essential identifying information", type="subgroup", has_groups=False, fields=["plugin__identifier", "plugin__type"], children=[], )]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.
StandardMetadataMapperclass#
class StandardMetadataMapper()Class representing bidirectional mapping between plugin fields and madbot fields.
This class manages the mapping and transformation of fields between a plugin’s referential and the madbot referential. It follows RDF-like concepts where:
- Plugin fields are considered “subjects” in plugin->madbot direction
- Madbot fields are considered “objects” in plugin->madbot direction
- The transformation functions act as “predicates” defining the relationship
This class definition can be enhanced to support the specification of SSSOM mappings. For more information on SSSOM, see https://mapping-commons.github.io/sssom/
Attributes
| Name | Type | Description |
|---|---|---|
_plugin_to_madbot | Dict[str, List[MetadataFieldMapping]] | Internal dictionary mapping plugin fields to lists of MetadataFieldMapping instances |
_madbot_to_plugin | Dict[str, List[MetadataFieldMapping]] | Internal dictionary mapping madbot fields to lists of MetadataFieldMapping instances |
Examples
Create a new StandardMetadataMapper instance
>>> mapper = StandardMetadataMapper()Simple one-to-one mapping
>>> mapper.add_mapping(... plugin_fields="title",... madbot_fields="name",... transform_plugin_to_madbot=lambda x: {"name": x["title"].upper()},... transform_madbot_to_plugin=lambda x: {"title": x["name"].lower()}... )Many-to-one mapping
>>> mapper.add_mapping(... plugin_fields=["first_name", "last_name"],... madbot_fields="full_name",... transform_plugin_to_madbot=lambda x: {... "full_name": f"{x['first_name']} {x['last_name']}"... },... transform_madbot_to_plugin=lambda x: {... "first_name": x["full_name"].split()[0],... "last_name": x["full_name"].split()[1]... }... )Multiple mapping rules for the same field (e.g., different ENA checklists)
>>> mapper.add_mapping(... plugin_fields="sample_name",... madbot_fields="name",... transform_plugin_to_madbot=lambda x: {"name": x["sample_name"]},... transform_madbot_to_plugin=lambda x: {"sample_name": x["name"]},... mapping_id="erc000010" # Specific checklist... )>>> mapper.add_mapping(... plugin_fields="sample_name",... madbot_fields="name",... transform_plugin_to_madbot=lambda x: {"name": f"ENA_{x['sample_name']}"},... transform_madbot_to_plugin=lambda x: {"sample_name": x["name"].replace("ENA_", "")},... mapping_id="erc000028" # Different checklist... )Convert plugin to madbot with filtering
>>> print(mapper.convert_plugin_to_madbot({"title": "Hello World"}, mapping_filter={"mapping_id": "erc000010"})){"name": "HELLO WORLD"}Convert madbot to plugin with filtering
>>> print(mapper.convert_madbot_to_plugin({"name": "HELLO WORLD"}, mapping_filter={"mapping_id": "erc000010"})){"title": "hello world"}>>> print(mapper.get_plugin_field_mapping(plugin_field="first_name", mapping_filter={"mapping_id": "erc000010"}))MetadataFieldMapping( plugin_fields=["first_name", "last_name"], madbot_fields=["full_name"], transform_madbot_to_plugin=<function>, transform_plugin_to_madbot=<function>,)add_mappingmethod#
def add_mapping(plugin_fields: str | list[str], madbot_fields: str | list[str], transform_plugin_to_madbot: Callable[[dict[str, Any]], dict[str, Any]] = lambda x: x, transform_madbot_to_plugin: Callable[[dict[str, Any]], dict[str, Any]] = lambda x: x, mapping_id: str | None = None, **kwargs) -> NoneAdd a bidirectional mapping between plugin and madbot fields.
This method creates a new MetadataFieldMapping instance and stores it in both the plugin->madbot and madbot->plugin mapping dictionaries. Multiple mappings can be added for the same field, distinguished by the mapping_id and additional kwargs.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
plugin_fields | Union[str, List[str]] | required | Plugin field slug, or list of slugs. |
madbot_fields | Union[str, List[str]] | required | Madbot field slug, or list of slugs. |
transform_plugin_to_madbot | Callable | lambda x: x | Function to transform values from plugin to madbot format. Should accept a dict of plugin field values and return a dict of madbot field values. By default, returns the input unchanged. |
transform_madbot_to_plugin | Callable | lambda x: x | Function to transform values from madbot to plugin format. Should accept a dict of madbot field values and return a dict of plugin field values. By default, returns the input unchanged. |
mapping_id | Optional[str] | None | Unique identifier for this mapping rule. Useful for distinguishing between multiple mappings for the same field (e.g., different checklists). |
**kwargs | Any | {} | Additional metadata for the mapping (e.g., checklist, version, etc.) |
convert_madbot_to_pluginmethod#
def convert_madbot_to_plugin(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]Convert values from madbot referential to plugin referential.
This method handles the conversion of one or more fields from the madbot referential to the plugin referential. The input values should be a dictionary where keys are madbot field slugs and values are the corresponding values to convert.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
values | Dict[str, Any] | required | Dictionary of madbot field slugs to their values. All fields must belong to the same mapping group (e.g., if converting a full name, both first_name and last_name must be provided). |
mapping_filter | Optional[Dict[str, Any]] | None | Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping. |
Raises
ValueError- If the fields don’t belong to the same mapping group or if any field is not found.
Examples
Convert a full name from madbot to plugin format
>>> print(mapper.convert_madbot_to_plugin({"full_name": "John Doe"})){"first_name": "John", "last_name": "Doe"}Convert multiple fields
>>> print(mapper.convert_madbot_to_plugin({"title": "Hello World", "description": "A test"})){"name": "HELLO WORLD", "desc": "A test"}Convert with specific checklist filter
>>> print(mapper.convert_madbot_to_plugin({"name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"})){"sample_name": "Sample123"}convert_plugin_to_madbotmethod#
def convert_plugin_to_madbot(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]Convert values from plugin referential to madbot referential.
This method handles the conversion of one or more fields from the plugin referential to the madbot referential. The input values should be a dictionary where keys are plugin field slugs and values are the corresponding values to convert.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
values | Dict[str, Any] | required | Dictionary of plugin field slugs to their values. All fields must belong to the same mapping group (e.g., if converting a full name, both first_name and last_name must be provided). |
mapping_filter | Optional[Dict[str, Any]] | None | Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping. |
Raises
ValueError- If the fields don’t belong to the same mapping group or if any field is not found.
Examples
Convert a full name from plugin to madbot format
>>> print(mapper.convert_plugin_to_madbot({"first_name": "John", "last_name": "Doe"})){"full_name": "John Doe"}Convert multiple fields
>>> print(mapper.convert_plugin_to_madbot({"name": "Hello World", "desc": "A test"})){"title": "HELLO WORLD", "description": "A test"}Convert with specific checklist filter
>>> print(mapper.convert_plugin_to_madbot({"sample_name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"})){"name": "Sample123"}get_all_mappingsmethod#
def get_all_mappings(mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]Get all mappings for the plugin, optionally filtered.
Parameters
Returns
List[MetadataFieldMapping]- List of all field mappings between both referential, optionally filtered.
get_madbot_field_mappingmethod#
def get_madbot_field_mapping(madbot_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]Get the mapping information for a specific field in the madbot referential.
Parameters
Returns
List[MetadataFieldMapping]- List of mapping information for the specified field.
get_plugin_field_mappingmethod#
def get_plugin_field_mapping(plugin_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]Get the mapping information for a specific field in the plugin referential.
Parameters
Returns
List[MetadataFieldMapping]: List of mapping information for the specified field.

