Merge branch '48-cleanup-and-documentation' into 'master'

Resolve "cleanup and documentation"

Closes #48

See merge request !51

api/__init__.py

@@ -6,7 +6,7 @@ from flask_sqlalchemy import SQLAlchemy
 from flask_limiter import Limiter
 from flask_limiter.util import get_remote_address
 
-
+# flask application setup, with database, JWT, bcrypt and limiter
 app = Flask(__name__)
 app.config['SECRET_KEY'] = 'randomchangethisshit'
 app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///database/database.db'
@@ -18,7 +18,7 @@ bcrypt = Bcrypt(app)
 limiter = Limiter(app, key_func=get_remote_address)
 api = Api(app)
 
-
+# import all classes that is used to create endpoints
 from api.endpoints.login import Login
 from api.endpoints.user import UserEndpoint
 from api.endpoints.location import LocationEndpoint
@@ -32,6 +32,7 @@ from api.endpoints.salamanders import SalamandersEndpoint
 from api.endpoints.findsalamanderinfo import FindSalamanderInfo
 
 
+# add the imported classes to a route
 api.add_resource(Login, "/login")
 api.add_resource(UserEndpoint, "/user")
 api.add_resource(LocationEndpoint, "/location")

api/endpoints/editsalamander.py

@@ -12,6 +12,13 @@ from path_constants import _ACCESS_DATABASE
 from image_encoder.image_encoder import *
 import cv2
 
+"""
+Endpoint for editing salamanders.
+GET: Gets a specific salamanders original and processed image, and all its data.
+PUT: Edits a specific salamander with new data like sex, species, location etc.
+DELETE: Deletes a specific salamander from the system.
+"""
+
 
 class EditSalamander(Resource):
     decorators = [limiter.limit("60/minute")]
@@ -41,7 +48,6 @@ class EditSalamander(Resource):
 
                                 height, width, _ = image.shape
                                 desired_long_side = 320
-                                scaling_factor = 1
 
                                 if width > height:
                                     scaling_factor = desired_long_side / width
