This is the full developer documentation for madbot
# madbot documentation
> Organise a research project, link its data where they are stored, describe them and submit them to repositories.
[Use madbot](/use/concepts/)Workspaces, nodes, data, samples, metadata and submissions: the concepts of madbot.
[Run an instance](/run/reference/commands/)The management commands of a madbot instance.
[Automate with the API](/api/getting-started/)Drive madbot from your scripts and tools through its REST API.
[Extend madbot](/extend/plugins/development-guide/)Connect a new data source or repository with a plugin.
[Contribute](/contribute/)Report a problem, suggest an idea, or change the code.
## What madbot is
[Section titled “What madbot is”](#what-madbot-is)
madbot (Metadata And Data Brokering Online Tool) helps research teams manage their data and metadata. It does not store the data: it links them where they already are, a computing cluster, a storage server, an analysis platform, a repository, through plugins. Around these links, a team organises its project, describes its data with metadata, and submits them to public repositories such as ENA, Zenodo or Recherche Data Gouv.
To discover madbot in a guided session, follow the [madbot training](https://ifb-elixirfr.gitlab.io/madbot/madbot-training/). To learn about the project, visit the [madbot website](https://madbot.france-bioinformatique.fr/).
# Get started with the REST API
> Authenticate with a personal access token, choose a workspace, try the endpoints in Swagger UI, read paginated lists and errors, then run a first script against madbot.
Every madbot instance serves a REST API. The web client uses it, and so can your scripts. The [reference](/api/reference/) describes each endpoint for the latest release of `madbot-api`. This page explains what all the endpoints have in common, then runs a first script.
Tip
The reference does not call an API. To try an endpoint, use the Swagger UI of an instance: see [Try the endpoints in Swagger UI](#try-the-endpoints-in-swagger-ui).
## Authenticate with a personal access token
[Section titled “Authenticate with a personal access token”](#authenticate-with-a-personal-access-token)
A script authenticates with a personal access token, created in the web client:
1. Open the user menu, then **Account settings**, then **Tokens**.
2. Select **Create a new token**, name it and choose its scopes:
* `read`: read the resources;
* `write`: create, change and delete them;
* `*`: full access, alone.
3. Copy the token. It starts with `pat_`, and the web client shows it only once.
Send it in the `Authorization` header of each request:
```http
Authorization: Bearer pat_…
```
The account of the token must be approved by an administrator of the instance. Tokens are managed in the web client only: the API does not create a token from another token.
## Name the workspace
[Section titled “Name the workspace”](#name-the-workspace)
Many endpoints work inside one workspace: nodes and their samples, data, connections, submissions and tasks. Name it in the `X-Workspace` header, with its identifier:
```http
X-Workspace: 143fbb1c-a639-4c33-8c41-2c1c02d7b8c2
```
The reference lists the header among the parameters of each endpoint that needs it. [`GET /api/workspaces`](/api/reference/operations/workspaces_list/) lists the workspaces of the account, with their identifiers.
## Try the endpoints in Swagger UI
[Section titled “Try the endpoints in Swagger UI”](#try-the-endpoints-in-swagger-ui)
Every instance serves an interactive reference of its API, for the version it runs, and its OpenAPI schema:
| What | Path on the API of the instance |
| ------------------------------------------------------------------- | ------------------------------- |
| Interactive reference (Swagger UI), where you can try the endpoints | `/api/schema/swagger-ui/` |
| OpenAPI schema, to generate a client or import it into a tool | `/api/schema/` |
For example, on the national instance run by the French Institute of Bioinformatics: [api.madbot.france-bioinformatique.fr/api/schema/swagger-ui/](https://api.madbot.france-bioinformatique.fr/api/schema/swagger-ui/). On a local instance: .
To call an endpoint from Swagger UI:
1. Create a personal access token (see above), and copy it with **Copy token (with Bearer)**.
2. Select **Authorize**. In the `ApiKeyAuth` box, paste the token in **Value**, as `Bearer pat_…`, then select **Authorize** and **Close**.
3. Open an endpoint, select **Try it out**, fill in its parameters, `X-Workspace` among them when it needs one, then select **Execute**.
Caution
Swagger UI calls the instance for real: a `POST`, `PUT`, `PATCH` or `DELETE` changes its data. Try them on a local instance, or in a workspace made for the purpose.
## Read a list, page by page
[Section titled “Read a list, page by page”](#read-a-list-page-by-page)
An endpoint that lists resources returns them page by page:
| Query parameter | Meaning |
| --------------- | ----------------------------------------------------------- |
| `p` | The page, from 1. |
| `page_size` | The number of results per page: 10 by default, 500 at most. |
The response gives the results of the page and where to go next (here with the results shortened):
```json
{
"count": 2,
"next": "http://localhost:8000/api/workspaces?p=2&page_size=1",
"previous": null,
"results": [{ "id": "143fbb1c-a639-4c33-8c41-2c1c02d7b8c2", "name": "Coastal erosion survey" }],
"current_page": 1,
"total_pages": 2
}
```
To read the whole list, follow `next` until it is `null`. Many lists also take `search` and `ordering`: the reference gives the parameters of each one.
## Read an error
[Section titled “Read an error”](#read-an-error)
An error comes with an HTTP status and a body of the same shape:
```json
{
"code": "header_validation_error",
"message": "Invalid header. Check the `details` property for more details.",
"details": [{ "parameter": "x-workspace", "code": "required", "message": "This field is required." }]
}
```
* `code` names the kind of error, for a script to test.
* `message` describes it for a person.
* `details` lists the causes: the parameter at fault when there is one, a code and a message.
| Status | `code` | When |
| ------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 400 | `body_validation_error`, `query_validation_error`, `header_validation_error` | The body, a query parameter or a header is missing or invalid. |
| 401 | `unauthorized` | The token is missing, invalid, expired or revoked. |
| 403 | `forbidden` | The token lacks the scope, the account is not approved, or it is not a member of the resource. |
| 404 | `object_not_found` | The resource does not exist. |
| 500 | `internal_server_error` | An unexpected error. `details` gives an identifier: send it to the administrators of the instance. |
## A first script
[Section titled “A first script”](#a-first-script)
This script creates a workspace and two nodes in it, reads them back one page at a time, and shows an error. It runs on a local instance (see [Set up a development environment](/contribute/development-setup/)), with `curl` and [`jq`](https://jqlang.org/).
Create a token with the `read` and `write` scopes in your local web client, then set the address of the API and the token:
```bash
export MADBOT_API=http://localhost:8000
export MADBOT_TOKEN=pat_…
```
Check that the API answers. This endpoint needs no token:
```bash
curl -s "$MADBOT_API/api/version"
```
```json
{"version":"2.1.0","plugins_api_version":"2.0.1"}
```
Create a workspace, and keep its identifier:
```bash
WORKSPACE=$(curl -s -X POST "$MADBOT_API/api/workspaces" \
-H "Authorization: Bearer $MADBOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Coastal erosion survey"}' | jq -r .id)
echo "$WORKSPACE"
```
Create two nodes in it:
```bash
for title in "Spring campaign" "Autumn campaign"; do
curl -s -X POST "$MADBOT_API/api/nodes" \
-H "Authorization: Bearer $MADBOT_TOKEN" \
-H "X-Workspace: $WORKSPACE" \
-H "Content-Type: application/json" \
-d "{\"title\": \"$title\"}" | jq -r '.id + " " + .title'
done
```
Read them back, one per page, from the first page until `next` is `null`:
```bash
page="$MADBOT_API/api/nodes?page_size=1"
while [ "$page" != "null" ]; do
response=$(curl -s "$page" \
-H "Authorization: Bearer $MADBOT_TOKEN" \
-H "X-Workspace: $WORKSPACE")
echo "$response" | jq -r '"page \(.current_page)/\(.total_pages): \(.results[0].title)"'
page=$(echo "$response" | jq -r .next)
done
```
```text
page 1/2: Spring campaign
page 2/2: Autumn campaign
```
Without the `X-Workspace` header, the API answers with an error:
```bash
curl -s "$MADBOT_API/api/nodes" -H "Authorization: Bearer $MADBOT_TOKEN" | jq
```
```json
{
"code": "header_validation_error",
"message": "Invalid header. Check the `details` property for more details.",
"details": [
{
"parameter": "x-workspace",
"code": "required",
"message": "This field is required."
}
]
}
```
The workspace and its nodes are in your local web client. Delete the workspace from there, or with `DELETE /api/workspaces/{id}`.
# Contribute to madbot
> Ask a question, report a bug, suggest an improvement or propose a change to madbot.
Thank you for taking the time to contribute. Every contribution is welcome: a question, a bug report, an idea, a fix in the documentation or in the code.
Everyone taking part in the project follows the [code of conduct](/contribute/code-of-conduct/).
## Ask a question
[Section titled “Ask a question”](#ask-a-question)
1. Search the [existing issues](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/issues): someone may have asked the same question. If an issue answers it only partly, ask in that issue.
2. Otherwise, [open an issue](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/issues/new) and give as much context as you can: what you were trying to do, what happened, and the versions involved (madbot, browser, operating system).
## Report a bug
[Section titled “Report a bug”](#report-a-bug)
Security issues
Never report a security problem, a vulnerability or a bug that exposes sensitive information in a public issue. Send it by email to .
A good bug report lets someone else reproduce the problem without asking you more questions. Before you write it:
* check that you use the latest version of madbot;
* check that the problem does not come from your own setup, such as an incompatible version of a dependency;
* search the [open bugs](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/issues/?state=opened\&label_name%5B%5D=bug) to see if it is already known;
* collect what describes the problem: the error message or traceback, your operating system and platform, the versions of the tools involved, the input and the output.
Then [open an issue](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/issues/new) with the **Bug** template:
* describe what you expected and what happened instead;
* list the steps that reproduce the problem, as short as possible;
* add the information you collected.
## Suggest an improvement
[Section titled “Suggest an improvement”](#suggest-an-improvement)
Before you suggest a new feature or a change to an existing one:
* check that you use the latest version of madbot, and that this documentation does not already cover it;
* search the [issues of the madbot group](https://gitlab.com/groups/ifb-elixirfr/madbot/-/issues): if someone already suggested it, add your use case in a comment;
* think about who would use it. madbot aims at features that serve most of its users; a connection to one specific system may fit better in a [plugin](/extend/plugins/development-guide/).
Then [open an issue](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/issues/new) with the **Suggestion** template:
* give it a clear and descriptive title;
* describe the improvement step by step;
* describe the current behaviour, the behaviour you expect instead, and why;
* add screenshots if they help;
* explain who would benefit from it.
## Propose a change
[Section titled “Propose a change”](#propose-a-change)
The code and this documentation live in the [madbot repository](https://gitlab.com/ifb-elixirfr/madbot/madbot).
1. [Set up a development environment](/contribute/development-setup/).
2. Create a branch and make your change, following the [branch and commit conventions](/contribute/branches-commits-releases/).
3. Run the [tests and quality checks](/contribute/tests-and-quality/), and add or update the tests of your change.
4. Update the documentation when your change is visible to users, people who run an instance, plugin developers or API users: see [Write documentation](/contribute/write-documentation/).
5. Open a merge request with a description that explains the context and the reason for the change.
### Use of AI
[Section titled “Use of AI”](#use-of-ai)
You may use an AI assistant to contribute, as the team does. The [AI policy](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/main/AI_POLICY.md) of the repository gives the rules; in short:
* you have read, understood and tested everything you submit, and you can explain it during the review;
* your merge request goes through the same tests, quality checks and review as any other, and a member of the team reviews and approves it: an AI review can help the reviewer, it never replaces them;
* your commits carry your own name and email: an AI assistant is never the author or the co-author of a commit;
* a commit made with the help of an AI assistant ends with an `Assisted-by: AI` line (see [Commit messages](/contribute/branches-commits-releases/#commit-messages)), and so does the description of a merge request that contains such commits;
* you never share secrets, personal data or the content of an instance with an AI tool, and you only use the tools your institution allows.
The [AGENTS.md](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/main/AGENTS.md) file at the root of the repository gives the same rules, the commit conventions and the checks to run to the AI assistant you work with.
### Legal notice
[Section titled “Legal notice”](#legal-notice)
By contributing, you confirm that you are the author of the content you submit and answer for all of it, including the parts written with the help of an AI assistant, that you have the rights to it, and that it can be distributed under the project licence.
# Architecture
> How the madbot API, web client, workers and plugins fit together, and where to make a change.
madbot is a web client that talks to a REST API. The API keeps its data in a database, delegates the long operations to Celery workers, pushes live events over WebSockets, and reaches the outside world through plugins.
```text
Browser
│
┌────────▼─────────┐
│ Web client │ Nuxt, Vue, Vuetify, Pinia
└────────┬─────────┘
│ REST (/api/), WebSocket (/ws/)
┌────────▼─────────┐ ┌───────────────┐
│ API │◀──────▶│ Redis │◀──┐
│ Django, DRF, │ └───────────────┘ │ tasks
│ Channels │ │
└──┬─────┬─────┬───┘ ┌───────────────┐ │
│ │ │ │ Celery worker │───┘
│ │ │ │ and beat │
│ │ │ └───────┬───────┘
│ │ └──── plugins ───────┤
│ │ (sources and repositories)
│ └── Vault (connection credentials)
└──── Database (SQLite in development, PostgreSQL in production)
```
## The repository
[Section titled “The repository”](#the-repository)
The repository holds three packages, released separately, and this documentation:
| Folder | What it holds |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| `api/` | The API, the Django project `madbot_api`. |
| `client/` | The web client, a Nuxt application. |
| `plugin_api/` | The `plugins_api` package: the contract that plugins implement, installed by the API as `plugins-api`. |
| `documentation/` | This site. |
## The API
[Section titled “The API”](#the-api)
The API is a Django application built on Django REST Framework. Its domain logic lives in the `madbot_api.core` app; analytics have their own app, `madbot_api.analytics`.
### From the request to the database
[Section titled “From the request to the database”](#from-the-request-to-the-database)
| Layer | Where | Role |
| ------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Routing | `madbot_api/urls.py`, `core/url_api.py` | Mounts the REST API under `api/`, OAuth under `o/`, the health checks; nested routers follow the resources (workspaces → members, nodes → samples, submissions → metadata objects…). |
| Views | `core/views/` | ViewSets and API views. Most derive from `MadbotViewSet` (`core/views/utils/drf.py`), which brings authentication, approval of the user, scopes, pagination and error format. |
| Access rules | `core/views/utils/mixin.py` | Resolve the workspace of the request and apply the workspace, node and submission memberships. |
| Models | `core/models.py` | The entities: see the [data models](/contribute/reference/data-models/). |
| Tasks | `core/tasks.py` | The Celery tasks. |
The client names the workspace of a request in the `X-Workspace` header.
### Authentication
[Section titled “Authentication”](#authentication)
| Mechanism | Used by |
| ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| OAuth 2 with OpenID Connect (`django-oauth-toolkit`, PKCE) | The web client. madbot signs its tokens with `MADBOT_OIDC_RSA_PRIVATE_KEY`. |
| Personal access tokens | Scripts and tools that call the API. |
| Sessions | The Django administration. |
The OAuth scopes are `read`, `write`, `openid`, `email` and `profile`. An account must be approved before it can use the API.
### Long operations and live events
[Section titled “Long operations and live events”](#long-operations-and-live-events)
The API hands the long operations to **Celery** workers, through Redis: creating the metadata objects of a submission, submitting, checking the connections and the access to data, copying a node and its subtree. **Celery Beat** runs the periodic tasks (see [`create_periodic_tasks`](/run/reference/commands/#create_periodic_tasks)).
While they run, the API pushes events to the client over WebSockets (Django Channels, served by Daphne):
| Path | Events |
| --------------------------------- | ----------------------------------------- |
| `ws/notifications/` | Notifications of the user. |
| `ws/workspaces//` | Events of a workspace: connections, data. |
| `ws/submissions//` | Progress of a submission. |
### Plugins
[Section titled “Plugins”](#plugins)
The API loads the plugins listed in `MADBOT_INSTALLED_PLUGINS` and adds their Django apps to `INSTALLED_APPS`. `plugins_api` defines the base classes they implement: data plugins, submission plugins and metadata field definition plugins. The connection and submission views call the plugin of the connection to browse a source, check credentials or send a submission. The credentials of the connections are kept in Vault, not in the database.
See the [plugin development guide](/extend/plugins/development-guide/).
## The web client
[Section titled “The web client”](#the-web-client)
The client is a Nuxt application, rendered in the browser only (`ssr: false`), written with Vue’s Composition API, Vuetify components and Pinia stores.
| Folder | Role |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `pages/` | Routes, by file. The workspace pages are under `pages/[w]/[wslug]/`. |
| `components/` | Components, by domain: `Workspace/`, `Node/`, `Connection/`, `DataObject/`, `Sample/`, `Submission/`, `Metadata/`… |
| `stores/` | One Pinia store per domain: workspaces, nodes, connections, samples, metadata, submissions, notifications, WebSockets. |
| `composables/` | Shared logic, including the calls to the API and the WebSockets. |
| `server/` | Server routes, for the authentication. |
| `locales/` | The interface texts, in English and French. |
* **Calls to the API** go through `useAPIFetch`, which adds the access token of the session and sends the user to a waiting page when the API does not answer.
* **Authentication** uses `@sidebase/nuxt-auth`: the client signs in with the OpenID Connect provider of the API.
* **Metadata forms** are generated from the JSON schemas of the fields with [JSON Forms](https://jsonforms.io/), and madbot’s own renderers in `components/JsonFormRenderers/`.
* **WebSockets** are opened by `MadbotWebSocket`, managed per workspace by `useWebsocketStore`.
## Where to make a change
[Section titled “Where to make a change”](#where-to-make-a-change)
| Change | Where |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A model | `api/madbot_api/core/models.py`, then `pixi run madbot makemigrations core`. Use a UUID primary key, the audit fields and, where history matters, `HistoricalRecords`. |
| An endpoint | A view in `core/views/`, its route in `core/url_api.py`, following the existing filtering, pagination and permissions. |
| A long operation | A task in `core/tasks.py`. |
| A screen | A page in `client/pages/`, components in `client/components/`, the state in a store. |
| An interface text | `client/locales/en.json` and `fr.json`. |
| A connection to another system | A [plugin](/extend/plugins/development-guide/), in its own repository. |
Write the tests with the change: see [Tests and quality checks](/contribute/tests-and-quality/).
# Branches, commits and releases
> Which branch to start from, how to write a commit message, and how madbot is released.
## Branches
[Section titled “Branches”](#branches)
The repository has two long-lived branches:
* **`dev`**, the default branch: the next release is prepared there. New features and most fixes go to `dev`.
* **`main`**: what is released. The packages and the Docker images are published from `main`, and so is this documentation.
| Your change | Start from | Merge request to |
| --------------------------------------------------- | ------------------------------ | --------------------------------------------- |
| A feature, a fix that can wait for the next release | `dev` | `dev` |
| A fix that cannot wait (hotfix) | `main` | `main`, then `main` is merged back into `dev` |
| Documentation of what is already released | `main` | `main`, then `main` is merged back into `dev` |
| Documentation of a feature that is not released yet | `dev`, in the feature’s branch | `dev`, with the feature |
[Write documentation](/contribute/write-documentation/) explains why a documentation change can start from `main`.
Name your branch after the merge request, in lowercase words separated by hyphens: `workspace-report-pdf`, or `fix-…` for a bug fix: `fix-datalink-created-by`.
Before you open the merge request, update your branch with its target branch, and write a description that gives the context and the reason for the change.
## Commit messages
[Section titled “Commit messages”](#commit-messages)
Commit messages follow [gitmoji](https://gitmoji.dev/) with a scope, then a short subject in the imperative:
```text
()
```
For example:
```text
✨(client) download a dated report of the workspace as a PDF
🐛(api) set the creator of a datalink created through the API
📝(doc) describe the management commands
```
* **Scope**: the part of the project concerned, for example `api`, `client`, `app` (API and client together), `ci`, `deploy`, `dependencies`, `doc`. Leave it out, with its parentheses, when the change concerns the whole project.
* **Subject**: in the imperative and the present tense: “add”, not “added” nor “adds”.
* **Body**: why the change is needed, and what it changes compared with the previous behaviour.
* **Footer**: the issues closed by the change, one per line, for example `Closes #234`, and the `Assisted-by: AI` line when an AI assistant helped you.
A commit made with the help of an AI assistant ends with this line, written exactly this way, after a blank line, so that git reads it as a trailer:
```text
✨(client) group and filter the metadata of an object by source
The metadata tab lists every field in one flat list, whatever madbot or plugin
it comes from. Two buttons next to the search now group and filter the fields
by source.
Assisted-by: AI
```
`git commit --trailer "Assisted-by: AI"` adds it for you, and `git log --grep="^Assisted-by: AI$"` lists the assisted commits. The author and the committer stay the person who made the commit, with their own name and email. Since merge requests are merged with squash, the description of a merge request that contains assisted commits ends with the same line. The [AI policy](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/main/AI_POLICY.md) gives the rules.
## Releases
[Section titled “Releases”](#releases)
The API (`api/`), the client (`client/`) and `plugins_api` (`plugin_api/`) are published separately, each with its own version and changelog. When commits reach `main`, [semantic-release](https://semantic-release.gitbook.io/) looks at the commits that touched each package since its last version, and the emoji of each commit decides the next version:
| Emoji | Release |
| ----------------------------------------------- | ------------------------- |
| 💥 breaking change | major (`2.0.0` → `3.0.0`) |
| ✨ new feature | minor (`2.0.0` → `2.1.0`) |
| 🐛 bug fix, 🚑 critical hotfix, 🔒 security fix | patch (`2.0.0` → `2.0.1`) |
| any other emoji | no new version |
For each new version, the CI then:
* updates the version and the changelog of the package, and commits them to `main`;
* publishes the package to the GitLab package registry;
* builds and pushes the Docker image of the API or of the client.
The `documentation/` folder is not a package: it has no version, and it is published on every merge into `main`.
# Code of conduct
> The code of conduct that everyone taking part in madbot follows.
Everyone taking part in the project follows this code of conduct. Report unacceptable behaviour to .
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others’ private information, such as a physical or email address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at . All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series of actions.
**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at .
Community Impact Guidelines were inspired by [Mozilla’s code of conduct enforcement ladder](https://github.com/mozilla/diversity).
For answers to common questions about this code of conduct, see the FAQ at . Translations are available at .
# Set up a development environment
> Run madbot from source on your machine, the API and the web client, to change its code.
This tutorial runs madbot from source on your machine: the API with its services (Vault, Redis, Celery), then the web client. At the end, you can sign in to your local madbot at .
Note
This page is for people who change madbot. To run madbot for its users, install a released version instead.
## Before you start
[Section titled “Before you start”](#before-you-start)
Install:
* [Git](https://git-scm.com/);
* [pixi](https://pixi.sh/), which installs Python and every dependency of the API;
* [Node.js](https://nodejs.org/) 22.23.4, the version required by the client, with [Corepack](https://nodejs.org/api/corepack.html), which provides the right version of [pnpm](https://pnpm.io/).
```bash
# macOS and Linux
curl -fsSL https://pixi.sh/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex"
```
Docker is only needed for the optional parts: [debugging emails with Mailhog](/contribute/performance-and-debugging/#debug-emails) and the [Docker Compose stack](/contribute/development-setup-docker/).
## Get the code
[Section titled “Get the code”](#get-the-code)
```bash
git clone https://gitlab.com/ifb-elixirfr/madbot/madbot.git
cd madbot
```
The repository holds the API (`api/`), the web client (`client/`), the `plugins_api` package (`plugin_api/`) and this documentation (`documentation/`).
## Set up the API
[Section titled “Set up the API”](#set-up-the-api)
### Install the dependencies
[Section titled “Install the dependencies”](#install-the-dependencies)
```bash
cd api
pixi install
pixi install -e dev
```
The `default` environment holds what madbot needs to run; the `dev` environment adds the test, lint and security tools. This also installs `plugins-api` from the package registry: you only need the `plugin_api/` folder to [change `plugins_api` itself](/extend/plugins/local-plugins-api/).
### Run commands with pixi
[Section titled “Run commands with pixi”](#run-commands-with-pixi)
Run a madbot command with `pixi run madbot `, from `api/`:
```bash
pixi run madbot migrate
```
Or open a shell in the environment and call `madbot` directly:
```bash
pixi shell -e dev
madbot migrate
```
The project also defines shortcuts such as `pixi run test` or `pixi run lint`: see [Tests and quality checks](/contribute/tests-and-quality/).
### Configure the API
[Section titled “Configure the API”](#configure-the-api)
Copy the example configuration:
```bash
cp .env.example .env
```
`.env.example` lists every setting with an example value and explains the syntax the file must follow. For a first run, fill in:
* `SECRET_KEY`: required, and the same for the API and the Celery workers. madbot refuses to start with an empty or placeholder value. Generate one:
```bash
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
```
* `MADBOT_OIDC_RSA_PRIVATE_KEY`: the private key with which madbot signs its OpenID Connect tokens, on a single line. Generate it and copy it:
```bash
openssl genrsa -out oidc.key 4096
# macOS
awk -v ORS='\\n' '1' oidc.key | pbcopy
# Linux
awk -v ORS='\\n' '1' oidc.key | xclip -selection clipboard
```
* `PUBLIC_BACKEND_DOMAIN`: the address of the API, as `host:port` without the scheme (default `localhost:8000`).
### Start Vault
[Section titled “Start Vault”](#start-vault)
madbot keeps the credentials of the connections in [Vault](https://developer.hashicorp.com/vault). In a new terminal, from `api/`:
```bash
pixi run vault
```
The script starts a local Vault and prints the settings madbot needs:
```bash
MADBOT_VAULT_URL=http://localhost:8200
MADBOT_VAULT_MOUNT_POINT=madbot
MADBOT_VAULT_ROLEID=
MADBOT_VAULT_SECRETID=
```
Copy them into `api/.env`. Keep the terminal open.
### Start Redis
[Section titled “Start Redis”](#start-redis)
Redis carries the Celery tasks and the WebSocket messages. In a new terminal, from `api/`:
```bash
pixi run redis
```
`pixi run redis` uses `REDIS_PORT` from `api/.env` (default 6379).
### Start Meilisearch (optional)
[Section titled “Start Meilisearch (optional)”](#start-meilisearch-optional)
The global workspace search is backed by [Meilisearch](https://www.meilisearch.com/). It is **off by default** (`SEARCH_ENABLED=false`): no indexing task is dispatched, `/api/search` answers 503 and the client hides its entry point. Skip this section unless you work on the search itself.
Meilisearch ships as a single binary (the `meilisearch` package on conda-forge is stale, so it is not a pixi dependency). In a new terminal, from `api/`, install it with the official script and start it:
```bash
curl -L https://install.meilisearch.com | sh
./meilisearch --master-key=""
```
Running from `api/` keeps the binary and the `data.ms/` data directory where `api/.gitignore` already ignores them.
By default it listens on . The master key is a secret you choose (Meilisearch recommends at least 16 bytes). Locally, reuse that same value as `MEILISEARCH_API_KEY`.
In `api/.env`:
```bash
SEARCH_ENABLED=true
MEILISEARCH_HOST=http://localhost:7700
MEILISEARCH_API_KEY=
```
Enabling the search also registers a Meilisearch check on `/health-check` as a **non-critical** service: an unreachable Meilisearch shows as degraded there without failing the endpoint.
You build the index once the database is created (see below). Day-to-day updates then go through Celery, so keep a worker running (`pixi run madbot celery`). Whenever you turn `SEARCH_ENABLED` back on later, run `pixi run madbot rebuild_search_index` again: nothing written while the search was off is indexed automatically.
To enable the search on a deployed instance, see [Enable the global search](/run/enable-global-search/).
### Create the database
[Section titled “Create the database”](#create-the-database)
Back in the first terminal, from `api/`:
```bash
pixi run madbot migrate
pixi run madbot collectstatic
pixi run madbot initialise_madbot_metadata_fields
pixi run madbot create_periodic_tasks
pixi run madbot reload_plugins
```
If you enabled the search, build its index:
```bash
pixi run madbot rebuild_search_index
```
The [management commands reference](/run/reference/commands/) explains each madbot command.
Create an administrator account. Adapt the username, email, password and names; the ROR identifier of the institution is optional here:
```bash
echo "from django.contrib.auth import get_user_model; User = get_user_model(); User.objects.create_superuser('admin', 'admin@example.org', '', id='9da4931b-e89e-48f1-988d-0aeb6a2ea1bd', first_name='Madbot', last_name='Admin', ror='https://ror.org/', is_approved=True)" | pixi run madbot shell
```
Register the web client as an OpenID Connect application of the API:
```bash
pixi run madbot createapplication --client-id=madbot --client-secret=madbot --name="madbot" --algorithm=RS256 --redirect-uris=http://localhost:3000/api/auth/callback/madbot --user="9da4931b-e89e-48f1-988d-0aeb6a2ea1bd" public authorization-code
```
If the client does not run on port 3000, adapt `--redirect-uris`, and `CORS_ALLOWED_ORIGINS` and `CSRF_TRUSTED_ORIGINS` in `api/.env`.
### Start the Celery workers
[Section titled “Start the Celery workers”](#start-the-celery-workers)
Celery runs the long tasks: submissions, copies, imports. In a new terminal, from `api/`:
```bash
pixi run madbot celery
```
When `DEBUG` is on, the worker restarts whenever the code changes. In another terminal, start the scheduler of the periodic tasks:
```bash
pixi run madbot beat
```
To follow the tasks in a web interface, start [Flower](https://flower.readthedocs.io/) and open :
```bash
pixi run celery --broker=redis://localhost flower --port=5555 --basic_auth=$CELERY_FLOWER_OPTIONS
```
### Start the API
[Section titled “Start the API”](#start-the-api)
```bash
pixi run runserver
```
The API answers at the address of `PUBLIC_BACKEND_DOMAIN`, by default. Its interactive reference is at .
## Install plugins
[Section titled “Install plugins”](#install-plugins)
madbot alone has no source to link data from: plugins bring them. List the plugins to use in `api/.env`:
```bash
MADBOT_INSTALLED_PLUGINS=madbot_sshfs,madbot_zenodo
```
Then install them, from `api/`:
```bash
pixi run install-plugins
```
The script has two modes:
* **editable** (default, or `-e`): it clones each plugin into `MADBOT_PLUGINS_DIR` (default `madbot-plugins`, a path relative to the folder that holds `madbot/`) and installs it with `pip install -e`. Your changes to the plugin code apply without reinstalling. When a plugin is already cloned, the script updates it with `git pull` if it is on `main` or `dev` without local changes, and leaves it as it is otherwise; `--no-update-check` skips this.
* **package** (`-p`, or `pixi run install-plugins-package`): it installs each plugin from its Git repository, as a regular package.
Add `-y` to skip the confirmation. Then reload the plugins and check what is installed:
```bash
pixi run madbot reload_plugins
pixi run list-plugins
```
The [plugins reference](/use/reference/plugins/) lists the available plugins.
To install a plugin by hand, install it in both environments:
```bash
pixi run -e default pip install -e /path/to/plugin
pixi run -e dev pip install -e /path/to/plugin
```
## Set up the client
[Section titled “Set up the client”](#set-up-the-client)
In a new terminal, from the root of the repository:
```bash
cd client
node -v
```
The client requires Node.js 22.23.4. Then install the dependencies, with the version of pnpm pinned by the project:
```bash
corepack enable
pnpm install
```
If the dependencies look corrupted, `pnpm clean` removes `node_modules`; run `pnpm install` again.
### Configure the client
[Section titled “Configure the client”](#configure-the-client)
```bash
cp .env.example .env
```
Generate `NUXT_SECRET`:
```bash
openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | head -c 32; echo
```
`AUTH_ORIGIN` and `NEXTAUTH_URL` are the full address of the authentication routes of the client, for example `http://localhost:3000/api/auth`. Keep them in line with `NITRO_PORT`: without `NEXTAUTH_URL`, the sign-in returns to port 3000.
### Start the client
[Section titled “Start the client”](#start-the-client)
```bash
pnpm dev
```
Open (or the port of `NITRO_PORT`) and sign in with the administrator account.
## When something does not start
[Section titled “When something does not start”](#when-something-does-not-start)
| Symptom | Check |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| The API refuses to start and mentions `SECRET_KEY` | `SECRET_KEY` is set in `api/.env`, and is not a placeholder. |
| Errors about Vault | The terminal of `pixi run vault` is still open, and its settings are in `api/.env`. |
| Errors about Redis, tasks that never run | Redis and the Celery worker are running. |
| The client stays on “Loading madbot…” | The API answers, and its migrations are applied: `pixi run madbot migrate`. |
| A plugin is missing | It is listed in `MADBOT_INSTALLED_PLUGINS`, installed, and `reload_plugins` ran after the installation. |
## Next steps
[Section titled “Next steps”](#next-steps)
* [Run the tests and the quality checks](/contribute/tests-and-quality/).
* [Profile the API and debug emails](/contribute/performance-and-debugging/).
* [Understand the architecture](/contribute/architecture/).
# Run the API with Docker Compose
> Run the madbot API in a development container, with live reload and the plugins mounted.
`api/docker-compose.dev.yml` runs the API in a container, with your code and your plugins mounted for live reload. Only the Django server runs in the container: Vault, Redis and the Celery workers keep running on your machine, as in the [development setup](/contribute/development-setup/), and the container reaches them through `host.docker.internal`.
## Before you start
[Section titled “Before you start”](#before-you-start)
* Docker, with Docker Compose.
* An `api/.env` file, created as described in [Configure the API](/contribute/development-setup/#configure-the-api).
* Vault and Redis running on your machine (`pixi run vault`, `pixi run redis`).
## Where the plugins come from
[Section titled “Where the plugins come from”](#where-the-plugins-come-from)
The build context is the folder that holds `madbot/`, so that the image can include your plugins. By default, it takes them from a `madbot-plugins/` folder next to `madbot/`:
```text
.
├── madbot/
│ ├── api/
│ └── client/
└── madbot-plugins/
├── madbot_ena_plugin/
└── …
```
To use another folder, set `MADBOT_PLUGINS_DIR` before you start the stack. The path is relative to the folder that holds `madbot/`:
```bash
export MADBOT_PLUGINS_DIR=my-plugins
```
## Start the API
[Section titled “Start the API”](#start-the-api)
From `api/`:
```bash
# First run, or after a change to the Dockerfile or the dependencies
docker compose -f docker-compose.dev.yml up --build
# Next runs
docker compose -f docker-compose.dev.yml up
```
The API answers on port 8000. Add `-d` to run the container in the background, then follow its logs:
```bash
docker compose -f docker-compose.dev.yml up -d
docker compose -f docker-compose.dev.yml logs -f
```
Stop and remove the container:
```bash
docker compose -f docker-compose.dev.yml down
```
## Start the Celery workers
[Section titled “Start the Celery workers”](#start-the-celery-workers)
The workers run on your machine. Point them to the Redis of your machine, then start them from `api/`:
```bash
export REDIS_HOST=localhost
export CELERY_BROKER_URL=redis://localhost:6379/0
export CELERY_RESULT_BACKEND=redis://localhost:6379/1
pixi run madbot celery
```
## Settings set by the stack
[Section titled “Settings set by the stack”](#settings-set-by-the-stack)
The Compose file sets these variables for the container, on top of `api/.env`:
| Variable | Value |
| ----------------------- | ------------------------------------- |
| `REDIS_HOST` | `host.docker.internal` |
| `DB_HOST` | `host.docker.internal` |
| `MADBOT_VAULT_URL` | `http://host.docker.internal:8200` |
| `CELERY_BROKER_URL` | `redis://host.docker.internal:6379/0` |
| `CELERY_RESULT_BACKEND` | `redis://host.docker.internal:6379/1` |
## Limit the resources
[Section titled “Limit the resources”](#limit-the-resources)
The container has no CPU, memory or disk limit, so that live reload and the mounted plugins work freely. To limit it on a small machine, uncomment the lines of `docker-compose.dev.yml`:
```yaml
mem_limit: 2g # at most 2 GB of memory
cpus: 1.5 # at most 1.5 CPU cores
```
```yaml
driver_opts:
type: tmpfs
device: tmpfs
o: size=5G # at most 5 GB for /app/data
```
## Troubleshooting
[Section titled “Troubleshooting”](#troubleshooting)
| Symptom | Check |
| ---------------------------- | --------------------------------------------------------------------------------- |
| The container does not start | Port 8000 is free. |
| Errors about Vault or Redis | They run on your machine, and `host.docker.internal` resolves from the container. |
| Missing settings | `api/.env` holds them, next to `docker-compose.dev.yml`. |
To look inside the container, run a shell in it:
```bash
docker compose -f docker-compose.dev.yml run --rm madbot /bin/bash
```
To free disk space, remove the unused containers, networks, images and build cache:
```bash
docker system prune -a --volumes
```
# Performance and debugging
> Profile the API with Silk, measure it on a large workspace, and read the emails madbot sends.
These tools help when you work on the speed of madbot, or on what it sends by email. They need the [development setup](/contribute/development-setup/).
## Profile the API with Silk
[Section titled “Profile the API with Silk”](#profile-the-api-with-silk)
[Django Silk](https://github.com/jazzband/django-silk) records each request with its time and its database queries. Enable it in `api/.env`:
```bash
SILKY_PYTHON_PROFILER=True
```
Then start the API in the `dev` environment, which holds Silk:
```bash
pixi run -e dev madbot runserver
```
Open to read the requests. Silk is always off while the tests run: it adds queries that the tests would count.
## Measure on a large workspace
[Section titled “Measure on a large workspace”](#measure-on-a-large-workspace)
`create_load_workspace` generates a large workspace — deep node trees, data, samples, metadata and members with heterogeneous rights — to measure the API and the client on a realistic volume, identical from one machine and one measure to the next.
```bash
cd api
pixi run madbot create_load_workspace --username --profile medium --seed 42
# Print the planned volumetry, write nothing
pixi run madbot create_load_workspace --username --profile large --dry-run
```
| Option | Role |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--username` | Owner of the workspace (required, must exist) |
| `--profile {small,medium,large}` | Predefined volumetry (default: `small`) |
| `--root-nodes`, `--depth`, `--node-per-node` | Shape of the tree: every non-leaf node has `--node-per-node` children |
| `--data-per-node`, `--samples-per-node` | Density of every node of the tree |
| `--metadata-per-object` | Size of each root tree’s field set: every node and sample of the tree gets all of its fields |
| `--metadata-per-data` | Metadata of each data: the first fields of its tree’s set |
| `--wide-nodes`, `--wide-node-size` | Extra nodes, under the roots, each with that many samples and data — to load the batch edit tables |
| `--plugin-fields [PLUGIN ...]` | Plugins whose metadata fields are used besides Madbot’s (default: `ena`); pass it without a value for Madbot fields only |
| `--members` | Members invited besides the owner |
| `--seed` | Seed of the generation; drawn and printed when omitted |
| `--name` | Workspace name (default: `Load seed `) |
| `--plugin` | Data plugin of the connection holding the data (default: the first installed one) |
| `--force` | Delete the owner’s workspace of the same name, then recreate it |
| `--dry-run` | Print the planned volumetry without writing anything |
Every volumetry option overrides the profile, one by one: to check a problem that only shows at 5,000 nodes, push `--root-nodes` or `--depth` instead of adding a profile.
| Profile | Nodes (wide) | Depth | Datalinks per node | Data | Samples | Metadata per node and sample | Metadata per data | Metadata | Members |
| -------- | ------------- | ----- | ------------------ | ------ | ------- | ---------------------------- | ----------------- | -------- | ------- |
| `small` | 21 (none) | 3 | 2 | 42 | 21 | 5 | 5 | 420 | 3 |
| `medium` | 106 (1 × 100) | 4 | 5 | 625 | 310 | 30 | 30 | 31,230 | 5 |
| `large` | 506 (2 × 500) | 6 | 50 | 26,200 | 2,008 | 100 | 20 | 775,400 | 10 |
Each node has its data (one datalink each) and its samples, each sample bound to one data of its node. Wide nodes (titled `Wide node 1: …`) hang under the root nodes and carry `--wide-node-size` samples and data each: open one and switch its samples or data to the batch edit view to measure a large table. `small` backs the automated test of the command and stays fast rather than realistic.
**Metadata.** Each root tree draws its own set of `--metadata-per-object` fields, and every node and sample of the tree carries all of them — as a project following one checklist would. Data carry only the first `--metadata-per-data` fields of the set (20 in `large`), which keeps its 26,000 data affordable: at 100 each, they alone would make 2.6 million metadata. A batch edit table therefore shows as many columns as the set has fields, even with the samples inherited from ancestors; 100 is about the size of the largest ENA checklist. The relation flags of the fields (`node_related`…) are informational and not followed.
Values are generated from each field’s JSON schema. At start-up the command draws 40 values per field and checks them with the same validation as `Metadata.save()`, offline, keeping the fields where at least half pass. The values of the fields where some fail, and of every field whose values are objects — the only ones seen failing, such as a few ENA fields refusing some of their “missing” values — are checked again when written, and redrawn until valid. Fields cross-checked against external services (taxon, protocol, topic, DOI…), patterns and a few formats are left out. With ENA loaded, 812 fields are usable (40 Madbot, 772 ENA); this probe takes about 15 seconds and the command prints how many fields it kept. Without the ENA fields, the metadata per object are capped at the Madbot fields available.
**Cost of `large`.** `large` writes 775,400 metadata; the command prints how long the writing took. The metadata are generated and written chunk by chunk, so memory does not grow with `--metadata-per-object`.
**Rights.** The owner owns every node. The first member co-owns the workspace, which reads every node without any node membership. The other members are plain workspace members, invited to some root trees as a whole, to a sub-tree only or to nothing, with mixed node roles. As through the API, a member of a node is a member of its parent: a member invited to a sub-tree collaborates on its ancestors, and the rest of the tree stays unreadable to them. Member users are named `load-member-01`, `load-member-02`… with an unusable password, and are reused from one run to the next. Each gets a made-up first and last name that depends on its number only, so it stays the same from one run to the next; a reused member without a name is given one.
**Reproducibility.** The same seed and options give the same structure: titles, tree, data, metadata values and memberships. Identifiers and timestamps differ.
**What it bypasses — keep it in mind when reading a measure.**
* Objects are written with `bulk_create`, which skips model `save()` and signals: no `simple_history` record is created, and nothing would be indexed by a search engine. The history tables therefore do not grow as they would with real use.
* Metadata are written directly, without the Celery task: the command needs neither a Celery worker nor a search engine.
* The workspace is the same from one machine to the next only if they have the same metadata fields: the same Madbot version, and the same ENA plugin version loaded (`pixi run madbot reload_plugins`). The command warns when a plugin of `--plugin-fields` has no field.
* The Madbot metadata fields must exist: run `pixi run madbot initialise_madbot_metadata_fields` first, the command says so otherwise.
* Data have made-up external identifiers and an access right for the owner only. Anything that asks the plugin about them (refresh, access verification) will fail — the connection exists to hold them, not to reach a real service.
* `--force` deletes with history disabled, so recreating a large workspace stays quick.
## Debug emails
[Section titled “Debug emails”](#debug-emails)
In development, madbot writes the emails it sends to files instead of sending them: they land in `api/sent_emails/`.
To read them in a web interface instead, use [Mailhog](https://github.com/mailhog/MailHog), which needs Docker:
1. In `api/.env`, with `DEBUG` on:
```bash
USE_MAILHOG=true
```
2. Start the Mailhog container, from `api/`:
```bash
sh ./scripts/start_mailhog.sh
```
3. Restart the API, then open .
# Continuous integration
> The stages and jobs of the madbot pipeline, and when each one runs.
The pipeline is defined in `.gitlab-ci.yml`, at the root of the repository. Most jobs only run when the files they check change: a merge request that only touches the client does not run the API tests.
## When jobs run
[Section titled “When jobs run”](#when-jobs-run)
| Pipeline | What runs |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Merge request | The checks of each package whose files changed (`api/`, `plugin_api/`, `client/`, `documentation/`). A change to `.gitlab-ci.yml` runs them all. |
| Push to `dev` | The CI images of the packages that changed, and the API tests, so that the coverage badge follows `dev`. |
| Push to `main` | The release of each package whose files changed, its Docker image, and the documentation site. |
When no job applies, `pipeline-noop` runs so that the pipeline still exists.
## Stages
[Section titled “Stages”](#stages)
### 📦 ci-images
[Section titled “📦 ci-images”](#-ci-images)
The jobs of the API, `plugins_api` and the client run in images that already hold their dependencies. For each package, `Resolve … CI image` computes the name of the image from a hash of its dependency files, and `Build … CI image` builds it and pushes it to the GitLab registry when it does not exist yet. A merge request that does not change the dependencies reuses the existing image.
### 💎 quality
[Section titled “💎 quality”](#-quality)
| Job | Checks |
| ------------------------------ | ------------------------------------------------------------- |
| `API Code audit (ruff)` | `pixi run lint` and `pixi run format-check` on `api/`. |
| `Plugin API Code audit (ruff)` | The same on `plugin_api/`. |
| `client (eslint)` | `pnpm run lint` on `client/`. |
| `client (mdi icons)` | `pnpm run icons:check`: the icon map lists every icon in use. |
### 🛡️ security
[Section titled “🛡️ security”](#️-security)
| Job | Checks |
| ------------------------------------------------ | --------------------------------------------------------------- |
| `API Dependencies vulnerability (safety)` | Known vulnerabilities in the dependencies of the API. |
| `Plugin API Dependencies vulnerability (safety)` | The same for `plugins_api`. |
| `Client Dependencies vulnerability (pnpm audit)` | `pnpm audit --audit-level=high` on the client. Allowed to fail. |
| `API Security breach (bandit)` | Insecure patterns in the code of the API. |
| `Plugin API Security breach (bandit)` | The same for `plugins_api`. |
### 🤖 tests
[Section titled “🤖 tests”](#-tests)
| Job | Runs |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `API Tests` | The whole API suite under coverage, with a Redis service. Publishes the coverage report to the merge request, and fails below the threshold of `api/pyproject.toml`. |
| `Client test-and-coverage` | `pnpm test`, the unit tests of the client. |
### 🛠️ build
[Section titled “🛠️ build”](#️-build)
| Job | Runs |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `API Test Build` | Builds the Python package of the API. |
| `Plugin API Test Build` | Builds the Python package of `plugins_api`. |
| `Client Test Build` | Builds the client and checks the size of the output. |
| `Documentation build` | Builds this site, and fails on a broken internal link. The result is the **Documentation preview** of the merge request. |
| `Documentation external links` | Checks the links of the site to other sites. Allowed to fail. |
### 📤 release
[Section titled “📤 release”](#-release)
These jobs run on `main` only.
| Job | Runs |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Release plugins-api`, `Release madbot-api`, `Release madbot-client` | semantic-release for each package: version, changelog, publication to the GitLab package registry. When `plugins-api` is released, the API raises its dependency on it before its own release. See [Releases](/contribute/branches-commits-releases/#releases). |
| `API Docker Image`, `Client Docker Image` | Build the image of the released version and push it to the GitLab registry, with provenance and SBOM attestations. |
| `pages` | Builds this site and publishes it on GitLab Pages. |
| `Documentation site` | Builds this site for the IFB web server and publishes it as the generic package `madbot-documentation`; the server downloads it and serves it on its own domain. Runs only when the CI/CD variable `DOCS_SERVER_SITE` holds the address of that domain. |
To release every package whatever changed, run a pipeline on `main` with the variable `FORCE_RELEASE_ALL` set to `true`.
# Data models
> The main models of the madbot API and how they relate to each other.
The models of the API are in `api/madbot_api/core/models.py`. Most use a UUID primary key and carry audit fields: `created_by`, `last_edited_by`, `created_time` and `last_edited_time`. The [concepts](/use/concepts/) page explains what each object means for the people who use madbot.
The full list of models is kept for developers and agents in `docs/data-models-api.md`.
## Overview
[Section titled “Overview”](#overview)
```text
Workspace
├── WorkspaceMember
├── Connection ──── Credential (in Vault), SharedConnectionParam
│ └── Data (tree) ──── DataAccessRight
└── Node (tree) ──── NodeMember
├── DataLink ──── Data
├── Sample ──── SampleBoundData ──── Data
└── Metadata
Submission ──── Connection
├── SubmissionMember, SubmissionSettings
├── SubmissionData ──── Data
├── SubmissionMetadataObject ──── SubmissionMetadata
├── SubmissionAssociation ──── SubmissionAssociationObject
└── ExternalIdentifier
```
## Organisation
[Section titled “Organisation”](#organisation)
| Model | Role |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| `Workspace` | The container of a project. Every other object belongs to a workspace. |
| `WorkspaceMember` | A user’s membership of a workspace, with their role. |
| `Node` | An element of the project tree. A tree node (`django-tree-queries`): parent, children, subtree. |
| `NodeMember` | A user’s membership of a node, with their role. A member of a node is also a member of its ancestors. |
## Data
[Section titled “Data”](#data)
| Model | Role |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Connection` | A connection to a source or a repository, through a plugin, with its settings. |
| `Credential` | The credentials of a user for a connection. The secrets themselves are in Vault. |
| `Data` | A file or a folder of a source, seen through a connection. A tree node, like `Node`. Holds its size, media type and extension, and an enrichment status (see below). |
| `DataAccessRight` | Whether a user can reach a data in its source. |
| `DataLink` | The link between a node and a data. |
| `DataAssociation` | A group of data that belong together, which can carry metadata. |
| `Sample` | An object the project studies, attached to a node. Its `alias` is unique among the samples of the node (constraint `unique_sample_alias_per_node`). |
| `SampleBoundData` | The link between a sample and a data. |
`Data` carries a `status`, in the vocabulary of `Node`. A data created by a batch of datalinks is `in progress` until the `enrich_datalinks` task has read it from its source, then `active`, or `failed` with an `enrichment_error` (`{code, message}`). `enrichment_task_id` is the last task that enriched it. The status belongs to the data, not to the datalink: what is read from the source (attributes, metadata, associations) is shared by every datalink of the data. A data that is not `active` can only be read and deleted.
## Metadata
[Section titled “Metadata”](#metadata)
| Model | Role |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `RawSchema` | A JSON schema: `MadbotRawSchema` for madbot’s own fields, `PluginRawSchema` for the fields of a plugin. |
| `MetadataField` | The definition of a field: `MadbotMetadataField` or `PluginMetadataField`. |
| `MetadataMapping` | The correspondence between fields of different sources. |
| `Metadata` | A value of a field, on a node, a sample, a data or a data association. Validated against the JSON schema of its field. |
Metadata are inherited down the node tree, and from samples to their data.
## Submissions
[Section titled “Submissions”](#submissions)
A `Submission` sends data and metadata to a repository through a `Connection`. Its status follows the steps of the submission:
| Status | Meaning |
| ------------------------ | ---------------------------------------------------------------------------- |
| `draft` | Being prepared. |
| `generating metadata` | The Celery task `async_create_metadata_objects` builds the metadata objects. |
| `ready` | Ready to submit. |
| `submission in progress` | The Celery task `async_submit` sends it. |
| `submitted` | Accepted by the repository. |
| `update available` | Deposited, and an update can be sent to the repository. |
A submission records its `errors`, and the last task that failed, to help diagnose it.
| Model | Role |
| ------------------------------------------------------ | -------------------------------------------------------------- |
| `SubmissionMember` | A user’s membership of a submission. |
| `SubmissionSettings` | The settings of the submission plugin. |
| `SubmissionData` | A data included in the submission. |
| `SubmissionMetadataObject` | A metadata object of the target repository: a study, a sample… |
| `SubmissionMetadata`, `SubmissionMetadataValue` | The metadata of the submission and their values. |
| `SubmissionAssociation`, `SubmissionAssociationObject` | Associations of objects inside the submission. |
| `ExternalIdentifier` | An identifier given by the repository after the deposit. |
## Users and access
[Section titled “Users and access”](#users-and-access)
| Model | Role |
| -------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `MadbotUser` | The user. Extends Django’s user with an approval workflow and a profile (ORCID, ROR). |
| `ApplicationUserParam`, `UserNotificationSettings` | The preferences of a user. |
| `PersonalAccessToken` | A token to call the API from a script. |
| `ImpersonateIntent`, `ImpersonateSession` | The impersonation of a user by an administrator, and its audit trail. |
| `AlertBanner` | A banner shown to the users, served by `/api/alerts`. |
## History
[Section titled “History”](#history)
`django-simple-history` records the changes of the main models. When you add a field to a model that has a history, check whether the history should exclude it.
# Naming conventions
> The verbs to use in the names of functions that call an API.
## Functions that call an API
[Section titled “Functions that call an API”](#functions-that-call-an-api)
Name a function that calls an API with an action verb that says what it does. The diagram below gives the verb to use for each kind of call.

# Repositories
> The repositories of the madbot project and what each one holds.
The madbot project lives in the [ifb-elixirfr/madbot](https://gitlab.com/ifb-elixirfr/madbot) group on GitLab.
| Repository | What it holds |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [madbot](https://gitlab.com/ifb-elixirfr/madbot/madbot) | The application: the API (`api/`), the web client (`client/`), the `plugins_api` package (`plugin_api/`) and this documentation (`documentation/`). |
| [plugins](https://gitlab.com/ifb-elixirfr/madbot/plugins) | The plugins, one repository each: `official/` for the plugins maintained by the madbot team, `community/` for the others. See the [plugins reference](/use/reference/plugins/). |
| [madbot-training](https://gitlab.com/ifb-elixirfr/madbot/madbot-training) | The training site, with its tracks and the material for trainers. |
| [madbot-website](https://gitlab.com/ifb-elixirfr/madbot/madbot-website) | The [madbot showcase website](https://madbot.france-bioinformatique.fr/). |
# Tests and quality checks
> Run the tests, the linters, the formatters and the security checks before opening a merge request.
The CI runs these checks on every merge request that touches the code they cover. Run them on your machine first: a failure is quicker to fix before the push. The [CI reference](/contribute/reference/ci/) lists the jobs.
## Pre-commit hooks
[Section titled “Pre-commit hooks”](#pre-commit-hooks)
The repository defines pre-commit hooks that run most of the checks below on the files of each commit: migrations, ruff, ESLint, the icon map, `pixi.lock`, safety and bandit. With [pre-commit](https://pre-commit.com/#install) installed, set up the hooks once, from the root of the repository:
```bash
pre-commit install
```
## API
[Section titled “API”](#api)
From `api/`:
### Tests
[Section titled “Tests”](#tests)
```bash
# The whole suite, in parallel and in a random order
pixi run test
# One module
pixi run test madbot_api.core.tests.functional.workspaces
# In series, when a parallel failure is hard to read
pixi run test-serial
```
The tests run in the `dev` environment, on an in-memory SQLite database. A production instance runs PostgreSQL: check raw SQL on PostgreSQL by hand.
### Coverage
[Section titled “Coverage”](#coverage)
```bash
# Run the suite under coverage, then compare with the threshold
pixi run test-cov && pixi run cov-report
# Line-by-line report in htmlcov/
pixi run test-cov && pixi run cov-html
```
The CI fails when the coverage drops below the threshold held in `api/pyproject.toml` (`[tool.coverage.report] fail_under`). The threshold only goes up. `api/docs/test-coverage-plan.md` describes the measured perimeter, the exclusions and the state of the effort.
### Lint and format
[Section titled “Lint and format”](#lint-and-format)
```bash
pixi run lint
pixi run format
pixi run format-check
```
`format` rewrites the files; `format-check` only reports, as the CI does. Run both `lint` and `format-check`: they are different checks, and the CI runs both.
### Security
[Section titled “Security”](#security)
```bash
# Known vulnerabilities in the dependencies
pixi run safety
# Insecure patterns in the code
pixi run bandit
```
`pixi run quality-check` runs `lint`, `format-check`, `bandit` and `safety` in one go.
## `plugins_api`
[Section titled “plugins_api”](#plugins_api)
`plugin_api/` has its own pixi project and the same tasks. From `plugin_api/`:
```bash
pixi run lint
pixi run format-check
pixi run safety
pixi run bandit
```
## Client
[Section titled “Client”](#client)
From `client/`:
```bash
# Unit tests (Jest)
pnpm test
# End-to-end tests (Playwright), with or without the interface
pnpm e2e
pnpm e2e:ui
# Lint, with or without the automatic fixes
pnpm lint
pnpm lint:fix
# Check that the icon map lists every icon in use
pnpm icons:check
# Known vulnerabilities in the dependencies
pnpm audit --audit-level=high
```
The client shows Material Design icons from a generated list, `client/utils/mdiIcons.ts`. An `mdi-*` icon missing from it is shown as a question mark: after adding an icon, run `pnpm icons` and commit the regenerated file.
### Supply-chain protections
[Section titled “Supply-chain protections”](#supply-chain-protections)
`pnpm-workspace.yaml` (in `client/`, at the root and in `documentation/`) sets [pnpm’s supply-chain protections](https://pnpm.io/supply-chain-security). Keep the copies in line.
* **Release quarantine** (`minimumReleaseAge`): a version published less than a day ago is not installed. For an urgent security fix, add a commented `minimumReleaseAgeExclude` entry.
* **Trust policy** (`trustPolicy: no-downgrade`): an install fails when the trust evidence of a package weakens compared with its earlier releases.
* **Build scripts allow-list** (`allowBuilds`, `strictDepBuilds`): the install scripts of dependencies only run for the packages listed. When you add a dependency that needs one, approve it with `pnpm approve-builds` and commit the configuration.
* **No exotic sub-dependencies** (`blockExoticSubdeps`): transitive dependencies come from the registry, not from Git or tarball URLs.
Never use `dangerouslyAllowAllBuilds`.
## Documentation
[Section titled “Documentation”](#documentation)
From `documentation/`:
```bash
pnpm build
```
The build fails on a broken internal link. See [Write documentation](/contribute/write-documentation/).
# Write documentation
> Where a documentation change goes, how to preview it, and the rules the pages follow.
This site lives in the `documentation/` folder of the madbot repository. It is built with [Starlight](https://starlight.astro.build/) and published on GitLab Pages from `main`: it always describes the released madbot.
## Where a change goes
[Section titled “Where a change goes”](#where-a-change-goes)
* **Documentation of released behaviour** (a new page about an existing feature, a correction, a reorganisation): start from `main` and open the merge request to `main`. The page is online at the end of its pipeline, then `main` is merged back into `dev`, as for a hotfix. Starting from `dev` would bring unreleased features into `main` with your page.
* **Documentation of an unreleased feature**: write it in the feature’s merge request, to `dev`. It is published with the release.
A merge request that changes something visible to users, people who run an instance, plugin developers or API users updates the documentation in the same merge request: the reviewer reads the code and its documentation together.
## Preview a change
[Section titled “Preview a change”](#preview-a-change)
### On your machine
[Section titled “On your machine”](#on-your-machine)
From `documentation/`, with Node.js 22, Corepack and [uv](https://docs.astral.sh/uv/) (the `plugins_api` reference runs Griffe through `uvx`, and the REST API reference reads the schema of `api/` through uv):
```bash
corepack enable
pnpm install
pnpm dev
```
Open . The page reloads when you save a file. `pnpm build` builds the whole site and fails on a broken internal link, as the CI does.
### In the merge request
[Section titled “In the merge request”](#in-the-merge-request)
The pipeline of a merge request that touches `documentation/` builds the site. Open it from the **Documentation preview** link of the merge request, or from the address printed at the end of the `Documentation build` job. The preview is kept two weeks.
The `Documentation external links` job checks the links to other sites. It may fail when a site is down: read its log, but it does not block the merge request. It skips the links to the madbot group on gitlab.com (this repository, the plugins, the issues): gitlab.com rate-limits an anonymous check of the hundreds of source links that the site generates.
## Where pages go
[Section titled “Where pages go”](#where-pages-go)
The site has one section per audience, and each page is one of the four types of [Diátaxis](https://diataxis.fr/):
| Section | For | Folder |
| --------------------- | --------------------------------------------------- | ------------- |
| Use madbot | people who use madbot | `use/` |
| Run an instance | people who install and run an instance | `run/` |
| Automate with the API | people who call the REST API from their own scripts | `api/` |
| Extend madbot | developers who write plugins | `extend/` |
| Contribute | people who change madbot | `contribute/` |
* **Tutorial**: a lesson that leads a beginner to a first result.
* **How-to guide**: the steps to reach a precise goal, for someone who knows what they want.
* **Reference**: a description to look up: commands, settings, roles.
* **Explanation**: how something works and why.
Pages live in `documentation/src/content/docs/`, under the folder of their section. Add a new page to the `sidebar` of `documentation/astro.config.mjs`.
## The `plugins_api` reference
[Section titled “The plugins_api reference”](#the-plugins_api-reference)
The pages under `extend/plugins/reference/` are generated from the docstrings of `plugin_api/` by [starlight-pydocs](https://ewels.github.io/starlight-pydocs/), at each build: to change them, change the docstrings. They follow the numpy convention, which `pixi run lint` checks in `plugin_api/`.
* **What is documented**: the modules of `plugins_api` and, in each one, the names listed in its `__all__`. A new public class goes into the `__all__` of its module and of `plugins_api/__init__.py`.
* **Major versions**: `documentation/plugins-api.config.mjs` lists the majors still supported by plugins. The current one is read from `plugin_api/`; an older one from the git tag of its last release. Its pages carry a banner that links to the current major, and the search leaves them out.
* **Links**: link to the reference without a version, as `/extend/plugins/reference/data_plugins/`. That address leads to the current major, so the link stays valid when a new major is released.
## The files for coding assistants
[Section titled “The files for coding assistants”](#the-files-for-coding-assistants)
Each build also publishes the documentation in the [llms.txt format](https://llmstxt.org/), for coding assistants: `/llms.txt` lists what is available, `/llms-full.txt` holds the English pages followed by the `plugins_api` reference of the current major, and `/llms-small.txt` an abridged version of the pages. They are generated from the pages by [starlight-llms-txt](https://github.com/delucis/starlight-llms-txt) and `documentation/src/plugins/llms-txt.mjs`: there is nothing to edit by hand.
## The REST API reference
[Section titled “The REST API reference”](#the-rest-api-reference)
The pages under `api/reference/` are generated by [starlight-openapi](https://github.com/HiDeoo/starlight-openapi) from the OpenAPI schema of `api/`, which drf-spectacular writes at each build: to change them, change the views and serializers of the API, or their `extend_schema` decorators. A merge request that changes the API shows the changed reference in its preview.
* **Version**: the overview page shows the version of `madbot-api`, read from `api/pyproject.toml`.
* **The build fails** when the schema cannot be written, for example when the API does not start: it does not publish a reference without its endpoints.
* **Links**: link to an endpoint by its operation id, as `/api/reference/operations/workspaces_list/`. The build checks that the page exists.
## Writing rules
[Section titled “Writing rules”](#writing-rules)
1. **One audience and one type per page.** A how-to guide does not explain a concept at length: it links to the explanation.
2. **Version mentions.**
* **Users**: none. An instance runs the latest release.
* **People who run an instance**: name the package version (`madbot-api 2.1`, an image tag), with a badge such as “Since 2.1”.
* **API users**: name the version of `madbot-api`, with the same badge.
* **Plugin developers**: name the version of `plugins_api`.
* **When to remove them**: once the version they compare with is no longer supported. The upgrade guides keep the history.
3. **Interface labels are quoted exactly** as `client/locales/en.json` shows them (`fr.json` for French pages).
4. **Examples come from several disciplines**: a soil core, a material, a cohort participant, an archive document. Biology is one example among others.
5. **Screenshots** are taken from a local instance with a fictitious account. When a screenshot is missing, say so in the text rather than using an old one.
6. **English is the source language.** French comes first for the home page, `use/` and `run/`; `api/`, `extend/` and `contribute/` stay in English. A French page lives under `fr/`, with the same path as the English one. A page without a French version is shown in English, with a notice.
## Syntax
[Section titled “Syntax”](#syntax)
Pages are Markdown (`.md`), or MDX (`.mdx`) when they use components. Starlight adds:
* asides: `:::note`, `:::tip`, `:::caution`, `:::danger`, closed with `:::`;
* [components](https://starlight.astro.build/components/using-components/) such as `Tabs`, `Steps`, `Card` and `Badge`, in MDX pages.
Write internal links from the root of the site, with a trailing slash: `[the roles](/use/reference/roles/)`. The build adds the path under which the site is served.
# Plugin development guide
> Create a madbot plugin from scratch, with a file system data plugin as an example.
This comprehensive guide will walk you through creating a madbot plugin from scratch. We’ll build a simple file system data plugin as an example to demonstrate the complete development process.
## Overview
[Section titled “Overview”](#overview)
Madbot’s plugin system provides a flexible architecture for integrating with external systems. Plugins are Python classes that inherit from specific base classes and implement required interfaces. The system supports three main types of plugins:
* **Data Plugins**: Connect to external data sources and provide access to files and directories
* **Submission Plugins**: Handle data submission to external repositories and services
* **Metadata Field Definition Plugins**: Define metadata schemas to extend the madbot metadata referential
In this tutorial, we’ll create a **Data Plugin** that connects to a remote file system and allows users to browse and download files from remote servers.
Every class, method and exception of `plugins_api` is described in the [`plugins_api` reference](/extend/plugins/reference/).
If you write your plugin with a coding assistant, give it the documentation as plain Markdown: [`llms-full.txt`](/llms-full.txt) holds every page of this site and the `plugins_api` reference of the current version, and [`llms.txt`](/llms.txt) lists what is available.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Before starting, ensure you have:
* Python 3.11
* Basic knowledge of Python classes and inheritance
* Access to a madbot development environment
## Step 1: Project Setup
[Section titled “Step 1: Project Setup”](#step-1-project-setup)
Let’s create a new plugin project called `madbot_filesystem`. This will be a data plugin that allows browsing remote directories.
### 1.1 Create Project Structure
[Section titled “1.1 Create Project Structure”](#11-create-project-structure)
Create the following directory structure:
```plaintext
madbot_filesystem_plugin/
├── pyproject.toml # Project configuration and dependencies
├── README.md # Plugin documentation
├── LICENSE # License terms for the plugin
├── CONTRIBUTING.md # Contribution guidelines (recommended)
├── code_of_conduct.md # Community behavior standards (recommended)
├── .gitlab-ci.yml # GitLab CI/CD pipeline configuration (recommended)
└── madbot_filesystem/
├── __init__.py
├── plugins.py # Your plugin class
├── app.py # The app that registers the plugin
└── static/
├── json/
│ └── schema/ # JSON schema files
│ └── uischema/ # Optional JSON Forms UI schema files (if they exist)
└── images/
└── filesystem.png # Your plugin logo
```
### 1.2 Initialize Project Files
[Section titled “1.2 Initialize Project Files”](#12-initialize-project-files)
**pyproject.toml**:
```toml
[project]
name = "madbot-filesystem"
version = "1.0.0"
description = "A remote filesystem data plugin for madbot"
authors = [
{name = "Your Name", email = "your.email@example.com"}
]
readme = "README.md"
license = "BSD-3-Clause"
license-files = ["LICEN[CS]E*"]
requires-python = ">=3.11,<3.12"
keywords = ["madbot"]
dependencies = [
"plugins-api >=3.0.0,<4",
]
[project.optional-dependencies]
dev = [
'ruff',
'bandit[toml]',
'safety >= 2.4',
]
[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"
[tool.setuptools.packages.find]
include = ["madbot-filesystem*"]
exclude = ["logs*", "tests*"]
```
For more information about the `pyproject.toml` file, see [this guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/).
This file is enough to write the plugin. The repository around it also needs the registry that publishes `plugins-api`, floors on the build tools, and its own CI with the quality and security jobs: [Set up a plugin repository](/extend/plugins/repository-setup/) lists them.
**README.md**:
```markdown
# Madbot Filesystem Plugin
A madbot data plugin that provides access to remote file systems.
## Features
- Browse remote directories
- List files and subdirectories on remote servers
- Download files with integrity verification
## Installation
This plugin is designed to be installed as a madbot plugin. See the madbot documentation for installation instructions.
```
## Step 2: Understanding Data Plugin Requirements
[Section titled “Step 2: Understanding Data Plugin Requirements”](#step-2-understanding-data-plugin-requirements)
Before implementing our plugin, let’s understand what we need to build. A Data Plugin inherits from `DataPlugin` which inherits from `ConnectionPlugin` which inherits from `MadbotPlugin`. This means we need to implement methods from all three base classes:
### 2.1 From MadbotPlugin (Base Plugin Class)
[Section titled “2.1 From MadbotPlugin (Base Plugin Class)”](#21-from-madbotplugin-base-plugin-class)
1. `get_name()`: Return the plugin name
2. `get_slug()`: Return the plugin slug
3. `get_description()`: Return plugin description
4. `get_author()`: Return plugin author
5. `get_logo()`: Return the path of the plugin logo
6. `get_color()`: Return the color of the plugin
7. `get_status()`: Return maturity status keyed by plugin type (e.g. `{"data_plugin": PluginStatus.STABLE}`)
### 2.2 From ConnectionPlugin (Connection Management)
[Section titled “2.2 From ConnectionPlugin (Connection Management)”](#22-from-connectionplugin-connection-management)
1. `get_instance_name()`: Return the instance name of the connection plugin
2. `get_connection_fields()`: Return connection fields (shared and private)
3. `get_shared_parameters()`: Return all shared parameters in a cleaned form
### 2.3 From DataPlugin (Data Operations)
[Section titled “2.3 From DataPlugin (Data Operations)”](#23-from-dataplugin-data-operations)
1. `__init__(connection_parameters)`: Initialize the plugin with connection parameters
2. `get_root_name()`: Return the name of the root data object
3. `get_root_id()`: Return the unique identifier of the root data object
4. `browse_data_objects(parent_id)`: Return the direct children of a parent (navigation / listing). When `parent_id` is `None`, browse from the root of the source. Distinct from reading objects by id.
5. `get_data_objects_by_ids(object_ids)`: Return detailed information for a list of data object ids. Return a `dict` keyed by id: either a `PluginDataObject` or a `PluginError` (`DataNotFoundError`, `PluginPermissionError`, …). Raise source-level errors (`SOURCE_ERRORS`: `UnreachableError`, `HostConnectionRefusedError`, `AuthenticationError`) instead of storing them. Empty list returns `{}`. Duplicate ids appear once. Use `self._read_each(object_ids, read_one)` when the source has no batch API.
6. `get_batch_read_size()` *(optional)*: Max ids madbot sends per batch-read call. Default `DEFAULT_BATCH_READ_SIZE` (100). Return `None` to disable chunking.
7. `get_metadata_for_data_objects(object_ids)` *(optional)*: Return metadata for each id (`dict` of lists or per-id errors). Defaults to `[]` per id.
8. `get_data_associations_for_data_objects(object_ids)` *(optional)*: Return associations for each id. Defaults to `[]` per id.
9. `download_data(external_dataobject_id, destination_path)`: Download a data object to local storage
See the [`DataPlugin` reference](/extend/plugins/reference/data_plugins/) for full signatures.
## Step 3: Creating Our Example Plugin
[Section titled “Step 3: Creating Our Example Plugin”](#step-3-creating-our-example-plugin)
Let’s create our filesystem plugin step by step.
### 3.1 Basic Plugin Structure
[Section titled “3.1 Basic Plugin Structure”](#31-basic-plugin-structure)
Create `madbot_filesystem/plugins.py`:
```python
import os
from pathlib import Path
from typing import Any
import requests
from plugins_api import (
AuthenticationError,
ConnectionField,
DataInvalidError,
DataNotFoundError,
DataPlugin,
DownloadDataError,
PluginDataObject,
PluginError,
PluginStatus,
UnreachableError,
)
class FilesystemDataPlugin(DataPlugin):
"""
A data plugin that provides access to remote file system directories.
This example demonstrates the plugin architecture without being tied to a
specific transport library.
"""
def __init__(self, connection_parameters: dict[str, Any]):
"""
Initialize the filesystem plugin.
Args:
connection_parameters: Dictionary containing connection parameters
"""
self.host = connection_parameters.get("host", "")
self.port = int(connection_parameters.get("port", 22))
self.username = connection_parameters.get("username", "")
self.password = connection_parameters.get("password", "")
# Example connection check, adapt to your protocol / client:
try:
response = requests.get(
f"https://{self.host}:{self.port}",
auth=(self.username, self.password),
timeout=20,
)
response.raise_for_status()
except requests.HTTPError:
raise AuthenticationError()
except requests.RequestException:
raise UnreachableError(self.host)
# ===== MadbotPlugin Methods =====
@classmethod
def get_name(cls) -> str:
"""Return the plugin name."""
return "Remote Filesystem Plugin"
@classmethod
def get_slug(cls) -> str:
"""Return the plugin slug."""
return "remote_filesystem_plugin"
@classmethod
def get_description(cls) -> str:
"""Return plugin description."""
return "A data plugin that provides access to remote file systems for browsing and downloading files."
@classmethod
def get_author(cls) -> str:
"""Return plugin author."""
return "John Doe"
@classmethod
def get_logo(cls) -> str:
"""Return the path of the plugin logo."""
return "images/filesystem.png"
@classmethod
def get_color(cls) -> str:
"""Return the color of the plugin."""
return "#4CAF50"
@classmethod
def get_status(cls) -> dict[str, PluginStatus]:
return {"data_plugin": PluginStatus.STABLE}
# ===== ConnectionPlugin Methods =====
def get_instance_name(self) -> str:
"""Return the instance name of the connection plugin."""
return f"Filesystem-{self.host}-{self.username}"
@classmethod
def get_connection_fields(
cls,
) -> tuple[list[ConnectionField], list[ConnectionField]]:
"""
Retrieve the connection fields for the connection plugin.
Returns:
Tuple containing shared and private connection fields
"""
shared_fields = [
ConnectionField(
slug="host",
schema_content={
"type": "string",
"title": "Host",
"description": "Remote server hostname or IP address",
},
),
ConnectionField(
slug="port",
schema_content={
"type": "integer",
"title": "Port",
"description": "Remote server port",
"default": 22,
},
),
]
private_fields = [
ConnectionField(
slug="username",
schema_content={
"type": "string",
"title": "Username",
"description": "Remote server username",
},
),
ConnectionField(
slug="password",
schema_content={
"type": "string",
"title": "Password",
"description": "Remote server password",
},
),
]
return shared_fields, private_fields
def get_shared_parameters(self) -> dict[str, Any]:
"""Return all shared parameters."""
return {"host": self.host, "port": self.port}
# ===== DataPlugin Methods =====
@staticmethod
def get_root_name() -> str:
"""Return the name of the root data object."""
return "Remote Filesystem Root"
@staticmethod
def get_root_id() -> str:
"""Return the unique identifier of the root data object."""
return "/"
def browse_data_objects(self, parent_id: str | None) -> list[PluginDataObject]:
"""Return the direct children of a parent; ``None`` starts at the root."""
parent_id = self.get_root_id() if parent_id is None else parent_id
path = parent_id if parent_id != self.get_root_id() else ""
items = get_directory_contents_from_remote_system(path)
if items is None:
return []
objects = [
PluginDataObject(
id=item_data["path"],
name=item_data["name"],
type="directory" if item_data["is_directory"] else "file",
size=item_data["size"],
has_children=item_data["is_directory"],
file_extension=(
Path(item_data["path"]).suffix.lstrip(".")
if not item_data["is_directory"]
else None
),
)
for item_data in items
]
return sorted(objects, key=lambda obj: obj.name)
def _read_data_object(self, object_id: str) -> PluginDataObject:
"""Read one object. Used via `_read_each` when the source has no batch API."""
if object_id == "/":
return PluginDataObject(
id="/",
name="Remote Filesystem Root",
type="directory",
size=0,
has_children=True,
)
data = get_file_data_from_remote_system(object_id)
if not data:
raise DataNotFoundError(object_id)
return PluginDataObject(
id=object_id,
name=Path(object_id).name,
type="directory" if data["is_directory"] else "file",
size=data["size"],
has_children=data["is_directory"],
file_extension=(
Path(object_id).suffix.lstrip(".")
if not data["is_directory"]
else None
),
)
def get_data_objects_by_ids(
self, object_ids: list[str]
) -> dict[str, PluginDataObject | PluginError]:
"""
Return detailed information for each requested id.
Prefer one remote call when the source allows it; otherwise wrap a
one-id reader with `_read_each` as below.
"""
return self._read_each(object_ids, self._read_data_object)
def download_data(self, external_dataobject_id: str, destination_path: str) -> str:
"""Download a data object to local storage and return the download report."""
data_object = self._read_data_object(external_dataobject_id)
if data_object.type == "directory":
raise DataInvalidError(external_dataobject_id)
content = download_file_from_remote_system(external_dataobject_id)
with open(destination_path, "wb") as handle:
handle.write(content)
local_size = os.path.getsize(destination_path)
if data_object.size is not None and local_size != data_object.size:
raise DownloadDataError(
f"Size mismatch: expected {data_object.size}, got {local_size}"
)
return destination_path
```
`get_metadata_for_data_objects` and `get_data_associations_for_data_objects` are optional. Override them when your source exposes metadata or associations. Otherwise, the base class returns an empty list for each id.
When the remote API can fetch several ids in one call, implement the batch method directly. It must show the three rules: one entry per distinct id, per-id errors stored in the result, source errors raised:
```python
def get_data_objects_by_ids(self, object_ids):
if not object_ids:
return {}
# One remote call; connection or auth failures raise
# UnreachableError / AuthenticationError.
found = self.client.get_many(object_ids)
return {
object_id: (
self._to_data_object(found[object_id])
if object_id in found
else DataNotFoundError(object_id)
)
for object_id in dict.fromkeys(object_ids)
}
```
### 3.2 Plugin Registration
[Section titled “3.2 Plugin Registration”](#32-plugin-registration)
Create `madbot_filesystem/app.py`:
```python
from django.apps import AppConfig
class MadbotFilesystemPluginConfig(AppConfig):
"""Django app configuration for the madbot filesystem plugin."""
default_auto_field = 'django.db.models.BigAutoField'
name = 'madbot_filesystem'
verbose_name = 'Madbot Filesystem Data Plugin'
def ready(self):
"""Called when Django starts up."""
# Import here to avoid circular imports
from . import plugins # noqa
```
## Step 4: Implementing the Plugin Class
[Section titled “Step 4: Implementing the Plugin Class”](#step-4-implementing-the-plugin-class)
### 4.1 Key Implementation Details
[Section titled “4.1 Key Implementation Details”](#41-key-implementation-details)
Our plugin implementation includes several important aspects:
1. **Plugin identity**: required `MadbotPlugin` methods, including `get_status()`
2. **Connection management**: shared/private `ConnectionField` DTOs (`slug` + JSON Schema)
3. **Navigation vs read**: `browse_data_objects` lists children; `get_data_objects_by_ids` reads by id (batch)
4. **Batch reads**: use `_read_each` when there is no batch API, or one remote call when there is; result keys must match the requested ids exactly. Override `get_batch_read_size()` when the source has a different id-list limit (or return `None` for no chunking).
5. **Error handling**: store per-id `PluginError`; raise `SOURCE_ERRORS` (`UnreachableError`, `HostConnectionRefusedError`, `AuthenticationError`)
## Advanced Features
[Section titled “Advanced Features”](#advanced-features)
### JSON Schema Support
[Section titled “JSON Schema Support”](#json-schema-support)
Madbot relies on JSON Schema to describe plugin configuration, connection parameters, and metadata fields. This section explains what schemas are expected, where they live, and how they should be structured.
### What JSON Schemas Are Used For
[Section titled “What JSON Schemas Are Used For”](#what-json-schemas-are-used-for)
JSON Schemas in madbot serve three distinct purposes:
1. Plugin settings schemas (optional and depending on the plugin type)
* Global configuration of a plugin instance
2. Connection field schemas
* Describe connection parameters (host, credentials, tokens, etc.)
3. Metadata field schemas
* Describe metadata fields exposed by metadata plugins
All schemas follow JSON Schema Draft 7+ conventions.
### Plugin Settings Schema
[Section titled “Plugin Settings Schema”](#plugin-settings-schema)
Plugin settings schemas define instance-level configuration for a plugin.
#### Location
[Section titled “Location”](#location)
```bash
madbot_filesystem/static/json/schema/_schema.json
```
#### Characteristics
[Section titled “Characteristics”](#characteristics)
* Root type must be object
* Each setting is defined in properties
* Defaults are strongly recommended
* Validation rules (minimum, enum, pattern, etc.) should be explicit
#### Example
[Section titled “Example”](#example)
```json
{
"type": "object",
"title": "Filesystem Plugin Configuration",
"properties": {
"max_file_size": {
"type": "integer",
"title": "Maximum File Size (MB)",
"description": "Maximum file size to allow for download",
"minimum": 1,
"maximum": 1000,
"default": 100
},
"allowed_extensions": {
"type": "string",
"title": "Allowed File Extensions",
"description": "Comma-separated list of allowed file extensions",
"pattern": "^(\\.\\w+)(,\\s*\\.\\w+)*$"
}
}
}
```
#### Validating Metadata Against JSON Schema
[Section titled “Validating Metadata Against JSON Schema”](#validating-metadata-against-json-schema)
If your plugin needs to validate metadata values against JSON Schema, you can use the following implementation:
```python
from jsonschema import Draft201909Validator
from referencing import Registry, Resource
def validate_metadata_schema(schema, value):
"""
Validate a metadata value against a JSON Schema.
This function ensures that the provided metadata value conforms to the structure
and constraints defined in the schema. It uses the Draft 2019-09 version
of JSON Schema for validation.
Parameters
----------
schema : dict
The JSON Schema to validate against.
value : dict
The metadata object to be validated.
Raises
------
jsonschema.exceptions.ValidationError
If value does not conform to schema.
Examples
--------
>>> schema = {"type": "object", "properties": {"name": {"type": "string"}}}
>>> value = {"name": "test"}
>>> validate_metadata_schema(schema, value) # No exception raised
"""
schema["$schema"] = "https://json-schema.org/draft/2019-09/schema"
registry = Registry(retrieve=Resource.from_contents(schema))
validator = Draft201909Validator(
schema,
registry=registry,
)
validator.validate(value)
```
**Dependencies**: You’ll need to add `jsonschema >= 4.0.0` to your plugin’s `pyproject.toml` dependencies.
### UI Schema for Better User Experience
[Section titled “UI Schema for Better User Experience”](#ui-schema-for-better-user-experience)
If you want to provide a better user experience, you can provide a UI schema to control the appearance and behavior of the metadata fields.
Create `madbot_filesystem/static/json/uischema/filesystem_uischema.json`:
```json
{
"type": "VerticalLayout",
"elements": [
{
"type": "Control",
"scope": "#/properties/max_file_size",
"options": {
"slider": true
}
},
{
"type": "Control",
"scope": "#/properties/allowed_extensions",
"options": {
"placeholder": ".txt,.pdf,.jpg"
}
}
]
}
```
### EditorJS Content Support
[Section titled “EditorJS Content Support”](#editorjs-content-support)
EditorJS is a block-styled editor used in madbot for rich text editing of metadata fields. It provides a structured JSON format for content that includes paragraphs, headers, lists, tables, code blocks, and various other formatting options.
#### How EditorJS is Used in madbot
[Section titled “How EditorJS is Used in madbot”](#how-editorjs-is-used-in-madbot)
In madbot, EditorJS is used as the primary rich text editor for metadata fields that require formatted content, such as descriptions, abstracts, and notes. The content is stored as JSON in a structured format that can be converted to different output formats (HTML, Markdown, plain text) depending on the needs of the plugin or the target system.
The EditorJS JSON structure follows this general format:
```json
{
"blocks": [
{
"type": "paragraph",
"data": {
"text": "This is a paragraph with bold and italic text."
},
"tunes": {
"textVariant": "default"
}
},
{
"type": "header",
"data": {
"level": 2,
"text": "Section Title"
}
}
]
}
```
#### Using EditorJS Content in Plugins
[Section titled “Using EditorJS Content in Plugins”](#using-editorjs-content-in-plugins)
When your plugin receives metadata values from madbot, some fields may contain EditorJS JSON content. Depending on your target system’s requirements, you may need to convert this content to:
* **HTML** (e.g., Zenodo)
* **Markdown** (e.g., GitHub, GitLab)
* **Plain Text** (e.g., ENA)
#### Converting EditorJS Content
[Section titled “Converting EditorJS Content”](#converting-editorjs-content)
If your plugin needs to convert EditorJS content to HTML, Markdown, or plain text, you can use the following reference implementations. Simply copy these functions into your plugin code:
**Helper Function: `deep_json_load`**
```python
import html
import json
import re
def deep_json_load(obj):
"""
Parse recursively a JSON-like structure.
Parameters
----------
obj : Any
A JSON string, list, dict, or primitive type.
Returns
-------
Any
A Python object with all nested JSON strings parsed into native types.
"""
if isinstance(obj, str):
s = obj.strip()
if s.startswith(("{", "[")):
try:
parsed = json.loads(obj)
return deep_json_load(parsed)
except (json.JSONDecodeError, TypeError):
return obj
return obj
if isinstance(obj, dict):
return {k: deep_json_load(v) for k, v in obj.items()}
if isinstance(obj, list):
return [deep_json_load(elem) for elem in obj]
return obj
```
**Convert to HTML: `convert_editorjs_to_html`**
```python
import json
import re
def convert_editorjs_to_html(json_to_convert):
"""
Convert EditorJS content to HTML format.
This function converts EditorJS JSON content to HTML format,
supporting various block types like paragraphs, headers, lists, tables, and code blocks.
Parameters
----------
json_to_convert : dict or str
JSON from EditorJS to convert to HTML.
Returns
-------
str
HTML formatted description.
"""
if not json_to_convert:
return ""
html_parts = []
def process_list_items(items, style, level=0):
if style == "unordered":
tag = "ul"
elif style == "ordered":
tag = "ol"
elif style == "checklist":
tag = "ul"
else:
return ""
result = [f"<{tag}>"]
for item in items:
content = item.get("content", "")
if style == "checklist":
checked = item.get("meta", {}).get("checked", False)
checkbox = "☑" if checked else "☐"
result.append(f"{checkbox} {content} ")
else:
result.append(f"{content} ")
nested_items = item.get("items", [])
if nested_items:
result.append(process_list_items(nested_items, style, level + 1))
result.append(f"{tag}>")
return "\n".join(result)
if not isinstance(json_to_convert, dict):
try:
json_to_convert = deep_json_load(json_to_convert)
except (json.JSONDecodeError, TypeError) as e:
raise ValueError(
{
"error": "Invalid JSON",
"original": json_to_convert,
}
) from e
for block in json_to_convert.get("blocks", []):
block_type = block.get("type")
block_data = block.get("data", {})
variant = block.get("tunes", {}).get("textVariant", "")
if block_type == "paragraph":
text = block_data.get("text", "")
# Handle inline formatting
text = (
text.replace("", "")
.replace(" ", "")
.replace("", "")
.replace(" ", "")
.replace('', "")
.replace("", "")
.replace('', "")
.replace(" ", " ")
.replace('', "")
.replace(" ", " ")
)
# Handle URLs
url_pattern = r'([^<]+) '
text = re.sub(url_pattern, r'\2 ', text)
# Handle blockquote styles
if variant in ["citation", "call-out", "details"]:
prefix = ""
if variant == "call-out":
prefix = "💡 "
elif variant == "details":
prefix = "ℹ️ "
html_parts.append(f"{prefix}{text} ")
else:
html_parts.append(f"{text}
")
elif block_type == "header":
level = block_data.get("level", 1)
text = block_data.get("text", "")
html_parts.append(f"{text} ")
elif block_type == "list":
items = block_data.get("items", [])
style = block_data.get("style")
html_parts.append(process_list_items(items, style))
elif block_type == "table":
content = block_data.get("content", [])
with_headings = block_data.get("withHeadings", False)
if content:
html_parts.append("")
if with_headings:
header_row = "".join(f"{col} " for col in content.pop(0))
html_parts.append(f"{header_row} ")
for row in content:
data_row = "".join(f"{col} " for col in row)
html_parts.append(f"{data_row} ")
html_parts.append("
")
elif block_type == "code":
code = block_data.get("code", "")
html_parts.append(f"{code} ")
return "\n".join(html_parts)
```
**Convert to Markdown: `convert_editorjs_to_markdown`**
````python
import json
import re
def convert_editorjs_to_markdown(json_to_convert):
"""
Convert EditorJS content to Markdown format.
This function converts EditorJS JSON content to Markdown format,
supporting various block types like paragraphs, headers, lists, tables, and code blocks.
Parameters
----------
json_to_convert : dict or str
JSON from EditorJS to convert to Markdown.
Returns
-------
str
Markdown formatted description.
"""
if not json_to_convert:
return ""
markdown_parts = []
def process_list_items(items, style, level=0, counter=None):
result = []
if counter is None:
counter = {}
if level not in counter:
counter[level] = 1
for item in items:
content = item.get("content", "")
indent = " " * level
if style == "unordered":
result.append(f"{indent}- {content}")
elif style == "ordered":
result.append(f"{indent}{counter[level]}. {content}")
counter[level] += 1
elif style == "checklist":
checked = item.get("meta", {}).get("checked", False)
checkbox = "x" if checked else " "
result.append(f"{indent}- [{checkbox}] {content}")
nested_items = item.get("items", [])
if nested_items:
result.extend(
process_list_items(nested_items, style, level + 1, counter)
)
return result
if not isinstance(json_to_convert, dict):
try:
json_to_convert = deep_json_load(json_to_convert)
except (json.JSONDecodeError, TypeError) as e:
raise ValueError(
{
"error": "Invalid JSON",
"original": json_to_convert,
}
) from e
for block in json_to_convert.get("blocks", []):
block_type = block.get("type")
block_data = block.get("data", {})
variant = block.get("tunes", {}).get("textVariant", "")
if block_type == "paragraph":
text = block_data.get("text", "")
text = (
text.replace("", "*")
.replace(" ", "*")
.replace("", "**")
.replace(" ", "**")
.replace('', "`")
.replace("", "`")
.replace('', "")
.replace(" ", "")
.replace('', "")
.replace(" ", "")
)
url_pattern = r'([^<]+) '
text = re.sub(url_pattern, r"[\2](\1)", text)
if variant in ["citation", "call-out", "details"]:
prefix = ""
if variant == "call-out":
prefix = "💡 "
elif variant == "details":
prefix = "ℹ️ "
markdown_parts.append(f"> {prefix}{text}\n")
else:
markdown_parts.append(f"{text}\n")
elif block_type == "header":
level = block_data.get("level", 1)
text = block_data.get("text", "")
markdown_parts.append(f"{'#' * level} {text}\n")
elif block_type == "list":
items = block_data.get("items", [])
style = block_data.get("style")
list_items = process_list_items(items, style)
markdown_parts.extend(item + "\n" for item in list_items)
elif block_type == "table":
content = block_data.get("content", [])
with_headings = block_data.get("withHeadings", False)
if content:
if with_headings:
heading = content.pop(0)
header_row = " | ".join(heading)
markdown_parts.append(f"| {header_row} |")
else:
header_row = " | ".join([""] * len(content[0]))
markdown_parts.append(f"| {header_row} |")
separator = " | ".join(["---"] * len(content[0]))
markdown_parts.append(f"| {separator} |")
for row in content:
data_row = " | ".join(row)
markdown_parts.append(f"| {data_row} |")
markdown_parts.append("\n")
elif block_type == "code":
code = block_data.get("code", "")
markdown_parts.append(f"```\n{code}\n```\n")
return "\n".join(markdown_parts)
````
**Convert to Plain Text: `convert_editorjs_to_plain`**
```python
import json
import re
def convert_editorjs_to_plain(json_to_convert):
"""
Convert EditorJS content to plain text format.
This function converts EditorJS JSON content to plain text format,
removing all formatting and supporting various block types.
Parameters
----------
json_to_convert : dict or str
JSON from EditorJS to convert to plain text.
Returns
-------
str
Plain text formatted description.
"""
if not json_to_convert:
return ""
block_texts = []
def normalize_text(text):
"""Normalize text for plain-text export while preserving line breaks."""
text = html.unescape(text or "")
text = text.replace("\u00A0", " ")
text = text.replace("\r\n", "\n").replace("\r", "\n")
normalized_lines = []
for line in text.split("\n"):
normalized_line = re.sub(r"[ \t]+", " ", line).strip()
normalized_lines.append(normalized_line)
return "\n".join(normalized_lines).strip()
def process_list_items(items, level=0):
result = []
for item in items:
content = normalize_text(item.get("content", ""))
indent = " " * level
result.append(f"{indent}- {content}")
nested_items = item.get("items", [])
if nested_items:
result.extend(process_list_items(nested_items, level + 1))
return result
if not isinstance(json_to_convert, dict):
try:
json_to_convert = deep_json_load(json_to_convert)
except (json.JSONDecodeError, TypeError) as e:
raise ValueError(
{
"error": "Invalid JSON",
"original": json_to_convert,
}
) from e
for block in json_to_convert.get("blocks", []):
block_type = block.get("type")
block_data = block.get("data", {})
if block_type == "paragraph":
text = block_data.get("text", "")
text = (
text.replace(" ", "\n")
.replace("", "")
.replace(" ", "")
.replace("", "")
.replace(" ", "")
.replace('', "")
.replace("", "")
.replace('', "")
.replace(" ", "")
.replace('', "")
.replace(" ", "")
)
# Preserve links as plain text with URL
def replace_link(match):
href = match.group(1).strip()
label = match.group(2).strip()
if not href:
return label
if not label or label == href:
return href
return f"{label} ({href})"
text = re.sub(r'([^<]*) ', replace_link, text)
block_texts.append(normalize_text(text))
elif block_type == "header":
text = block_data.get("text", "")
block_texts.append(normalize_text(text))
elif block_type == "list":
items = block_data.get("items", [])
list_items = process_list_items(items)
block_texts.append("\n".join(list_items).strip())
elif block_type == "table":
content = block_data.get("content", [])
table_rows = [
normalize_text(" ".join(str(cell) for cell in row)) for row in content
]
block_texts.append("\n".join(table_rows).strip())
elif block_type == "code":
code = block_data.get("code", "")
block_texts.append(normalize_text(code))
return "\n\n".join(part for part in block_texts if part)
```
**Note**: These EditorJS conversion functions use the `deep_json_load` helper function shown above. Make sure to include it in your plugin if you use any of the conversion functions.
## Metadata Field Slug Structure in Plugins
[Section titled “Metadata Field Slug Structure in Plugins”](#metadata-field-slug-structure-in-plugins)
Each plugin can define **metadata fields** that are uniquely identified using a **slug** — a structured, machine-readable identifier.
The general form of a slug is:
```text
__[__]
```
### Components
[Section titled “Components”](#components)
1. **``**
* The first part of the slug must always be the plugin name.
* It identifies which plugin the field belongs to.
* Example: `zenodo`, `darwin_core`
2. **``** *(optional)*
* Used when the plugin defines fields for a specific metadata object type.
* If included, it appears **between double underscores** after the plugin name.
* Example: `dwc` in `darwin_core__dwc__vertical_datum`
3. **``**
* The actual name of the metadata field.
* Should be descriptive, lowercase, and use underscores instead of spaces.
* Example: `title`, `vertical_datum`
### Examples of Valid Slugs
[Section titled “Examples of Valid Slugs”](#examples-of-valid-slugs)
* `zenodo__title` → Plugin: `zenodo`, Field: `title`
* `darwin_core__dwc__vertical_datum` → Plugin: `darwin_core`, Metadata Object Type: `dwc`, Field: `vertical_datum`
* `myplugin__fieldname` → Plugin: `myplugin`, Field: `fieldname`
* `myplugin__object_type__fieldname` → Plugin: `myplugin`, Metadata Object Type: `object_type`, Field: `fieldname`
### Rules
[Section titled “Rules”](#rules)
* Use only **lowercase letters, digits, underscores, or hyphens**.
* The slug must start with the plugin name followed by `__`.
* Only one or two double-underscore sections are allowed:
* `plugin__field`
* `plugin__metadata_object_type__field`
* Example of invalid slugs:
* `Plugin__Title` (uppercase letters)
* `plugin__metadata__object__field` (too many sections)
* `plugin-field` (missing double underscores)
This ensures that all plugin metadata fields are uniquely and predictably identified across madbot.
## ENA Plugin
[Section titled “ENA Plugin”](#ena-plugin)
### ENA Overview
[Section titled “ENA Overview”](#ena-overview)
The ENA (European Nucleotide Archive) plugin provides submission support for biological sequence data. Its metadata field schemas are **auto-generated** from ENA’s public checklist API rather than written by hand, ensuring they always reflect the official ENA specification.
Each ENA sample field has a single **canonical slug** shared across all checklists that include it:
```plaintext
ena__sample__elevation
ena__sample__collection_date
```
The checklist code (`erc000029`, `erc000011`, etc.) is **not** part of the slug. Which checklists use a field and at which requirement level (mandatory / recommended / optional) is stored separately in `madbot_ena/checklists.py`.
### Schema Generation
[Section titled “Schema Generation”](#schema-generation)
The generator script fetches every ENA sample checklist XML from the EBI API, deduplicates fields that appear in multiple checklists, and writes one JSON schema file per unique field.
**What the script does, step by step:**
1. **Fetches** all ENA checklist XMLs from `https://www.ebi.ac.uk/ena/browser/api/xml/ERC0000` for N = 11 to 59.
2. **Parses** each field inside every `` block — name, description, format, restriction pattern, allowed values, and units.
3. **Deduplicates** fields by structural fingerprint. Two fields with the same name and the same validation rules share one output file (e.g. `elevation.json`) with one canonical slug (`ena__sample__elevation`).
4. **Writes** one JSON schema file per unique field under:
```plaintext
madbot_ena/static/json/schema/sample/
```
5. **Updates** `patterns.json` an internal registry that tracks which regex patterns are used across fields and which checklists reference them, used to generate human-readable help text.
6. **Writes** `madbot_ena/checklists.py` a plain Python dict mapping each checklist code to its title, description, and its fields pre-bucketed by requirement level.
7. **Writes** `madbot_ena/static/json/schema/checklist.json` the JSON schema for the checklist selector field shown in the submission UI.
> **Note:** Checklist names in `patterns.json` may appear as either a human-readable label (e.g. `GSC MIxS host associated`) or as a bare ERC code (e.g. `ERC000013`). This reflects what ENA’s API returns in the `` element for each checklist, some checklists have a descriptive label registered, others only expose their accession code.
### Running the Generator
[Section titled “Running the Generator”](#running-the-generator)
Run the script from the root of the `madbot_ena` plugin:
```bash
pixi run python madbot_ena/utils/generateMetadataJsonSchema.py
```
Re-run it whenever ENA updates its checklists (new fields, new allowed values, new checklists). The output files should be committed to the repository.
> **Requirements:** the script needs network access to reach `https://www.ebi.ac.uk`. It has no other external dependencies beyond the packages already declared in `pyproject.toml`.
### Schema File Structure
[Section titled “Schema File Structure”](#schema-file-structure)
Each generated file in `madbot_ena/static/json/schema/sample/` is a standard JSON Schema fragment. The `level` (mandatory / recommended / optional) is **not stored in the schema file**, it is a property of the relationship between a field and a checklist, and lives exclusively in `checklists.py`. Depending on the field type, the schema takes one of the following shapes:
**Text field with a regex restriction:**
```json
{
"title": "Elevation",
"originalTitle": "elevation",
"description": "The elevation of the sampling site as measured by the vertical distance from mean sea level.",
"oneOf": [
{
"title": "Value available",
"type": "object",
"properties": {
"status": { "const": "Value available" },
"value": {
"type": "string",
"pattern": "-?[0-9]+(\\.[0-9]+)?"
}
}
},
{
"title": "Value unavailable",
"type": "object",
"properties": {
"status": { "const": "Value unavailable" }
}
}
]
}
```
**Text choice field (controlled vocabulary):**
```json
{
"title": "Library layout",
"originalTitle": "library_layout",
"description": "Sequencing library layout.",
"type": "string",
"enum": ["SINGLE", "PAIRED"]
}
```
**Field with a unit:**
```json
{
"title": "Sample volume or weight for DNA extraction",
"originalTitle": "sample_volume_or_weight_for_dna_extraction",
"description": "Volume (ml) or mass (g) of total collected sample processed for DNA extraction.",
"type": "object",
"properties": {
"value": {
"type": "string",
"pattern": "[0-9]+(\\.[0-9]+)?"
},
"unit": {
"type": "string",
"enum": ["g", "ml", "mg", "ng", "l"]
}
},
"required": ["value", "unit"]
}
```
The key properties present in every schema file are:
| Key | Description |
| ---------------- | -------------------------------------------------------- |
| `title` | Human-readable field name (derived from the ENA `LABEL`) |
| `originalTitle` | Raw field name exactly as returned by ENA’s API |
| `description` | Field description from ENA |
| `type` / `oneOf` | JSON Schema validation rules for the field value |
| `pattern` | Regex constraint on the value, when applicable |
| `enum` | Allowed values for controlled vocabulary fields |
| `fieldgroup` | ENA field group the field belongs to (e.g. `Organism`) |
> **Note:** There is no `level` key in individual schema files. Requirement levels (mandatory / recommended / optional) are a checklist-scoped property and are stored in `checklists.py` only.
### Checklist Configuration
[Section titled “Checklist Configuration”](#checklist-configuration)
`madbot_ena/checklists.py` is the single source of truth for which fields each checklist requires, and at which level. It is auto-generated, **do not edit manually**.
```python
ENA_CHECKLIST_CONFIGS = {
"erc000011": {
"title": "ERC000011 - GSC MIxS plant associated",
"description": "Minimum information about a MIxS plant-associated sample.",
"fields": {
"mandatory": ["ena__sample__collection_date", "ena__sample__lat_lon", ...],
"recommended": ["ena__sample__elevation", ...],
"optional": ["ena__sample__depth", ...],
},
},
...
}
```
At runtime, `plugins.py` uses two utility classes from `madbot_ena/utils/checklist_handler.py` to convert this dict into fully typed metadata object types:
**`ChecklistFieldAssociation`**
Couples a `FieldRepresentation` (resolved from the slug at runtime after `add_fields()` has loaded all JSON schema files) to a requirement level string. It is the explicit, typed representation of the statement *“this field is mandatory for this checklist”*.
```python
@dataclass
class ChecklistFieldAssociation:
field: FieldRepresentation # resolved from slug at runtime
level: Literal["mandatory", "recommended", "optional"]
```
**`ChecklistMetadataObjectType`**
Subclass of `MetadataObjectType` that takes a `checklist_code` and a list of `ChecklistFieldAssociation` objects. It derives the three bucket lists (`mandatory_fields`, `recommended_fields`, `optional_fields`) automatically in `model_post_init`, preserving full backward compatibility with all existing consumers.
```python
class ChecklistMetadataObjectType(MetadataObjectType):
checklist_code: str
field_associations: list[ChecklistFieldAssociation]
def model_post_init(self, __context: Any) -> None:
self.mandatory_fields = [a.field for a in self.field_associations if a.level == "mandatory"]
self.recommended_fields = [a.field for a in self.field_associations if a.level == "recommended"]
self.optional_fields = [a.field for a in self.field_associations if a.level == "optional"]
```
**`build_metadata_object_types()` in `plugins.py`**
Iterates over `ENA_CHECKLIST_CONFIGS` and produces one `ChecklistMetadataObjectType` per checklist. No manual field bucketing is needed, adding a new checklist only requires re-running the generator.
## Keeping Plugins Up to Date
[Section titled “Keeping Plugins Up to Date”](#keeping-plugins-up-to-date)
Whenever plugin field schemas are added, removed, or modified, including after re-running the ENA schema generator, you must reload the plugins into the database:
```bash
pixi run madbot reload_plugins
```
This command synchronises the PluginRawSchema and PluginMetadataField tables with the current state of all installed plugins. Without it, any new or changed fields will not be visible in the application.
# Develop against a local plugins_api
> Make a local madbot use your checkout of plugin_api instead of the released plugins-api package.
By default, madbot installs `plugins-api` from the GitLab package registry: a fresh clone, a test installation or a server needs nothing else. When you change `plugin_api/` itself and want madbot to run your changes, switch to your local checkout.
This page assumes the [development setup](/contribute/development-setup/).
## Use the local checkout
[Section titled “Use the local checkout”](#use-the-local-checkout)
In `api/.env`:
```bash
MADBOT_PLUGIN_API_LOCAL=true
```
pixi reads it each time it activates an environment and puts your local `plugin_api/` ahead of the installed package. The setting applies from the next `pixi run` or `pixi shell`, to every pixi environment, until you set it back to `false`.
To use the other source for a single command, for example to run the tests against the released package:
```bash
MADBOT_PLUGIN_API_LOCAL=false pixi run test
```
The local checkout is the `plugin_api` folder next to `api/`. To use another folder, set `MADBOT_PLUGIN_API_DIR` in `api/.env`, as a path relative to the root of the repository.
## Check which source is in use
[Section titled “Check which source is in use”](#check-which-source-is-in-use)
```bash
pixi run list-plugins
```
The released `plugins-api` package stays installed underneath, so `pixi list` keeps showing its version. Trust the `plugins-api source` line printed by `pixi run list-plugins`, and at the end of every `pixi run install-plugins`.
## Add a dependency to plugins_api
[Section titled “Add a dependency to plugins_api”](#add-a-dependency-to-plugins_api)
pixi resolves the dependencies of the released `plugins-api`, not those of your checkout. A dependency you add to `plugin_api/pyproject.toml` is not installed, and its import fails when madbot runs. Until a release of `plugins-api` declares it, install it in both environments yourself:
```bash
pixi run -e default pip install
pixi run -e dev pip install
```
This leaves `pixi.lock` untouched, as it should for a dependency that is not released yet. Once the new `plugins-api` is published and its version range is raised in `api/pyproject.toml`, pixi installs the dependency itself.
## A local source that does not go away
[Section titled “A local source that does not go away”](#a-local-source-that-does-not-go-away)
If `pixi run list-plugins` reports a local source while `MADBOT_PLUGIN_API_LOCAL` is `false`, the environment may still hold a copy of `plugins-api` installed by hand, for example with `pip install -e ../plugin_api`. It overrides the setting. `pixi run install-plugins` detects it and asks to run the `pixi reinstall plugins-api` commands that remove it.
# Set up a plugin repository
> What a madbot plugin repository needs around its code — dependency conventions, quality and security jobs, and the weekly security scan.
The [plugin development guide](/extend/plugins/development-guide/) covers writing the plugin itself: inheriting the base classes, declaring metadata fields, installing it locally. This page covers the repository around it. Everything here is per project: each plugin lives in its own GitLab repository, pins its own dependencies and carries its own CI, so nothing is inherited from `madbot`.
Plugins live under [`ifb-elixirfr/madbot/plugins`](https://gitlab.com/ifb-elixirfr/madbot/plugins), in `official/` or `community/`. The steps are the same for both.
## 1. Declare the quality tooling
[Section titled “1. Declare the quality tooling”](#1-declare-the-quality-tooling)
In `pyproject.toml`, the dev extra holds the tools that the CI runs, and the two that publish a release:
```toml
[project.optional-dependencies]
dev = [
"ruff",
"bandit[toml]",
"safety >= 3.8.0",
"build >= 1.4.2, < 2",
"twine >= 6.2.0, < 7",
]
```
`pip` and `setuptools` carry advisories of their own: give them a floor in `[tool.pixi.dependencies]`, and in the build system.
```toml
[tool.pixi.dependencies]
pip = ">=26.2.2,<27"
setuptools = ">=83.0.0"
[build-system]
requires = ["setuptools >= 83.0.0"]
build-backend = "setuptools.build_meta"
```
## 2. Declare the pixi tasks
[Section titled “2. Declare the pixi tasks”](#2-declare-the-pixi-tasks)
The CI calls tasks, never raw commands, so the same checks run the same way on a laptop and in a pipeline:
```toml
[tool.pixi.tasks]
lint = { cmd = "ruff check .", default-environment = "dev" }
format = { cmd = "ruff format .", default-environment = "dev" }
format-check = { cmd = "ruff format --diff .", default-environment = "dev" }
safety = { cmd = "safety check", default-environment = "dev" }
bandit = { cmd = "bandit -c pyproject.toml -r ", default-environment = "dev" }
quality-check = { depends-on = [
{ task = "lint" },
{ task = "format-check" },
{ task = "bandit" },
{ task = "safety" }
] }
```
Run `pixi run quality-check` before opening your first merge request. A new repository usually fails `safety` straight away: see [step 5](#5-fix-what-safety-reports-and-record-why).
## 3. Get `plugins-api` from the madbot registry
[Section titled “3. Get plugins-api from the madbot registry”](#3-get-plugins-api-from-the-madbot-registry)
`plugins-api` is published to the package registry of the madbot project on GitLab, not to PyPI. Depend on the major your plugin is written for, and add the registry as an extra index, for pixi:
```toml
[project]
dependencies = [
"plugins-api >=3.0.0,<4",
]
[tool.pixi.pypi-options]
extra-index-urls = [
"https://gitlab.com/api/v4/projects/ifb-elixirfr%2Fmadbot%2Fmadbot/packages/pypi/simple",
]
```
and for pip, in `.gitlab-ci.yml`:
```yaml
variables:
PIP_EXTRA_INDEX_URL: "https://gitlab.com/api/v4/projects/50871918/packages/pypi/simple"
```
To run your plugin against a change of `plugin_api/` that is not released yet, see [Develop against a local plugins_api](/extend/plugins/local-plugins-api/).
### Keep Django inside the API’s range
[Section titled “Keep Django inside the API’s range”](#keep-django-inside-the-apis-range)
A plugin runs inside the Django process of `madbot-api`. Whatever Django your plugin resolves in its own environment is not the one it runs with: in production it gets the API’s. `plugins-api` carries the right range, so a plugin that depends on it needs nothing more. If your plugin declares Django itself, pin it to the range that `madbot-api` uses, currently `>=5.2.18,<5.3`.
A loose `django>=4.1` floats to the newest release, drifts out of the API’s range, and collects advisories that do not even apply to how the plugin is deployed. That happened, and cost eleven advisories on one plugin.
## 4. Add the CI file
[Section titled “4. Add the CI file”](#4-add-the-ci-file)
Copy `.gitlab-ci.yml` from an official plugin. The parts that matter:
```yaml
.base:
retry:
max: 2
when:
- api_failure
- stuck_or_timeout_failure
- runner_system_failure
tags: [docker, XL, nncr, idris]
image:
name: ghcr.io/prefix-dev/pixi:latest
pull_policy: always
before_script:
- pixi global install git
- pixi install -e dev
stages:
- 💎 quality
- 🛡️ security
Code audit (ruff):
extends: .base
stage: 💎 quality
script:
- pixi run lint
- pixi run format-check
only:
- merge_requests
Dependencies vulnerability (safety):
extends: .base
stage: 🛡️ security
script:
- pixi run safety
only:
- merge_requests
Security breach (bandit):
extends: .base
stage: 🛡️ security
script:
- pixi run bandit
only:
- merge_requests
```
If your plugin publishes releases, add the release stage of an existing plugin as well.
## 5. Fix what safety reports, and record why
[Section titled “5. Fix what safety reports, and record why”](#5-fix-what-safety-reports-and-record-why)
A new repository almost always fails `pixi run safety` on its first run, because its lock has been resolving freely since the day it was created. Fix each finding by pinning above the affected range, with a comment that names the advisory, so the next reader knows why the pin exists:
```toml
# NOTE: Safety reports vulnerability in nltk < 3.10.1 (CVE-2026-72818)
"nltk>=3.10.1",
```
Then run `pixi lock` and `pixi run safety` again. Worth knowing:
* Prefer a **lock refresh** to a manifest change when the existing range already allows a fixed version. `pixi update ` often clears an advisory without relaxing or tightening anything you declared.
* Pin transitive dependencies where they actually come from. `urllib3` and `idna` arrive through `requests`, which is a runtime dependency, so they belong in `dependencies` and not in the dev extra.
* When an advisory has no fixed version yet, and the affected code is never called, ignore that one advisory in the `safety` task, with a comment that says why and when to drop it:
```toml
# NOTE: SFTY-20260902-58666 flags every nltk release, with no fixed version
# yet. nltk is only pulled by safety itself, which never calls the affected
# APIs. Drop the ignore once nltk ships a fix.
safety = { cmd = "safety check --ignore SFTY-20260902-58666", default-environment = "dev" }
```
If `safety` reports something on your machine that is not in `pixi.lock`, it is scanning a Python outside the pixi environment: check with `grep -c '' pixi.lock` before chasing it.
## 6. Scan every week
[Section titled “6. Scan every week”](#6-scan-every-week)
A safety advisory is published against code that is already released, so nothing in `merge_requests` fires when one lands: without a scheduled run, an advisory stays invisible until someone happens to open a merge request. That is how CVE-2026-13346 went unnoticed for weeks.
### Run safety on schedules too
[Section titled “Run safety on schedules too”](#run-safety-on-schedules-too)
Add `schedules` to the safety job, and a report of the dependencies that are behind, which only runs on schedules:
```yaml
Dependencies vulnerability (safety):
extends: .base
stage: 🛡️ security
script:
- pixi run safety
only:
- merge_requests
# Weekly schedule. A safety advisory is published against code already
# released, so nothing in `merge_requests` fires when one lands.
- schedules
Dependency updates:
extends: .base
stage: 🛡️ security
script:
# `update`: newer versions the current constraints already allow.
- pixi update --dry-run --no-install
# `upgrade`: newer versions a pin in pyproject.toml is blocking.
- pixi upgrade --dry-run --no-install
allow_failure: true
only:
- schedules
```
`Dependency updates` is a report, not a breakage: on a merge request it would be noise. Both pixi commands exit 0 whether or not anything is behind, so the report is the job log, and `--dry-run` writes neither the lock nor the manifest.
### Create the schedule
[Section titled “Create the schedule”](#create-the-schedule)
A pipeline schedule is a project setting, not CI configuration, so it cannot live in `.gitlab-ci.yml`. In the plugin project, open **Build → Pipeline schedules → New schedule**:
* description: `Contrôle de sécurité hebdomadaire`;
* a cron on Monday morning, ten minutes after the previous plugin’s, with the timezone `Europe/Paris`;
* target branch: the default branch, `dev` (or `main`);
* leave **Activated** unchecked until the merge request that adds the `schedules` trigger has landed.
Then check it, because the failure is silent: **a schedule whose pipeline matches no job creates no pipeline at all, and GitLab reports nothing**, neither in the schedule list nor in the pipeline list. After activating it, run the schedule once from the same page and check that the pipeline holds `Dependencies vulnerability (safety)`. Do not wait until Monday to find out.
### Who owns the schedule
[Section titled “Who owns the schedule”](#who-owns-the-schedule)
A schedule is owned by whoever creates it, and **runs with that person’s permissions**. If they are later blocked or removed from the project, the schedule silently becomes inactive. Create schedules with the shared bot account rather than your own; if one becomes inactive, any Maintainer can reactivate it with **Take ownership**.
Creating a schedule that targets a protected branch also requires permission to merge into that branch: the account needs the Maintainer role, not Developer.
## Checklist
[Section titled “Checklist”](#checklist)
* [ ] ruff, bandit and safety in the dev extra
* [ ] pip and setuptools floors in `[tool.pixi.dependencies]` and `[build-system]`
* [ ] `lint`, `format-check`, `safety`, `bandit` and `quality-check` pixi tasks
* [ ] `plugins-api` from the madbot registry, in pixi and in the CI
* [ ] Django comes from `plugins-api`, or is pinned to the API’s range
* [ ] `.gitlab-ci.yml` with the quality and security stages
* [ ] `pixi run quality-check` passes locally
* [ ] the safety job runs on `schedules` as well as `merge_requests`
* [ ] a schedule-only, `allow_failure` `Dependency updates` job
* [ ] a pipeline schedule, owned by the bot account
* [ ] the schedule run once by hand, with the safety job in its pipeline
# Enable the global search
> Turn on Meilisearch for the global workspace search on a madbot instance.
The global workspace search is backed by [Meilisearch](https://www.meilisearch.com/). It is **off by default** (`SEARCH_ENABLED=false`): no indexing task is dispatched, `/api/search` answers 503 and the client hides its entry point.
This page is for people who run a madbot instance. For a local development checkout, see [Start Meilisearch](/contribute/development-setup/#start-meilisearch-optional).
## Install and run Meilisearch
[Section titled “Install and run Meilisearch”](#install-and-run-meilisearch)
Prefer a dedicated host when possible: memory usage scales with index size and (re)indexing is CPU-intensive. Install Meilisearch with the [official install script](https://www.meilisearch.com/docs/resources/self_hosting/getting_started/install_locally) and run it under systemd or Supervisor, with `--env production`. Bind it to an address only the API can reach: `127.0.0.1:7700` when it shares the API host, otherwise a private address closed by a firewall.
Choose a master key of at least 16 bytes. Keep it for administrators only: it grants every right on the Meilisearch instance, including creating API keys. Production mode requires that key and disables Meilisearch’s preview web UI.
## Restrict the API key
[Section titled “Restrict the API key”](#restrict-the-api-key)
Do not put the master key in the madbot configuration. Create a key limited to the `workspace_search` index and to what the API uses:
```bash
curl -X POST "$MEILISEARCH_HOST/keys" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
--data '{
"description": "madbot API",
"actions": ["search", "documents.add", "documents.get", "documents.delete",
"indexes.create", "indexes.get", "indexes.update",
"settings.get", "settings.update", "tasks.get"],
"indexes": ["workspace_search"],
"expiresAt": null
}'
```
Put the `key` of the response in the madbot environment as `MEILISEARCH_API_KEY`.
## Configure madbot
[Section titled “Configure madbot”](#configure-madbot)
In the API environment (for example `/etc/madbot/madbot.env`):
```bash
SEARCH_ENABLED=true
MEILISEARCH_HOST=http://:7700
MEILISEARCH_API_KEY=
```
`SEARCH_ENABLED=true` must be present: the flag defaults to off, and without it the search simply disappears from the interface. Restart the API and the Celery workers so they pick up the settings.
Enabling the search also registers a Meilisearch check on `/health-check` as a **non-critical** service: an unreachable Meilisearch shows as degraded there without failing the endpoint.
## Build the index
[Section titled “Build the index”](#build-the-index)
After enabling the search, and after upgrades that change filterable attributes, rebuild the index from the database:
```bash
madbot rebuild_search_index
```
See [`rebuild_search_index`](/run/reference/commands/#rebuild_search_index). The index is never emptied first, so the search keeps answering while the command runs. Day-to-day updates then go through Celery: keep a worker running.
# Management commands
> The madbot management commands, what they do and their options.
madbot is a Django application: besides Django’s own commands (`migrate`, `createsuperuser`, `collectstatic`…), it adds the commands below. Run them with the `madbot` entry point of the API package, for example `madbot list_plugins`. From a development checkout, prefix them with `pixi run` in `api/`.
Every command accepts Django’s common options, including `--verbosity {0,1,2,3}` and `--help`.
## Services
[Section titled “Services”](#services)
### `celery`
[Section titled “celery”](#celery)
Start a Celery worker. When `DEBUG` is on, the worker restarts whenever the code changes.
Caution
The command first stops every running process named `celery -A madbot_api worker` on the machine, including the workers of another checkout.
### `beat`
[Section titled “beat”](#beat)
Start Celery Beat, the scheduler of the periodic tasks, with the database scheduler of `django-celery-beat`. It warns when no periodic task exists: run [`create_periodic_tasks`](#create_periodic_tasks) first.
## Setup and maintenance
[Section titled “Setup and maintenance”](#setup-and-maintenance)
### `initialise_madbot_metadata_fields`
[Section titled “initialise_madbot_metadata_fields”](#initialise_madbot_metadata_fields)
Create or update the metadata schemas and the fields of the madbot referential in the database. Run it after each update of madbot.
### `create_periodic_tasks`
[Section titled “create_periodic_tasks”](#create_periodic_tasks)
Delete all periodic tasks, then create the tasks of madbot:
| Task | Interval |
| ------------------------------------ | ---------- |
| Clear health checks task results | every hour |
| Close expired impersonation sessions | every hour |
| Cleanup node exports | every day |
### `reload_plugins`
[Section titled “reload_plugins”](#reload_plugins)
Read every installed plugin and store in the database its connection and settings schemas, its metadata object types and the mappings between its fields and the madbot metadata fields. Run it after installing, removing or updating a plugin.
### `list_plugins`
[Section titled “list_plugins”](#list_plugins)
List the installed plugins by type, then say which `plugins_api` is imported: the released package or a local checkout.
| Option | Effect |
| -------------------------------------------------- | ---------------------------------------------- |
| `--type {connection,data,submission,metadata,all}` | Only list one type of plugin (default: `all`). |
| `--verbosity 1` | Plugin names only. |
| `--verbosity 2` | Plugins grouped by type (default). |
| `--verbosity 3` | Plugins grouped by type, with details. |
### `cleanup_unverified_users`
[Section titled “cleanup_unverified_users”](#cleanup_unverified_users)
Delete the inactive accounts whose email address was never verified, once the confirmation period (`ACCOUNT_EMAIL_CONFIRMATION_EXPIRE_DAYS`) is over, then delete the expired invitations.
### `rebuild_search_index`
[Section titled “rebuild_search_index”](#rebuild_search_index)
Configure and (re)populate the Meilisearch `workspace_search` index from the current database. Requires `SEARCH_ENABLED=true` and a reachable Meilisearch server; see [Enable the global search](/run/enable-global-search/) and [Start Meilisearch](/contribute/development-setup/#start-meilisearch-optional).
The command writes every searchable object, then removes documents for objects that no longer exist. It does **not** empty the index first, so the search keeps answering while it runs. Run it after enabling the search, and after upgrades that change filterable attributes. Day-to-day updates then go through Celery.
| Option | Effect |
| -------------- | -------------------------------------------------------------------- |
| `--batch-size` | Number of documents sent to Meilisearch per batch (default: `1000`). |
## Test data
[Section titled “Test data”](#test-data)
These commands create workspaces for development and tests. Do not run them on a production instance.
### `create_demo_workspace`
[Section titled “create_demo_workspace”](#create_demo_workspace)
Create a demo workspace for a user: an ISA structure (investigation, study, assay) with samples and data.
| Option | Effect |
| ------------------ | --------------------------------- |
| `-u`, `--username` | Owner of the workspace. Required. |
### `create_load_workspace`
[Section titled “create_load_workspace”](#create_load_workspace)
Generate a large and reproducible workspace, to test performance. [Measure on a large workspace](/contribute/performance-and-debugging/#measure-on-a-large-workspace) describes the profiles and what the command bypasses.
| Option | Effect |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `--username` | Owner of the workspace. Required. |
| `--profile {small,medium,large}` | Predefined volume, refined by the options below (default: `small`). |
| `--root-nodes`, `--depth`, `--node-per-node` | Shape of the trees. |
| `--data-per-node`, `--samples-per-node` | Data and samples of each node. |
| `--metadata-per-object`, `--metadata-per-data` | Metadata of nodes, samples and data. |
| `--members` | Members invited besides the owner. |
| `--wide-nodes`, `--wide-node-size` | Nodes with many samples and data, added under the root nodes. |
| `--plugin-fields [PLUGIN ...]` | Plugins whose metadata fields are used besides madbot’s (default: `ena`). Without a value, only madbot fields. |
| `--plugin` | Data plugin of the connection holding the data (default: the first installed data plugin). |
| `--seed` | Seed of the generation. Drawn and printed when omitted. |
| `--name` | Name of the workspace (default: derived from the profile and the seed). |
| `--force` | Delete an existing workspace of the same name first. |
| `--dry-run` | Print the planned volume without writing anything. |
# Concepts
> What a workspace, node, data, sample, metadata and submission are in madbot, and how they fit together.
This page defines the concepts and terms used throughout madbot.
## Workspace
[Section titled “Workspace”](#workspace)
A **workspace** is where a project lives in madbot. You create a workspace, invite collaborators and give each of them a role. Workspaces keep projects and their contributors apart: each workspace is independent from the others.
Each workspace has a dashboard that gives an overview of its data, the recent activity and the state of its submissions.
## Nodes
[Section titled “Nodes”](#nodes)
**Nodes** organise the project inside a workspace. They form trees that represent the parts of a research project: a campaign and its sites, a cohort and its visits, a collection and its boxes.
### What a node holds
[Section titled “What a node holds”](#what-a-node-holds)
Each node holds:
* **a title and a description**, in rich text;
* **data**, linked where they are stored;
* **metadata**, which describe the content of the node;
* **samples**, the objects the project studies;
* **child nodes**.
### Inheritance
[Section titled “Inheritance”](#inheritance)
Metadata flow down the tree: a value set on a node applies to its child nodes. You can override an inherited value at any level, while the rest of the tree keeps the shared value.
## Members
[Section titled “Members”](#members)
Workspaces and nodes have members, each with a role. A workspace or a node can have several owners, so that its management is shared. The [roles reference](/use/reference/roles/) lists what each role can do.
## Plugins
[Section titled “Plugins”](#plugins)
**Plugins** connect madbot to other systems. There are three kinds:
* **data plugins** give access to the files and folders of a source;
* **submission plugins** send data and metadata to a repository;
* **metadata field definition plugins** add metadata fields from a standard to the madbot referential.
The [plugins reference](/use/reference/plugins/) lists the available plugins.
## Datalink
[Section titled “Datalink”](#datalink)
A **datalink** links data to a madbot node without copying the data into madbot. Data plugins give access to the data and create the datalinks.
* **No copy**: the data stay where they are.
* **Access on demand**: madbot downloads the data only when a submission needs them.
* **One plugin per kind of source**: each data plugin supports one kind of storage.
### Data associations
[Section titled “Data associations”](#data-associations)
A **data association** groups several data together and can carry its own metadata. For example:
* the two files of paired-end reads;
* processed data and the raw data they come from;
* an analysis script, its input data and its results.
## Sample
[Section titled “Sample”](#sample)
**Samples** are the objects a project studies: a soil core, a material specimen, a cohort participant, an archive document, a biological specimen. They belong to nodes and carry their own metadata.
## Metadata
[Section titled “Metadata”](#metadata)
**Metadata** describe research data and give them context. They can be attached to:
* nodes;
* samples;
* data;
* data associations.
Metadata are inherited:
* **down the node tree**: a value set on a node applies to its child nodes;
* **from samples to data**: data inherit the metadata of the samples they are associated with;
* **with overrides**: an inherited value can be changed at any level.
## Submission
[Section titled “Submission”](#submission)
A **submission** sends data and metadata to an external repository. Submission plugins gather the metadata, organise the files, check them and send them to the repository. This spares manual copying, keeps metadata consistent across platforms and records what was sent.
### Steps of a submission
[Section titled “Steps of a submission”](#steps-of-a-submission)
1. **Collect the metadata** of the submitted data.
2. **Organise the data** as the repository expects them.
3. **Validate** the metadata and the data before sending.
4. **Transfer** them to the repository.
### Metadata objects
[Section titled “Metadata objects”](#metadata-objects)
**Metadata objects** hold the metadata of a submission in units that a repository understands. They mirror the containers of the target repository: for example a study, a sample or an experiment.
# Plugins
> The plugins available for madbot and what each one brings.
Plugins connect madbot to other systems. A plugin can bring one or more of three things:
* **Data**: link the files of a source to madbot nodes.
* **Submission**: send data and metadata to a repository.
* **Metadata fields**: add the fields of a metadata standard to the madbot referential.
Which plugins you can use depends on the instance: the people who run it choose the plugins they install. Each plugin’s README explains how to install and configure it.
## Plugins maintained by the madbot team
[Section titled “Plugins maintained by the madbot team”](#plugins-maintained-by-the-madbot-team)
| Plugin | What it connects | Data | Submission | Metadata fields |
| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | :--: | :--------: | :-------------: |
| [Galaxy](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_galaxy_plugin) | Galaxy, a web platform for data analysis. | ✓ | | |
| [SSHFS](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_sshfs_plugin) | Any storage reachable over SSH: a NAS, a computing cluster. | ✓ | | |
| [GitHub](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_github_plugin) | GitHub repositories. Experimental. | ✓ | | |
| [GitLab](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_gitlab_plugin) | GitLab repositories. Experimental. | ✓ | | |
| [ENA](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_ena_plugin) | The European Nucleotide Archive, for nucleotide sequencing data. | | ✓ | ✓ |
| [Zenodo](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_zenodo_plugin) | Zenodo, a general-purpose open repository. | | ✓ | ✓ |
| [Recherche Data Gouv](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_recherche_data_gouv_plugin) | Recherche Data Gouv, the French national research data repository, based on Dataverse. | | ✓ | ✓ |
| [Dublin Core](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_dublin_core_plugin) | Dublin Core, fifteen core elements to describe any resource. | | | ✓ |
| [Darwin Core](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_darwin_core_plugin) | Darwin Core, a standard for biodiversity data: species occurrences and specimens. | | | ✓ |
| [ISA](https://gitlab.com/ifb-elixirfr/madbot/plugins/official/madbot_isa_plugin) | ISA (Investigation, Study, Assay), a framework for experimental metadata in the life sciences. | | | ✓ |
## Community plugins
[Section titled “Community plugins”](#community-plugins)
| Plugin | What it connects | Data | Submission | Metadata fields |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | :--: | :--------: | :-------------: |
| [S3](https://gitlab.com/ifb-elixirfr/madbot/plugins/community/madbot_s3_plugin) | Any S3-compatible object storage. Experimental. | ✓ | | |
| [OMERO](https://gitlab.com/ifb-elixirfr/madbot/plugins/community/madbot-omero-plugin) | OMERO, a server for microscopy images and their metadata. Experimental. | ✓ | | |
| [ABRomics](https://gitlab.com/ifb-elixirfr/madbot/plugins/community/madbot_community_abromics) | The genomic files of the ABRomics platform. Experimental. | ✓ | | |
## In development
[Section titled “In development”](#in-development)
These plugins are not published yet:
* **Nakala**: submission to Nakala, the Huma-Num repository for the humanities and social sciences, and its metadata fields.
* **eLabFTW**: import of eLabFTW experiments and items as a tree of nodes, and their metadata fields.
# Roles
> What each workspace role and node role can do.
Workspaces and nodes each have their own roles. A workspace or a node can have several owners.
## Workspace roles
[Section titled “Workspace roles”](#workspace-roles)
| Action | Owner | Member |
| ---------------------------- | :---: | :---------------------------------: |
| Access the workspace | ✓ | ✓ |
| Access all nodes | ✓ | Only the nodes they are a member of |
| Create root nodes | ✓ | ✓ |
| Delete the workspace | ✓ | ✗ |
| Manage the workspace members | ✓ | ✗ |
## Node roles
[Section titled “Node roles”](#node-roles)
| Action | Owner | Manager | Contributor | Collaborator |
| ----------------------- | :---: | :-----: | :---------: | :----------: |
| View the node | ✓ | ✓ | ✓ | ✓ |
| Modify the node content | ✓ | ✓ | ✓ | ✗ |
| Create child nodes | ✓ | ✓ | ✓ | ✗ |
| Delete the node | ✓ | ✗ | ✗ | ✗ |
| Manage the node members | ✓ | ✓ | ✗ | ✗ |
# plugins_api 3.0.0
> API reference for the Python package `plugins_api`, generated by starlight-pydocs.
> Rendered pages: https://docs.madbot.france-bioinformatique.fr/extend/plugins/reference/v3/
# plugins_api
*module*
Plugins app for madbot API.
This app contains all plugin-related functionality, split into logical modules.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/__init__.py#L1-1)
**Modules**
- `plugins_api.base`
- `plugins_api.data_plugins`
- `plugins_api.decorators`
- `plugins_api.dtos`
- `plugins_api.exceptions`
- `plugins_api.metadata_plugins`
- `plugins_api.submission_plugins`
- `plugins_api.utils`
---
# plugins_api.base
*module*
Base plugin classes.
This module contains the core plugin classes that define the plugin architecture.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L1-1)
## plugins_api.base.ConnectionPlugin
*class*
```python
class ConnectionPlugin(MadbotPlugin)
```
Bases: `plugins_api.base.MadbotPlugin`
Abstract class for connection plugins.
A connection plugin is a plugin that can be instantiated and used to connect to a specific service.
A connection plugin thus has public and private parameters to establish the connection to the service.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L184-296)
### plugins_api.base.ConnectionPlugin.close
*method*
```python
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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L237-249)
### plugins_api.base.ConnectionPlugin.get_connection_fields
*method* · *abstract* · *classmethod*
```python
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).
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L206-222)
### plugins_api.base.ConnectionPlugin.get_instance_name
*method* · *abstract*
```python
def get_instance_name() -> str
```
Return the instance name of the connection plugin.
**Returns**
- (`str`) — Instance name.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L193-204)
### plugins_api.base.ConnectionPlugin.get_shared_parameters
*method* · *abstract*
```python
def get_shared_parameters() -> dict[str, Any]
```
Return all shared parameters in a cleaned form.
**Returns**
- (`dict`) — Shared parameters cleaned.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L224-235)
### plugins_api.base.ConnectionPlugin.is_sandbox
*method* · *classmethod*
```python
def is_sandbox(shared_parameters: dict[str, Any]) -> bool
```
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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L251-268)
### plugins_api.base.ConnectionPlugin.on_before_store_credentials
*method* · *classmethod*
```python
def on_before_store_credentials(shared_params: dict, private_params: dict) -> dict
```
Transform the private parameters just before they are written to the Vault.
Allows the plugin to transform or enrich the private_params.
By default, returns the params unchanged.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L270-282)
### plugins_api.base.ConnectionPlugin.on_delete_credentials
*method* · *classmethod*
```python
def on_delete_credentials(shared_params: dict, vault_secret: dict) -> None
```
Clean up just before the credentials are deleted 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L284-296)
### plugins_api.base.ConnectionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L82-94)
### plugins_api.base.ConnectionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L113-127)
### plugins_api.base.ConnectionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L68-80)
### plugins_api.base.ConnectionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L24-35)
### plugins_api.base.ConnectionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L96-111)
### plugins_api.base.ConnectionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L37-49)
### plugins_api.base.ConnectionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L51-66)
### plugins_api.base.ConnectionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L129-162)
### plugins_api.base.ConnectionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L164-181)
## plugins_api.base.MadbotPlugin
*class*
```python
class MadbotPlugin(ABC)
```
Bases: `ABC`
Abstract base class for all plugins, declaring basic functions of a plugin.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L20-181)
### plugins_api.base.MadbotPlugin.get_author
*method* · *abstract* · *classmethod*
```python
def get_author() -> str
```
Return plugin author.
**Returns**
- (`str`) — Plugin author.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L82-94)
### plugins_api.base.MadbotPlugin.get_color
*method* · *abstract* · *classmethod*
```python
def get_color() -> str
```
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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L113-127)
### plugins_api.base.MadbotPlugin.get_description
*method* · *abstract* · *classmethod*
```python
def get_description() -> str
```
Return plugin description.
**Returns**
- (`str`) — Plugin description.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L68-80)
### plugins_api.base.MadbotPlugin.get_id
*method* · *classmethod*
```python
def get_id() -> str
```
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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L24-35)
### plugins_api.base.MadbotPlugin.get_logo
*method* · *abstract* · *classmethod*
```python
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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L96-111)
### plugins_api.base.MadbotPlugin.get_name
*method* · *abstract* · *classmethod*
```python
def get_name() -> str
```
Return the plugin name.
**Returns**
- (`str`) — Plugin name.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L37-49)
### plugins_api.base.MadbotPlugin.get_slug
*method* · *abstract* · *classmethod*
```python
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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L51-66)
### plugins_api.base.MadbotPlugin.get_status
*method* · *abstract* · *classmethod*
```python
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:
```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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L129-162)
### plugins_api.base.MadbotPlugin.get_types
*method* · *classmethod*
```python
def get_types() -> list[str]
```
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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L164-181)
---
# plugins_api.data_plugins
*module*
Data plugins.
This module contains plugin classes for data management operations.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L1-1)
## plugins_api.data_plugins.DEFAULT_BATCH_READ_SIZE
*attribute* · *module attribute*
```python
DEFAULT_BATCH_READ_SIZE = 100
```
Default maximum number of ids madbot sends per batch-read call.
Plugins can override ``DataPlugin.get_batch_read_size`` when their source has
a different limit, or return ``None`` to disable chunking.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L18-18)
## plugins_api.data_plugins.DataPlugin
*class*
```python
class DataPlugin(ConnectionPlugin)
```
Bases: `plugins_api.base.ConnectionPlugin`
Abstract class defining the minimum API for a data plugin.
Data plugins connect to external data sources and provide access to files and directories.
They are used to browse, list, and download data from external systems.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L32-383)
### plugins_api.data_plugins.DataPlugin.browse_data_objects
*method* · *abstract*
```python
def browse_data_objects(parent_id: str | None) -> list[PluginDataObject]
```
Return the direct children of a parent data object.
**Parameters**
- `parent_id` (`str or None`) — ID of the parent object. When ``None``, browse from the root of the source (same as passing ``get_root_id()``).
**Returns**
- (`List[PluginDataObject]`) — Direct children of ``parent_id``, or of the root when ``parent_id`` is ``None``.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L129-147)
### plugins_api.data_plugins.DataPlugin.download_data
*method* · *abstract*
```python
def download_data(external_dataobject_id: str, destination_path: str) -> str
```
Download a data object to local storage and returns an download report.
It is **strongly recommended** to implement data integrity verification in this method.
This may include, but is not limited to:
- Checksum validation (e.g., MD5, SHA256) if available.
- File size comparison with the source.
- Any other consistency checks relevant to the data source.
Implementing integrity checks helps prevent data corruption or incomplete downloads,
ensuring reliable processing of the imported data.
**Parameters**
- `external_dataobject_id` (`str`) — Unique identifier of the data object in the external system.
- `destination_path` (`str`) — Local path where the file should be saved.
**Returns**
- (`str`) — Path to the local file.
**Raises**
- `NotImplementedError` — This method must be implemented in a subclass.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L351-383)
### plugins_api.data_plugins.DataPlugin.get_batch_read_size
*method* · *classmethod*
```python
def get_batch_read_size() -> int | None
```
Return how many ids madbot should send per batch-read call.
Madbot uses this when calling ``get_data_objects_by_ids``,
``get_metadata_for_data_objects`` and
``get_data_associations_for_data_objects`` for a long list of ids
on one connection.
**Returns**
- (`int or None`) — A positive integer to split the id list into chunks of that size, or ``None`` to pass the full list in a single call. The default is :data:`DEFAULT_BATCH_READ_SIZE` (100).
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L110-127)
### plugins_api.data_plugins.DataPlugin.get_data_associations_for_data_objects
*method*
```python
def get_data_associations_for_data_objects(object_ids: list[str]) -> dict[str, list[PluginDataAssociation] | PluginError]
```
Return data associations for each requested data object.
Each association represents a group of data objects that should be
associated together. A data object can participate in multiple
associations, each returned as a separate PluginDataAssociation.
Associations should be returned bidirectionally - if data objects A,
B, and C are associated together, then when querying A, B, or C, they
should all return the same association group containing all three.
**Parameters**
- `object_ids` (`list[str]`) — IDs of the data objects.
**Returns**
- (`dict[str, list[PluginDataAssociation] | PluginError]`) — Mapping from object id to its association list, or to a per-id ``PluginError``. Returns ``{}`` when ``object_ids`` is empty. The default implementation returns an empty list for each distinct id, making this method optional for plugins that have no associations. Only requested ids may appear in the result.
> **Notes**
>
> Per-id errors follow the same rules as
> ``get_data_objects_by_ids``. Source-level errors must be raised.
**Examples**
If data object A is associated with B and C in one group:
```pycon
>>> {"A": [PluginDataAssociation(associated_external_ids=["A", "B", "C"])]}
```
If data object A has two separate associations (one with B, one with C):
```pycon
>>> {
... "A": [
... PluginDataAssociation(associated_external_ids=["A", "B"]),
... PluginDataAssociation(associated_external_ids=["A", "C"]),
... ]
... }
```
With metadata:
```pycon
>>> {
... "A": [
... PluginDataAssociation(
... associated_external_ids=["A", "B", "C"],
... metadata=[
... PluginMetadata(
... field=MetadataFieldID(
... slug="association_type",
... source="referential",
... name="Association Type",
... ),
... value=MetadataValue(value="paired"),
... )
... ],
... )
... ]
... }
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L236-302)
### plugins_api.data_plugins.DataPlugin.get_data_objects_by_ids
*method* · *abstract*
```python
def get_data_objects_by_ids(object_ids: list[str]) -> dict[str, PluginDataObject | PluginError]
```
Return detailed information for each requested data object.
Every distinct id from ``object_ids`` must appear in the result, either
as a ``PluginDataObject`` or as the ``PluginError`` raised while reading
that id (for example ``DataNotFoundError`` or ``PluginPermissionError``).
The result must contain **only** those requested ids. Extras should be
ignored if the remote API returns more.
Errors that affect the whole source (see ``SOURCE_ERRORS``) must be
raised, not stored in the result.
Plugins whose source has no batch API can implement this in one line
with ``_read_each``:
```python
def get_data_objects_by_ids(self, object_ids):
return self._read_each(object_ids, self._read_data_object)
```
When the source can answer several ids in one request, no need to call
``_read_each``. Instead, call the remote API directly:
```python
def get_data_objects_by_ids(self, object_ids):
unique_ids = list(dict.fromkeys(object_ids))
try:
remote = self.client.fetch_many(unique_ids)
except ConnectionError as exc:
raise UnreachableError(self.host) from exc
result = {}
for object_id in unique_ids:
item = remote.get(object_id)
if item is None:
result[object_id] = DataNotFoundError(object_id)
else:
result[object_id] = self._to_plugin_data_object(item)
return result
```
**Parameters**
- `object_ids` (`list[str]`) — IDs of the data objects to read. May be empty or contain duplicates.
**Returns**
- (`dict[str, PluginDataObject | PluginError]`) — Mapping from object id to the object or a per-id plugin error. Returns ``{}`` when ``object_ids`` is empty.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L149-206)
### plugins_api.data_plugins.DataPlugin.get_metadata_for_data_objects
*method*
```python
def get_metadata_for_data_objects(object_ids: list[str]) -> dict[str, list[PluginMetadata] | PluginError]
```
Return the metadata for each requested data object.
**Parameters**
- `object_ids` (`list[str]`) — IDs of the data objects.
**Returns**
- (`dict[str, list[PluginMetadata] | PluginError]`) — Mapping from object id to its metadata list, or to a per-id ``PluginError``. Returns ``{}`` when ``object_ids`` is empty. The default implementation returns an empty list for each distinct id, making this method optional for plugins that have no metadata. Only requested ids may appear in the result.
> **Notes**
>
> Per-id errors follow the same rules as
> ``get_data_objects_by_ids``. Source-level errors must be raised.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L208-234)
### plugins_api.data_plugins.DataPlugin.get_root_id
*method* · *abstract* · *staticmethod*
```python
def get_root_id() -> str
```
Return the unique identifier of the root data object.
**Returns**
- (`str`) — Unique identifier of the root data object.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L96-108)
### plugins_api.data_plugins.DataPlugin.get_root_name
*method* · *abstract* · *staticmethod*
```python
def get_root_name() -> str
```
Return the name of the root data object.
**Returns**
- (`str`) — Name of the root data object.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/data_plugins.py#L82-94)
### plugins_api.data_plugins.DataPlugin.close
*method*
```python
def close() -> None
```
Inherited from: `plugins_api.base.ConnectionPlugin`
Release connection resources (optional).
Plugins that hold long-lived connections (e.g. SSH, persistent HTTP
sessions) may override this method to close the underlying connection
and release file descriptors. Callers (e.g. core) should call
``close()`` when done with the plugin instance.
The base implementation does nothing. Plugins that do not need to
release resources need not override it.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L237-249)
### plugins_api.data_plugins.DataPlugin.get_connection_fields
*method* · *abstract* · *classmethod*
```python
def get_connection_fields() -> tuple[list[ConnectionField], list[ConnectionField]]
```
Inherited from: `plugins_api.base.ConnectionPlugin`
Retrieve the connection fields for the connection plugin.
**Returns**
- (`tuple[list[ConnectionField], list[ConnectionField]]`) — ``(shared_fields, private_fields)``. Shared fields are instance-level (URL, host). Private fields are per-user secrets (token, password).
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L206-222)
### plugins_api.data_plugins.DataPlugin.get_instance_name
*method* · *abstract*
```python
def get_instance_name() -> str
```
Inherited from: `plugins_api.base.ConnectionPlugin`
Return the instance name of the connection plugin.
**Returns**
- (`str`) — Instance name.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L193-204)
### plugins_api.data_plugins.DataPlugin.get_shared_parameters
*method* · *abstract*
```python
def get_shared_parameters() -> dict[str, Any]
```
Inherited from: `plugins_api.base.ConnectionPlugin`
Return all shared parameters in a cleaned form.
**Returns**
- (`dict`) — Shared parameters cleaned.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L224-235)
### plugins_api.data_plugins.DataPlugin.is_sandbox
*method* · *classmethod*
```python
def is_sandbox(shared_parameters: dict[str, Any]) -> bool
```
Inherited from: `plugins_api.base.ConnectionPlugin`
Return whether the shared parameters are for a sandbox connection or not.
**Parameters**
- `shared_parameters` (`dict`) — The shared parameters to check.
**Returns**
- (`bool`) — Plugin is sandbox.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L251-268)
### plugins_api.data_plugins.DataPlugin.on_before_store_credentials
*method* · *classmethod*
```python
def on_before_store_credentials(shared_params: dict, private_params: dict) -> dict
```
Inherited from: `plugins_api.base.ConnectionPlugin`
Transform the private parameters just before they are written to the Vault.
Allows the plugin to transform or enrich the private_params.
By default, returns the params unchanged.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L270-282)
### plugins_api.data_plugins.DataPlugin.on_delete_credentials
*method* · *classmethod*
```python
def on_delete_credentials(shared_params: dict, vault_secret: dict) -> None
```
Inherited from: `plugins_api.base.ConnectionPlugin`
Clean up just before the credentials are deleted 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L284-296)
### plugins_api.data_plugins.DataPlugin.get_author
*method* · *abstract* · *classmethod*
```python
def get_author() -> str
```
Inherited from: `plugins_api.base.MadbotPlugin`
Return plugin author.
**Returns**
- (`str`) — Plugin author.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L82-94)
### plugins_api.data_plugins.DataPlugin.get_color
*method* · *abstract* · *classmethod*
```python
def get_color() -> str
```
Inherited from: `plugins_api.base.MadbotPlugin`
Return the color of the plugin.
Typically a hex value such as ``"#3B82F6"``.
**Returns**
- (`str`) — Plugin color.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L113-127)
### plugins_api.data_plugins.DataPlugin.get_description
*method* · *abstract* · *classmethod*
```python
def get_description() -> str
```
Inherited from: `plugins_api.base.MadbotPlugin`
Return plugin description.
**Returns**
- (`str`) — Plugin description.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L68-80)
### plugins_api.data_plugins.DataPlugin.get_id
*method* · *classmethod*
```python
def get_id() -> str
```
Inherited from: `plugins_api.base.MadbotPlugin`
Return the unique identifier of the plugin.
**Returns**
- (`str`) — Unique identifier in the format 'module.class'.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L24-35)
### plugins_api.data_plugins.DataPlugin.get_logo
*method* · *abstract* · *classmethod*
```python
def get_logo() -> str
```
Inherited from: `plugins_api.base.MadbotPlugin`
Return the static path of the plugin logo.
Path is relative to the plugin package static files.
Example: ``"images/ena.png"``.
**Returns**
- (`str`) — Plugin logo static path.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L96-111)
### plugins_api.data_plugins.DataPlugin.get_name
*method* · *abstract* · *classmethod*
```python
def get_name() -> str
```
Inherited from: `plugins_api.base.MadbotPlugin`
Return the plugin name.
**Returns**
- (`str`) — Plugin name.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L37-49)
### plugins_api.data_plugins.DataPlugin.get_slug
*method* · *abstract* · *classmethod*
```python
def get_slug() -> str
```
Inherited from: `plugins_api.base.MadbotPlugin`
Return the plugin slug.
Lowercase, no spaces (e.g. ``"ena"``, ``"omero"``).
Used as ``MetadataFieldID.source`` and as the schema source at reload.
**Returns**
- (`str`) — Plugin slug.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L51-66)
### plugins_api.data_plugins.DataPlugin.get_status
*method* · *abstract* · *classmethod*
```python
def get_status() -> dict[str, PluginStatus]
```
Inherited from: `plugins_api.base.MadbotPlugin`
Return the maturity status of the plugin, keyed by capability type.
A plugin implementing several capability types at once (e.g. a class
inheriting from both `SubmissionPlugin` and
`MetadataFieldDefinitionPlugin`) must return one entry per type it
implements, using the same type strings as `get_types()`.
**Returns**
- (`dict[str, PluginStatus]`) — Mapping of plugin type (as returned by `get_types()`) to its maturity status.
**Examples**
A plugin implementing a single type:
```pycon
>>> print(self.get_status())
{"data_plugin": PluginStatus.PREVIEW}
```
A plugin implementing several types at once:
```pycon
>>> print(self.get_status())
{
"submission_plugin": PluginStatus.STABLE,
"metadata_field_definition_plugin": PluginStatus.STABLE,
}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L129-162)
### plugins_api.data_plugins.DataPlugin.get_types
*method* · *classmethod*
```python
def get_types() -> list[str]
```
Inherited from: `plugins_api.base.MadbotPlugin`
Return the list of the plugin types in snake_case.
**Returns**
- (`list`) — List of plugin types.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L164-181)
---
# plugins_api.decorators
*module*
Plugin decorators.
This module contains decorators used for plugin registration and management.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/decorators.py#L1-1)
## plugins_api.decorators.base_plugin_class
*function*
```python
def base_plugin_class() -> type[T]
```
Mark a class as a plugin.
This function adds the name of the decorated class to the
`plugin_class_names` set, indicating that the class is
recognized as a base plugin class.
**Parameters**
- `cls` (`type`) — The class to mark as a plugin.
**Returns**
- (`type`) — The decorated class.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/decorators.py#L22-42)
## plugins_api.decorators.enforce_constructor_signature
*function*
```python
def enforce_constructor_signature(reference_class: type | None = None) -> Callable
```
Enforce the constructor signature of a class.
A class decorator to enforce that all subclasses of the decorated class
define an `__init__` method with the same signature as a given reference.
If no argument is provided, the decorated class itself is used as the reference.
Subclasses must:
- Include all the required parameters in the same order
Subclasses may:
- Add optional parameters (with or without defaults)
- Change default values
- Use *args / **kwargs
Subclasses must not:
- Have missing required parameters
- Have a different order of required parameters
**Parameters**
- `reference_class` (`type`) (default: `None`) — A class whose `__init__` signature should be enforced on subclasses of the decorated class. If None (or the decorator is used without parentheses), the signature of the decorated class's own `__init__` method is used as the reference.
**Returns**
- (`Callable`) — A class decorator that modifies the class's `__init_subclass__` method to enforce the constructor signature.
**Raises**
- `TypeError` — If a subclass defines an `__init__` method with a different signature than the reference.
**Examples**
Enforcing a class's own constructor:
```pycon
>>> @enforce_constructor_signature
>>> class SubmissionPlugin(ConnectionPlugin):
... def __init__(self, submission_id: str, user: str):
... ...
```
Enforcing a different class's constructor:
```pycon
>>> @enforce_constructor_signature(SubmissionPlugin)
>>> class AnotherPlugin(SubmissionPlugin):
... def __init__(self, ignored): # signature doesn't matter, you don't even need to define it
... ...
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/decorators.py#L45-183)
---
# plugins_api.dtos
*module*
Data Transfer Objects (DTOs) for plugins.
This module contains all DTOs used in the plugin system.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1-1)
## plugins_api.dtos.AccessType
*class*
```python
class AccessType(StrEnum)
```
Bases: `StrEnum`
Enum for supported access types for external data objects.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1051-1055)
### plugins_api.dtos.AccessType.SHELL
*attribute* · *class attribute* · *instance attribute*
```python
SHELL = 'shell'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1055-1055)
### plugins_api.dtos.AccessType.URL
*attribute* · *class attribute* · *instance attribute*
```python
URL = 'url'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1054-1054)
## plugins_api.dtos.AssociationRole
*class*
```python
class AssociationRole(StrEnum)
```
Bases: `StrEnum`
Possible roles of an object within a submission association.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L982-986)
### plugins_api.dtos.AssociationRole.SOURCE
*attribute* · *class attribute* · *instance attribute*
```python
SOURCE = 'source'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L985-985)
### plugins_api.dtos.AssociationRole.TARGET
*attribute* · *class attribute* · *instance attribute*
```python
TARGET = 'target'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L986-986)
## plugins_api.dtos.ConnectionField
*class*
```python
class ConnectionField(BaseModel)
```
Bases: `BaseModel`
DTO representing a connection field.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L860-865)
### plugins_api.dtos.ConnectionField.schema_content
*attribute* · *instance attribute*
```python
schema_content: dict[str, Any]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L864-864)
### plugins_api.dtos.ConnectionField.slug
*attribute* · *instance attribute*
```python
slug: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L863-863)
### plugins_api.dtos.ConnectionField.uischema
*attribute* · *class attribute* · *instance attribute*
```python
uischema: dict[str, Any] | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L865-865)
## plugins_api.dtos.ExternalAccess
*class*
```python
class ExternalAccess(BaseModel)
```
Bases: `BaseModel`
DTO for how to access an external data object.
**Attributes**
- `access_type` (`AccessType`) — Type of access to the external data object.
- `details` (`str`) — For ``AccessType.URL``: a URL string. For ``AccessType.SHELL``: a command string. Stored as a string of at most 1000 characters.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1058-1072)
### plugins_api.dtos.ExternalAccess.access_type
*attribute* · *instance attribute*
```python
access_type: AccessType
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1071-1071)
### plugins_api.dtos.ExternalAccess.details
*attribute* · *instance attribute*
```python
details: Any
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1072-1072)
## plugins_api.dtos.ExternalIdentifier
*class*
```python
class ExternalIdentifier(BaseModel)
```
Bases: `BaseModel`
DTO for an identifier assigned by an external repository for submission plugins.
**Attributes**
- `identifier` (`str`) — The identifier string itself (DOI, accession, …).
- `type` (`ExternalIdentifierType`) — Kind of identifier. Must be one of the enum values.
- `url` (`(str, optional)`) — URL for the identifier, if any.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L115-131)
### plugins_api.dtos.ExternalIdentifier.identifier
*attribute* · *instance attribute*
```python
identifier: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L129-129)
### plugins_api.dtos.ExternalIdentifier.type
*attribute* · *class attribute* · *instance attribute*
```python
type: ExternalIdentifierType = Field(..., description='Type of identifier')
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L130-130)
### plugins_api.dtos.ExternalIdentifier.url
*attribute* · *class attribute* · *instance attribute*
```python
url: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L131-131)
## plugins_api.dtos.ExternalIdentifierType
*class*
```python
class ExternalIdentifierType(StrEnum)
```
Bases: `StrEnum`
Type of external identifier.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L92-105)
### plugins_api.dtos.ExternalIdentifierType.ACCESSION
*attribute* · *class attribute* · *instance attribute*
```python
ACCESSION = 'ACCESSION'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L99-99)
### plugins_api.dtos.ExternalIdentifierType.ARK
*attribute* · *class attribute* · *instance attribute*
```python
ARK = 'ARK'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L96-96)
### plugins_api.dtos.ExternalIdentifierType.BIOPROJECT
*attribute* · *class attribute* · *instance attribute*
```python
BIOPROJECT = 'BIOPROJECT'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L104-104)
### plugins_api.dtos.ExternalIdentifierType.BIOSAMPLE
*attribute* · *class attribute* · *instance attribute*
```python
BIOSAMPLE = 'BIOSAMPLE'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L105-105)
### plugins_api.dtos.ExternalIdentifierType.DOI
*attribute* · *class attribute* · *instance attribute*
```python
DOI = 'DOI'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L95-95)
### plugins_api.dtos.ExternalIdentifierType.ENA_EXPERIMENT
*attribute* · *class attribute* · *instance attribute*
```python
ENA_EXPERIMENT = 'ENA EXPERIMENT'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L102-102)
### plugins_api.dtos.ExternalIdentifierType.ENA_PROJECT
*attribute* · *class attribute* · *instance attribute*
```python
ENA_PROJECT = 'ENA PROJECT'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L100-100)
### plugins_api.dtos.ExternalIdentifierType.ENA_RUN
*attribute* · *class attribute* · *instance attribute*
```python
ENA_RUN = 'ENA RUN'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L103-103)
### plugins_api.dtos.ExternalIdentifierType.ENA_SAMPLE
*attribute* · *class attribute* · *instance attribute*
```python
ENA_SAMPLE = 'ENA SAMPLE'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L101-101)
### plugins_api.dtos.ExternalIdentifierType.ID
*attribute* · *class attribute* · *instance attribute*
```python
ID = 'ID'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L97-97)
### plugins_api.dtos.ExternalIdentifierType.PURL
*attribute* · *class attribute* · *instance attribute*
```python
PURL = 'PURL'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L98-98)
## plugins_api.dtos.FieldRepresentation
*class*
```python
class FieldRepresentation(BaseModel)
```
Bases: `BaseModel`
DTO for a metadata field defined by a plugin.
**Attributes**
- `slug` (`str`) — Field slug: ``plugin__field`` or ``plugin__mot__field``.
- `schema_rep` (`SchemaRepresentation`) — Schema for this field. ``schema_rep.slug`` should match ``slug``.
- `title` (`str`) — Display name.
- `description` (`str`) — Human-readable description. May be empty.
- `external_url` (`str`) — Documentation URL for the field. Use ``""`` if none.
- `madbot_fields` (`list[str]`) — Slugs of mapped madbot fields. Empty list if unmapped.
- `hidden` (`bool`) — If True, the field should be hidden in the UI.
- `standard` (`(str, optional)`) — Metadata standard this field belongs to, or None.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L688-719)
### plugins_api.dtos.FieldRepresentation.description
*attribute* · *instance attribute*
```python
description: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L715-715)
### plugins_api.dtos.FieldRepresentation.external_url
*attribute* · *instance attribute*
```python
external_url: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L716-716)
### plugins_api.dtos.FieldRepresentation.hidden
*attribute* · *instance attribute*
```python
hidden: bool
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L718-718)
### plugins_api.dtos.FieldRepresentation.madbot_fields
*attribute* · *instance attribute*
```python
madbot_fields: list[str]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L717-717)
### plugins_api.dtos.FieldRepresentation.schema_rep
*attribute* · *instance attribute*
```python
schema_rep: SchemaRepresentation
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L713-713)
### plugins_api.dtos.FieldRepresentation.slug
*attribute* · *instance attribute*
```python
slug: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L712-712)
### plugins_api.dtos.FieldRepresentation.standard
*attribute* · *class attribute* · *instance attribute*
```python
standard: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L719-719)
### plugins_api.dtos.FieldRepresentation.title
*attribute* · *instance attribute*
```python
title: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L714-714)
## plugins_api.dtos.MadbotMetadata
*class*
```python
class MadbotMetadata(BaseModel)
```
Bases: `BaseModel`
DTO for metadata attached to a madbot object, provided by madbot core to plugins.
**Attributes**
- `field` (`MetadataFieldID`) — Field this value belongs to.
- `metadata_value` (`(MetadataValue, optional)`) — Selected value. Named ``metadata_value`` here (not ``value``).
- `inherited_values` (`list[MetadataValue]`) — Candidate values inherited from ancestors. Same role as ``MetadataObjectMetadata.candidate_values``.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L304-321)
### plugins_api.dtos.MadbotMetadata.field
*attribute* · *instance attribute*
```python
field: MetadataFieldID
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L319-319)
### plugins_api.dtos.MadbotMetadata.inherited_values
*attribute* · *class attribute* · *instance attribute*
```python
inherited_values: list[MetadataValue] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L321-321)
### plugins_api.dtos.MadbotMetadata.metadata_value
*attribute* · *class attribute* · *instance attribute*
```python
metadata_value: MetadataValue | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L320-320)
## plugins_api.dtos.MadbotMetadataObject
*class*
```python
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**
- `id` (`UUID`) — Madbot identifier of the metadata object.
- `type` (`str`) — Metadata object type slug (e.g. ``"sample"``).
- `metadata` (`list[MetadataObjectMetadata]`) — Field values on this object.
- `cross_validation` (`dict[str, Any]`) — Cross-field validation errors, keyed by field slug. Empty dict if valid.
- `external_identifiers` (`list[ExternalIdentifier]`) — Identifiers assigned after submission, if any.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L517-552)
### plugins_api.dtos.MadbotMetadataObject.cross_validation
*attribute* · *instance attribute*
```python
cross_validation: dict[str, Any]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L540-540)
### plugins_api.dtos.MadbotMetadataObject.external_identifiers
*attribute* · *class attribute* · *instance attribute*
```python
external_identifiers: list[ExternalIdentifier] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L541-541)
### plugins_api.dtos.MadbotMetadataObject.id
*attribute* · *class attribute* · *instance attribute*
```python
id: UUID = Field(default_factory=uuid4)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L537-537)
### plugins_api.dtos.MadbotMetadataObject.metadata
*attribute* · *instance attribute*
```python
metadata: list[MetadataObjectMetadata]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L539-539)
### plugins_api.dtos.MadbotMetadataObject.type
*attribute* · *instance attribute*
```python
type: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L538-538)
## plugins_api.dtos.MetadataFieldID
*class*
```python
class MetadataFieldID(BaseModel)
```
Bases: `BaseModel`
DTO for metadata field.
**Attributes**
- `slug` (`str`) — Unique identifier for the metadata field. For plugin fields: ``plugin__field`` or ``plugin__mot__field``. For madbot fields: the madbot field slug.
- `name` (`str`) — Display name of the metadata field.
- `source` (`str`) — ``"referential"`` for a madbot field, or the plugin slug for a plugin field.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L134-152)
### plugins_api.dtos.MetadataFieldID.name
*attribute* · *instance attribute*
```python
name: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L151-151)
### plugins_api.dtos.MetadataFieldID.slug
*attribute* · *instance attribute*
```python
slug: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L150-150)
### plugins_api.dtos.MetadataFieldID.source
*attribute* · *instance attribute*
```python
source: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L152-152)
## plugins_api.dtos.MetadataFieldMapping
*class*
```python
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**
- `plugin_fields` (`list[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_fields` (`list[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_plugin` (`Callable`) — ``dict[madbot_slug, value] -> dict[plugin_slug, value]``.
- `transform_plugin_to_madbot` (`Callable`) — ``dict[plugin_slug, value] -> dict[madbot_slug, value]``.
- `mapping_id` (`Optional[str]`) — Unique identifier for this mapping rule. Useful for distinguishing between multiple mappings for the same field (e.g., different checklists).
> **Notes**
>
> Additional metadata for the mapping (e.g., checklist, version, etc.) can be
> added through extra fields.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L155-194)
### plugins_api.dtos.MetadataFieldMapping.madbot_fields
*attribute* · *instance attribute*
```python
madbot_fields: list[str]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L188-188)
### plugins_api.dtos.MetadataFieldMapping.mapping_id
*attribute* · *class attribute* · *instance attribute*
```python
mapping_id: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L191-191)
### plugins_api.dtos.MetadataFieldMapping.model_config
*attribute* · *class attribute* · *instance attribute*
```python
model_config = ConfigDict(extra='allow')
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L194-194)
### plugins_api.dtos.MetadataFieldMapping.plugin_fields
*attribute* · *instance attribute*
```python
plugin_fields: list[str]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L187-187)
### plugins_api.dtos.MetadataFieldMapping.transform_madbot_to_plugin
*attribute* · *instance attribute*
```python
transform_madbot_to_plugin: Callable[[dict[str, Any]], dict[str, Any]]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L189-189)
### plugins_api.dtos.MetadataFieldMapping.transform_plugin_to_madbot
*attribute* · *instance attribute*
```python
transform_plugin_to_madbot: Callable[[dict[str, Any]], dict[str, Any]]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L190-190)
## plugins_api.dtos.MetadataGroupNodeDTO
*class*
```python
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.
> **Node types**
>
> - ``type="mot"``: mirrors a metadata object type. ``slug`` must match a key
> from ``get_all_metadata_object_types()``. Usually has no ``fields`` if it
> has children, if so use ``fields=[]``, and the children are subgroups.
> - ``type="subgroup"``: UI folder under an MOT (or under another subgroup).
> Holds field slugs that belong to that MOT only.
> **Rules**
>
> - Recreate each MOT as a ``type="mot"`` node (e.g. Zenodo's ``"general"``).
> - Do not mix fields from different MOTs in the same subgroup.
> - Nodes with ``has_groups=True`` must have ``children``; nodes with
> ``has_groups=False`` must not.
> - Field entries are either a slug string, or
> ``{"slug": "...", "level": "mandatory"|"recommended"|"optional"}``.
**Attributes**
- `slug` (`str`) — Unique slug for the group node. For ``type="mot"``, use the MOT slug.
- `name` (`str`) — Display name of the group node.
- `description` (`str`) — Human-readable description of the group node.
- `type` (`Literal['mot', 'subgroup'] | None`) — ``"mot"`` for a metadata object type node, ``"subgroup"`` for nested groups.
- `has_groups` (`bool`) — True when this node has child group nodes.
- `fields` (`list[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"
- `children` (`list[MetadataGroupNodeDTO]`) — Child group nodes.
**Examples**
A single MOT with subgroups (Zenodo-style):
```pycon
>>> 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:
```pycon
>>> [
... 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:
```pycon
>>> 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=[],
... )
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L722-854)
### plugins_api.dtos.MetadataGroupNodeDTO.children
*attribute* · *class attribute* · *instance attribute*
```python
children: list[MetadataGroupNodeDTO] = Field(default_factory=list)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L843-843)
### plugins_api.dtos.MetadataGroupNodeDTO.description
*attribute* · *instance attribute*
```python
description: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L833-833)
### plugins_api.dtos.MetadataGroupNodeDTO.fields
*attribute* · *class attribute* · *instance attribute*
```python
fields: list[str | dict[Literal['slug', 'level'], str | Literal['mandatory', 'recommended', 'optional'] | None]] = Field(default_factory=list)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L836-842)
### plugins_api.dtos.MetadataGroupNodeDTO.has_groups
*attribute* · *class attribute* · *instance attribute*
```python
has_groups: bool = False
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L835-835)
### plugins_api.dtos.MetadataGroupNodeDTO.name
*attribute* · *instance attribute*
```python
name: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L832-832)
### plugins_api.dtos.MetadataGroupNodeDTO.slug
*attribute* · *instance attribute*
```python
slug: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L831-831)
### plugins_api.dtos.MetadataGroupNodeDTO.type
*attribute* · *class attribute* · *instance attribute*
```python
type: Literal['mot', 'subgroup'] | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L834-834)
## plugins_api.dtos.MetadataObject
*class*
```python
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**
- `id` (`(UUID, optional)`) — Existing madbot ID when updating, or a new UUID when creating.
- `type` (`MetadataObjectType`) — Full type definition, not a slug.
- `metadata` (`list[MetadataObjectMetadata]`) — Field values on this object.
- `cross_validation` (`dict[str, Any]`) — Cross-field validation errors, keyed by field slug. Empty dict if valid.
- `external_identifiers` (`list[ExternalIdentifier]`) — Identifiers assigned after submission, if any.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L943-979)
### plugins_api.dtos.MetadataObject.cross_validation
*attribute* · *instance attribute*
```python
cross_validation: dict[str, Any]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L967-967)
### plugins_api.dtos.MetadataObject.external_identifiers
*attribute* · *class attribute* · *instance attribute*
```python
external_identifiers: list[ExternalIdentifier] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L968-968)
### plugins_api.dtos.MetadataObject.id
*attribute* · *class attribute* · *instance attribute*
```python
id: UUID | None = Field(default_factory=uuid4)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L964-964)
### plugins_api.dtos.MetadataObject.metadata
*attribute* · *instance attribute*
```python
metadata: list[MetadataObjectMetadata]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L966-966)
### plugins_api.dtos.MetadataObject.type
*attribute* · *instance attribute*
```python
type: MetadataObjectType
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L965-965)
## plugins_api.dtos.MetadataObjectMetadata
*class*
```python
class MetadataObjectMetadata(BaseModel)
```
Bases: `BaseModel`
DTO for one metadata field on a metadata object.
**Attributes**
- `field` (`MetadataFieldID`) — Field this value belongs to.
- `metadata_value` (`(MetadataValue or SubmissionMetadataValue, optional)`) — Selected value.
- `candidate_values` (`list[MetadataValue | SubmissionMetadataValue]`) — Alternative values the user may pick. Same role as ``MadbotMetadata.inherited_values``.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L340-383)
### plugins_api.dtos.MetadataObjectMetadata.candidate_values
*attribute* · *class attribute* · *instance attribute*
```python
candidate_values: list[MetadataValue | SubmissionMetadataValue] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L357-357)
### plugins_api.dtos.MetadataObjectMetadata.field
*attribute* · *instance attribute*
```python
field: MetadataFieldID
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L355-355)
### plugins_api.dtos.MetadataObjectMetadata.metadata_value
*attribute* · *class attribute* · *instance attribute*
```python
metadata_value: MetadataValue | SubmissionMetadataValue | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L356-356)
### plugins_api.dtos.MetadataObjectMetadata.from_metadata
*method* · *classmethod*
```python
def from_metadata(metadata: MadbotMetadata) -> MetadataObjectMetadata
```
Convert a Metadata to a MetadataObjectMetadata.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L359-366)
### plugins_api.dtos.MetadataObjectMetadata.to_metadata
*method*
```python
def to_metadata() -> MadbotMetadata
```
Convert a MetadataObjectMetadata to a Metadata.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L368-374)
## plugins_api.dtos.MetadataObjectType
*class*
```python
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**
- `name` (`str`) — The display name of the metadata object type (e.g., 'Sample', 'Experiment', 'Dataset').
- `slug` (`str`) — A unique identifier for the metadata object type, used in URLs and API endpoints. Should be lowercase with hyphens (e.g., 'sample', 'experiment', 'dataset').
- `summary_fields` (`List[str]`) — List of field names that should be displayed in summary views or lists. These fields provide a quick overview of the metadata object.
- `priority` (`List[str]`) — Ordered list of field names indicating their display priority. Fields listed first will be displayed before fields listed later.
- `description` (`str`) — A 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_tab` (`bool`) — Whether 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_occurrence` (`int`) — The 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_occurrence` (`Optional[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_schemas` (`list[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_schemas` (`list[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_schemas` (`list[FieldRepresentation]`) — List of field schemas that are optional for this metadata object type. These fields can be provided but are not required or recommended.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L878-940)
### plugins_api.dtos.MetadataObjectType.additional_information
*attribute* · *class attribute* · *instance attribute*
```python
additional_information: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L934-934)
### plugins_api.dtos.MetadataObjectType.description
*attribute* · *instance attribute*
```python
description: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L933-933)
### plugins_api.dtos.MetadataObjectType.mandatory_fields_schemas
*attribute* · *instance attribute*
```python
mandatory_fields_schemas: list[FieldRepresentation]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L938-938)
### plugins_api.dtos.MetadataObjectType.maximal_occurrence
*attribute* · *class attribute* · *instance attribute*
```python
maximal_occurrence: int | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L937-937)
### plugins_api.dtos.MetadataObjectType.minimal_occurrence
*attribute* · *instance attribute*
```python
minimal_occurrence: int
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L936-936)
### plugins_api.dtos.MetadataObjectType.name
*attribute* · *instance attribute*
```python
name: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L929-929)
### plugins_api.dtos.MetadataObjectType.optional_fields_schemas
*attribute* · *instance attribute*
```python
optional_fields_schemas: list[FieldRepresentation]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L940-940)
### plugins_api.dtos.MetadataObjectType.priority
*attribute* · *instance attribute*
```python
priority: list[str]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L932-932)
### plugins_api.dtos.MetadataObjectType.recommended_fields_schemas
*attribute* · *instance attribute*
```python
recommended_fields_schemas: list[FieldRepresentation]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L939-939)
### plugins_api.dtos.MetadataObjectType.show_additional_information_on_data_tab
*attribute* · *class attribute* · *instance attribute*
```python
show_additional_information_on_data_tab: bool = False
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L935-935)
### plugins_api.dtos.MetadataObjectType.slug
*attribute* · *instance attribute*
```python
slug: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L930-930)
### plugins_api.dtos.MetadataObjectType.summary_fields
*attribute* · *instance attribute*
```python
summary_fields: list[str]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L931-931)
## plugins_api.dtos.MetadataValue
*class*
```python
class MetadataValue(BaseModel)
```
Bases: `BaseModel`
DTO for a metadata value.
**Attributes**
- `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``.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L197-215)
### plugins_api.dtos.MetadataValue.source_id
*attribute* · *class attribute* · *instance attribute*
```python
source_id: UUID | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L211-211)
### plugins_api.dtos.MetadataValue.value
*attribute* · *class attribute* · *instance attribute*
```python
value: Any | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L210-210)
## plugins_api.dtos.PluginDataAssociation
*class*
```python
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**
- `associated_external_ids` (`list[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.
> **Notes**
>
> Plugins should return associations bidirectionally - if data object A is associated
> with data objects B and C in association group 1, then when querying A, B, or C,
> they should all return the same association group containing [A, B, C].
**Examples**
If data objects A, B, and C should be associated together:
```pycon
>>> PluginDataAssociation(associated_external_ids=["A", "B", "C"])
```
If data object A has two separate associations (one with B, one with C):
```pycon
>>> [
... PluginDataAssociation(associated_external_ids=["A", "B"]),
... PluginDataAssociation(associated_external_ids=["A", "C"]),
... ]
```
With metadata:
```pycon
>>> PluginDataAssociation(
... associated_external_ids=["B", "C"],
... metadata=[
... PluginMetadata(
... field=MetadataFieldID(slug="association_type", source="referential", name="Association Type"),
... value=MetadataValue(value="paired")
... )
... ]
... )
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1075-1123)
### plugins_api.dtos.PluginDataAssociation.associated_external_ids
*attribute* · *instance attribute*
```python
associated_external_ids: list[str]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1122-1122)
### plugins_api.dtos.PluginDataAssociation.metadata
*attribute* · *class attribute* · *instance attribute*
```python
metadata: list[PluginMetadata] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1123-1123)
## plugins_api.dtos.PluginDataObject
*class*
```python
class PluginDataObject(BaseModel)
```
Bases: `BaseModel`
DTO for an external data object returned by a data plugin.
**Attributes**
- `id` (`str`) — Stable identifier in the external system. Becomes madbot ``external_id``.
- `name` (`str`) — Display 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_children` (`bool`) — True if ``browse_data_objects(this id)`` will return items.
- `linkable` (`bool`) — Whether the object can be linked into a madbot node.
- `children` (`list[PluginDataObject]`) — List of child external data objects. Defaults to None.
- `accesses` (`list[ExternalAccess]`) — Ways to open or download the object.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1126-1195)
### plugins_api.dtos.PluginDataObject.accesses
*attribute* · *class attribute* · *instance attribute*
```python
accesses: list[ExternalAccess] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1170-1170)
### plugins_api.dtos.PluginDataObject.children
*attribute* · *class attribute* · *instance attribute*
```python
children: list[PluginDataObject] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1169-1169)
### plugins_api.dtos.PluginDataObject.description
*attribute* · *class attribute* · *instance attribute*
```python
description: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1162-1162)
### plugins_api.dtos.PluginDataObject.file_extension
*attribute* · *class attribute* · *instance attribute*
```python
file_extension: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1164-1164)
### plugins_api.dtos.PluginDataObject.has_children
*attribute* · *class attribute* · *instance attribute*
```python
has_children: bool = False
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1167-1167)
### plugins_api.dtos.PluginDataObject.icon
*attribute* · *class attribute* · *instance attribute*
```python
icon: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1166-1166)
### plugins_api.dtos.PluginDataObject.id
*attribute* · *instance attribute*
```python
id: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1159-1159)
### plugins_api.dtos.PluginDataObject.linkable
*attribute* · *class attribute* · *instance attribute*
```python
linkable: bool = False
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1168-1168)
### plugins_api.dtos.PluginDataObject.media_type
*attribute* · *class attribute* · *instance attribute*
```python
media_type: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1163-1163)
### plugins_api.dtos.PluginDataObject.name
*attribute* · *instance attribute*
```python
name: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1160-1160)
### plugins_api.dtos.PluginDataObject.size
*attribute* · *class attribute* · *instance attribute*
```python
size: int | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1165-1165)
### plugins_api.dtos.PluginDataObject.type
*attribute* · *class attribute* · *instance attribute*
```python
type: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1161-1161)
### plugins_api.dtos.PluginDataObject.add_external_access
*method*
```python
def add_external_access(access_type: AccessType, access_details: str) -> None
```
Add external access information to the data object.
**Parameters**
- `access_type` (`AccessType`) — The type of access being added (must be one of the supported access types).
- `access_details` (`str`) — The 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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1172-1195)
## plugins_api.dtos.PluginMetadata
*class*
```python
class PluginMetadata(BaseModel)
```
Bases: `BaseModel`
DTO for metadata returned by a plugin.
**Attributes**
- `field` (`MetadataFieldID`) — Field this value belongs to.
- `value` (`(MetadataValue, optional)`) — The value.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L324-337)
### plugins_api.dtos.PluginMetadata.field
*attribute* · *instance attribute*
```python
field: MetadataFieldID
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L336-336)
### plugins_api.dtos.PluginMetadata.value
*attribute* · *class attribute* · *instance attribute*
```python
value: MetadataValue | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L337-337)
## plugins_api.dtos.PluginStatus
*class*
```python
class PluginStatus(StrEnum)
```
Bases: `StrEnum`
Maturity status of a plugin for a given capability type.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L108-112)
### plugins_api.dtos.PluginStatus.PREVIEW
*attribute* · *class attribute* · *instance attribute*
```python
PREVIEW = 'preview'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L111-111)
### plugins_api.dtos.PluginStatus.STABLE
*attribute* · *class attribute* · *instance attribute*
```python
STABLE = 'stable'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L112-112)
## plugins_api.dtos.SchemaRepresentation
*class*
```python
class SchemaRepresentation(BaseModel)
```
Bases: `BaseModel`
DTO for the JSON schema of a metadata or connection field.
**Attributes**
- `slug` (`str`) — Field slug. For metadata fields: ``plugin__field`` or ``plugin__mot__field``.
- `schema_content` (`dict[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.
- `source` (`str`) — Plugin slug.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L665-685)
### plugins_api.dtos.SchemaRepresentation.schema_content
*attribute* · *instance attribute*
```python
schema_content: dict[str, Any]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L683-683)
### plugins_api.dtos.SchemaRepresentation.slug
*attribute* · *instance attribute*
```python
slug: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L682-682)
### plugins_api.dtos.SchemaRepresentation.source
*attribute* · *instance attribute*
```python
source: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L685-685)
### plugins_api.dtos.SchemaRepresentation.uischema
*attribute* · *class attribute* · *instance attribute*
```python
uischema: dict[str, Any] | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L684-684)
## plugins_api.dtos.SettingField
*class*
```python
class SettingField(ConnectionField)
```
Bases: `plugins_api.dtos.ConnectionField`
DTO for a submission setting schema, returned by ``get_settings_fields()``.
The slug must match ``Settings.field`` in the plugin constructor.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L868-875)
### plugins_api.dtos.SettingField.schema_content
*attribute* · *instance attribute*
```python
schema_content: dict[str, Any]
```
Inherited from: `plugins_api.dtos.ConnectionField`
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L864-864)
### plugins_api.dtos.SettingField.slug
*attribute* · *instance attribute*
```python
slug: str
```
Inherited from: `plugins_api.dtos.ConnectionField`
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L863-863)
### plugins_api.dtos.SettingField.uischema
*attribute* · *class attribute* · *instance attribute*
```python
uischema: dict[str, Any] | None = None
```
Inherited from: `plugins_api.dtos.ConnectionField`
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L865-865)
## plugins_api.dtos.Settings
*class*
```python
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**
- `field` (`str`) — Setting slug, matching a `SettingField.slug` from `get_settings_fields()`.
- `setting_value` (`Any`) — User-provided value, validated against that setting's JSON schema.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L55-71)
### plugins_api.dtos.Settings.field
*attribute* · *instance attribute*
```python
field: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L70-70)
### plugins_api.dtos.Settings.setting_value
*attribute* · *instance attribute*
```python
setting_value: Any
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L71-71)
## plugins_api.dtos.Source
*class*
```python
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**
- `madbot_id` (`UUID`) — Madbot identifier of the source object.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L386-407)
### plugins_api.dtos.Source.madbot_id
*attribute* · *class attribute* · *instance attribute*
```python
madbot_id: UUID = Field(default_factory=uuid4)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L399-399)
### plugins_api.dtos.Source.model_post_init
*method*
```python
def model_post_init(__context: Any) -> None
```
Reject direct instantiation of the abstract base.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L401-407)
## plugins_api.dtos.SourceAssociationData
*class*
```python
class SourceAssociationData(Source)
```
Bases: `plugins_api.dtos.Source`
DTO for a data association that is the source of a metadata value.
**Attributes**
- `source_data` (`list[SourceData]`) — Data objects in the association.
- `metadata` (`list[MadbotMetadata]`) — Metadata attached to the association.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L501-514)
### plugins_api.dtos.SourceAssociationData.metadata
*attribute* · *class attribute* · *instance attribute*
```python
metadata: list[MadbotMetadata] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L514-514)
### plugins_api.dtos.SourceAssociationData.source_data
*attribute* · *instance attribute*
```python
source_data: list[SourceData]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L513-513)
### plugins_api.dtos.SourceAssociationData.madbot_id
*attribute* · *class attribute* · *instance attribute*
```python
madbot_id: UUID = Field(default_factory=uuid4)
```
Inherited from: `plugins_api.dtos.Source`
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L399-399)
### plugins_api.dtos.SourceAssociationData.model_post_init
*method*
```python
def model_post_init(__context: Any) -> None
```
Inherited from: `plugins_api.dtos.Source`
Reject direct instantiation of the abstract base.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L401-407)
## plugins_api.dtos.SourceData
*class*
```python
class SourceData(Source)
```
Bases: `plugins_api.dtos.Source`
DTO for a madbot data object that is the source of a metadata value.
**Attributes**
- `name` (`str`) — Display name of the data object.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L410-420)
### plugins_api.dtos.SourceData.name
*attribute* · *instance attribute*
```python
name: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L420-420)
### plugins_api.dtos.SourceData.madbot_id
*attribute* · *class attribute* · *instance attribute*
```python
madbot_id: UUID = Field(default_factory=uuid4)
```
Inherited from: `plugins_api.dtos.Source`
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L399-399)
### plugins_api.dtos.SourceData.model_post_init
*method*
```python
def model_post_init(__context: Any) -> None
```
Inherited from: `plugins_api.dtos.Source`
Reject direct instantiation of the abstract base.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L401-407)
## plugins_api.dtos.SourceNode
*class*
```python
class SourceNode(Source)
```
Bases: `plugins_api.dtos.Source`
DTO for a madbot node that is the source of a metadata value.
**Attributes**
- `title` (`str`) — Node title.
- `description` (`(str, optional)`) — Node description as a JSON string of EditorJS content.
- `parent` (`(SourceNode, optional)`) — Parent node, or None for a root node.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L423-482)
### plugins_api.dtos.SourceNode.description
*attribute* · *class attribute* · *instance attribute*
```python
description: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L438-438)
### plugins_api.dtos.SourceNode.parent
*attribute* · *class attribute* · *instance attribute*
```python
parent: Optional[SourceNode] = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L439-439)
### plugins_api.dtos.SourceNode.title
*attribute* · *instance attribute*
```python
title: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L437-437)
### plugins_api.dtos.SourceNode.madbot_id
*attribute* · *class attribute* · *instance attribute*
```python
madbot_id: UUID = Field(default_factory=uuid4)
```
Inherited from: `plugins_api.dtos.Source`
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L399-399)
### plugins_api.dtos.SourceNode.from_node
*method* · *classmethod*
```python
def from_node(values: Any) -> Any
```
Convert a generic node object into a SourceNode.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L441-465)
### plugins_api.dtos.SourceNode.get_ancestors
*method*
```python
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
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L467-482)
### plugins_api.dtos.SourceNode.model_post_init
*method*
```python
def model_post_init(__context: Any) -> None
```
Inherited from: `plugins_api.dtos.Source`
Reject direct instantiation of the abstract base.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L401-407)
## plugins_api.dtos.SourceSample
*class*
```python
class SourceSample(Source)
```
Bases: `plugins_api.dtos.Source`
DTO for a madbot sample that is the source of a metadata value.
**Attributes**
- `title` (`str`) — Sample title.
- `alias` (`str`) — Sample alias.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L485-498)
### plugins_api.dtos.SourceSample.alias
*attribute* · *instance attribute*
```python
alias: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L498-498)
### plugins_api.dtos.SourceSample.title
*attribute* · *instance attribute*
```python
title: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L497-497)
### plugins_api.dtos.SourceSample.madbot_id
*attribute* · *class attribute* · *instance attribute*
```python
madbot_id: UUID = Field(default_factory=uuid4)
```
Inherited from: `plugins_api.dtos.Source`
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L399-399)
### plugins_api.dtos.SourceSample.model_post_init
*method*
```python
def model_post_init(__context: Any) -> None
```
Inherited from: `plugins_api.dtos.Source`
Reject direct instantiation of the abstract base.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L401-407)
## plugins_api.dtos.Submission
*class*
```python
class Submission(BaseModel)
```
Bases: `BaseModel`
DTO for a submission.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L83-89)
### plugins_api.dtos.Submission.id
*attribute* · *class attribute* · *instance attribute*
```python
id: UUID = Field(default_factory=uuid4)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L86-86)
### plugins_api.dtos.Submission.members
*attribute* · *instance attribute*
```python
members: list[SubmissionMember]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L89-89)
### plugins_api.dtos.Submission.status
*attribute* · *instance attribute*
```python
status: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L88-88)
### plugins_api.dtos.Submission.title
*attribute* · *instance attribute*
```python
title: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L87-87)
## plugins_api.dtos.SubmissionAssociation
*class*
```python
class SubmissionAssociation(BaseModel)
```
Bases: `BaseModel`
DTO representing an association (a group of related objects).
**Attributes**
- `id` (`UUID`) — Unique identifier for the association.
- `submission_id` (`UUID`) — Identifier of the submission to which this association belongs.
- `association_name` (`str`) — Descriptive name for the association, indicating the kind of relationship between objects (free-form, e.g. ``"paired_end"``).
- `objects` (`list[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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1020-1048)
### plugins_api.dtos.SubmissionAssociation.association_name
*attribute* · *instance attribute*
```python
association_name: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1043-1043)
### plugins_api.dtos.SubmissionAssociation.id
*attribute* · *class attribute* · *instance attribute*
```python
id: UUID = Field(default_factory=uuid4)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1041-1041)
### plugins_api.dtos.SubmissionAssociation.objects
*attribute* · *instance attribute*
```python
objects: list[SubmissionAssociationObject]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1044-1044)
### plugins_api.dtos.SubmissionAssociation.submission_id
*attribute* · *instance attribute*
```python
submission_id: UUID
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1042-1042)
## plugins_api.dtos.SubmissionAssociationObject
*class*
```python
class SubmissionAssociationObject(BaseModel)
```
Bases: `BaseModel`
DTO representing an object within a submission association.
**Attributes**
- `id` (`UUID`) — Unique identifier for the association object.
- `role` (`Optional[AssociationRole]`) — Role of this object in the association. - "source": object initiating the association - "target": object receiving the association - None: neutral, undirected membership (no orientation)
- `object` (`MadbotMetadataObject 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`)
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L989-1017)
### plugins_api.dtos.SubmissionAssociationObject.id
*attribute* · *instance attribute*
```python
id: UUID
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1011-1011)
### plugins_api.dtos.SubmissionAssociationObject.object
*attribute* · *instance attribute*
```python
object: Union[MadbotMetadataObject, SubmissionData, MetadataObject]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1013-1013)
### plugins_api.dtos.SubmissionAssociationObject.role
*attribute* · *class attribute* · *instance attribute*
```python
role: AssociationRole | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L1012-1012)
## plugins_api.dtos.SubmissionData
*class*
```python
class SubmissionData(BaseModel)
```
Bases: `BaseModel`
DTO for a data object included in a submission, provided by madbot core.
**Attributes**
- `filename` (`str`) — File name as stored in madbot.
- `size` (`int`) — File size in bytes.
- `madbot_id` (`UUID`) — Identifier of the submission-data row (not the Data object).
- `data_madbot_id` (`UUID`) — Identifier 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.
- `metadata` (`list[MadbotMetadata]`) — Metadata attached to this data object.
- `data_associations` (`list[SourceAssociationData]`) — Associations this data object belongs to.
- `bound_samples` (`list[dict]`) — Samples bound to this data. Each dict has ``id`` (UUID string), ``title`` (str), and ``alias`` (str or None).
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L555-662)
### plugins_api.dtos.SubmissionData.bound_samples
*attribute* · *class attribute* · *instance attribute*
```python
bound_samples: list[dict] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L596-596)
### plugins_api.dtos.SubmissionData.data_associations
*attribute* · *class attribute* · *instance attribute*
```python
data_associations: list[SourceAssociationData] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L595-595)
### plugins_api.dtos.SubmissionData.data_madbot_id
*attribute* · *class attribute* · *instance attribute*
```python
data_madbot_id: UUID = Field(default_factory=uuid4)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L589-589)
### plugins_api.dtos.SubmissionData.file_type
*attribute* · *class attribute* · *instance attribute*
```python
file_type: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L593-593)
### plugins_api.dtos.SubmissionData.filename
*attribute* · *instance attribute*
```python
filename: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L586-586)
### plugins_api.dtos.SubmissionData.madbot_id
*attribute* · *class attribute* · *instance attribute*
```python
madbot_id: UUID = Field(default_factory=uuid4)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L588-588)
### plugins_api.dtos.SubmissionData.md5_hash
*attribute* · *class attribute* · *instance attribute*
```python
md5_hash: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L592-592)
### plugins_api.dtos.SubmissionData.metadata
*attribute* · *class attribute* · *instance attribute*
```python
metadata: list[MadbotMetadata] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L594-594)
### plugins_api.dtos.SubmissionData.parent_node
*attribute* · *class attribute* · *instance attribute*
```python
parent_node: SourceNode | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L590-590)
### plugins_api.dtos.SubmissionData.path
*attribute* · *class attribute* · *instance attribute*
```python
path: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L591-591)
### plugins_api.dtos.SubmissionData.size
*attribute* · *instance attribute*
```python
size: int
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L587-587)
### plugins_api.dtos.SubmissionData.find_last_common_ancestor
*method* · *staticmethod*
```python
def find_last_common_ancestor(data_objects: list[SubmissionData]) -> list[SourceNode] | None
```
Find the last common ancestor of multiple data objects.
**Parameters**
- `data_objects` (`List[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
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L598-662)
## plugins_api.dtos.SubmissionMember
*class*
```python
class SubmissionMember(BaseModel)
```
Bases: `BaseModel`
DTO for a submission member.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L74-80)
### plugins_api.dtos.SubmissionMember.first_name
*attribute* · *instance attribute*
```python
first_name: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L77-77)
### plugins_api.dtos.SubmissionMember.last_name
*attribute* · *instance attribute*
```python
last_name: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L78-78)
### plugins_api.dtos.SubmissionMember.orcid_uri
*attribute* · *class attribute* · *instance attribute*
```python
orcid_uri: str | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L80-80)
### plugins_api.dtos.SubmissionMember.role
*attribute* · *instance attribute*
```python
role: str
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L79-79)
## plugins_api.dtos.SubmissionMetadataValue
*class*
```python
class SubmissionMetadataValue(MetadataValue)
```
Bases: `plugins_api.dtos.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**
- `sources_submission_data` (`list[UUID]`) — Submission-data UUIDs this value was derived from. Used by madbot core to drop the value when those data objects are removed.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L218-301)
### plugins_api.dtos.SubmissionMetadataValue.sources_submission_data
*attribute* · *class attribute* · *instance attribute*
```python
sources_submission_data: list[UUID] = Field(default_factory=list)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L233-233)
### plugins_api.dtos.SubmissionMetadataValue.source_id
*attribute* · *class attribute* · *instance attribute*
```python
source_id: UUID | None = None
```
Inherited from: `plugins_api.dtos.MetadataValue`
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L211-211)
### plugins_api.dtos.SubmissionMetadataValue.value
*attribute* · *class attribute* · *instance attribute*
```python
value: Any | None = None
```
Inherited from: `plugins_api.dtos.MetadataValue`
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L210-210)
### plugins_api.dtos.SubmissionMetadataValue.add_source_for_all
*method* · *classmethod*
```python
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**
- `metadata_values` (`List[SubmissionMetadataValue]`) — The list of SubmissionMetadataValue instances.
- `source_id` (`UUID`) — The source ID to add.
**Returns**
- (`List[SubmissionMetadataValue]`) — The list of updated SubmissionMetadataValue instances.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L280-301)
### plugins_api.dtos.SubmissionMetadataValue.add_sources_submission_data
*method*
```python
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**
- `submission_data_ids` (`UUID or List[UUID]`) — The ID(s) of the submission data to add as sources.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L239-255)
### plugins_api.dtos.SubmissionMetadataValue.create_from_metadata_value
*method* · *classmethod*
```python
def create_from_metadata_value(metadata_value: MetadataValue) -> SubmissionMetadataValue
```
Create a SubmissionMetadataValue from a MetadataValue.
**Parameters**
- `metadata_value` (`MetadataValue`) — The MetadataValue to convert.
**Returns**
- (`SubmissionMetadataValue`) — The converted SubmissionMetadataValue instance.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/dtos.py#L257-278)
---
# plugins_api.exceptions
*module*
Plugin-related exceptions.
This module contains all exception classes related to plugin operations.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L1-1)
## plugins_api.exceptions.SOURCE_ERRORS
*attribute* · *module attribute*
```python
SOURCE_ERRORS: tuple[type[PluginError], ...] = (UnreachableError, HostConnectionRefusedError, AuthenticationError)
```
Errors that affect the whole source connection.
In batch reads they must be raised, not stored per id. Shared by
``DataPlugin._read_each``, madbot core, and plugins that implement a native
batch override.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L141-145)
## plugins_api.exceptions.AuthenticationError
*class*
```python
class AuthenticationError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised for authentication errors.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L61-69)
### plugins_api.exceptions.AuthenticationError.code
*attribute* · *instance attribute*
```python
code: str = 'invalid_credentials'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L66-66)
### plugins_api.exceptions.AuthenticationError.message
*attribute* · *instance attribute*
```python
message = 'Invalid username, password or token.'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L68-68)
### plugins_api.exceptions.AuthenticationError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'credentials'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L67-67)
## plugins_api.exceptions.DataIntegrityError
*class*
```python
class DataIntegrityError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised for data integrity issues.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L275-301)
### plugins_api.exceptions.DataIntegrityError.code
*attribute* · *instance attribute*
```python
code: str = 'data_integrity_error'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L288-288)
### plugins_api.exceptions.DataIntegrityError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'dataobject'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L289-289)
### plugins_api.exceptions.DataIntegrityError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = dataobject
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L290-290)
## plugins_api.exceptions.DataInvalidError
*class*
```python
class DataInvalidError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised for invalid data objects.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L185-212)
### plugins_api.exceptions.DataInvalidError.code
*attribute* · *instance attribute*
```python
code: str = 'invalid_dataobject'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L198-198)
### plugins_api.exceptions.DataInvalidError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'dataobject'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L199-199)
### plugins_api.exceptions.DataInvalidError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = dataobject
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L200-200)
## plugins_api.exceptions.DataNotFoundError
*class*
```python
class DataNotFoundError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised when a data object is not found.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L155-182)
### plugins_api.exceptions.DataNotFoundError.code
*attribute* · *instance attribute*
```python
code: str = 'dataobject_not_found'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L168-168)
### plugins_api.exceptions.DataNotFoundError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'dataobject'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L169-169)
### plugins_api.exceptions.DataNotFoundError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = dataobject
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L170-170)
## plugins_api.exceptions.DownloadDataError
*class*
```python
class DownloadDataError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised for error during data download.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L245-272)
### plugins_api.exceptions.DownloadDataError.code
*attribute* · *instance attribute*
```python
code: str = 'download_data_error'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L258-258)
### plugins_api.exceptions.DownloadDataError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'dataobject'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L259-259)
### plugins_api.exceptions.DownloadDataError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = reason
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L260-260)
## plugins_api.exceptions.HostConnectionRefusedError
*class*
```python
class HostConnectionRefusedError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised when the host is reachable but refuses the TCP connection.
Distinct from ``UnreachableError``: the network path to the host works,
but nothing accepted the connection (for example sshd down, wrong port, or
an active reject). Plugins typically map ``errno.ECONNREFUSED`` to this.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L102-138)
### plugins_api.exceptions.HostConnectionRefusedError.code
*attribute* · *instance attribute*
```python
code: str = 'connection_refused'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L121-121)
### plugins_api.exceptions.HostConnectionRefusedError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'hostname'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L122-122)
### plugins_api.exceptions.HostConnectionRefusedError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = host
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L123-123)
## plugins_api.exceptions.InvalidPluginTypeError
*class*
```python
class InvalidPluginTypeError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised for invalid plugin types.
This error is raised when an invalid plugin type is provided for a certain operation.
For instance, when trying to retrieve the instance of a plugin that is not a ConnectionPlugin,
as only ConnectionPlugins (and its subclasses) are allowed to be instantiated.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L304-337)
### plugins_api.exceptions.InvalidPluginTypeError.code
*attribute* · *instance attribute*
```python
code: str = 'invalid_plugin_type'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L323-323)
### plugins_api.exceptions.InvalidPluginTypeError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'plugin_type'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L324-324)
### plugins_api.exceptions.InvalidPluginTypeError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = plugin_type
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L325-325)
## plugins_api.exceptions.PluginError
*class*
```python
class PluginError(Exception)
```
Bases: `Exception`
Base class for exceptions related to plugins.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L25-28)
## plugins_api.exceptions.PluginNotFoundError
*class*
```python
class PluginNotFoundError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised when a plugin is not found.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L31-58)
### plugins_api.exceptions.PluginNotFoundError.code
*attribute* · *instance attribute*
```python
code: str = 'plugin_not_found'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L44-44)
### plugins_api.exceptions.PluginNotFoundError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'plugin'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L45-45)
### plugins_api.exceptions.PluginNotFoundError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = plugin
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L46-46)
## plugins_api.exceptions.PluginPermissionError
*class*
```python
class PluginPermissionError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised for permission errors related to plugins.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L215-242)
### plugins_api.exceptions.PluginPermissionError.code
*attribute* · *instance attribute*
```python
code: str = 'permission_error'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L228-228)
### plugins_api.exceptions.PluginPermissionError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'plugin'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L229-229)
### plugins_api.exceptions.PluginPermissionError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = reason
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L230-230)
## plugins_api.exceptions.PluginSubmissionError
*class*
```python
class PluginSubmissionError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised for submission-related errors in plugins.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L340-367)
### plugins_api.exceptions.PluginSubmissionError.code
*attribute* · *instance attribute*
```python
code: str = 'plugin_submission_error'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L353-353)
### plugins_api.exceptions.PluginSubmissionError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'submission'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L354-354)
### plugins_api.exceptions.PluginSubmissionError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = reason
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L355-355)
## plugins_api.exceptions.SizeLimitExceededError
*class*
```python
class SizeLimitExceededError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised when size or file count limits are exceeded.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L370-396)
### plugins_api.exceptions.SizeLimitExceededError.code
*attribute* · *instance attribute*
```python
code: str = 'size_limit_exceeded'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L382-382)
### plugins_api.exceptions.SizeLimitExceededError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'submission'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L383-383)
### plugins_api.exceptions.SizeLimitExceededError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = reason
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L384-384)
## plugins_api.exceptions.UnreachableError
*class*
```python
class UnreachableError(PluginError)
```
Bases: `plugins_api.exceptions.PluginError`
Exception raised when a host is unreachable.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L72-99)
### plugins_api.exceptions.UnreachableError.code
*attribute* · *instance attribute*
```python
code: str = 'hostname_unreachable'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L85-85)
### plugins_api.exceptions.UnreachableError.parameter
*attribute* · *instance attribute*
```python
parameter: str = 'hostname'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L86-86)
### plugins_api.exceptions.UnreachableError.parameter_value
*attribute* · *instance attribute*
```python
parameter_value: str = host
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/exceptions.py#L87-87)
---
# plugins_api.metadata_plugins
*module*
Metadata-related plugin classes.
This module contains classes for metadata field definition and mapping.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L1-1)
## plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin
*class*
```python
class MetadataFieldDefinitionPlugin(MadbotPlugin)
```
Bases: `plugins_api.base.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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L22-296)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.convert_madbot_to_plugin
*method* · *abstract* · *classmethod*
```python
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**
- `values` (`Dict[str, Any]`) — Values keyed by madbot field slug.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`Dict[str, Any]`) — The transformed values from the madbot referential to the plugin referential.
**Examples**
Convert a full name from madbot to plugin format
```pycon
>>> print(self.convert_madbot_to_plugin({"full_name": "John Doe"}))
{"first_name": "John", "last_name": "Doe"}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L238-266)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.convert_plugin_to_madbot
*method* · *abstract* · *classmethod*
```python
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**
- `values` (`Dict[str, Any]`) — Values keyed by plugin field slug.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`Dict[str, Any]`) — The transformed values from the plugin referential to the madbot referential.
**Examples**
Convert a full name from plugin to madbot format
```pycon
>>> print(self.convert_plugin_to_madbot({"first_name": "John", "last_name": "Doe"}))
{"full_name": "John Doe"}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L268-296)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_all_mappings
*method* · *abstract* · *classmethod*
```python
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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L149-163)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_all_metadata_object_types
*method* · *abstract* · *classmethod*
```python
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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L118-130)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_contextual_metadata_object_types
*method* · *abstract*
```python
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).
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L132-147)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_madbot_field_mapping
*method* · *abstract* · *classmethod*
```python
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**
- `madbot_field` (`str`) — Madbot field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L192-213)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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.
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.
> **Required shape**
>
> - Recreate each MOT as a ``type="mot"`` node whose ``slug`` matches
> ``get_all_metadata_object_types()`` (e.g. Zenodo ``"general"``).
> - Put UI folders under those MOTs as ``type="subgroup"`` children.
> - Do not mix fields from different MOTs in the same subgroup.
> - Use ``children`` (not a ``groups`` key).
> **Parent semantics**
>
> - ``parent=None``: full tree from root nodes.
> - ``parent=``: direct children of that node.
> - Unknown parent: raise ``ValueError``.
**Parameters**
- `parent` (`str`) (default: `None`) — Parent slug to expand.
**Returns**
- (`list[MetadataGroupNodeDTO]`) — Metadata group nodes.
**Examples**
One MOT with subgroups (``parent=None``):
```pycon
>>> 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:
```pycon
>>> 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=[],
)
]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L37-116)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_plugin_field_mapping
*method* · *abstract* · *classmethod*
```python
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**
- `plugin_field` (`str`) — Plugin field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L215-236)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L82-94)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L113-127)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L68-80)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L24-35)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L96-111)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L37-49)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L51-66)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L129-162)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L164-181)
## plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping
*class*
```python
class MetadataFieldDefinitionPluginWithStandardMapping(MetadataFieldDefinitionPlugin)
```
Bases: `plugins_api.metadata_plugins.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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L774-1025)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.mapper
*attribute* · *class attribute* · *instance attribute*
```python
mapper: StandardMetadataMapper | None = None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L792-792)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.convert_madbot_to_plugin
*method* · *classmethod*
```python
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**
- `values` (`Dict[str, Any]`) — Values keyed by madbot field slug.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`Dict[str, Any]`) — The transformed values from the madbot referential to the plugin referential.
**Raises**
- `NotImplementedError` — If no mapper is set.
**Examples**
Convert a full name from madbot to plugin format
```pycon
>>> print(self.convert_madbot_to_plugin({"full_name": "John Doe"}))
{"first_name": "John", "last_name": "Doe"}
```
Convert multiple fields
```pycon
>>> print(self.convert_madbot_to_plugin({"title": "Hello World", "description": "A test"}))
{"name": "HELLO WORLD", "desc": "A test"}
```
Convert with specific checklist filter
```pycon
>>> print(self.convert_madbot_to_plugin({"name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"}))
{"sample_name": "Sample123"}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L931-977)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.convert_plugin_to_madbot
*method* · *classmethod*
```python
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**
- `values` (`Dict[str, Any]`) — Values keyed by plugin field slug.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`Dict[str, Any]`) — The transformed values from the plugin referential to the madbot referential.
**Raises**
- `NotImplementedError` — If no mapper is set.
**Examples**
Convert a full name from plugin to madbot format
```pycon
>>> print(self.convert_plugin_to_madbot({"first_name": "John", "last_name": "Doe"}))
{"full_name": "John Doe"}
```
Convert multiple fields
```pycon
>>> print(self.convert_plugin_to_madbot({"name": "Hello World", "desc": "A test"}))
{"title": "HELLO WORLD", "description": "A test"}
```
Convert with specific checklist filter
```pycon
>>> print(self.convert_plugin_to_madbot({"sample_name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"}))
{"name": "Sample123"}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L979-1025)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_all_mappings
*method* · *classmethod*
```python
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**
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`List[MetadataFieldMapping]`) — List of all field mappings between both referential, optionally filtered.
**Raises**
- `NotImplementedError` — If no mapper is set.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L809-836)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_madbot_field_mapping
*method* · *classmethod*
```python
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**
- `madbot_field` (`str`) — Field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.
**Raises**
- `NotImplementedError` — If no mapper is set.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L873-900)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_plugin_field_mapping
*method* · *classmethod*
```python
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**
- `plugin_field` (`str`) — Field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.
**Raises**
- `NotImplementedError` — If no mapper is set.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L902-929)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.set_mapper
*method* · *classmethod*
```python
def set_mapper(mapper: StandardMetadataMapper) -> None
```
Set the mapper for this plugin class.
This method sets the mapper that will be used by all instances of this class.
**Parameters**
- `mapper` (`StandardMetadataMapper`) — The mapper to use for field transformations.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L794-807)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_all_metadata_object_types
*method* · *abstract* · *classmethod*
```python
def get_all_metadata_object_types() -> dict[str, MetadataObjectType]
```
Inherited from: `plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin`
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.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L118-130)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_contextual_metadata_object_types
*method* · *abstract*
```python
def get_contextual_metadata_object_types() -> dict[str, MetadataObjectType]
```
Inherited from: `plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin`
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).
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L132-147)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_metadata_fields_groups
*method* · *abstract* · *classmethod*
```python
def get_metadata_fields_groups(parent: str | None = None) -> list[MetadataGroupNodeDTO]
```
Inherited from: `plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin`
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.
> **Required shape**
>
> - Recreate each MOT as a ``type="mot"`` node whose ``slug`` matches
> ``get_all_metadata_object_types()`` (e.g. Zenodo ``"general"``).
> - Put UI folders under those MOTs as ``type="subgroup"`` children.
> - Do not mix fields from different MOTs in the same subgroup.
> - Use ``children`` (not a ``groups`` key).
> **Parent semantics**
>
> - ``parent=None``: full tree from root nodes.
> - ``parent=``: direct children of that node.
> - Unknown parent: raise ``ValueError``.
**Parameters**
- `parent` (`str`) (default: `None`) — Parent slug to expand.
**Returns**
- (`list[MetadataGroupNodeDTO]`) — Metadata group nodes.
**Examples**
One MOT with subgroups (``parent=None``):
```pycon
>>> 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:
```pycon
>>> 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=[],
)
]
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L37-116)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L82-94)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L113-127)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L68-80)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L24-35)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L96-111)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L37-49)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L51-66)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L129-162)
### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L164-181)
## plugins_api.metadata_plugins.StandardMetadataMapper
*class*
```python
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**
- `_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
```pycon
>>> mapper = StandardMetadataMapper()
```
Simple one-to-one mapping
```pycon
>>> 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
```pycon
>>> 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)
```pycon
>>> 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
... )
```
```pycon
>>> 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
```pycon
>>> print(mapper.convert_plugin_to_madbot({"title": "Hello World"}, mapping_filter={"mapping_id": "erc000010"}))
{"name": "HELLO WORLD"}
```
Convert madbot to plugin with filtering
```pycon
>>> print(mapper.convert_madbot_to_plugin({"name": "HELLO WORLD"}, mapping_filter={"mapping_id": "erc000010"}))
{"title": "hello world"}
```
```pycon
>>> 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=,
transform_plugin_to_madbot=,
)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L299-771)
### plugins_api.metadata_plugins.StandardMetadataMapper.add_mapping
*method*
```python
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) -> None
```
Add 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**
- `plugin_fields` (`Union[str, List[str]]`) — Plugin field slug, or list of slugs.
- `madbot_fields` (`Union[str, List[str]]`) — Madbot field slug, or list of slugs.
- `transform_plugin_to_madbot` (`Callable`) (default: `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`) (default: `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]`) (default: `None`) — Unique identifier for this mapping rule. Useful for distinguishing between multiple mappings for the same field (e.g., different checklists).
- `**kwargs` (`Any`) (default: `{}`) — Additional metadata for the mapping (e.g., checklist, version, etc.)
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L393-462)
### plugins_api.metadata_plugins.StandardMetadataMapper.convert_madbot_to_plugin
*method*
```python
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**
- `values` (`Dict[str, Any]`) — 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]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`Dict[str, Any]`) — Dictionary of plugin field slugs to their converted values.
**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
```pycon
>>> print(mapper.convert_madbot_to_plugin({"full_name": "John Doe"}))
{"first_name": "John", "last_name": "Doe"}
```
Convert multiple fields
```pycon
>>> print(mapper.convert_madbot_to_plugin({"title": "Hello World", "description": "A test"}))
{"name": "HELLO WORLD", "desc": "A test"}
```
Convert with specific checklist filter
```pycon
>>> print(mapper.convert_madbot_to_plugin({"name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"}))
{"sample_name": "Sample123"}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L617-693)
### plugins_api.metadata_plugins.StandardMetadataMapper.convert_plugin_to_madbot
*method*
```python
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**
- `values` (`Dict[str, Any]`) — 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]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`Dict[str, Any]`) — Dictionary of madbot field slugs to their converted values.
**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
```pycon
>>> print(mapper.convert_plugin_to_madbot({"first_name": "John", "last_name": "Doe"}))
{"full_name": "John Doe"}
```
Convert multiple fields
```pycon
>>> print(mapper.convert_plugin_to_madbot({"name": "Hello World", "desc": "A test"}))
{"title": "HELLO WORLD", "description": "A test"}
```
Convert with specific checklist filter
```pycon
>>> print(mapper.convert_plugin_to_madbot({"sample_name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"}))
{"name": "Sample123"}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L695-771)
### plugins_api.metadata_plugins.StandardMetadataMapper.get_all_mappings
*method*
```python
def get_all_mappings(mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```
Get all mappings for the plugin, optionally filtered.
**Parameters**
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`List[MetadataFieldMapping]`) — List of all field mappings between both referential, optionally filtered.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L506-527)
### plugins_api.metadata_plugins.StandardMetadataMapper.get_madbot_field_mapping
*method*
```python
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**
- `madbot_field` (`str`) — Madbot field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L572-593)
### plugins_api.metadata_plugins.StandardMetadataMapper.get_plugin_field_mapping
*method*
```python
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**
- `plugin_field` (`str`) — Plugin field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.
**Returns**
- (` List[MetadataFieldMapping]: List of mapping information for the specified field.`)
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L595-615)
---
# 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L28-410)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L266-299)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L85-101)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L175-211)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L252-264)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L213-250)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L103-130)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L132-145)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L147-173)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L345-380)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L301-343)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/submission_plugins.py#L382-410)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L237-249)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L206-222)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L193-204)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L224-235)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L251-268)
### 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`
Transform the private parameters just before they are written to the Vault.
Allows the plugin to transform or enrich the private_params.
By default, returns the params unchanged.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L270-282)
### 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`
Clean up just before the credentials are deleted 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L284-296)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L82-94)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L113-127)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L68-80)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L24-35)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L96-111)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L37-49)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L51-66)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L129-162)
### 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/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L164-181)
---
# plugins_api.utils
*module*
Helpers shared by madbot and the plugins.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/__init__.py#L1-1)
**Modules**
- `plugins_api.utils.format_utils`
- `plugins_api.utils.icons`
- `plugins_api.utils.level_from_plugin`
- `plugins_api.utils.plugin_utils`
---
# plugins_api.utils.format_utils
*module*
Format and conversion utilities for plugins_api.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/format_utils.py#L1-1)
## plugins_api.utils.format_utils.extract_file_extension
*function*
```python
def extract_file_extension(filename: str | None) -> str | None
```
Derive a normalized file extension from a filename or path.
Uses the basename only. When the final segment is a known compression
suffix (``gz``, ``bz2``, ``xz``, ``zst``, ``zip``, ``z``) and a preceding
segment exists, returns a compound extension (e.g. ``fastq.gz``).
**Parameters**
- `filename` (`str or None`) — File name or path (e.g. ``"/data/sample.fastq.gz"``).
**Returns**
- (`str or None`) — Extension without a leading dot, or ``None`` when none can be derived.
**Examples**
```pycon
>>> extract_file_extension("sample.fastq.gz")
'fastq.gz'
>>> extract_file_extension("reads.fq")
'fq'
>>> extract_file_extension("archive.tar.gz")
'tar.gz'
>>> extract_file_extension("README")
None
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/format_utils.py#L32-73)
## plugins_api.utils.format_utils.is_file_extension_supported
*function*
```python
def is_file_extension_supported(file_extension: str | None, supported_extensions: list[str] | tuple[str, ...] | set[str]) -> bool
```
Return whether ``file_extension`` is allowed by ``supported_extensions``.
An empty ``supported_extensions`` list means all extensions are allowed.
Missing / blank ``file_extension`` is never allowed when the list is
non-empty. Comparison is case-insensitive and ignores a leading dot.
**Parameters**
- `file_extension` (`str or None`) — Extension stored on a data object.
- `supported_extensions` (`list[str] | tuple[str, ...] | set[str]`) — Plugin-declared supported extensions. Empty means unrestricted.
**Returns**
- (`bool`) — ``True`` if the extension is accepted.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/format_utils.py#L76-110)
## plugins_api.utils.format_utils.normalize_file_extension
*function*
```python
def normalize_file_extension(extension: str | None) -> str | None
```
Normalize a stored or declared file extension.
Strips whitespace and a leading dot, lowercases the value, and maps empty
results to ``None``. Compound extensions such as ``fastq.gz`` are preserved.
**Parameters**
- `extension` (`str or None`) — Raw extension (e.g. ``".FASTQ"``, ``"fastq.gz"``, ``""``).
**Returns**
- (`str or None`) — Normalized extension without a leading dot, or ``None`` if missing.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/format_utils.py#L9-29)
## plugins_api.utils.format_utils.size_to_bytes
*function*
```python
def size_to_bytes(size: float, unit: str = 'bytes') -> int
```
Convert a size value with unit to bytes.
**Parameters**
- `size` (`float`) — The size value to convert.
- `unit` (`str`) (default: `'bytes'`) — The unit of the size. Must be one of: - SI (decimal) units: 'bytes', 'KB', 'MB', 'GB', 'TB' - Binary (IEC) units: 'KiB', 'MiB', 'GiB', 'TiB' Case-insensitive. Default is 'bytes'.
**Returns**
- (`int`) — The size in bytes.
**Raises**
- `ValueError` — If an invalid unit is provided.
**Examples**
Decimal (SI) conversion:
```pycon
>>> size_to_bytes(100, "MB")
100000000
```
```pycon
>>> size_to_bytes(50, "GB")
50000000000
```
Binary (IEC) conversion:
```pycon
>>> size_to_bytes(1024, "KiB")
1048576
```
```pycon
>>> size_to_bytes(100, "MiB")
104857600
```
```pycon
>>> size_to_bytes(50, "GiB")
53687091200
```
> **Notes**
>
> **Decimal (SI) conversion** (using KB, MB, GB, TB):
> - 1 KB = 1000 bytes
> - 1 MB = 1000 KB = 1,000,000 bytes
> - 1 GB = 1000 MB = 1,000,000,000 bytes
> - 1 TB = 1000 GB = 1,000,000,000,000 bytes
>
> **Binary (IEC) conversion** (using KiB, MiB, GiB, TiB):
> - 1 KiB = 1024 bytes
> - 1 MiB = 1024 KiB = 1,048,576 bytes
> - 1 GiB = 1024 MiB = 1,073,741,824 bytes
> - 1 TiB = 1024 GiB = 1,099,511,627,776 bytes
>
> Most APIs and cloud storage services use decimal (SI) conversion.
> Use binary (IEC) units when working with system-level file sizes.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/format_utils.py#L113-195)
---
# plugins_api.utils.icons
*module*
Icon utilities for plugins_api.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/icons.py#L1-1)
## plugins_api.utils.icons.ByExtension
*attribute* · *module attribute*
```python
ByExtension = {'1': 'nf nf-fa-book', '2': 'nf nf-fa-book', '3': 'nf nf-fa-book', '4': 'nf nf-fa-book', '5': 'nf nf-fa-book', '6': 'nf nf-fa-book', '7': 'nf nf-fa-book', '7z': 'nf nf-oct-file_zip', '8': 'nf nf-fa-book', 'a': 'nf nf-seti-julia', 'ai': 'nf nf-dev-illustrator', 'ape': 'nf nf-fa-music', 'apk': 'nf nf-dev-android', 'apng': 'nf nf-fa-file_image', 'ar': 'nf nf-oct-file_zip', 'asc': 'nf nf-md-shield_lock', 'asm': 'nf nf-oct-file_binary', 'asp': 'nf nf-fa-code', 'avi': 'nf nf-fa-film', 'avif': 'nf nf-fa-file_image', 'avro': 'nf nf-seti-json', 'awk': 'nf nf-oct-terminal', 'bak': 'nf nf-md-backup_restore', 'bash_history': 'nf nf-oct-terminal', 'bash_profile': 'nf nf-oct-terminal', 'bashrc': 'nf nf-oct-terminal', 'bash': 'nf nf-oct-terminal', 'bat': 'nf nf-fa-windows', 'bin': 'nf nf-cod-file_binary', 'bio': 'nf nf-md-playlist_play', 'blend': 'nf nf-md-blender_software', 'blend1': 'nf nf-md-blender_software', 'bmp': 'nf nf-fa-file_image', 'bz2': 'nf nf-oct-file_zip', 'cc': 'nf nf-custom-cpp', 'cfg': 'nf nf-seti-config', 'cjs': 'nf nf-dev-javascript', 'class': 'nf nf-dev-java', 'cljs': 'nf nf-dev-clojure_alt', 'clj': 'nf nf-dev-clojure', 'cls': 'nf nf-seti-stylus', 'cl': 'nf nf-md-code_parentheses', 'coffee': 'nf nf-fa-coffee', 'conf': 'nf nf-seti-config', 'cpp': 'nf nf-custom-cpp', 'cp': 'nf nf-custom-cpp', 'cshtml': 'nf nf-fa-at', 'csh': 'nf nf-oct-terminal', 'csproj': 'nf nf-md-language_csharp', 'css': 'nf nf-dev-css3', 'cs': 'nf nf-md-language_csharp', 'csv': 'nf nf-fa-file_excel', 'csx': 'nf nf-md-language_csharp', 'cts': 'nf nf-seti-typescript', 'c++': 'nf nf-custom-cpp', 'c': 'nf nf-custom-c', 'cue': 'nf nf-fa-music', 'cxx': 'nf nf-custom-cpp', 'cypher': 'nf nf-fa-database', 'dart': 'nf nf-dev-dart', 'dat': 'nf nf-fa-database', 'db': 'nf nf-fa-database', 'deb': 'nf nf-fa-archive', 'desktop': 'nf nf-fa-desktop', 'diff': 'nf nf-dev-git_compare', 'dll': 'nf nf-fa-windows', 'dockerfile': 'nf nf-linux-docker', 'doc': 'nf nf-fa-file_word', 'docx': 'nf nf-fa-file_word', 'download': 'nf nf-oct-clock', 'ds_store': 'nf nf-fa-apple', 'dump': 'nf nf-fa-database', 'ebook': 'nf nf-fae-book_open_o', 'ebuild': 'nf nf-linux-gentoo', 'eclass': 'nf nf-linux-gentoo', 'editorconfig': 'nf nf-seti-config', 'egg-info': 'nf nf-seti-python', 'ejs': 'nf nf-seti-ejs', 'elc': 'nf nf-md-code_parentheses', 'elf': 'nf nf-oct-terminal', 'elm': 'nf nf-custom-elm', 'el': 'nf nf-md-code_parentheses', 'env': 'nf nf-oct-sliders', 'eot': 'nf nf-fa-font', 'epub': 'nf nf-fae-book_open', 'erb': 'nf nf-dev-ruby_on_rails', 'erl': 'nf nf-dev-erlang', 'exe': 'nf nf-fa-windows', 'exs': 'nf nf-custom-elixir', 'ex': 'nf nf-custom-elixir', 'fish': 'nf nf-oct-terminal', 'flac': 'nf nf-fa-music', 'flv': 'nf nf-fa-film', 'fnl': 'nf nf-custom-fennel', 'font': 'nf nf-fa-font', 'fpl': 'nf nf-md-playlist_play', 'fsi': 'nf nf-dev-fsharp', 'fs': 'nf nf-dev-fsharp', 'fsx': 'nf nf-dev-fsharp', 'gdoc': 'nf nf-fa-file_word', 'gemfile': 'nf nf-fae-ruby_o', 'gemspec': 'nf nf-fae-ruby_o', 'gform': 'nf nf-fa-wpforms', 'gif': 'nf nf-fa-file_image', 'git': 'nf nf-fa-git', 'go': 'nf nf-seti-go', 'gradle': 'nf nf-seti-gradle', 'gsheet': 'nf nf-fa-file_excel', 'gslides': 'nf nf-fa-file_powerpoint', 'guardfile': 'nf nf-fae-ruby_o', 'gv': 'nf nf-md-graph', 'gz': 'nf nf-oct-file_zip', 'hbs': 'nf nf-seti-mustache', 'heic': 'nf nf-fa-file_image', 'heif': 'nf nf-fa-file_image', 'heix': 'nf nf-fa-file_image', 'hh': 'nf nf-fa-h_square', 'hpp': 'nf nf-fa-h_square', 'hs': 'nf nf-dev-haskell', 'html': 'nf nf-fa-html5', 'htm': 'nf nf-fa-html5', 'h': 'nf nf-fa-h_square', 'hxx': 'nf nf-fa-h_square', 'ico': 'nf nf-fa-file_image', 'image': 'nf nf-fa-file_image', 'img': 'nf nf-fa-database', 'iml': 'nf nf-dev-intellij', 'info': 'nf nf-dev-terminal', 'in': 'nf nf-fa-file_lines', 'ini': 'nf nf-seti-config', 'ipynb': 'nf nf-seti-python', 'iso': 'nf nf-fa-database', 'j2': 'nf nf-pom-clean_code', 'jar': 'nf nf-dev-java', 'java': 'nf nf-dev-java', 'jinja': 'nf nf-pom-clean_code', 'jl': 'nf nf-seti-julia', 'jpeg': 'nf nf-fa-file_image', 'jpg': 'nf nf-fa-file_image', 'jsonc': 'nf nf-seti-json', 'json': 'nf nf-seti-json', 'js': 'nf nf-dev-javascript', 'jsx': 'nf nf-dev-react', 'key': 'nf nf-md-key', 'ksh': 'nf nf-oct-terminal', 'kt': 'nf nf-custom-kotlin', 'kts': 'nf nf-custom-kotlin', 'kusto': 'nf nf-fa-database', 'ldb': 'nf nf-fa-database', 'ld': 'nf nf-seti-julia', 'less': 'nf nf-dev-less', 'lhs': 'nf nf-dev-haskell', 'license': 'nf nf-seti-license', 'lisp': 'nf nf-md-code_parentheses', 'list': 'nf nf-fa-list', 'localized': 'nf nf-fa-apple', 'lock': 'nf nf-fa-lock', 'log': 'nf nf-fa-stack_exchange', 'lss': 'nf nf-dev-css3', 'lua': 'nf nf-seti-lua', 'lz': 'nf nf-oct-file_zip', 'mgc': 'nf nf-fa-magic', 'm3u8': 'nf nf-md-playlist_play', 'm3u': 'nf nf-md-playlist_play', 'm4a': 'nf nf-fa-music', 'm4v': 'nf nf-fa-film', 'magnet': 'nf nf-fa-magnet', 'malloy': 'nf nf-fa-database', 'man': 'nf nf-fa-book', 'markdown': 'nf nf-fa-markdown', 'md': 'nf nf-fa-markdown', 'mjs': 'nf nf-dev-javascript', 'mkd': 'nf nf-fa-markdown', 'mk': 'nf nf-fa-cogs', 'mkv': 'nf nf-fa-film', 'ml': 'nf nf-seti-ocaml', 'mli': 'nf nf-seti-ocaml', 'mll': 'nf nf-seti-ocaml', 'mly': 'nf nf-seti-ocaml', 'mobi': 'nf nf-fae-book_open_o', 'mov': 'nf nf-fa-film', 'mp3': 'nf nf-fa-music', 'mp4': 'nf nf-fa-film', 'msi': 'nf nf-fa-windows', 'mts': 'nf nf-seti-typescript', 'mustache': 'nf nf-seti-mustache', 'nim': 'nf nf-seti-nim', 'nimble': 'nf nf-seti-nim', 'nix': 'nf nf-linux-nixos', 'npmignore': 'nf nf-dev-npm', 'odp': 'nf nf-fa-file_powerpoint', 'ods': 'nf nf-fa-file_excel', 'odt': 'nf nf-fa-file_word', 'ogg': 'nf nf-fa-music', 'ogv': 'nf nf-fa-film', 'old': 'nf nf-md-backup_restore', 'opus': 'nf nf-fa-music', 'orig': 'nf nf-md-backup_restore', 'org': 'nf nf-custom-orgmode', 'otf': 'nf nf-fa-font', 'o': 'nf nf-cod-file_binary', 'part': 'nf nf-oct-clock', 'patch': 'nf nf-dev-git_compare', 'pdb': 'nf nf-md-database_lock', 'pdf': 'nf nf-fa-file_pdf', 'pem': 'nf nf-md-key', 'phar': 'nf nf-seti-php', 'php': 'nf nf-seti-php', 'pkg': 'nf nf-fa-archive', 'pl': 'nf nf-seti-perl', 'plist': 'nf nf-linux-apple', 'pls': 'nf nf-md-playlist_play', 'plx': 'nf nf-seti-perl', 'pm': 'nf nf-seti-perl', 'png': 'nf nf-fa-file_image', 'pod': 'nf nf-seti-perl', 'pp': 'nf nf-custom-puppet', 'ppt': 'nf nf-fa-file_powerpoint', 'pptx': 'nf nf-fa-file_powerpoint', 'procfile': 'nf nf-fae-ruby_o', 'properties': 'nf nf-seti-json', 'prql': 'nf nf-fa-database', 'ps1': 'nf nf-oct-terminal', 'psd': 'nf nf-dev-photoshop', 'pub': 'nf nf-md-key', 'slt': 'nf nf-md-file_lock', 'pxm': 'nf nf-fa-file_image', 'pyc': 'nf nf-seti-python', 'py': 'nf nf-seti-python', 'rakefile': 'nf nf-fae-ruby_o', 'rar': 'nf nf-oct-file_zip', 'razor': 'nf nf-fa-at', 'rb': 'nf nf-fae-ruby_o', 'rdata': 'nf nf-md-language_r', 'rdb': 'nf nf-dev-redis', 'rdoc': 'nf nf-fa-markdown', 'rds': 'nf nf-md-language_r', 'readme': 'nf nf-fa-readme', 'rlib': 'nf nf-seti-rust', 'rl': 'nf nf-fa-keyboard', 'rmd': 'nf nf-fa-markdown', 'rmeta': 'nf nf-seti-rust', 'rpm': 'nf nf-fa-archive', 'rproj': 'nf nf-md-vector_rectangle', 'rq': 'nf nf-fa-database', 'rspec_parallel': 'nf nf-fae-ruby_o', 'rspec_status': 'nf nf-fae-ruby_o', 'rspec': 'nf nf-fae-ruby_o', 'rss': 'nf nf-fa-feed', 'rs': 'nf nf-seti-rust', 'rtf': 'nf nf-fa-file_lines', 'rubydoc': 'nf nf-dev-ruby_on_rails', 'r': 'nf nf-md-language_r', 'ru': 'nf nf-fae-ruby_o', 'sass': 'nf nf-seti-sass', 'scala': 'nf nf-dev-scala', 'scpt': 'nf nf-linux-apple', 'scss': 'nf nf-seti-sass', 'shell': 'nf nf-oct-terminal', 'sh': 'nf nf-oct-terminal', 'sig': 'nf nf-seti-license', 'slim': 'nf nf-dev-ruby_on_rails', 'sln': 'nf nf-dev-visualstudio', 'so': 'nf nf-seti-julia', 'sqlite3': 'nf nf-dev-sqlite', 'sql': 'nf nf-fa-database', 'srt': 'nf nf-md-subtitles', 'styl': 'nf nf-seti-stylus', 'stylus': 'nf nf-seti-stylus', 'sublime-menu': 'nf nf-dev-sublime', 'sublime-package': 'nf nf-dev-sublime', 'sublime-project': 'nf nf-dev-sublime', 'sublime-session': 'nf nf-dev-sublime', 'sub': 'nf nf-md-subtitles', 's': 'nf nf-oct-file_binary', 'svg': 'nf nf-fa-file_image', 'svelte': 'nf nf-seti-svelte', 'swift': 'nf nf-dev-swift', 'swp': 'nf nf-custom-vim', 'sym': 'nf nf-cod-file_binary', 'tar': 'nf nf-oct-file_zip', 'taz': 'nf nf-oct-file_zip', 'tbz': 'nf nf-oct-file_zip', 'tbz2': 'nf nf-oct-file_zip', 'tex': 'nf nf-seti-stylus', 'tgz': 'nf nf-oct-file_zip', 'tiff': 'nf nf-fa-file_image', 'timestamp': 'nf nf-oct-clock', 'toml': 'nf nf-seti-json', 'torrent': 'nf nf-md-server_network', 'trash': 'nf nf-fa-trash', 'ts': 'nf nf-seti-typescript', 'tsx': 'nf nf-dev-react', 'ttc': 'nf nf-fa-font', 'ttf': 'nf nf-fa-font', 't': 'nf nf-dev-perl', 'twig': 'nf nf-seti-twig', 'txt': 'nf nf-fa-file_lines', 'unity': 'nf nf-dev-unity_small', 'unity32': 'nf nf-dev-unity_small', 'video': 'nf nf-fa-film', 'vim': 'nf nf-custom-vim', 'vlc': 'nf nf-md-playlist_play', 'vue': 'nf nf-md-vuejs', 'wav': 'nf nf-fa-music', 'webm': 'nf nf-fa-film', 'webp': 'nf nf-fa-file_image', 'whl': 'nf nf-oct-package', 'windows': 'nf nf-fa-windows', 'wma': 'nf nf-fa-music', 'wmv': 'nf nf-fa-film', 'woff2': 'nf nf-fa-font', 'woff': 'nf nf-fa-font', 'wpl': 'nf nf-md-playlist_play', 'xbps': 'nf nf-fa-archive', 'xcf': 'nf nf-fa-file_image', 'xls': 'nf nf-fa-file_excel', 'xlsx': 'nf nf-fa-file_excel', 'xml': 'nf nf-fa-code', 'xul': 'nf nf-fa-firefox', 'xz': 'nf nf-oct-file_zip', 'yaml': 'nf nf-seti-json', 'yml': 'nf nf-seti-json', 'zip': 'nf nf-oct-file_zip', 'zig': 'nf nf-seti-zig', 'zshrc': 'nf nf-oct-terminal', 'zsh-theme': 'nf nf-oct-terminal', 'zsh': 'nf nf-oct-terminal', 'zst': 'nf nf-oct-file_zip'}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/icons.py#L7-337)
## plugins_api.utils.icons.ByFileName
*attribute* · *module attribute*
```python
ByFileName = {'a.out': 'nf nf-oct-terminal', 'api': 'nf nf-md-server_network', '.asoundrc': 'nf nf-seti-config', '.atom': 'nf nf-dev-atom', '.ash': 'nf nf-oct-terminal', '.ash_history': 'nf nf-oct-terminal', 'authorized_keys': 'nf nf-seti-license', 'assets': 'nf nf-fa-floppy_disk', '.android': 'nf nf-fa-android', '.audacity-data': 'nf nf-custom-folder_config', 'backups': 'nf nf-md-backup_restore', '.bash_history': 'nf nf-md-bash', '.bash_logout': 'nf nf-md-bash', '.bash_profile': 'nf nf-md-bash', '.bashrc': 'nf nf-md-bash', 'bin': 'nf nf-custom-folder_config', '.bpython_history': 'nf nf-seti-python', 'build': 'nf nf-oct-package', 'bspwmrc': 'nf nf-seti-config', 'build.ninja': 'nf nf-fa-wrench', '.cache': 'nf nf-md-cached', 'cache': 'nf nf-md-cached', 'cargo.lock': 'nf nf-seti-rust', 'cargo.toml': 'nf nf-seti-rust', '.cargo': 'nf nf-seti-rust', '.ccls-cache': 'nf nf-md-cached', 'changelog': 'nf nf-fa-markdown', '.clang-format': 'nf nf-seti-config', 'composer.json': 'nf nf-seti-php', 'composer.lock': 'nf nf-seti-php', 'conf.d': 'nf nf-custom-folder_config', 'config.ac': 'nf nf-seti-config', 'config.el': 'nf nf-custom-emacs', 'config.mk': 'nf nf-seti-config', '.config': 'nf nf-custom-folder_config', 'config': 'nf nf-custom-folder_config', 'configure': 'nf nf-fa-wrench', 'content': 'nf nf-fa-floppy_disk', 'contributing': 'nf nf-seti-license', 'copyright': 'nf nf-seti-license', 'cron.daily': 'nf nf-custom-folder_config', 'cron.d': 'nf nf-custom-folder_config', 'cron.deny': 'nf nf-seti-config', 'cron.hourly': 'nf nf-custom-folder_config', 'cron.monthly': 'nf nf-custom-folder_config', 'crontab': 'nf nf-seti-config', 'cron.weekly': 'nf nf-custom-folder_config', 'crypttab': 'nf nf-seti-config', '.cshrc': 'nf nf-md-bash', 'csh.cshrc': 'nf nf-md-bash', 'csh.login': 'nf nf-md-bash', 'csh.logout': 'nf nf-md-bash', 'css': 'nf nf-dev-css3', 'custom.el': 'nf nf-custom-emacs', '.dbus': 'nf nf-fa-cog', 'desktop': 'nf nf-fa-desktop', 'docker-compose.yml': 'nf nf-linux-docker', 'dockerfile': 'nf nf-linux-docker', 'doc': 'nf nf-fa-book', 'dist': 'nf nf-oct-package', 'documents': 'nf nf-fa-book', '.doom.d': 'nf nf-custom-emacs', 'downloads': 'nf nf-md-folder_download', '.ds_store': 'nf nf-fa-apple', '.editorconfig': 'nf nf-seti-config', '.electron-gyp': 'nf nf-custom-folder_npm', '.emacs.d': 'nf nf-custom-emacs', '.env': 'nf nf-oct-sliders', 'environment': 'nf nf-oct-sliders', '.eslintrc.json': 'nf nf-oct-sliders', '.eslintrc.js': 'nf nf-oct-sliders', '.eslintrc.yml': 'nf nf-oct-sliders', 'etc': 'nf nf-custom-folder_config', 'favicon.ico': 'nf nf-fa-star', 'favicons': 'nf nf-fa-star', '.fennelrc': 'nf nf-seti-config', 'fstab': 'nf nf-fa-database', '.fastboot': 'nf nf-fa-android', '.gitattributes': 'nf nf-fa-git', '.gitconfig': 'nf nf-fa-git', '.git-credentials': 'nf nf-seti-license', '.github': 'nf nf-custom-folder_github', 'gitignore_global': 'nf nf-fa-git', '.gitignore': 'nf nf-fa-git', '.gitlab-ci.yml': 'nf nf-fa-gitlab', '.gitmodules': 'nf nf-fa-git', '.git': 'nf nf-custom-folder_git', '.gnupg': 'nf nf-md-folder_key', 'go.mod': 'nf nf-seti-go', 'go.sum': 'nf nf-seti-go', 'go.work': 'nf nf-seti-go', 'gradle': 'nf nf-seti-gradle', 'gradle.properties': 'nf nf-seti-gradle', 'gradlew': 'nf nf-seti-gradle', 'gradlew.bat': 'nf nf-seti-gradle', 'group': 'nf nf-seti-config', 'gruntfile.coffee': 'nf nf-seti-grunt', 'gruntfile.js': 'nf nf-seti-grunt', 'gruntfile.ls': 'nf nf-seti-grunt', 'gshadow': 'nf nf-seti-config', 'gulpfile.coffee': 'nf nf-seti-gulp', 'gulpfile.js': 'nf nf-seti-gulp', 'gulpfile.ls': 'nf nf-seti-gulp', 'heroku.yml': 'nf nf-dev-heroku', 'hidden': 'nf nf-fa-lock', 'home': 'nf nf-fa-home', 'hostname': 'nf nf-seti-config', 'hosts': 'nf nf-md-access_point_network', '.htaccess': 'nf nf-seti-config', 'htoprc': 'nf nf-seti-config', '.htpasswd': 'nf nf-seti-config', '.icons': 'nf nf-fa-star', 'icons': 'nf nf-fa-star', 'id_dsa': 'nf nf-md-key_outline', 'id_ecdsa': 'nf nf-md-key_outline', 'id_rsa': 'nf nf-md-key_outline', '.idlerc': 'nf nf-fae-python', 'img': 'nf nf-fa-file_image', 'include': 'nf nf-custom-folder_config', 'init.el': 'nf nf-custom-emacs', '.inputrc': 'nf nf-seti-config', 'inputrc': 'nf nf-seti-config', '.java': 'nf nf-fae-java', 'jenkinsfile': 'nf nf-seti-jenkins', 'js': 'nf nf-dev-javascript', '.jupyter': 'nf nf-seti-python', 'kbuild': 'nf nf-seti-config', 'kconfig': 'nf nf-seti-config', 'kdeglobals': 'nf nf-seti-config', 'kdenliverc': 'nf nf-seti-config', 'known_hosts': 'nf nf-seti-license', '.kshrc': 'nf nf-oct-terminal', 'libexec': 'nf nf-fa-code', 'lib32': 'nf nf-fa-code', 'lib64': 'nf nf-fa-code', 'lib': 'nf nf-fa-code', 'license.md': 'nf nf-seti-license', 'licenses': 'nf nf-seti-license', 'license.txt': 'nf nf-seti-license', 'license': 'nf nf-seti-license', 'localized': 'nf nf-fa-apple', 'lsb-release': 'nf nf-seti-config', '.lynxrc': 'nf nf-seti-config', '.mailcap': 'nf nf-md-email_outline', 'mail': 'nf nf-md-email_outline', 'magic': 'nf nf-fa-magic', 'maintainers': 'nf nf-seti-license', 'makefile.ac': 'nf nf-seti-config', 'makefile': 'nf nf-seti-config', 'manifest': 'nf nf-fa-hashtag', 'md5sum': 'nf nf-md-shield_check', 'meson.build': 'nf nf-fa-wrench', 'metadata': 'nf nf-custom-folder_config', 'metadata.xml': 'nf nf-oct-sliders', 'media': 'nf nf-oct-file_media', '.mime.types': 'nf nf-md-file_tree', 'mime.types': 'nf nf-md-file_tree', 'module.symvers': 'nf nf-oct-file_binary', '.mozilla': 'nf nf-dev-mozilla', 'music': 'nf nf-md-folder_music', 'muttrc': 'nf nf-seti-config', '.muttrc': 'nf nf-seti-config', '.mutt': 'nf nf-seti-config', '.mypy_cache': 'nf nf-md-cached', 'neomuttrc': 'nf nf-seti-config', '.neomuttrc': 'nf nf-seti-config', 'netlify.toml': 'nf nf-fa-server', '.nix-channels': 'nf nf-linux-nixos', '.nix-defexpr': 'nf nf-linux-nixos', '.node-gyp': 'nf nf-custom-folder_npm', 'node_modules': 'nf nf-custom-folder_npm', '.node_repl_history': 'nf nf-dev-nodejs_small', 'npmignore': 'nf nf-dev-npm', '.npm': 'nf nf-custom-folder_npm', 'nvim': 'nf nf-linux-neovim', 'obj': 'nf nf-seti-julia', 'os-release': 'nf nf-seti-config', 'package.json': 'nf nf-dev-nodejs_small', 'package-lock.json': 'nf nf-dev-nodejs_small', 'packages.el': 'nf nf-custom-emacs', 'pam.d': 'nf nf-md-folder_key', 'passwd': 'nf nf-fa-lock', 'pictures': 'nf nf-md-folder_image', 'pkgbuild': 'nf nf-linux-archlinux', '.pki': 'nf nf-fa-lock', 'portage': 'nf nf-linux-gentoo', 'profile': 'nf nf-seti-config', '.profile': 'nf nf-seti-config', 'public': 'nf nf-oct-person', '__pycache__': 'nf nf-seti-python', 'pyproject.toml': 'nf nf-seti-python', '.python_history': 'nf nf-seti-python', '.pypirc': 'nf nf-seti-python', 'rc.lua': 'nf nf-seti-config', 'readme': 'nf nf-fa-markdown', '.release.toml': 'nf nf-seti-rust', 'requirements.txt': 'nf nf-md-language_python', 'robots.txt': 'nf nf-md-robot', 'root': 'nf nf-md-folder_lock', 'rubydoc': 'nf nf-dev-ruby_on_rails', 'runtime.txt': 'nf nf-md-language_python', '.rustup': 'nf nf-seti-rust', 'rustfmt.toml': 'nf nf-seti-rust', '.rvm': 'nf nf-fae-ruby_o', 'sass': 'nf nf-seti-sass', 'sbin': 'nf nf-custom-folder_config', 'scripts': 'nf nf-oct-terminal', 'scss': 'nf nf-seti-sass', 'sha256sum': 'nf nf-md-shield_check', 'shadow': 'nf nf-seti-config', 'share': 'nf nf-fa-mail_forward', '.shellcheckrc': 'nf nf-seti-config', 'shells': 'nf nf-seti-config', '.spacemacs': 'nf nf-custom-emacs', '.sqlite_history': 'nf nf-dev-sqlite', 'src': 'nf nf-md-folder_wrench', '.ssh': 'nf nf-md-folder_key', 'static': 'nf nf-fa-floppy_disk', 'std': 'nf nf-md-code_not_equal_variant', 'styles': 'nf nf-dev-css3', 'subgid': 'nf nf-seti-config', 'subuid': 'nf nf-seti-config', 'sudoers': 'nf nf-fa-lock', 'sxhkdrc': 'nf nf-seti-config', 'template': 'nf nf-linux-void', 'tests': 'nf nf-md-test_tube', 'tigrc': 'nf nf-seti-config', 'timezone': 'nf nf-oct-clock', 'tox.ini': 'nf nf-seti-config', '.trash': 'nf nf-fa-trash', 'ts': 'nf nf-seti-typescript', '.tox': 'nf nf-seti-python', 'unlicense': 'nf nf-seti-license', 'url': 'nf nf-fa-globe', 'user-dirs.dirs': 'nf nf-custom-folder_config', 'vagrantfile': 'nf nf-seti-config', 'vendor': 'nf nf-md-symfony', 'venv': 'nf nf-md-language_python', 'videos': 'nf nf-fa-video', '.viminfo': 'nf nf-custom-vim', '.vimrc': 'nf nf-custom-vim', 'vimrc': 'nf nf-custom-vim', '.vim': 'nf nf-custom-vim', 'vim': 'nf nf-custom-vim', '.vscode': 'nf nf-dev-visualstudio', 'webpack.config.js': 'nf nf-md-webpack', '.wgetrc': 'nf nf-seti-config', 'wgetrc': 'nf nf-seti-config', '.xauthority': 'nf nf-seti-config', '.Xauthority': 'nf nf-seti-config', 'xbps.d': 'nf nf-linux-void', 'xbps-src': 'nf nf-linux-void', '.xinitrc': 'nf nf-seti-config', '.xmodmap': 'nf nf-seti-config', '.Xmodmap': 'nf nf-seti-config', 'xmonad.hs': 'nf nf-seti-config', 'xorg.conf.d': 'nf nf-custom-folder_config', '.xprofile': 'nf nf-seti-config', '.Xprofile': 'nf nf-seti-config', '.xresources': 'nf nf-seti-config', '.yarnrc': 'nf nf-seti-yarn', 'yarn.lock': 'nf nf-seti-yarn', 'zathurarc': 'nf nf-seti-config', '.zcompdump': 'nf nf-seti-config', '.zlogin': 'nf nf-md-bash', '.zlogout': 'nf nf-md-bash', '.zprofile': 'nf nf-md-bash', '.zsh_history': 'nf nf-md-bash', '.zshrc': 'nf nf-md-bash'}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/icons.py#L339-609)
## plugins_api.utils.icons.ByType
*attribute* · *module attribute*
```python
ByType = {'dir': 'nf nf-fa-folder', 'file': 'nf nf-fa-file', 'pipe': 'nf nf-md-filter', 'socket': 'nf nf-md-cube_send', 'executable': 'nf nf-oct-terminal', 'symlink_dir': 'nf nf-oct-file_symlink_directory', 'symlink_file': 'nf nf-oct-file_symlink_file', 'device_char': 'nf nf-seti-project', 'device_block': 'nf nf-md-webpack', 'special': 'nf nf-fa-snowflake', 'history': 'nf nf-fa-clock_rotate_left'}
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/icons.py#L611-623)
## plugins_api.utils.icons.get_icon
*function*
```python
def get_icon(item_type, item_name)
```
Get the appropriate icon for a file or directory.
This function returns the appropriate Nerd Font icon class for files and
directories based on their type and name/extension.
**Parameters**
- `item_type` (`str`) — The type of the item (e.g., 'file', 'dir', 'symlink').
- `item_name` (`str`) — The name of the item, used to determine the appropriate icon.
**Returns**
- (`str`) — A string representing the appropriate icon class.
**Examples**
```pycon
>>> get_icon("file", "test.py")
'nf nf-seti-python'
>>> get_icon("dir", "src")
'nf nf-fa-folder'
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/icons.py#L631-669)
---
# plugins_api.utils.level_from_plugin
*module*
Resolve the level of a metadata field defined by a plugin.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/level_from_plugin.py#L1-1)
## plugins_api.utils.level_from_plugin.resolve_field_level_by_plugin_slug
*function*
```python
def resolve_field_level_by_plugin_slug(field_slug: str, source: str) -> str | None
```
Resolve the most restrictive level of a plugin field by scanning all MetadataObjectTypes.
Useful when only the plugin slug is available (e.g. from a serializer context
or a DB source name), without a direct reference to the plugin class or a
specific metadata object instance.
The most restrictive level wins across all object types:
``mandatory`` (0) > ``recommended`` (1) > ``optional`` (2).
**Parameters**
- `field_slug` (`str`) — The slug of the plugin field to look up.
- `source` (`str`) — The source plugin that owns the field.
**Returns**
- (`str or None`) — The most restrictive level (``"mandatory"``, ``"recommended"``, or ``"optional"``) across all MetadataObjectTypes, or ``None`` if the field is not declared in any of them.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/level_from_plugin.py#L4-47)
## plugins_api.utils.level_from_plugin.resolve_field_level_in_metadata_object
*function*
```python
def resolve_field_level_in_metadata_object(plugin_class, metadata_object, field_slug: str, metadata_object_types: dict | None = None) -> str | None
```
Resolve the level of a plugin field within a specific MetadataObjectType.
Useful in contexts where both the plugin class and the metadata object are
already available (e.g. during submission validation or promotion), avoiding
a full scan across all object types.
**Parameters**
- `plugin_class` (`type`) — The plugin class (not an instance) returned by ``get_plugin_class()``.
- `metadata_object` (`SubmissionMetadataObject`) — The metadata object whose type is used to look up the correct MetadataObjectType on the plugin.
- `field_slug` (`str`) — The slug of the plugin field to look up.
**Returns**
- (`str or None`) — The level (``"mandatory"``, ``"recommended"``, or ``"optional"``) of the field within the matching MetadataObjectType, or ``None`` if the object type is not found on the plugin or the field is not declared in it.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/level_from_plugin.py#L50-88)
---
# plugins_api.utils.plugin_utils
*module*
Plugin utilities.
This module contains utility functions for plugin discovery and management.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L1-1)
## plugins_api.utils.plugin_utils.logger
*attribute* · *module attribute*
```python
logger = logging.getLogger(__name__)
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L30-30)
## plugins_api.utils.plugin_utils.plugins
*attribute* · *module attribute*
```python
plugins: list[type[MadbotPlugin]] = []
```
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L175-175)
## plugins_api.utils.plugin_utils.find_plugins_in_module
*function*
```python
def find_plugins_in_module(module: types.ModuleType) -> list[type[MadbotPlugin]]
```
Find and return all plugin classes defined in the specified module.
**Parameters**
- `module` (`any`) — The module to inspect for plugin classes.
**Returns**
- (`list`) — A list of plugin classes found in the module.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L146-172)
## plugins_api.utils.plugin_utils.get_plugin_class
*function*
```python
def get_plugin_class(plugin_id: str) -> type[MadbotPlugin]
```
Return the class object of a plugin based on its ID.
**Parameters**
- `plugin_id` (`str`) — The unique ID of the plugin in the module.class format.
**Returns**
- (`type`) — The class object of the plugin.
**Raises**
- `PluginNotFoundError` — If the plugin cannot be found.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L258-287)
## plugins_api.utils.plugin_utils.get_plugin_instance
*function*
```python
def get_plugin_instance(plugin_id: str, connection_parameters: dict[str, Any], settings: dict[str, Settings] | None = None) -> ConnectionPlugin
```
Get an instance of a connection plugin.
**Parameters**
- `plugin_id` (`str`) — The unique ID of the plugin in the module.class format.
- `connection_parameters` (`Dict[str, Any]`) — Connection parameters (URLs, credentials, etc.)
- `settings` (`Dict[str, Any]`) (default: `None`) — Settings parameters (only for SubmissionPlugin)
**Returns**
- (`ConnectionPlugin`) — The plugin instance.
**Raises**
- `InvalidPluginTypeError` — If the plugin cannot be instantiated.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L290-335)
## plugins_api.utils.plugin_utils.get_plugin_version
*function*
```python
def get_plugin_version(plugin_class: type[MadbotPlugin]) -> str | None
```
Get the version of a plugin.
This function tries multiple methods to retrieve the plugin version:
1. First tries to get version from the plugin's __init__.py module (__version__)
2. Falls back to using importlib.metadata.distribution() to get the installed package version
3. Returns None if version cannot be determined
**Parameters**
- `plugin_class` (`Type[MadbotPlugin]`) — The plugin class to get the version for
**Returns**
- (`str | None`) — The plugin version string, or None if version cannot be determined
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L83-143)
## plugins_api.utils.plugin_utils.get_plugins
*function*
```python
def get_plugins(plugin_type: type[MadbotPlugin] | None = None) -> list[type[MadbotPlugin]]
```
Retrieve dynamically all implementations of plugins in apps, optionally filtered by plugin type.
**Parameters**
- `plugin_type` (`type`) (default: `None`) — The type of plugins to filter (DataPlugin or SubmissionPlugin or MetadataFieldDefinitionPlugin).
**Returns**
- (`list`) — A list of plugins.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L178-250)
## plugins_api.utils.plugin_utils.is_plugin_in_dev_mode
*function*
```python
def is_plugin_in_dev_mode(plugin_class: type[MadbotPlugin]) -> bool
```
Check if a plugin is installed in development mode (editable install).
This function uses Python's importlib.metadata to check the package's
direct_url.json file, which contains information about how the package
was installed. For editable installs, this file contains:
{"dir_info": {"editable": true}, "url": "file:///path/to/source"}
**Parameters**
- `plugin_class` (`Type[MadbotPlugin]`) — The plugin class to check
**Returns**
- (`bool`) — True if the plugin is installed in editable mode, False otherwise
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L33-80)
## plugins_api.utils.plugin_utils.reload_plugins
*function*
```python
def reload_plugins() -> None
```
Retrieve all available plugins.
[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/utils/plugin_utils.py#L253-255)