New experiments plugin - [merged] #83

Closed alexander-haller closed 2 months ago

In GitLab by @mhxion on Mar 7, 2024, 03:07

Merges add-experiments-plugin -> dev

Experiment plugin

`append`

The append command appends text content to existing experiments. append accepts the following arguments.

$ elapi experiments append --help

--id: Experiment ID or experiment unique eLab ID.
--text/-t: Text string to append to an experiment.
--path/-P: Path to file (UTF-8 only) whose content to append to an experiment.
--markdown-to-html/-M: If this flag is passed then experiments plugin attempt to convert any given --text or --path to HTML, that is if the given content is in markdown. If given content isn't in markdown then the text content is just wrapped with <p> tag.

We elaborate the details and a few corner cases in brief details. We use the experiment 16 to demonstrate our examples.

1. Normal use-case

Passing any text content to --text is appended to the experiment without any change to the content.

Before:

$ python -m src.elapi.cli experiments append --id 16 -t "New content."
Successfully appended content to experiment.

After:

Similarly, if a file is passed with --path, its content will be appended to the experiment.

If --path isn't UTF-8 encoded plugin will show an error and quit (exit code 1).

$ elapi experiments append --id 16 -P ~/Chemikalienverzeichnis_Beispiel.zip
ERROR    File in given path must be UTF-8 encoded!

If --path isn't a file (but a directory) plugin will show an error and quit.

$ elapi experiments append --id 16 -P ~/Downloads
ERROR     Given path '/Users/culdesac/Downloads' must be a file!

If both --path and --text are passed, the expected outcome can be ambiguous, so experiments plugin will shown an error and quit.

$ experiments append --id 16 -t "New content." -P ~/content.txt
ERROR    Either '--text/-t' or '--path/-P' can be defined, not both!

If content is empty (i.e., --text is an empty string "" or the --path file is empty), plugin will show nothing has been appended message.
```
$ elapi experiments append --id 16 -t ""
Content is empty. Nothing was appended to experiment.
```

2. Multi-line text

Passing multi-line text on the terminal via --text is possible depending on the terminal.

Before:

$ elapi experiments append --id 16 -t "New # <- new line
# <- new line
# <- new line
content."

After:

3. Markdown to HTML

experiments plugin support converting markdown content to HTML. eLabFTW's editor supports rendering HTML text either in HTML editor mode or in markdown mode.

Before:

$ python -m src.elapi.cli experiments append --id 16 -M -t "**New content.**"
Successfully appended content to experiment.

After:

The output of multi-line markdown content via --text with -M flag is slightly different than that of without the -M flag which was shown above. Multi-line here is handled better which has been already shown in HeiChat.
When eLabFTW editor is already in markdown mode, the case has been described also in HeiChat.
-M flag enables the following markdown syntax features supported by Mistune: url, task_lists, task_lists, abbr, superscript, subscript, math.

Downsides of markdown conversion

One (one of many perhaps!) downside with the -M flag is when a file is a passed with --path and the file's contents aren't markdown. This, of course, isn't the intended the use-case, and mainly a mistake from the user's end. Consider the following Chemikalienverzeichnis_Beispiel.csv file:

4;Glutamin;Merck;L202312-04;fest;angelegt;Kategorie 1;56-85-9

If this CSV file was appended with -M (elapi experiments append -P ./Chemikalienverzeichnis_Beispiel.csv) then above CSV row will be parsed as:

<p>4;Glutamin;Merck;L202312-04;fest;angelegt;Kategorie 1;56-85-9</p>

The output is simple wrapped in <p> tag. If the above CSV row however had un-escaped markdown syntax, -M will try to parse the text in markdown. I.e., If Chemikalienverzeichnis_Beispiel.csv file contained:

4;**Glutamin**;Merck;### L202312-04;fest;angelegt;Kategorie 1;56-85-9

It will be parsed as:

<p>4;<strong>Glutamin</strong>;Merck;### L202312-04;fest;angelegt;Kategorie 1;56-85-9</p>
     ^^^^^^^^^^^^^^^^^^^^^^^^^

In other words, --markdown-to-html is safest to use with only markdown (.md) and HTML files/content.

Also fixes #16.

In GitLab by @mhxion on Mar 8, 2024, 17:46

requested review from @alexander-haller

In GitLab by @mhxion on Mar 9, 2024, 18:05

To-do:

[ ] Mention in CLI documenation that users willing to automate with IDs or eLab unique IDs should be mindful about the fact that the IDs aren't persistent across eLabFTW instances.
[ ] download-attachment, when no explicit file path is passed with --export, will create a directory hierarchy <date>/<time?>/experiment_<id>/ and export <attachment_name> to experiment_<id> directory.
[ ] A sub-command to show list of all available attachments.

In GitLab by @mhxion on Mar 11, 2024, 16:40

added 6 commits

838ce26c - Rename command 'read' to 'get'
ac320e35 - Fix function docstring
228165f2 - Fix error message
987edd9b - Validate file type and UnicodeDecodeError
70a0ecd2 - Move bill-teams CLI to plugins/bill-teams
c0d61f5a - Remove unnecessary imports

uhd-urz / elAPI