Add some docstrings to models.py

app/models.py

@@ -7,6 +7,11 @@ from . import login_manager
 
 
 class Permission:
+    """
+    Defines User permissions as integers by the power of 2. User permission
+    can be evaluated using the bitwise operator &. 3 equals to CREATE_JOB and
+    DELETE_JOB and so on.
+    """
     CREATE_JOB = 1
     DELETE_JOB = 2
     # WRITE = 4
@@ -15,6 +20,10 @@ class Permission:
 
 
 class Role(db.Model):
+    """
+    Model for the different roles Users can have. Is a one-to-many relationship.
+    A Role can be associated with many User rows.
+    """
     __tablename__ = 'roles'
     id = db.Column(db.Integer, primary_key=True)
     name = db.Column(db.String(64), unique=True)
@@ -28,24 +37,46 @@ class Role(db.Model):
             self.permissions = 0
 
     def __repr__(self):
+        """
+        String representation of the Role. For human readability.
+        """
         return '<Role %r>' % self.name
 
     def add_permission(self, perm):
+        """
+        Add new permission to Role. Input is a Permission.
+        """
         if not self.has_permission(perm):
             self.permissions += perm
 
     def remove_permission(self, perm):
+        """
+        Removes permission from a Role. Input a Permission.
+        """
         if self.has_permission(perm):
             self.permissions -= perm
 
     def reset_permissions(self):
+        """
+        Resets permissions to zero. Zero equals no permissions at all.
+        """
         self.permissions = 0
 
     def has_permission(self, perm):
+        """
+        Checks if a Role has a specific Permission. Does this wit hthe bitwise
+        operator.
+        """
         return self.permissions & perm == perm
 
     @staticmethod
     def insert_roles():
+        """
+        Inserts roles into the databes. This has to be executed befor Users are
+        added to the database. Otherwiese Users will not have a Role assigned
+        to them. Order of the roles dictionary determines the ID of each role.
+        User hast the ID 1 and Administrator has the ID 2.
+        """
         roles = {
                     'User': [Permission.CREATE_JOB],
                     'Administrator': [Permission.ADMIN,
@@ -66,6 +97,9 @@ class Role(db.Model):
 
 
 class User(UserMixin, db.Model):
+    """
+    Model for Users that are registered to Opaque.
+    """
     __tablename__ = 'users'
     id = db.Column(db.Integer, primary_key=True)
     email = db.Column(db.String(64), unique=True, index=True)
@@ -75,6 +109,9 @@ class User(UserMixin, db.Model):
     confirmed = db.Column(db.Boolean, default=False)
 
     def __repr__(self):
+        """
+        String representation of the User. For human readability.
+        """
         return '<User %r>' % self.username
 
     def __init__(self, **kwargs):
@@ -86,14 +123,23 @@ class User(UserMixin, db.Model):
                 self.role = Role.query.filter_by(default=True).first()
 
     def generate_confirmation_token(self, expiration=3600):
+        """
+        Generates a confirmation token for user confirmation via email.
+        """
         s = Serializer(current_app.config['SECRET_KEY'], expiration)
         return s.dumps({'confirm': self.id}).decode('utf-8')
 
     def generate_reset_token(self, expiration=3600):
+        """
+        Generates a reset token for password reset via email.
+        """
         s = Serializer(current_app.config['SECRET_KEY'], expiration)
         return s.dumps({'reset': self.id}).decode('utf-8')
 
     def confirm(self, token):
+        """
+        Confirms User if the given token is valid and not expired.
+        """
         s = Serializer(current_app.config['SECRET_KEY'])
         try:
             data = s.loads(token.encode('utf-8'))
@@ -107,6 +153,9 @@ class User(UserMixin, db.Model):
 
     @staticmethod
     def reset_password(token, new_password):
+        """
+        Resets password for User if the given token is valid and not expired.
+        """
         s = Serializer(current_app.config['SECRET_KEY'])
         try:
             data = s.loads(token.encode('utf-8'))
@@ -131,13 +180,23 @@ class User(UserMixin, db.Model):
         return check_password_hash(self.password_hash, password)
 
     def can(self, perm):
+        """
+        Checks if a User with its current role can doe something. Checks if the
+        associated role actually has the needed Permission.
+        """
         return self.role is not None and self.role.has_permission(perm)
 
     def is_administrator(self):
+        """
+        Checks if User has Admin permissions.
+        """
         return self.can(Permission.ADMIN)
 
 
 class AnonymousUser(AnonymousUserMixin):
+    """
+    Model replaces the default AnonymousUser.
+    """
     def can(self, permissions):
         return False