feat(cli): Added CLI command for handling plugins

* Install / Uninstall plugins
* List plugins

README.md

@@ -3,14 +3,17 @@
 
 This is the backend of the Flaschengeist.
 
-## Installation
+# Installation
-### Requirements
+## Main package
-- `mysql` or `mariadb`
+### System dependencies
-    - maybe `libmariadb` development files[1]
+- **python 3.7+**
-- python 3.7+
+- Database (MySQL / mariadb by default)
 
-[1] By default Flaschengeist uses mysql as database backend, if you are on Windows Flaschengeist uses `PyMySQL`, but on
+By default Flaschengeist uses mysql as database backend,
-Linux / Mac the faster `mysqlclient` is used, if it is not already installed installing from pypi requires the
+if you are on Windows Flaschengeist uses `PyMySQL`, which does not require any other system packages.
+
+But on Linux / Mac / *nix the faster `mysqlclient` is used,
+if it is not already installed, installing from PyPi requires the
 development files for `libmariadb` to be present on your system.
 
 ### Install python files
@@ -22,18 +25,35 @@ or if you want to also run the tests:
 
     pip3 install --user ".[ldap,test]"
 
-You will also need a MySQL driver, recommended drivers are
+You will also need a MySQL driver, by default one of this is installed:
-- `mysqlclient`
+- `mysqlclient` (non Windows)
-- `PyMySQL`
+- `PyMySQL` (on Windows)
 
