319 lines
9.7 KiB
Python
319 lines
9.7 KiB
Python
"""Flaschengeist Plugins
|
|
|
|
## Custom database tables
|
|
|
|
You can add tables by declaring them using the SQLAlchemy syntax,
|
|
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`
|
|
"""
|
|
|
|
from importlib_metadata import Distribution, EntryPoint
|
|
from werkzeug.exceptions import MethodNotAllowed, NotFound
|
|
from werkzeug.datastructures import FileStorage
|
|
|
|
from flaschengeist.models.user import _Avatar, User
|
|
from flaschengeist.utils.hook import HookBefore, HookAfter
|
|
|
|
__all__ = [
|
|
"plugins_installed",
|
|
"plugins_loaded",
|
|
"before_delete_user",
|
|
"before_role_updated",
|
|
"before_update_user",
|
|
"after_role_updated",
|
|
"Plugin",
|
|
"AuthPlugin",
|
|
]
|
|
|
|
# Documentation hacks, see https://github.com/mitmproxy/pdoc/issues/320
|
|
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")
|
|
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
|
|
|
|
Passed args:
|
|
- *app:* Current flask app instance (args)
|
|
"""
|
|
|
|
before_role_updated = HookBefore("update_role")
|
|
before_role_updated.__doc__ = """Hook decorator for when roles are modified
|
|
|
|
Passed args:
|
|
- *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")
|
|
after_role_updated.__doc__ = """Hook decorator for when roles are modified
|
|
|
|
Passed args:
|
|
- *role:* modified `flaschengeist.models.user.Role`
|
|
- *new_name:* New name if the name was changed (*None* if deleted)
|
|
"""
|
|
|
|
before_update_user = HookBefore("update_user")
|
|
before_update_user.__doc__ = """Hook decorator, when ever an user update is done, this is called before.
|
|
|
|
Passed args:
|
|
- *user:* `flaschengeist.models.user.User` object
|
|
"""
|
|
|
|
before_delete_user = HookBefore("delete_user")
|
|
before_delete_user.__doc__ = """Hook decorator,this is called before an user gets deleted.
|
|
|
|
Passed args:
|
|
- *user:* `flaschengeist.models.user.User` object
|
|
"""
|
|
|
|
|
|
class Plugin:
|
|
"""Base class for all Plugins
|
|
|
|
All plugins must derived from this class.
|
|
|
|
Optional:
|
|
- *blueprint*: `flask.Blueprint` providing your routes
|
|
- *permissions*: List of your custom permissions
|
|
- *models*: Your models, used for API export
|
|
"""
|
|
|
|
name: str
|
|
"""Name of the plugin, loaded from EntryPoint"""
|
|
|
|
version: str
|
|
"""Version of the plugin, loaded from Distribution"""
|
|
|
|
dist: Distribution
|
|
"""Distribution of this plugin"""
|
|
|
|
blueprint = None
|
|
"""Optional `flask.blueprint` if the plugin uses custom routes"""
|
|
|
|
permissions: list[str] = []
|
|
"""Optional list of 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*.
|
|
"""
|
|
|
|
models = None
|
|
"""Optional module containing the SQLAlchemy models used by the plugin"""
|
|
|
|
migrations_path = None
|
|
"""Optional location of the path to migration files, required if custome db tables are used"""
|
|
|
|
def __init__(self, entry_point: EntryPoint, config=None):
|
|
"""Constructor called by create_app
|
|
Args:
|
|
config: Dict configuration containing the plugin section
|
|
"""
|
|
self.version = entry_point.dist.version
|
|
self.name = entry_point.name
|
|
self.dist = entry_point.dist
|
|
|
|
def install(self):
|
|
"""Installation routine
|
|
|
|
Is always called with Flask application context
|
|
"""
|
|
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
|
|
|
|
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
|
|
"""
|
|
from ..controller import pluginController
|
|
|
|
return pluginController.get_setting(self.id, name, **kwargs)
|
|
|
|
def set_setting(self, name: str, value):
|
|
"""Save setting in database
|
|
|
|
Args:
|
|
name: String identifying the setting
|
|
value: Value to be stored
|
|
"""
|
|
from ..controller import pluginController
|
|
|
|
return pluginController.set_setting(self.id, name, value)
|
|
|
|
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.
|
|
"""
|
|
from ..controller import pluginController
|
|
|
|
return pluginController.notify(self.id, user, text, data)
|
|
|
|
def serialize(self):
|
|
"""Serialize a plugin into a dict
|
|
|
|
Returns:
|
|
Dict containing version and permissions of the plugin
|
|
"""
|
|
from flaschengeist.utils.plugin import plugin_version
|
|
return {"version": plugin_version(self), "permissions": self.permissions}
|
|
|
|
|
|
class AuthPlugin(Plugin):
|
|
"""Base class for all authentification plugins
|
|
|
|
See also `Plugin`
|
|
"""
|
|
|
|
def login(self, user, pw):
|
|
"""Login routine, MUST BE IMPLEMENTED!
|
|
|
|
Args:
|
|
user: User class containing at least the uid
|
|
pw: given password
|
|
Returns:
|
|
Must return False if not found or invalid credentials, True if success
|
|
"""
|
|
raise NotImplemented
|
|
|
|
def update_user(self, user):
|
|
"""If backend is using external data, then update this user instance with external data
|
|
Args:
|
|
user: User object
|
|
"""
|
|
pass
|
|
|
|
def find_user(self, userid, mail=None):
|
|
"""Find an user by userid or mail
|
|
Args:
|
|
userid: Userid to search
|
|
mail: If set, mail to search
|
|
Returns:
|
|
None or User
|
|
"""
|
|
return None
|
|
|
|
def modify_user(self, user, password, new_password=None):
|
|
"""If backend is using (writeable) external data, then update the external database with the user provided.
|
|
User might have roles not existing on the external database, so you might have to create those.
|
|
|
|
Args:
|
|
user: User object
|
|
password: Password (some backends need the current password for changes) if None force edit (admin)
|
|
new_password: If set a password change is requested
|
|
Raises:
|
|
NotImplemented: If backend does not support this feature (or no password change)
|
|
BadRequest: Logic error, e.g. password is wrong.
|
|
Error: Other errors if backend went mad (are not handled and will result in a 500 error)
|
|
"""
|
|
raise NotImplemented
|
|
|
|
def create_user(self, user, password):
|
|
"""If backend is using (writeable) external data, then create a new user on the external database.
|
|
|
|
Args:
|
|
user: User object
|
|
password: string
|
|
|
|
"""
|
|
raise MethodNotAllowed
|
|
|
|
def delete_user(self, user):
|
|
"""If backend is using (writeable) external data, then delete the user from external database.
|
|
|
|
Args:
|
|
user: User object
|
|
|
|
"""
|
|
raise MethodNotAllowed
|
|
|
|
def get_avatar(self, user):
|
|
"""Retrieve avatar for given user (if supported by auth backend)
|
|
|
|
Default behavior is to use native Image objects,
|
|
so by default this function is never called, as the userController checks
|
|
native Image objects first.
|
|
|
|
Args:
|
|
user: User to retrieve the avatar for
|
|
Raises:
|
|
NotFound: If no avatar found or not implemented
|
|
"""
|
|
raise NotFound
|
|
|
|
def set_avatar(self, user, file: FileStorage):
|
|
"""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: `werkzeug.datastructures.FileStorage` uploaded by the user
|
|
Raises:
|
|
MethodNotAllowed: If not supported by Backend
|
|
Any valid HTTP exception
|
|
"""
|
|
# By default save the image to the avatar,
|
|
# deleting would happen by unsetting it
|
|
from ..controller import imageController
|
|
|
|
user.avatar_ = imageController.upload_image(file)
|
|
|
|
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.
|
|
|
|
Args:
|
|
user: Uset to delete the avatar for
|
|
|
|
Raises:
|
|
MethodNotAllowed: If not supported by Backend
|
|
"""
|
|
user.avatar_ = None
|