From 4df7f1cc01638963c46ca9d0adfd129aa227ad73 Mon Sep 17 00:00:00 2001 From: Ferdinand Thiessen Date: Sun, 19 Dec 2021 18:58:57 +0100 Subject: [PATCH] docs(plugins): Some more documentation on the plugin class --- flaschengeist/plugins/__init__.py | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/flaschengeist/plugins/__init__.py b/flaschengeist/plugins/__init__.py index 1b6f701..6932110 100644 --- a/flaschengeist/plugins/__init__.py +++ b/flaschengeist/plugins/__init__.py @@ -54,10 +54,21 @@ class Plugin: If your class uses custom models add a static property called ``models``""" blueprint = None # You have to override + """Override with a `flask.blueprint` if the plugin uses custom routes""" permissions = [] # 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)""" name = "plugin" # You have to override + """Override with human readable name of the plugin""" models = None # You have to override + """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""" def __init__(self, config=None): """Constructor called by create_app @@ -68,17 +79,21 @@ class Plugin: def install(self): """Installation routine + Is always called with Flask application context """ pass def get_setting(self, name: str, **kwargs): """Get plugin setting from database + Args: name: string identifying the setting default: Default value Returns: Value stored in database (native python) + Raises: + `KeyError` if no such setting exists in the database """ try: setting = ( @@ -95,6 +110,7 @@ class Plugin: def set_setting(self, name: str, value): """Save setting in database + Args: name: String identifying the setting value: Value to be stored @@ -114,10 +130,22 @@ class Plugin: db.session.commit() def notify(self, user, text: str, data=None): + """Create a new notification for an user + + Args: + user: `flaschengeist.models.user.User` to notify + text: Visibile notification text + data: Optional data passed to the notificaton + Returns: + ID of the created `flaschengeist.models.notification.Notification` + + Hint: use the data for frontend actions. + """ if not user.deleted: n = Notification(text=text, data=data, plugin=self.id, user_=user) db.session.add(n) db.session.commit() + return n.id def serialize(self): """Serialize a plugin into a dict