From 4918d185c2c7994dd2410aada2dad51cd79d9605 Mon Sep 17 00:00:00 2001
From: Stephan Porada <sporada@uni-bielefeld.de>
Date: Thu, 11 Jul 2019 15:33:48 +0200
Subject: [PATCH] Add some docstrings to models.py
---
app/models.py | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 59 insertions(+)
diff --git a/app/models.py b/app/models.py
index 2a32cb3c..6d6474c0 100644
--- a/app/models.py
+++ b/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
--
GitLab