@@ -145,7 +151,7 @@ class EditSalamander(Resource):
 
                     if "location" in data and "new_location" in data and "new_sex" in data and "new_species" in data:
                         if data['location'] != data['new_location'] or salamander.sex != data[
-                            'new_sex'] or salamander.species != data['new_species']:
+                                'new_sex'] or salamander.species != data['new_species']:
                             salamander_path = os.path.join("images", data['location'], salamander.species,
                                                            salamander.sex, str(salamander.id))
                             new_path_to_images = os.path.join("images", data['new_location'], data['new_species'],

api/endpoints/findsalamanderinfo.py

@@ -8,11 +8,14 @@ from api import limiter
 from image_encoder.image_encoder import *
 from path_constants import image_type
 import glob
-# import mimetypes
 ALLOWED_EXTENSIONS = ['jpg', 'png', 'jpeg']
 
+"""
+Endpoint for processing the salamanders abdominal pattern.
+POST: Receives an image of a salamander, processes it, and returns the processed image back to the user.
+"""
+
 
-# findSalamanderInfo endpoint
 class FindSalamanderInfo(Resource):
     decorators = [limiter.limit("5/minute")]
 
@@ -53,7 +56,6 @@ class FindSalamanderInfo(Resource):
 
 
 def allowed_image(filename):
-    # return mimetypes.guess_extension(filename).lower() in ALLOWED_EXTENSIONS
     return '.' in filename and \
            filename.rsplit('.', 1)[1].lower() in ALLOWED_EXTENSIONS
 

api/endpoints/location.py

 from flask import request, jsonify
 from flask_restful import Resource
 from flask_jwt_extended import jwt_required, get_jwt_identity
-
 from api import db, limiter
 from api.models.dbmodels import Location, Salamander, User
 import re
 import os
 from api.endpoints.matchsalamander import sanitize_int_str
 from path_constants import _ACCESS_DATABASE
-
 LATITUDE_REGEX = "^(\\+|-)?(?:90(?:(?:\\.0{1,6})?)|(?:[0-9]|[1-8][0-9])(?:(?:\\.[0-9]{1,6})?))$"
 LONGITUDE_REGEX = "^(\\+|-)?(?:180(?:(?:\\.0{1,6})?)|(?:[0-9]|[1-9][0-9]|1[0-7][0-9])(?:(?:\\.[0-9]{1,6})?))$"
 
 
-# location endpoint
+"""
+Endpoint for creating, updating, getting and deleting locations in the system.
+GET: Returns all data about all locations to the user.
+POST: Creates a new location with radius, name, longitude and latitude.
+PUT: For editing a location. Change its name or radius.
+DELETE: For deleting a specific location. This can only be done if the location does not contain a salamander.
+"""
+
+
 class LocationEndpoint(Resource):
     decorators = [limiter.limit("60/minute")]
 
@@ -121,6 +127,7 @@ class LocationEndpoint(Resource):
             return jsonify({"message": "user not admin", "status": 400})
 
 
+# creates the folder structure when a location is registered
 def create_directory_folders(location):
     dir_smooth_male = "images/" + location + "/smooth_newt/" + "male/"
     dir_smooth_female = "images/" + location + "/smooth_newt/" + "female/"

api/endpoints/login.py

@@ -5,6 +5,13 @@ from api.models.dbmodels import User
 from api import bcrypt, db, limiter
 
 
+"""
+Endpoint for logging in to the system.
+POST: Checks if the email and password matches. Returns a JSON Web Token to the user that requested the login.
+This JWT contains the users ID encrypted in it, so the server knows who sends request to other endpoints.
+"""
+
+
 class Login(Resource):
     decorators = [limiter.limit("3/minute")]
 

api/endpoints/manageuser.py

@@ -7,6 +7,15 @@ from random import choice
 from string import ascii_lowercase, digits
 
 
+"""
+Endpoint for administrators to manage users.
+GET: Get all users in the system.
+POST: Change a users access rights. The admin can update them to admin, remove admin or remove all access rights.
+PUT: Is used if a user forgets their password. The admin can reset it, so that the user can login and change it at a 
+later point.
+"""
+
+
 class AdminManageUser(Resource):
     decorators = [limiter.limit("60/minute")]
 

api/endpoints/matchsalamander.py

@@ -14,6 +14,13 @@ APPROVED_SEX = ["male", "female", "juvenile"]
 APPROVED_SPECIES = ["smooth_newt", "northern_crested_newt"]
 
 
+"""
+Endpoint for matching a newly registered salamander with the once in the database.
+POST: Matched the processed image of the salamander pattern with the once in the database.
+It only matches females and males, not juveniles.
+"""
+
+
 # matchSalamander endpoint
 class MatchSalamander(Resource):
     decorators = [limiter.limit("5/minute")]

api/endpoints/pendingusers.py

@@ -5,6 +5,13 @@ from api import db, limiter
 from flask_jwt_extended import get_jwt_identity, jwt_required
 
 
+"""
+Endpoint for administrators to accept newly created users.
+GET: Gets all pending users in the system.
+POST: For either accepting or denying a users access permissions. If the user is not accepted, it will be deleted.
+"""
+
+
 class AdminPendingUsers(Resource):
     decorators = [limiter.limit("60/minute")]
 

api/endpoints/salamander.py

@@ -4,15 +4,17 @@ from flask_restful import Resource
 from api import db, limiter
 from api.models.dbmodels import Location, User, Salamander
 import os
-import cv2
 import glob
 import cv2
-import base64
 from image_encoder.image_encoder import *
 from path_constants import _ACCESS_DATABASE
 
+"""
+Endpoint for getting all original images of a specific salamander.
+GET: Gets all the images based on a salamanders ID.
+"""
+
 
-# get all images on a specific salamander based on id
 class SalamanderEndpoint(Resource):
     decorators = [limiter.limit("60/minute")]
 
@@ -34,11 +36,10 @@ class SalamanderEndpoint(Resource):
 
                             image = cv2.imread(path)
 
-                            #scaling to set size
+                            # scaling to set size
                             height, width, _ = image.shape
 
                             desired_long_side = 320
-                            scaling_factor = 1
 
                             if width > height:
                                 scaling_factor = desired_long_side / width

api/endpoints/salamanders.py

@@ -5,7 +5,12 @@ from api import db, limiter
 from api.models.dbmodels import Location, User, Salamander, SalamanderGrowth
 from path_constants import _ACCESS_DATABASE
 
-# get all salamanders on a specific location
+"""
+Endpoint for for getting data about all salamanders in a specific location.
+GET: Gets all salamanders and their data based on a specific location.
+"""
+
+
 class SalamandersEndpoint(Resource):
     decorators = [limiter.limit("60/minute")]
 

api/endpoints/user.py

@@ -8,6 +8,13 @@ from api.forms.userforms import RegistrationForm, DeleteUserForm
 
 EMAIL_REGEX = "^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"
 
+"""
+Endpoint for creating a new user, deleting a user and edit a user.
+POST: For creating a new user with email, name, password and confirm password.
+PUT: For editing a user. Either edit name, email or password.
+DELETE: For deleting a user. An administrator cannot delete their own account.
+"""
+
 
 class UserEndpoint(Resource):
     decorators = [limiter.limit("30/minute")]

api/endpoints/verifypassword.py

@@ -5,6 +5,12 @@ from flask_jwt_extended import get_jwt_identity, jwt_required
 from api.models.dbmodels import User
 
 
+"""
+Endpoint to verify a users password.
+POST: Checks that the password that the user typed in is correct.
+"""
+
+
 class VerifyPassword(Resource):
     decorators = [limiter.limit("30/minute")]