-`setup.py` will try to install a matching driver.
+#### Hint on MySQL driver on Windows:
+If you want to use `mysqlclient` instead of `PyMySQL` (performance?) you have to follow [this guide](https://www.radishlogic.com/coding/python-3/installing-mysqldb-for-python-3-in-windows/)
 
-#### Windows
+### Install database
-Same as above, but if you want to use `mysqlclient` instead of `PyMySQL` (performance?) you have to follow this guide:
+The user needs to have full permissions to the database.
+If not you need to create user and database manually do (or similar on Windows):
 
-https://www.radishlogic.com/coding/python-3/installing-mysqldb-for-python-3-in-windows/
+    (
+        echo "CREATE DATABASE flaschengeist;"
+        echo "CREATE USER 'flaschengeist'@'localhost' IDENTIFIED BY 'flaschengeist';"
+        echo "GRANT ALL PRIVILEGES ON flaschengeist.* TO 'flaschengeist'@'localhost';"
+        echo "FLUSH PRIVILEGES;"
+    ) | sudo mysql
 
-### Configuration
+Then you can install the database tables, this will update all tables from core + all enabled plugins.
+*Hint:* The same command can be later used to upgrade the database after plugins or core are updated.
+
+    $ flaschengeist db upgrade heads
+
+## Plugins
+To only upgrade one plugin (for example the `events` plugin):
+
+    $ flaschengeist db upgrade events@head
+
+## Configuration
 Configuration is done within the a `flaschengeist.toml`file, you can copy the one located inside the module path
 (where flaschegeist is installed) or create an empty one and place it inside either:
 1. `~/.config/`
@@ -54,21 +74,6 @@ So you have to configure one of the following options to call flaschengeists CRO
   - Pros: Guaranteed execution interval, no impact on user experience (at least if you do not limit wsgi worker threads)
   - Cons: Uses one of the webserver threads while executing
 
-### Database installation
-The user needs to have full permissions to the database.
-If not you need to create user and database manually do (or similar on Windows):
-
-    (
-        echo "CREATE DATABASE flaschengeist;"
-        echo "CREATE USER 'flaschengeist'@'localhost' IDENTIFIED BY 'flaschengeist';"
-        echo "GRANT ALL PRIVILEGES ON flaschengeist.* TO 'flaschengeist'@'localhost';"
-        echo "FLUSH PRIVILEGES;"
-    ) | sudo mysql
-
-Then you can install the database tables and initial entries:
-
-    $ flaschengeist install
-
 ### Run
     $ flaschengeist run
 or with debug messages:

flaschengeist/__init__.py

@@ -1,11 +1,9 @@
 """Flaschengeist"""
 import logging
 import pkg_resources
-from pathlib import Path
 from werkzeug.local import LocalProxy
 
 __version__ = pkg_resources.get_distribution("flaschengeist").version
-_module_path = Path(__file__).parent
 __pdoc__ = {}
 
 logger: logging.Logger = LocalProxy(lambda: logging.getLogger(__name__))

flaschengeist/app.py

@@ -1,18 +1,18 @@
 import enum
 
-import pkg_resources
+from flask import Flask
-from flask import Flask, current_app
 from flask_cors import CORS
 from datetime import datetime, date
 from flask.json import JSONEncoder, jsonify
 from sqlalchemy.exc import OperationalError
 from werkzeug.exceptions import HTTPException
 
+from flaschengeist.utils.plugin import get_plugins
+
 from . import logger
-from .plugins import AuthPlugin
+from .plugins import Plugin
-from flaschengeist.config import config, configure_app
+from .config import config, configure_app
-from flaschengeist.controller import roleController
+from .utils.hook import Hook
-from flaschengeist.utils.hook import Hook
 
 
 class CustomJSONEncoder(JSONEncoder):
@@ -37,75 +37,47 @@ class CustomJSONEncoder(JSONEncoder):
 
 
 @Hook("plugins.loaded")
-def __load_plugins(app):
+def load_plugins(app: Flask):
-    logger.debug("Search for plugins")
+    def load_plugin(cls: type[Plugin]):
-
+        logger.debug(f"Load plugin {cls.id}")
-    app.config["FG_PLUGINS"] = {}
+        # Initialize plugin with config section
-    for entry_point in pkg_resources.iter_entry_points("flaschengeist.plugins"):
+        plugin = cls(config.get(plugin_class.id, config.get(plugin_class.id.split(".")[-1], {})))
-        logger.debug(f"Found plugin: >{entry_point.name}<")
+        # Register blueprint if provided
-
+        if plugin.blueprint is not None:
-        if entry_point.name == config["FLASCHENGEIST"]["auth"] or (
-            entry_point.name in config and config[entry_point.name].get("enabled", False)
-        ):
-            logger.debug(f"Load plugin {entry_point.name}")
-            try:
-                plugin = entry_point.load()
-                if not hasattr(plugin, "name"):
-                    setattr(plugin, "name", entry_point.name)
-                plugin = plugin(config.get(entry_point.name, {}))
-                if hasattr(plugin, "blueprint") and plugin.blueprint is not None:
             app.register_blueprint(plugin.blueprint)
-            except:
+        # Save plugin application context
-                logger.error(
+        app.config.setdefault("FG_PLUGINS", {})[plugin.id] = plugin
-                    f"Plugin {entry_point.name} was enabled, but could not be loaded due to an error.",
+        return plugin
-                    exc_info=True,
+
-                )
+    for plugin_class in get_plugins():
-                continue
+        names = [plugin_class.id, plugin_class.id.split(".")[-1]]
-            if isinstance(plugin, AuthPlugin):
+        if config["FLASCHENGEIST"]["auth"] in names:
-                if entry_point.name != config["FLASCHENGEIST"]["auth"]:
+            # Load authentification plugin
-                    logger.debug(f"Unload not configured AuthPlugin {entry_point.name}")
+            app.config["FG_AUTH_BACKEND"] = load_plugin(plugin_class)
-                    del plugin
+            logger.info(f"Using authentication plugin: {plugin_class.id}")
-                    continue
+        elif any([i in config and config[i].get("enabled", False) for i in names]):
+            # Load all other enabled plugins
+            load_plugin(plugin_class)
+            logger.info(f"Using plugin: {plugin_class.id}")
         else:
-                    logger.info(f"Using authentication plugin: {entry_point.name}")
+            logger.debug(f"Skip disabled plugin {plugin_class.id}")
-                    app.config["FG_AUTH_BACKEND"] = plugin
-            else:
-                logger.info(f"Using plugin: {entry_point.name}")
-            app.config["FG_PLUGINS"][entry_point.name] = plugin
-        else:
-            logger.debug(f"Skip disabled plugin {entry_point.name}")
     if "FG_AUTH_BACKEND" not in app.config:
-        logger.error("No authentication plugin configured or authentication plugin not found")
+        logger.fatal("No authentication plugin configured or authentication plugin not found")
         raise RuntimeError("No authentication plugin configured or authentication plugin not found")
 
 
-@Hook("plugins.installed")
-def install_all():
-    from flaschengeist.database import db
-
-    db.create_all()
-    db.session.commit()
-    for name, plugin in current_app.config["FG_PLUGINS"].items():
-        if not plugin:
-            logger.debug(f"Skip disabled plugin: {name}")
-            continue
-        logger.info(f"Install plugin {name}")
-        plugin.install()
-        if plugin.permissions:
-            roleController.create_permissions(plugin.permissions)
-
-
 def create_app(test_config=None, cli=False):
     app = Flask(__name__)
     app.json_encoder = CustomJSONEncoder
     CORS(app)
 
     with app.app_context():
-        from flaschengeist.database import db
+        from flaschengeist.database import db, migrate
 
         configure_app(app, test_config, cli)
         db.init_app(app)
-        __load_plugins(app)
+        migrate.init_app(app, db, compare_type=True)
+        load_plugins(app)
 
     @app.route("/", methods=["GET"])
     def __get_state():

flaschengeist/cli/InterfaceGenerator.py

@@ -1,3 +1,4 @@
+import io
 import sys
 import inspect
 import logging
@@ -93,15 +94,32 @@ class InterfaceGenerator:
         self.basename = models.__name__
         self.walker(("models", models))
 
+    def _write_types(self):
+        TYPE = "type {name} = {alias};\n"
+        INTERFACE = "interface {name} {{\n{properties}}}\n"
+        PROPERTY = "\t{name}{modifier}: {type};\n"
+
+        buffer = io.StringIO()
+        for cls, props in self.classes.items():
+            if isinstance(props, str):
+                buffer.write(TYPE.format(name=cls, alias=props))
+            else:
+                buffer.write(
+                    INTERFACE.format(
+                        name=cls,
+                        properties="".join(
+                            [PROPERTY.format(name=name, modifier=props[name][0], type=props[name][1]) for name in props]
+                        ),
+                    )
+                )
+        return buffer
+
     def write(self):
         with (open(self.filename, "w") if self.filename else sys.stdout) as file:
-            file.write("declare namespace {} {{\n".format(self.namespace))
+            if self.namespace:
-            for cls, params in self.classes.items():
+                file.write(f"declare namespace {self.namespace} {{\n")
-                if isinstance(params, str):
+                for line in self._write_types().getvalue().split("\n"):
-                    file.write("\ttype {} = {};\n".format(cls, params))
+                    file.write(f"\t{line}\n")
-                else:
-                    file.write("\tinterface {} {{\n".format(cls))
-                    for name in params:
-                        file.write("\t\t{}{}: {};\n".format(name, *params[name]))
-                    file.write("\t}\n")
                 file.write("}\n")
+            else:
+                file.write(self._write_types().getvalue())

flaschengeist/cli/__init__.py

@@ -1,10 +1,5 @@
-import pathlib
-import subprocess
 import click
-from os import environ
+from flask.cli import FlaskGroup, with_appcontext
-from flask import current_app
-from flask.cli import FlaskGroup, run_command, with_appcontext
-import pkg_resources
 from flaschengeist.app import create_app
 from flaschengeist.config import configure_logger
 
@@ -63,98 +58,14 @@ def cli():
     pass
 
 
-@cli.command()
+def main(*args, **kwargs):
-@with_appcontext
+    from .plugin_cmd import plugin
-def install():
+    from .export_cmd import export
-    """Install and initialize enabled plugins.
+    from .docs_cmd import docs
+    from .run_cmd import run
 
-    Most plugins need to install custom tables into the database
+    cli.add_command(plugin)
-    running this command will lookup all enabled plugins and run
+    cli.add_command(export)
-    their database initalization routines.
+    cli.add_command(docs)
-    """
+    cli.add_command(run)
-    from flaschengeist.app import install_all
+    cli(*args, **kwargs)
-
-    install_all()
-
-
-@cli.command()
-@click.option("--output", "-o", help="Output file, default is stdout", type=click.Path())
-@click.option("--namespace", "-n", help="TS namespace for the interfaces", type=str, show_default=True)
-@click.option("--plugin", "-p", help="Also export types for a plugin (even if disabled)", multiple=True, type=str)
-@click.option("--no-core", help="Skip models / types from flaschengeist core", is_flag=True)
-def export(namespace, output, no_core, plugin):
-    from flaschengeist import models
-    from flaschengeist import logger
-    from .InterfaceGenerator import InterfaceGenerator
-
-    gen = InterfaceGenerator(namespace, output, logger)
-    if not no_core:
-        gen.run(models)
-    if plugin:
-        for entry_point in pkg_resources.iter_entry_points("flaschengeist.plugins"):
-            if len(plugin) == 0 or entry_point.name in plugin:
-                plg = entry_point.load()
-                if hasattr(plg, "models") and plg.models is not None:
-                    gen.run(plg.models)
-    gen.write()
-
-
-@cli.command()
-@click.option("--host", help="set hostname to listen on", default="127.0.0.1", show_default=True)
-@click.option("--port", help="set port to listen on", type=int, default=5000, show_default=True)
-@click.option("--debug", help="run in debug mode", is_flag=True)
-@with_appcontext
-@click.pass_context
-def run(ctx, host, port, debug):
-    """Run Flaschengeist using a development server."""
-
-    class PrefixMiddleware(object):
-        def __init__(self, app, prefix=""):
-            self.app = app
-            self.prefix = prefix
-
-        def __call__(self, environ, start_response):
-
-            if environ["PATH_INFO"].startswith(self.prefix):
-                environ["PATH_INFO"] = environ["PATH_INFO"][len(self.prefix) :]
-                environ["SCRIPT_NAME"] = self.prefix
-                return self.app(environ, start_response)
-            else:
-                start_response("404", [("Content-Type", "text/plain")])
-                return ["This url does not belong to the app.".encode()]
-
-    from flaschengeist.config import config
-
-    # re configure logger, as we are no logger in CLI mode
-    configure_logger()
-    current_app.wsgi_app = PrefixMiddleware(current_app.wsgi_app, prefix=config["FLASCHENGEIST"].get("root", ""))
-    if debug:
-        environ["FLASK_DEBUG"] = "1"
-        environ["FLASK_ENV"] = "development"
-
-    ctx.invoke(run_command, host=host, port=port, debugger=debug)
-
-
-@cli.command()
-@click.option(
-    "--output",
-    "-o",
-    help="Documentation output path",
-    default="./docs",
-    type=click.Path(file_okay=False, path_type=pathlib.Path),
-)
-def docs(output: pathlib.Path):
-    """Generate and export API documentation using pdoc3"""
-    output.mkdir(parents=True, exist_ok=True)
-    command = [
-        "python",
-        "-m",
-        "pdoc",
-        "--skip-errors",
-        "--html",
-        "--output-dir",
-        str(output),
-        "flaschengeist",
-    ]
-    click.echo(f"Running command: {command}")
-    subprocess.check_call(command)

flaschengeist/cli/docs_cmd.py

@@ -0,0 +1,38 @@
+import click
+import pathlib
+import subprocess
+
+
+@click.command()
+@click.option(
+    "--output",
+    "-o",
+    help="Documentation output path",
+    default="./docs",
+    type=click.Path(file_okay=False, path_type=pathlib.Path),
+)
+@click.pass_context
+def docs(ctx: click.Context, output: pathlib.Path):
+    """Generate and export API documentation using pdoc"""
+    import pkg_resources
+
+    try:
+        pkg_resources.get_distribution("pdoc>=8.0.1")
+    except pkg_resources.DistributionNotFound:
+        click.echo(
+            f"Error: pdoc was not found, maybe you need to install it. Try:\n" "\n" '$ pip install "pdoc>=8.0.1"\n'
+        )
+        ctx.exit(1)
+    output.mkdir(parents=True, exist_ok=True)
+    command = [
+        "python",
+        "-m",
+        "pdoc",
+        "--docformat",
+        "google",
+        "--output-directory",
+        str(output),
+        "flaschengeist",
+    ]
+    click.echo(f"Running command: {command}")
+    subprocess.check_call(command)

flaschengeist/cli/export_cmd.py

@@ -0,0 +1,21 @@
+import click
+
+
+@click.command()
+@click.option("--output", "-o", help="Output file, default is stdout", type=click.Path())
+@click.option("--namespace", "-n", help="TS namespace for the interfaces", type=str, show_default=True)
+@click.option("--plugin", "-p", help="Also export types for a plugin (even if disabled)", multiple=True, type=str)
+@click.option("--no-core", help="Skip models / types from flaschengeist core", is_flag=True)
+def export(namespace, output, no_core, plugin):
+    from flaschengeist import logger, models
+    from flaschengeist.app import get_plugins
+    from .InterfaceGenerator import InterfaceGenerator
+
+    gen = InterfaceGenerator(namespace, output, logger)
+    if not no_core:
+        gen.run(models)
+    if plugin:
+        for plugin_class in get_plugins():
+            if (len(plugin) == 0 or plugin_class.id in plugin) and plugin_class.models is not None:
+                gen.run(plugin_class.models)
+    gen.write()

flaschengeist/cli/plugin_cmd.py

@@ -0,0 +1,83 @@
+import click
+from click.decorators import pass_context
+from flask import current_app
+from flask.cli import with_appcontext
+from flaschengeist.utils.plugin import get_plugins, plugin_version
+
+
+@click.group()
+def plugin():
+    pass
+
+
+@plugin.command()
+@click.argument("plugin", nargs=-1, type=str)
+@click.option("--all", help="Install all enabled plugins", is_flag=True)
+@with_appcontext
+@pass_context
+def install(ctx, plugin, all):
+    """Install one or more plugins"""
+    if not all and len(plugin) == 0:
+        ctx.fail("At least one plugin must be specified, or use `--all` flag.")
+    if all:
+        plugins = current_app.config["FG_PLUGINS"].values()
+    else:
+        try:
+            plugins = [current_app.config["FG_PLUGINS"][p] for p in plugin]
+        except KeyError as e:
+            ctx.fail(f"Invalid plugin ID, could not find >{e.args[0]}<")
+    for p in plugins:
+        name = p.id.split(".")[-1]
+        click.echo(f"Installing {name}{'.'*(20-len(name))}", nl=False)
+        p.install()
+        click.secho(" ok", fg="green")
+
+
+@plugin.command()
+@click.argument("plugin", nargs=-1, type=str)
+@with_appcontext
+@pass_context
+def uninstall(ctx: click.Context, plugin):
+    """Uninstall one or more plugins"""
+
+    if len(plugin) == 0:
+        ctx.fail("At least one plugin must be specified")
+    try:
+        plugins = [current_app.config["FG_PLUGINS"][p] for p in plugin]
+    except KeyError as e:
+        ctx.fail(f"Invalid plugin ID, could not find >{e.args[0]}<")
+    if (
+        click.prompt(
+            "You are going to uninstall:\n\n"
+            f"\t{', '.join([p.id.split('.')[-1] for p in plugins])}\n\n"
+            "Are you sure?",
+            default="n",
+            show_choices=True,
+            type=click.Choice(["y", "N"], False),
+        ).lower()
+        != "y"
+    ):
+        ctx.exit()
+    for p in plugins:
+        name = p.id.split(".")[-1]
+        click.echo(f"Uninstalling {name}{'.'*(20-len(name))}", nl=False)
+        p.uninstall()
+        click.secho(" ok", fg="green")
+
+
+@plugin.command()
+@click.option("--enabled", "-e", help="List only enabled plugins", is_flag=True)
+@with_appcontext
+def ls(enabled):
+    if enabled:
+        plugins = current_app.config["FG_PLUGINS"].values()
+    else:
+        plugins = get_plugins()
+
+    print(f"{' '*13}{'name': <20}|{'version': >10}")
+    print("-" * 46)
+    for plugin in plugins:
+        print(
+            f"{plugin.id: <33}|{plugin_version(plugin): >12}"
+            f"{click.style(' (enabled)', fg='green') if plugin.id in current_app.config['FG_PLUGINS'] else click.style(' (disabled)', fg='red')}"
+        )

flaschengeist/cli/run_cmd.py

@@ -0,0 +1,40 @@
+import click
+from os import environ
+from flask import current_app
+from flask.cli import with_appcontext, run_command
+
+
+class PrefixMiddleware(object):
+    def __init__(self, app, prefix=""):
+        self.app = app
+        self.prefix = prefix
+
+    def __call__(self, environ, start_response):
+
+        if environ["PATH_INFO"].startswith(self.prefix):
+            environ["PATH_INFO"] = environ["PATH_INFO"][len(self.prefix) :]
+            environ["SCRIPT_NAME"] = self.prefix
+            return self.app(environ, start_response)
+        else:
+            start_response("404", [("Content-Type", "text/plain")])
+            return ["This url does not belong to the app.".encode()]
+
+
+@click.command()
+@click.option("--host", help="set hostname to listen on", default="127.0.0.1", show_default=True)
+@click.option("--port", help="set port to listen on", type=int, default=5000, show_default=True)
+@click.option("--debug", help="run in debug mode", is_flag=True)
+@with_appcontext
+@click.pass_context
+def run(ctx, host, port, debug):
+    """Run Flaschengeist using a development server."""
+    from flaschengeist.config import config, configure_logger
+
+    # re configure logger, as we are no logger in CLI mode
+    configure_logger()
+    current_app.wsgi_app = PrefixMiddleware(current_app.wsgi_app, prefix=config["FLASCHENGEIST"].get("root", ""))
+    if debug:
+        environ["FLASK_DEBUG"] = "1"
+        environ["FLASK_ENV"] = "development"
+
+    ctx.invoke(run_command, host=host, port=port, debugger=debug)

flaschengeist/config.py

@@ -5,7 +5,7 @@ import collections.abc
 
 from pathlib import Path
 from werkzeug.middleware.proxy_fix import ProxyFix
-from flaschengeist import _module_path, logger
+from flaschengeist import logger
 
 
 # Default config:
@@ -23,7 +23,7 @@ def update_dict(d, u):
 
 def read_configuration(test_config):
     global config
-    paths = [_module_path]
+    paths = [Path(__file__).parent]
 
     if not test_config:
         paths.append(Path.home() / ".config")
@@ -44,7 +44,7 @@ def read_configuration(test_config):
 def configure_logger(cli=False):
     global config
     # Read default config
-    logger_config = toml.load(_module_path / "logging.toml")
+    logger_config = toml.load(Path(__file__).parent / "logging.toml")
 
     if "LOGGING" in config:
         # Override with user config

flaschengeist/database.py

@@ -1,3 +1,6 @@
+import os
+from flask import current_app
+from flask_migrate import Migrate
 from flask_sqlalchemy import SQLAlchemy
 from sqlalchemy import MetaData
 
@@ -14,6 +17,36 @@ metadata = MetaData(
 
 
 db = SQLAlchemy(metadata=metadata)
+migrate = Migrate()
+
+
+@migrate.configure
+def configure_alembic(config):
+    """Alembic configuration hook
+
+    Inject all migrations paths into the ``version_locations`` config option.
+    This includes even disabled plugins, as simply disabling a plugin without
+    uninstall can break the alembic version management.
+    """
+    import inspect, pathlib
+    from flaschengeist.utils.plugin import get_plugins
+
+    # Load migration paths from plugins
+    migrations = [(pathlib.Path(inspect.getfile(p)).parent / "migrations") for p in get_plugins()]
+    migrations = [str(m.resolve()) for m in migrations if m.exists()]
+    if len(migrations) > 0:
+        # Get configured paths
+        paths = config.get_main_option("version_locations")
+        # Get configured path seperator
+        sep = config.get_main_option("version_path_separator", "os")
+        if paths:
+            # Insert configured paths at the front, before plugin migrations
+            migrations.insert(0, config.get_main_option("version_locations"))
+        sep = os.pathsep if sep == "os" else " " if sep == "space" else sep
+        # write back seperator (we changed it if neither seperator nor locations were specified)
+        config.set_main_option("version_path_separator", sep)
+        config.set_main_option("version_locations", sep.join(migrations))
+    return config
 
 
 def case_sensitive(s):

flaschengeist/models/__init__.py

@@ -1,7 +1,7 @@
 import sys
 import datetime
 
-from sqlalchemy import BigInteger
+from sqlalchemy import BigInteger, util
 from sqlalchemy.dialects import mysql, sqlite
 from sqlalchemy.types import DateTime, TypeDecorator
 
@@ -50,6 +50,10 @@ class Serial(TypeDecorator):
     cache_ok = True
     impl = BigInteger().with_variant(mysql.BIGINT(unsigned=True), "mysql").with_variant(sqlite.INTEGER(), "sqlite")
 
+    # https://alembic.sqlalchemy.org/en/latest/autogenerate.html?highlight=custom%20column#affecting-the-rendering-of-types-themselves
+    def __repr__(self) -> str:
+        return util.generic_repr(self)
+
 
 class UtcDateTime(TypeDecorator):
     """Almost equivalent to `sqlalchemy.types.DateTime` with
@@ -85,3 +89,7 @@ class UtcDateTime(TypeDecorator):
                 value = value.astimezone(datetime.timezone.utc)
             value = value.replace(tzinfo=datetime.timezone.utc)
         return value
+
+    # https://alembic.sqlalchemy.org/en/latest/autogenerate.html?highlight=custom%20column#affecting-the-rendering-of-types-themselves
+    def __repr__(self) -> str:
+        return util.generic_repr(self)

flaschengeist/plugins/__init__.py

@@ -1,81 +1,142 @@
-import sqlalchemy
+"""Flaschengeist Plugins
-import pkg_resources
-from werkzeug.datastructures import FileStorage
-from werkzeug.exceptions import MethodNotAllowed, NotFound
-from flaschengeist.controller import imageController
 
-from flaschengeist.database import db
+## Custom database tables
-from flaschengeist.models.notification import Notification
+
-from flaschengeist.models.user import _Avatar, User
+You can add tables by declaring them using the SQLAlchemy syntax,
-from flaschengeist.models.setting import _PluginSetting
+then use Alembic to generate migrations for your tables.
+This allows Flaschengeist to proper up- or downgrade the
+database tables if an user updates your plugin.
+
+migrations have to be provided in a directory called `migrations`
+next to your plugin. E.G.
+
+    myplugin
+        - __init__.py
+        - other/
+            - ...
+        - migrations/
+
+## Useful Hooks
+There are some predefined hooks, which might get handy for you.
+
+For more information, please refer to
+- `flaschengeist.utils.hook.HookBefore` and
+- `flaschengeist.utils.hook.HookAfter`
+"""
+
+import sqlalchemy
+from werkzeug.exceptions import MethodNotAllowed, NotFound
 from flaschengeist.utils.hook import HookBefore, HookAfter
 
-plugins_installed = HookAfter("plugins.installed")
+__all__ = [
-"""Hook decorator for when all plugins are installed
+    "plugins_installed",
-    Possible use case would be to populate the database with some presets.
+    "plugins_loaded",
+    "before_delete_user",
+    "before_role_updated",
+    "before_update_user",
+    "after_role_updated",
+    "Plugin",
+    "AuthPlugin",
+]
 
-    Args:
+# Documentation hacks, see https://github.com/mitmproxy/pdoc/issues/320
-        hook_result: void (kwargs)
+plugins_installed = HookAfter("plugins.installed")
+plugins_installed.__doc__ = """Hook decorator for when all plugins are installed
+
+Possible use case would be to populate the database with some presets.
 """
+
 plugins_loaded = HookAfter("plugins.loaded")
-"""Hook decorator for when all plugins are loaded
+plugins_loaded.__doc__ = """Hook decorator for when all plugins are loaded
+
 Possible use case would be to check if a specific other plugin is loaded and change own behavior
 
-    Args:
+Passed args:
-        app: Current flask app instance (args)
+    - *app:* Current flask app instance (args)
-        hook_result: void (kwargs)
 """
+
 before_role_updated = HookBefore("update_role")
-"""Hook decorator for when roles are modified
+before_role_updated.__doc__ = """Hook decorator for when roles are modified
-Args:
+    
-    role: Role object to modify
+Passed args:
-    new_name: New name if the name was changed (None if delete)
+    - *role:* `flaschengeist.models.user.Role` to modify
+    - *new_name:* New name if the name was changed (*None* if delete)
 """
+
 after_role_updated = HookAfter("update_role")
-"""Hook decorator for when roles are modified
+after_role_updated.__doc__ = """Hook decorator for when roles are modified
-Args:
+
-    role: Role object containing the modified role
+Passed args:
-    new_name: New name if the name was changed (None if deleted)
+    - *role:* modified `flaschengeist.models.user.Role`
+    - *new_name:* New name if the name was changed (*None* if deleted)
 """
+
 before_update_user = HookBefore("update_user")
-"""Hook decorator, when ever an user update is done, this is called before.
+before_update_user.__doc__ = """Hook decorator, when ever an user update is done, this is called before.
-Args:
+
-    user: User object
+Passed args:
+    - *user:* `flaschengeist.models.user.User` object
 """
+
 before_delete_user = HookBefore("delete_user")
-"""Hook decorator,this is called before an user gets deleted.
+before_delete_user.__doc__ = """Hook decorator,this is called before an user gets deleted.
-Args:
+
-    user: User object
+Passed args:
+    - *user:* `flaschengeist.models.user.User` object
 """
 
 
 class Plugin:
     """Base class for all Plugins
-    If your class uses custom models add a static property called ``models``"""
 
-    blueprint = None  # You have to override
+    All plugins must be derived from this class.
+    There are some static properties a plugin must provide,
+    and some properties a plugin can provide if you might want
+    to use more functionality.
+
+    Required:
+        - *id*: Unique identifier of your plugin
+
+    Optional:
+        - *blueprint*: `flask.Blueprint` providing your routes
+        - *permissions*: List of your custom permissions
+        - *models*: Your models, used for API export
+        - *version*: Version of your plugin, can also be guessed by Flaschengeist
+    """
+
+    id: str = None
+    """Override with the unique ID of the plugin
+    
+    Hint: Use a fully qualified name like "dev.flaschengeist.plugin"
+    """
+
+    blueprint = None
     """Override with a `flask.blueprint` if the plugin uses custom routes"""
-    permissions = []  # You have to override
+
+    permissions: list[str] = []  # You have to override
     """Override to add custom permissions used by the plugin
     
     A good style is to name the permissions with a prefix related to the plugin name,
     to prevent clashes with other plugins. E. g. instead of *delete* use *plugin_delete*.
     """
-    id = "dev.flaschengeist.plugin"  # You have to override
+
-    """Override with the unique ID of the plugin (Hint: FQN)"""
+    models = None
-    name = "plugin"  # You have to override
+    """Override with models module
-    """Override with human readable name of the plugin"""
+    
-    models = None  # You have to override
+    Used for API export, has to be a static property
-    """Override with models module"""
+    """
-    migrations_path = None  # Override this with the location of your db migrations directory
+
-    """Override with path to migration files, if custome db tables are used"""
+    version = None
+    """Override with a custom version, optional
+    
+    If not set, the version is guessed from the package / distribution
+    """
 
     def __init__(self, config=None):
         """Constructor called by create_app
         Args:
             config: Dict configuration containing the plugin section
         """
-        self.version = pkg_resources.get_distribution(self.__module__.split(".")[0]).version
 
     def install(self):
         """Installation routine
@@ -84,6 +145,17 @@ class Plugin:
         """
         pass
 
+    def uninstall(self):
+        """Uninstall routine
+
+        If the plugin has custom database tables, make sure to remove them.
+        This can be either done by downgrading the plugin *head* to the *base*.
+        Or use custom migrations for the uninstall and *stamp* some version.
+
+        Is always called with Flask application context.
+        """
+        pass
+
     def get_setting(self, name: str, **kwargs):
         """Get plugin setting from database
 
@@ -95,6 +167,8 @@ class Plugin:
         Raises:
             `KeyError` if no such setting exists in the database
         """
+        from flaschengeist.models.setting import _PluginSetting
+
         try:
             setting = (
                 _PluginSetting.query.filter(_PluginSetting.plugin == self.name)
@@ -115,6 +189,9 @@ class Plugin:
             name: String identifying the setting
             value: Value to be stored
         """
+        from flaschengeist.models.setting import _PluginSetting
+        from flaschengeist.database import db
+
         setting = (
             _PluginSetting.query.filter(_PluginSetting.plugin == self.name)
             .filter(_PluginSetting.name == name)
@@ -141,6 +218,9 @@ class Plugin:
 
         Hint: use the data for frontend actions.
         """
+        from flaschengeist.models.notification import Notification
+        from flaschengeist.database import db
+
         if not user.deleted:
             n = Notification(text=text, data=data, plugin=self.id, user_=user)
             db.session.add(n)
@@ -157,6 +237,11 @@ class Plugin:
 
 
 class AuthPlugin(Plugin):
+    """Base class for all authentification plugins
+
+    See also `Plugin`
+    """
+
     def login(self, user, pw):
         """Login routine, MUST BE IMPLEMENTED!
 
@@ -219,7 +304,7 @@ class AuthPlugin(Plugin):
         """
         raise MethodNotAllowed
 
-    def get_avatar(self, user: User) -> _Avatar:
+    def get_avatar(self, user):
         """Retrieve avatar for given user (if supported by auth backend)
 
         Default behavior is to use native Image objects,
@@ -233,21 +318,23 @@ class AuthPlugin(Plugin):
         """
         raise NotFound
 
-    def set_avatar(self, user: User, file: FileStorage):
+    def set_avatar(self, user, file):
         """Set the avatar for given user (if supported by auth backend)
 
         Default behavior is to use native Image objects stored on the Flaschengeist server
 
         Args:
             user: User to set the avatar for
-            file: FileStorage object uploaded by the user
+            file: `werkzeug.datastructures.FileStorage` uploaded by the user
         Raises:
             MethodNotAllowed: If not supported by Backend
             Any valid HTTP exception
         """
+        from flaschengeist.controller import imageController
+
         user.avatar_ = imageController.upload_image(file)
 
-    def delete_avatar(self, user: User):
+    def delete_avatar(self, user):
         """Delete the avatar for given user (if supported by auth backend)
 
         Default behavior is to use the imageController and native Image objects.

flaschengeist/plugins/auth/__init__.py

@@ -13,8 +13,8 @@ from flaschengeist.controller import sessionController, userController
 
 
 class AuthRoutePlugin(Plugin):
-    name = "auth"
+    id = "dev.flaschengeist.auth"
-    blueprint = Blueprint(name, __name__)
+    blueprint = Blueprint("auth", __name__)
 
 
 @AuthRoutePlugin.blueprint.route("/auth", methods=["POST"])

flaschengeist/plugins/auth_ldap/__init__.py

@@ -17,6 +17,8 @@ from flaschengeist.plugins import AuthPlugin, before_role_updated
 
 
 class AuthLDAP(AuthPlugin):
+    id = "auth_ldap"
+
     def __init__(self, config):
         super().__init__()
         app.config.update(

flaschengeist/plugins/auth_plain/__init__.py

@@ -14,6 +14,8 @@ from flaschengeist import logger
 
 
 class AuthPlain(AuthPlugin):
+    id = "auth_plain"
+
     def install(self):
         plugins_installed(self.post_install)
 

flaschengeist/plugins/balance/__init__.py

@@ -3,6 +3,7 @@
 Extends users plugin with balance functions
 """
 
+import pathlib
 from flask import Blueprint, current_app
 from werkzeug.local import LocalProxy
 from werkzeug.exceptions import NotFound
@@ -56,9 +57,10 @@ def service_debit():
 
 
 class BalancePlugin(Plugin):
-    name = "balance"
+    """Balance Plugin"""
+
     id = "dev.flaschengeist.balance"
-    blueprint = Blueprint(name, __name__)
+    blueprint = Blueprint("balance", __name__)
     permissions = permissions.permissions
     plugin: "BalancePlugin" = LocalProxy(lambda: current_app.config["FG_PLUGINS"][BalancePlugin.name])
     models = models
@@ -67,6 +69,8 @@ class BalancePlugin(Plugin):
         super(BalancePlugin, self).__init__(config)
         from . import routes
 
+        self.migrations_path = (pathlib.Path(__file__).parent / "migrations").resolve()
+
         @plugins_loaded
         def post_loaded(*args, **kwargs):
             if config.get("allow_service_debit", False) and "events" in current_app.config["FG_PLUGINS"]:

flaschengeist/plugins/balance/migrations/f07df84f7a95_initial_balance_migration.py

@@ -0,0 +1,47 @@
+"""Initial balance migration
+
+Revision ID: f07df84f7a95
+Revises: 
+Create Date: 2021-12-19 21:12:53.192267
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import flaschengeist
+
+
+# revision identifiers, used by Alembic.
+revision = "f07df84f7a95"
+down_revision = None
+branch_labels = ("balance",)
+depends_on = "d3026757c7cb"
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "balance_transaction",
+        sa.Column("receiver_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("sender_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("author_id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("time", flaschengeist.models.UtcDateTime(), nullable=False),
+        sa.Column("amount", sa.Numeric(precision=5, scale=2, asdecimal=False), nullable=False),
+        sa.Column("reversal_id", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(["author_id"], ["user.id"], name=op.f("fk_balance_transaction_author_id_user")),
+        sa.ForeignKeyConstraint(["receiver_id"], ["user.id"], name=op.f("fk_balance_transaction_receiver_id_user")),
+        sa.ForeignKeyConstraint(
+            ["reversal_id"],
+            ["balance_transaction.id"],
+            name=op.f("fk_balance_transaction_reversal_id_balance_transaction"),
+        ),
+        sa.ForeignKeyConstraint(["sender_id"], ["user.id"], name=op.f("fk_balance_transaction_sender_id_user")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_balance_transaction")),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("balance_transaction")
+    # ### end Alembic commands ###

flaschengeist/plugins/balance/routes.py

@@ -131,7 +131,7 @@ def get_balance(userid, current_session: Session):
 
     Route: ``/users/<userid>/balance`` | Method: ``GET``
 
-    GET-parameters: ```{from?: string, to?: string}```
+    GET-parameters: ``{from?: string, to?: string}``
 
     Args:
         userid: Userid of user to get balance from
@@ -170,7 +170,7 @@ def get_transactions(userid, current_session: Session):
 
     Route: ``/users/<userid>/balance/transactions`` | Method: ``GET``
 
-    GET-parameters: ```{from?: string, to?: string, limit?: int, offset?: int}```
+    GET-parameters: ``{from?: string, to?: string, limit?: int, offset?: int}``
 
     Args:
         userid: Userid of user to get transactions from

flaschengeist/plugins/message_mail.py

@@ -12,6 +12,8 @@ from . import Plugin
 
 
 class MailMessagePlugin(Plugin):
+    id = "dev.flaschengeist.mail_plugin"
+
     def __init__(self, config):
         super().__init__()
         self.server = config["SERVER"]

flaschengeist/plugins/pricelist/__init__.py

@@ -1,5 +1,6 @@
 """Pricelist plugin"""
 
+import pathlib
 from flask import Blueprint, jsonify, request, current_app
 from werkzeug.local import LocalProxy
 from werkzeug.exceptions import BadRequest, Forbidden, NotFound, Unauthorized
@@ -16,14 +17,15 @@ from . import pricelist_controller, permissions
 
 
 class PriceListPlugin(Plugin):
-    name = "pricelist"
+    id = "dev.flaschengeist.pricelist"
     permissions = permissions.permissions
-    blueprint = Blueprint(name, __name__, url_prefix="/pricelist")
+    blueprint = Blueprint("pricelist", __name__, url_prefix="/pricelist")
     plugin = LocalProxy(lambda: current_app.config["FG_PLUGINS"][PriceListPlugin.name])
     models = models
 
     def __init__(self, cfg):
         super().__init__(cfg)
+        self.migrations_path = (pathlib.Path(__file__).parent / "migrations").resolve()
         config = {"discount": 0}
         config.update(cfg)
 

flaschengeist/plugins/pricelist/migrations/7d9d306be676_initial_pricelist_migration.py

@@ -0,0 +1,141 @@
+"""Initial pricelist migration
+
+Revision ID: 7d9d306be676
+Revises: 
+Create Date: 2021-12-19 21:43:30.203811
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import flaschengeist
+
+
+# revision identifiers, used by Alembic.
+revision = "7d9d306be676"
+down_revision = None
+branch_labels = ("pricelist",)
+depends_on = "d3026757c7cb"
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "drink_extra_ingredient",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("name", sa.String(length=30), nullable=False),
+        sa.Column("price", sa.Numeric(precision=5, scale=2, asdecimal=False), nullable=True),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_drink_extra_ingredient")),
+        sa.UniqueConstraint("name", name=op.f("uq_drink_extra_ingredient_name")),
+    )
+    op.create_table(
+        "drink_tag",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("name", sa.String(length=30), nullable=False),
+        sa.Column("color", sa.String(length=7), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_drink_tag")),
+        sa.UniqueConstraint("name", name=op.f("uq_drink_tag_name")),
+    )
+    op.create_table(
+        "drink_type",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("name", sa.String(length=30), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_drink_type")),
+        sa.UniqueConstraint("name", name=op.f("uq_drink_type_name")),
+    )
+    op.create_table(
+        "drink",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("article_id", sa.String(length=64), nullable=True),
+        sa.Column("package_size", sa.Integer(), nullable=True),
+        sa.Column("name", sa.String(length=60), nullable=False),
+        sa.Column("volume", sa.Numeric(precision=5, scale=2, asdecimal=False), nullable=True),
+        sa.Column("cost_per_volume", sa.Numeric(precision=5, scale=3, asdecimal=False), nullable=True),
+        sa.Column("cost_per_package", sa.Numeric(precision=5, scale=3, asdecimal=False), nullable=True),
+        sa.Column("receipt", sa.PickleType(), nullable=True),
+        sa.Column("type_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("image_id", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(["image_id"], ["image.id"], name=op.f("fk_drink_image_id_image")),
+        sa.ForeignKeyConstraint(["type_id"], ["drink_type.id"], name=op.f("fk_drink_type_id_drink_type")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_drink")),
+    )
+    op.create_table(
+        "drink_ingredient",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("volume", sa.Numeric(precision=5, scale=2, asdecimal=False), nullable=False),
+        sa.Column("ingredient_id", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(["ingredient_id"], ["drink.id"], name=op.f("fk_drink_ingredient_ingredient_id_drink")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_drink_ingredient")),
+    )
+    op.create_table(
+        "drink_price_volume",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("drink_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("volume", sa.Numeric(precision=5, scale=2, asdecimal=False), nullable=True),
+        sa.ForeignKeyConstraint(["drink_id"], ["drink.id"], name=op.f("fk_drink_price_volume_drink_id_drink")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_drink_price_volume")),
+    )
+    op.create_table(
+        "drink_x_tag",
+        sa.Column("drink_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("tag_id", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(["drink_id"], ["drink.id"], name=op.f("fk_drink_x_tag_drink_id_drink")),
+        sa.ForeignKeyConstraint(["tag_id"], ["drink_tag.id"], name=op.f("fk_drink_x_tag_tag_id_drink_tag")),
+    )
+    op.create_table(
+        "drink_x_type",
+        sa.Column("drink_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("type_id", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(["drink_id"], ["drink.id"], name=op.f("fk_drink_x_type_drink_id_drink")),
+        sa.ForeignKeyConstraint(["type_id"], ["drink_type.id"], name=op.f("fk_drink_x_type_type_id_drink_type")),
+    )
+    op.create_table(
+        "drink_ingredient_association",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("volume_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("_drink_ingredient_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("_extra_ingredient_id", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(
+            ["_drink_ingredient_id"],
+            ["drink_ingredient.id"],
+            name=op.f("fk_drink_ingredient_association__drink_ingredient_id_drink_ingredient"),
+        ),
+        sa.ForeignKeyConstraint(
+            ["_extra_ingredient_id"],
+            ["drink_extra_ingredient.id"],
+            name=op.f("fk_drink_ingredient_association__extra_ingredient_id_drink_extra_ingredient"),
+        ),
+        sa.ForeignKeyConstraint(
+            ["volume_id"],
+            ["drink_price_volume.id"],
+            name=op.f("fk_drink_ingredient_association_volume_id_drink_price_volume"),
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_drink_ingredient_association")),
+    )
+    op.create_table(
+        "drink_price",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("price", sa.Numeric(precision=5, scale=2, asdecimal=False), nullable=True),
+        sa.Column("volume_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("public", sa.Boolean(), nullable=True),
+        sa.Column("description", sa.String(length=30), nullable=True),
+        sa.ForeignKeyConstraint(
+            ["volume_id"], ["drink_price_volume.id"], name=op.f("fk_drink_price_volume_id_drink_price_volume")
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_drink_price")),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("drink_price")
+    op.drop_table("drink_ingredient_association")
+    op.drop_table("drink_x_type")
+    op.drop_table("drink_x_tag")
+    op.drop_table("drink_price_volume")
+    op.drop_table("drink_ingredient")
+    op.drop_table("drink")
+    op.drop_table("drink_type")
+    op.drop_table("drink_tag")
+    op.drop_table("drink_extra_ingredient")
+    # ### end Alembic commands ###

flaschengeist/plugins/roles/__init__.py

@@ -16,8 +16,8 @@ from . import permissions
 
 
 class RolesPlugin(Plugin):
-    name = "roles"
+    id = "dev.flaschengeist.roles"
-    blueprint = Blueprint(name, __name__)
+    blueprint = Blueprint("roles", __name__)
     permissions = permissions.permissions
 
 

flaschengeist/plugins/users/__init__.py

@@ -18,8 +18,8 @@ from flaschengeist.utils.datetime import from_iso_format
 
 
 class UsersPlugin(Plugin):
-    name = "users"
+    id = "dev.flaschengeist.users"
-    blueprint = Blueprint(name, __name__)
+    blueprint = Blueprint("users", __name__)
     permissions = permissions.permissions
 
 

flaschengeist/utils/hook.py

@@ -7,6 +7,7 @@ _hooks_after = {}
 
 def Hook(function=None, id=None):
     """Hook decorator
+
     Use to decorate functions as hooks, so plugins can hook up their custom functions.
     """
     # `id` passed as `arg` not `kwarg`
@@ -38,8 +39,10 @@ def Hook(function=None, id=None):
 
 def HookBefore(id: str):
     """Decorator for functions to be called before a Hook-Function is called
+
     The hooked up function must accept the same arguments as the function hooked onto,
     as the functions are called with the same arguments.
+
     Hint: This enables you to modify the arguments!
     """
     if not id or not isinstance(id, str):
@@ -54,9 +57,18 @@ def HookBefore(id: str):
 
 def HookAfter(id: str):
     """Decorator for functions to be called after a Hook-Function is called
+
     As with the HookBefore, the hooked up function must accept the same
     arguments as the function hooked onto, but also receives a
     `hook_result` kwarg containing the result of the function.
+
+    Example:
+        ```py
+        @HookAfter("some.id")
+        def my_func(hook_result):
+            # This function is executed after the function registered with "some.id"
+            print(hook_result)  # This is the result of the function
+        ```
     """
 
     if not id or not isinstance(id, str):

flaschengeist/utils/plugin.py

@@ -0,0 +1,46 @@
+"""Plugin utils
+
+Utilities for handling Flaschengeist plugins
+"""
+
+import pkg_resources
+from flaschengeist import logger
+from flaschengeist.plugins import Plugin
+
+
+def get_plugins() -> list[type[Plugin]]:
+    """Get all installed plugins for Flaschengeist
+
+    Returns:
+        list of classes implementing `flaschengeist.plugins.Plugin`
+    """
+    logger.debug("Search for plugins")
+
+    plugins = []
+    for entry_point in pkg_resources.iter_entry_points("flaschengeist.plugins"):
+        try:
+            logger.debug(f"Found plugin: >{entry_point.name}<")
+            plugin_class = entry_point.load()
+            if issubclass(plugin_class, Plugin):
+                plugins.append(plugin_class)
+        except TypeError:
+            logger.error(f"Invalid entry point for plugin {entry_point.name} found.")
+    return plugins
+
+
+def plugin_version(plugin: type[Plugin]) -> str:
+    """Get version of plugin
+
+    Returns the version of a plugin, if plugin does not set the
+    version property, the version of the package providing the
+    plugin is taken.
+
+    Args:
+        plugin: Plugin or Plugin class
+
+    Returns:
+        Version as string
+    """
+    if plugin.version:
+        return plugin.version
+    return pkg_resources.get_distribution(plugin.__module__.split(".", 1)[0]).version

migrations/alembic.ini

@@ -0,0 +1,52 @@
+# A generic, single database configuration.
+
+[alembic]
+# template used to generate migration files
+# file_template = %%(rev)s_%%(slug)s
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+version_path_separator = os
+version_locations = %(here)s/versions
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic,flask_migrate
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[logger_flask_migrate]
+level = INFO
+handlers =
+qualname = flask_migrate
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

migrations/env.py

@@ -0,0 +1,73 @@
+import logging
+from logging.config import fileConfig
+from flask import current_app
+from alembic import context
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+fileConfig(config.config_file_name)
+logger = logging.getLogger("alembic.env")
+
+config.set_main_option("sqlalchemy.url", str(current_app.extensions["migrate"].db.get_engine().url).replace("%", "%%"))
+target_metadata = current_app.extensions["migrate"].db.metadata
+
+
+def run_migrations_offline():
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(url=url, target_metadata=target_metadata, literal_binds=True)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online():
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+
+    # this callback is used to prevent an auto-migration from being generated
+    # when there are no changes to the schema
+    # reference: http://alembic.zzzcomputing.com/en/latest/cookbook.html
+    def process_revision_directives(context, revision, directives):
+        if getattr(config.cmd_opts, "autogenerate", False):
+            script = directives[0]
+            if script.upgrade_ops.is_empty():
+                directives[:] = []
+                logger.info("No changes in schema detected.")
+
+    connectable = current_app.extensions["migrate"].db.get_engine()
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            process_revision_directives=process_revision_directives,
+            **current_app.extensions["migrate"].configure_args
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

migrations/script.py.mako

@@ -0,0 +1,25 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import flaschengeist
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade():
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade():
+    ${downgrades if downgrades else "pass"}

migrations/versions/d3026757c7cb_initial_migration.py

@@ -0,0 +1,141 @@
+"""Initial migration.
+
+Revision ID: d3026757c7cb
+Revises: 
+Create Date: 2021-12-19 20:34:34.122576
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import flaschengeist
+
+
+# revision identifiers, used by Alembic.
+revision = "d3026757c7cb"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "image",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("filename_", sa.String(length=127), nullable=False),
+        sa.Column("mimetype_", sa.String(length=30), nullable=False),
+        sa.Column("thumbnail_", sa.String(length=127), nullable=True),
+        sa.Column("path_", sa.String(length=127), nullable=True),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_image")),
+    )
+    op.create_table(
+        "permission",
+        sa.Column("name", sa.String(length=30), nullable=True),
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_permission")),
+        sa.UniqueConstraint("name", name=op.f("uq_permission_name")),
+    )
+    op.create_table(
+        "plugin_setting",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("plugin", sa.String(length=30), nullable=True),
+        sa.Column("name", sa.String(length=30), nullable=False),
+        sa.Column("value", sa.PickleType(), nullable=True),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_plugin_setting")),
+    )
+    op.create_table(
+        "role",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("name", sa.String(length=30), nullable=True),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_role")),
+        sa.UniqueConstraint("name", name=op.f("uq_role_name")),
+    )
+    op.create_table(
+        "role_x_permission",
+        sa.Column("role_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("permission_id", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(
+            ["permission_id"], ["permission.id"], name=op.f("fk_role_x_permission_permission_id_permission")
+        ),
+        sa.ForeignKeyConstraint(["role_id"], ["role.id"], name=op.f("fk_role_x_permission_role_id_role")),
+    )
+    op.create_table(
+        "user",
+        sa.Column("userid", sa.String(length=30), nullable=False),
+        sa.Column("display_name", sa.String(length=30), nullable=True),
+        sa.Column("firstname", sa.String(length=50), nullable=False),
+        sa.Column("lastname", sa.String(length=50), nullable=False),
+        sa.Column("deleted", sa.Boolean(), nullable=True),
+        sa.Column("birthday", sa.Date(), nullable=True),
+        sa.Column("mail", sa.String(length=60), nullable=True),
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("avatar", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(["avatar"], ["image.id"], name=op.f("fk_user_avatar_image")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_user")),
+        sa.UniqueConstraint("userid", name=op.f("uq_user_userid")),
+    )
+    op.create_table(
+        "notification",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("plugin", sa.String(length=127), nullable=False),
+        sa.Column("text", sa.Text(), nullable=True),
+        sa.Column("data", sa.PickleType(), nullable=True),
+        sa.Column("time", flaschengeist.models.UtcDateTime(), nullable=False),
+        sa.Column("user_id", flaschengeist.models.Serial(), nullable=False),
+        sa.ForeignKeyConstraint(["user_id"], ["user.id"], name=op.f("fk_notification_user_id_user")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_notification")),
+    )
+    op.create_table(
+        "password_reset",
+        sa.Column("user", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("token", sa.String(length=32), nullable=True),
+        sa.Column("expires", flaschengeist.models.UtcDateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["user"], ["user.id"], name=op.f("fk_password_reset_user_user")),
+        sa.PrimaryKeyConstraint("user", name=op.f("pk_password_reset")),
+    )
+    op.create_table(
+        "session",
+        sa.Column("expires", flaschengeist.models.UtcDateTime(), nullable=True),
+        sa.Column("token", sa.String(length=32), nullable=True),
+        sa.Column("lifetime", sa.Integer(), nullable=True),
+        sa.Column("browser", sa.String(length=30), nullable=True),
+        sa.Column("platform", sa.String(length=30), nullable=True),
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("user_id", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(["user_id"], ["user.id"], name=op.f("fk_session_user_id_user")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_session")),
+        sa.UniqueConstraint("token", name=op.f("uq_session_token")),
+    )
+    op.create_table(
+        "user_attribute",
+        sa.Column("id", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("user", flaschengeist.models.Serial(), nullable=False),
+        sa.Column("name", sa.String(length=30), nullable=True),
+        sa.Column("value", sa.PickleType(), nullable=True),
+        sa.ForeignKeyConstraint(["user"], ["user.id"], name=op.f("fk_user_attribute_user_user")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_user_attribute")),
+    )
+    op.create_table(
+        "user_x_role",
+        sa.Column("user_id", flaschengeist.models.Serial(), nullable=True),
+        sa.Column("role_id", flaschengeist.models.Serial(), nullable=True),
+        sa.ForeignKeyConstraint(["role_id"], ["role.id"], name=op.f("fk_user_x_role_role_id_role")),
+        sa.ForeignKeyConstraint(["user_id"], ["user.id"], name=op.f("fk_user_x_role_user_id_user")),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("user_x_role")
+    op.drop_table("user_attribute")
+    op.drop_table("session")
+    op.drop_table("password_reset")
+    op.drop_table("notification")
+    op.drop_table("user")
+    op.drop_table("role_x_permission")
+    op.drop_table("role")
+    op.drop_table("plugin_setting")
+    op.drop_table("permission")
+    op.drop_table("image")
+    # ### end Alembic commands ###

setup.cfg

@@ -23,13 +23,13 @@ python_requires = >=3.7
 packages = find:
 install_requires =
     Flask >= 2.0
+    Flask-Cors >= 3.0
+    Flask-Migrate >= 3.1.0 
+    Flask-SQLAlchemy >= 2.5
     Pillow >= 8.4.0
-    flask_cors
+    SQLAlchemy >= 1.4.28
-    flask_sqlalchemy>=2.5
-    sqlalchemy>=1.4.26
     toml
-    werkzeug
+    werkzeug >= 2.0
-    
 
 [options.extras_require]
 argon = argon2-cffi
@@ -44,7 +44,7 @@ mysql =
 
 [options.entry_points]
 console_scripts =
-    flaschengeist = flaschengeist.cli:cli
+    flaschengeist = flaschengeist.cli:main
 flask.commands =
     ldap = flaschengeist.plugins.auth_ldap.cli:ldap
     users = flaschengeist.plugins.users.cli:users