[Doc] User plugin documentation created

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
 

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):

flaschengeist/models/__init__.py

@@ -4,8 +4,10 @@ from sqlalchemy.types import DateTime, TypeDecorator
 
 class ModelSerializeMixin:
     def serialize(self):
-        """Return:
+        """Serialize class to dict
-            Dict of all not private or protected annotated member variables."""
+        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()

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)

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/<uid>     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/<uid>", methods=["GET"])
+@users_bp.route("/users/<userid>", methods=["GET"])
 @login_required()
-def __get_user(uid, **kwargs):
+def get_user(userid, current_session):
-    logger.debug("Get information of user {{ {} }}".format(uid))
+    """Retrieve user by userid
-    user = userController.get_user(uid)
+
-    if user:
+    Route: ``/users/<userid>`` | Method: ``GET``
-        return jsonify(user)
+
-    raise NotFound
+    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/<uid>", methods=["DELETE"])
+@users_bp.route("/users/<userid>", methods=["DELETE"])
 @login_required(permission=_permission_delete)
-def __delete_user(uid, **kwargs):
+def delete_user(userid, current_session):
-    logger.debug("Delete user {{ {} }}".format(uid))
+    """Delete user by userid
-    user = userController.get_user(uid)
+
+    Route: ``/users/<userid>`` | 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/<uid>", methods=["PUT"])
+@users_bp.route("/users/<userid>", methods=["PUT"])
 @login_required()
-def __edit_user(uid, current_session, **kwargs):
+def edit_user(userid, current_session):
-    logger.debug("Modify information of user {{ {} }}".format(uid))
+    """Modify user by userid
-    user = userController.get_user(uid)
+
+    Route: ``/users/<userid>`` | 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"})