From e0d3b211bb580e5c26b73151cacfc4e093061937 Mon Sep 17 00:00:00 2001 From: Ferdinand Thiessen Date: Fri, 30 Oct 2020 05:53:15 +0100 Subject: [PATCH] [Doc] User plugin documentation created --- flaschengeist/config.py | 2 +- flaschengeist/decorator.py | 1 + flaschengeist/models/__init__.py | 6 +- flaschengeist/plugins/roles/__init__.py | 2 +- flaschengeist/plugins/users/__init__.py | 95 +++++++++++++++++-------- 5 files changed, 73 insertions(+), 33 deletions(-) diff --git a/flaschengeist/config.py b/flaschengeist/config.py index 5d1fc6a..cda1e4f 100644 --- a/flaschengeist/config.py +++ b/flaschengeist/config.py @@ -43,7 +43,7 @@ def configure_app(app): user=config["DATABASE"]["user"], passwd=config["DATABASE"]["password"], host=config["DATABASE"]["host"], - database=config["DATABASE"]["database"] + database=config["DATABASE"]["database"], ) app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False diff --git a/flaschengeist/decorator.py b/flaschengeist/decorator.py index e9f61f8..848b0ee 100644 --- a/flaschengeist/decorator.py +++ b/flaschengeist/decorator.py @@ -16,6 +16,7 @@ def login_required(permission=None): Returns: Wrapped function with login (and permission) guard """ + def wrap(func): @wraps(func) def wrapped_f(*args, **kwargs): diff --git a/flaschengeist/models/__init__.py b/flaschengeist/models/__init__.py index 016672a..415ffee 100644 --- a/flaschengeist/models/__init__.py +++ b/flaschengeist/models/__init__.py @@ -4,8 +4,10 @@ from sqlalchemy.types import DateTime, TypeDecorator class ModelSerializeMixin: def serialize(self): - """Return: - Dict of all not private or protected annotated member variables.""" + """Serialize class to dict + Returns: + Dict of all not private or protected annotated member variables. + """ d = {param: getattr(self, param) for param in self.__class__.__annotations__ if not param.startswith("_")} if len(d) == 1: key, value = d.popitem() diff --git a/flaschengeist/plugins/roles/__init__.py b/flaschengeist/plugins/roles/__init__.py index 26588ab..edb6a37 100644 --- a/flaschengeist/plugins/roles/__init__.py +++ b/flaschengeist/plugins/roles/__init__.py @@ -31,7 +31,7 @@ def list_roles(current_session): current_session: Session sent with Authorization Header Returns: - JSON encodes array of `flaschengeist.models.user.Role` + JSON encoded array of `flaschengeist.models.user.Role` """ roles = roleController.get_all() return jsonify(roles) diff --git a/flaschengeist/plugins/users/__init__.py b/flaschengeist/plugins/users/__init__.py index 756ff01..648ba1d 100644 --- a/flaschengeist/plugins/users/__init__.py +++ b/flaschengeist/plugins/users/__init__.py @@ -1,3 +1,8 @@ +"""Users plugin + +Provides routes used to manage users +""" + from flask import Blueprint, request, jsonify from werkzeug.exceptions import NotFound, BadRequest, Forbidden @@ -16,16 +21,6 @@ class UsersPlugin(Plugin): def __init__(self, config): super().__init__(blueprint=users_bp, permissions=[_permission_edit, _permission_delete, _permission_set_roles]) - ################################################# - # Routes # - # # - # /users POST: register new # - # GET: get all users # - # /users/ GET: get user with uid # - # PUT: modify user # - # DELETE: remove user # - ################################################# - @users_bp.route("/users", methods=["POST"]) def __registration(self): @@ -35,42 +30,85 @@ def __registration(self): @users_bp.route("/users", methods=["GET"]) @login_required() -def __list_users(**kwargs): +def list_users(current_session): + """List all existing users + + Route: ``/users`` | Method: ``GET`` + + Args: + current_session: Session sent with Authorization Header + + Returns: + JSON encoded array of `flaschengeist.models.user.User` or HTTP error + """ logger.debug("Retrieve list of all users") users = userController.get_users() return jsonify(users) -@users_bp.route("/users/", methods=["GET"]) +@users_bp.route("/users/", methods=["GET"]) @login_required() -def __get_user(uid, **kwargs): - logger.debug("Get information of user {{ {} }}".format(uid)) - user = userController.get_user(uid) - if user: - return jsonify(user) - raise NotFound +def get_user(userid, current_session): + """Retrieve user by userid + + Route: ``/users/`` | Method: ``GET`` + + Args: + userid: UserID of user to retrieve + current_session: Session sent with Authorization Header + + Returns: + JSON encoded `flaschengeist.models.user.User` or HTTP error + """ + logger.debug("Get information of user {{ {} }}".format(userid)) + user = userController.get_user(userid) + return jsonify(user) -@users_bp.route("/users/", methods=["DELETE"]) +@users_bp.route("/users/", methods=["DELETE"]) @login_required(permission=_permission_delete) -def __delete_user(uid, **kwargs): - logger.debug("Delete user {{ {} }}".format(uid)) - user = userController.get_user(uid) +def delete_user(userid, current_session): + """Delete user by userid + + Route: ``/users/`` | Method: ``DELETE`` + + Args: + userid: UserID of user to retrieve + current_session: Session sent with Authorization Header + + Returns: + HTTP-200 or HTTP error + """ + logger.debug("Delete user {{ {} }}".format(userid)) + user = userController.get_user(userid) userController.delete(user) - return jsonify({"ok": "ok"}) -@users_bp.route("/users/", methods=["PUT"]) +@users_bp.route("/users/", methods=["PUT"]) @login_required() -def __edit_user(uid, current_session, **kwargs): - logger.debug("Modify information of user {{ {} }}".format(uid)) - user = userController.get_user(uid) +def edit_user(userid, current_session): + """Modify user by userid + + Route: ``/users/`` | Method: ``PUT`` + + POST-data: ```{firstname?: string, lastname?: string, display_name?: string, mail?: string, + password?: string, roles?: string[]}``` + + Args: + userid: UserID of user to retrieve + current_session: Session sent with Authorization Header + + Returns: + HTTP-200 or HTTP error + """ + logger.debug("Modify information of user {{ {} }}".format(userid)) + user = userController.get_user(userid) data = request.get_json() password = None new_password = data["new_password"] if "new_password" in data else None - if uid != current_session._user.userid: + if userid != current_session._user.userid: if not user.has_permission(_permission_edit): return Forbidden else: @@ -89,4 +127,3 @@ def __edit_user(uid, current_session, **kwargs): userController.modify_user(user, password, new_password) userController.update_user(user) - return jsonify({"ok": "ok"})