Local third-party plugin support - [merged] #111

Closed alexander-haller closed 1 month ago

In GitLab by @mhxion on Jul 1, 2024, 01:12

Merges local-plugin-support -> dev

This PR introduces local third-party plugin support. Mostly things that we have discussed in the meeting with fixes for we issues we discussed. A simple third-party local plugin can be created by:

Creating a new plugin folder in ~/.local/share/elapi/plugins
Creating a cli.py in that folder
Adding the following plugin metadata code to cli.py: from elapi.plugins.commons import Typer; app = Typer(name=name, help="Test plugin.")

We briefly summarize some of the main changes here.

Plugin location

There is only one plugin location for all third-party plugins where they can be found regardless of how they are installed (or how they will be installed in the future once we have designated a clear way for plugin distribution): ~/.local/share/elapi/plugins. This is also highlighted on elapi show-config.

Plugins will not cause elAPI to fail/abort

Since elAPI functions independently of third-party plugins, elAPI shouldn't fail when a plugin does. We show the errors on a new "Message panel" instead of throwing Python traceback. However, that can make debugging harder. So, we also introduce development_mode configuration field which by default is False. When development_mode is True, elAPI will give up protecting itself from failing, and show any traceback coming by a plugin.

When development_mode is True:

❯ elapi
Traceback (most recent call last):
  File "/Users/culdesac/Workshop/elapi/.venv/bin/elapi", line 3, in <module>
    from elapi.cli.elapi import app
  File "/Users/culdesac/Workshop/elapi/src/elapi/cli/elapi.py", line 1101, in <module>
    for plugin_info in external_local_plugin_typer_apps:
  File "/Users/culdesac/Workshop/elapi/src/elapi/cli/_plugin_handler.py", line 88, in get_typer_apps
    spec.loader.exec_module(module)
  File "/Users/culdesac/.local/share/elapi/plugins/test/cli.py", line 8
    name = "test
           ^
SyntaxError: unterminated string literal (detected at line 8)

Plugins with name conflicts are disabled

We only allow plugins with unique names. Though, it is likely many plugin names will clash, and in that case we disable the plugin with clashing name. Again, elAPI itself, and other non-conflicting plugins remain functioning.

Plugin names are also considered case-insensitive.

Message panel

We intend to utilize the new "Message panel" for notification-like log messages. Message panel is shows in all --help page. Any third-party plugin can put a log message or any other message on this panel. This opens up new possibilities for showing different kinds of information to plugin users.

import logging
from elapi.utils import add_message

app = Typer(name="test", help="Test plugin.")
add_message("A message", logging.INFO)

Currently, we are showing plugin related errors on this message panel. We also use the panel to show hint about when a configuration file ending with .yaml instead of .yml is found.

In GitLab by @mhxion on Jul 1, 2024, 01:12

requested review from @alexander-haller

approved this merge request

Great work!

In GitLab by @mhxion on Jul 1, 2024, 14:28

Thank you!

In GitLab by @mhxion on Jul 1, 2024, 14:28

resolved all threads

uhd-urz / elAPI