2.21. Plugins#
aiomisc can be extended with plugins as separate packages. Plugins can enhance aiomisc by mean of signals.
To make your plugin discoverable by aiomisc you should add
aiomisc.plugins
entry to entry to entry_points
argument of setup
call in setup.py
of a plugin.
# setup.py
setup(
# ...
entry_points={
"aiomisc": ["myplugin = aiomisc_myplugin.plugin"]
},
# ...
)
If you use pyproject.toml you might define it like this:
[tool.poetry.plugins.aiomisc]
myplugin = "aiomisc_myplugin.plugin"
Modules provided in entry_points
should have setup
function.
These functions would be called by aiomisc and must contain signals connecting.
If the services are started dynamically, the attached functions will run every
time the services are started and stopped, however, only services that are
currently starting or stopping will be in the services
parameter.
# Content of: ``aiomisc_myplugin/plugin.py``
from typing import Tuple
from threading import Event
import aiomisc
event = Event()
# Will be shown in ``python -m aiomisc.plugins``
__doc__ = "Example plugin"
async def hello(
*,
entrypoint: aiomisc.Entrypoint,
services: Tuple[aiomisc.Service, ...]
) -> None:
print('Hello from aiomisc plugin')
event.set()
def setup() -> None:
"""
This code will be called by loading plugins declared in
``pyproject.toml`` or ``setup.py``.
"""
aiomisc.Entrypoint.PRE_START.connect(hello)
# Content of: ``my_plugin_example.py``
# ======================================================================
# The code below is not related to the plugin, but serves to demonstrate
# how it works.
# ======================================================================
def main():
""" some function in user code """
# This function will be called by aiomisc.plugin module
# in this example it's just for demonstration.
setup()
assert not event.is_set()
with aiomisc.entrypoint() as loop:
pass
assert event.is_set()
main()
# remove the plugin on when unneeded
aiomisc.entrypoint.PRE_START.disconnect(hello)
The following signals are available in total:
Entrypoint.PRE_START
- Will be called before starting services.Entrypoint.PRE_STOP
- Will be called before stopping services.Entrypoint.POST_START
- Will be called after services has been started.Entrypoint.POST_STOP
- Will be called after services has been stopped.
2.21.1. List available plugins#
To see a list of all available plugins, you can call from the
command line python -m aiomisc.plugins
:
$ python -m aiomisc.plugins
[11:14:42] INFO Available 1 plugins.
INFO 'systemd_watchdog' - Adds SystemD watchdog support to the entrypoint.
systemd_watchdog
You can also change the behavior and output of the list of modules. To do this, there are the following flags:
$ python3 -m aiomisc.plugins -h
usage: python3 -m aiomisc.plugins [-h] [-q] [-n]
[-l {critical,error,warning,info,debug,notset}]
[-F {stream,color,json,syslog,plain,journald,rich,rich_tb}]
optional arguments:
-h, --help show this help message and exit
-q, -s, --quiet, --silent
Disable logs and just output plugin-list, alias for
--log-level=critical
-n, --no-output Disable output plugin-list to the stdout
-l {critical,error,warning,info,debug,notset}, --log-level {critical,error,warning,info,debug,notset}
Logging level
-F {stream,color,json,syslog,plain,journald,rich,rich_tb}, --log-format {stream,color,json,syslog,plain,journald,rich,rich_tb}
Logging format
Here are some run examples.
$ python3 -m aiomisc.plugins -n
[12:25:57] INFO Available 1 plugins.
INFO 'systemd_watchdog' - Adds SystemD watchdog support to the entrypoint.
This prints human-readable list of plugins and its descriptions.
$ python3 -m aiomisc.plugins -s
systemd_watchdog
This useful for grep
or other pipelining tools.
The default prints both, the human-readable log to stderr and the list of plugins to stdout, so you can use this without options in a pipeline, and read the list to stderr.