Models

`Permission` class

GENERAL = 0x01
ADMINISTER = 0xff

Okay so here is a seemingly simple piece of code I really think is really cool! First of all we are setting up two enums here. But they are set to weird hexadecimal numbers 0x01 and 0xff. If you stick these into a hexadecimal -> decimal converter you'll find that they represent 1 and 255 respectively. But in binary they come out to 00000001 and 11111111 (8 ones). If we do a binary and (&) on these two numbers, we can actually get some unique properties from these. So if we do GENERAL & ADMINSTER, it will come out to the following

  00000001
& 11111111
----------
  00000001

We get back the exact same value as GENERAL! Similarly if we do ADMINSTER & GENERAL we get back GENERAL. This is useful for checking user roles and who is exactly who in this system. So we can create a method 'check(input, checker)' that will take an input hex to test and one to text against. We only need to do '(input & checker) == checker'. But there are some more interesting applications for this. Let us define, for example, a set of enums CAN_LIKE = 0x01, CAN_POST = 0x02, CAN_EDIT = 0x04 and CAN_REMOVE = 0x08. These are respectively in binary 00000001, 00000010, 00000100, 00001000. We can use binary OR (|) to create composite user permissions e.g. CAN_LIKE | CAN_POST | CAN_EDIT = 0x07 = 00000111 -> NEW_ROLE. We can run 'check(NEW_ROLE, CAN_LIKE)' or 'check(NEW_ROLE, CAN_POST)' or 'check(NEW_ROLE, CAN_EDIT)' and all of these will return True. For example NEW_ROLE & CAN_EDIT

  00000111
& 00000001
----------
  00000001 <- equivalent to CAN_EDIT enum

A function similar to the check described above can be found in as the 'can' method below in the User class. Moving on!

`Role` class

The Role class instatiates Role model. This is used for the creation of users such as a general user and an administrator

COLUMN DEFINITIONS:

id serves as the primary key (expects int).

name is the name of the role itself (expects unique String len 64)

index is the name of the index route for the route

default is a T/F value that determines whether a new user created has that permission or note (ref insert_roles()). This is indexed meaning that a separate table has been created with default as the first column and id as the second column. Default in this table is sorted and a query for default performs a binary search rather than a linear search (reduces search time complexity from O(N) to O(log n)

permissions contains the permissions enum (see Permissions class)

users is not a column but it sets up a database relation. This case is a one-to-many relationship in that for ONE Role record, there are MANY associated User objects. The backref param specifies a bi-directional relationship between the two tables in that there is a new property on both a given Role and User object. E.g. Role.users will refer to the User object (i.e. the user table). and User.role (role being the string specified with backref) will refer to the Role object. Lazy = dynamic specifies to return a Query object instead of actually asking the relationship to load all of its child elements upon creating the relationship. It is best practice to include lazy=dynamic upon the establishment of a relationship.

Sub-note on lazy-dynamic and backref:

Currently, lazy-dynamic will make the User collection to be loaded in as a Query object (so not everything is loaded at once). Simiarly (as mentioned above), the User object can reference the Role object by doing User.role however, this uses the default collection loading behavior (i.e. load the entire collection at once). It is fine in this case since the amount of Roles in the Role collection will be much less than the amount of entries in the User collection. However, we can specify that User.role uses the lazy-dynamic loading scheme. Simply redefine users here to

users = db.relationship('User', backref=db.backref('role',
                                      lazy='dynamic'), lazy='dynamic')

insert_roles() and SQLAlchemy Sessions

The staticmethod decorator specifies that insert_roles() must be be called with a instance of the Role class. E.g. role_obj.insert_roles() This method is fairly self-explanatory. It specifies a 'roles' dict This is then iterated through and foreach role in the 'roles' dict we check to see if it already exists (by name) in the Role object i.e. the Roles table. If not, then a new Role object is instantiated After that, the perms, index, default props are set and the the role object is now added to the db session and then committed.

A note about sqlalchemy if you haven't noticed already: All changes are added to a Session object (handled by SQLAlchemy). Unless specified otherwise, the session object has a merge operation that finds the difs between the new object (that was created and added to the session object) and the currently existing (corresponding) object existing in the table right now. Then a commit() propegates these changes into the database making as little changes as possible (i.e. every time we update a record, the record's attribute is changed 'in place' rather than being deleted and then replaced. Neat :)

`repr`

def __repr__(self):
    return '<Role \'%s\'>' % self.name

this repr method is pretty much optional, but it is helpful in that it will allow the program to pretty print the user object when you come across an error

`User` Model

The class User represents users... it extends db.Model and UserMixin. Per the flask-login documentation, the User class needs to implement is_authenticated (returns True if the user is authenticated and in turn fulfill login_required), is_active (returns True if the user has been activated i.e. confirmed by email in our case), is_anonymous (returns if a user is Anonymous i.e. is_active = is_authenticated = False, is_anonymous = True, and get_id() = None), get_id() (returns a UNICODE that has the id of the user NOT an int).

Column Descriptions:

id - primary key for the table. Id of the user. i.e. the unique identifier for the collection

confirmed - boolean val (default value = False) that is an indication of whether the user has confirmed their account via email.

first_name - ... string self explanatory

last_name - ... string self explanatory

email - string self explanatory. But we impose the uniqueness constraint on this column. It is necessary to check for this on the backend before entering an email into the table, else there will be some nasty errors produced when the user tries to add an existing email into the table.

Note: first_name, last_name, email form an index table for easy lookup. See Role for more info

password_hash is a 128 char long string containing the hashed password. As always, it is best practice to never include the plaintext password on the server. This hashed password is checked against when authenticating users.

role_id is the id of the role the user is. It is a foreign key and relates to the id's in the Role collection. By default the general user is role.id = 1, and role.id = 2 is the admin. Also note that we refer to the Role collection with 'roles' rather than the assigned backref 'role' since we are referring to an individual column.

Other User Class Variables and Methods

Note that the following methods are actually available in your Jinja templates since they are attached to the user instance.

full_name provides the full name of the user given a first and last name

can provides a really cool way of determining whether a user has given permissions. See the Permissions class for more info. is_admin is an implementation of can to test a user against admin permissions.

password This does not give a password if a user just calls the method and throws an AttributeError. However if someone chooses to set a password e.g. u = User( password = test ) the second definition of password method is run, taking the keyword arg (kwarg) as the password to then call the generate_password_hash method and set the password_hash property of the user to the generated password.

verify_password well...verifies a provided user plaintext password against the password_hash in the user record. Uses the check_password_hash method.

generate_confirmation_token returns a cryptographically signed string with encrypted user id under key confirm. This will expire in 7 days. Note that Serializer is actually TimedJSONWebSerializer when looking for documentation.

generate_changed_email_token also returns a cryptographically signed string with encrypted user id under key change_email and a encrypted new_email parameter password into the method containing the desired new email the user wants to replace the old email with.

generate_password_reset_token operates similarly to generate_ confirmation_token. Generates token for password reset

NOTE: For context, the generate_..._token methods are used to create a random string that will be later added to an email (usually) to the requesting user.

`confirm_account`

The confirm_account method will take in a token (which was presumably generated from the generate_confirmation_token method) and then return True if the provided token is valid (and can be decrypted with the SECRET_KEY and has not expired) AND the decrypted token has the key 'confirm' with the id of the requesting user. If so, it flips the 'confirmed' attribute of the requesting user to True. Will throw BadSignature of the token is invalid, will throw SignatureExpired if the token is past the expiration time.

`change_email`

The change_email method will take in a token (which was presumably generated from the generate_email_token method) and then return True True if the token is valid (see above method for explanation of 'valid') and contains the key 'change_email' with value = user id in addition to the key 'new_email' with the new email address the user wants to change their email to. Before the new_email is committed to the session, a query is performed on the User collection on all the emails to maintain the unique constraint on the email columns. Then the user's 'email' attribute is set to the 'new_email' specified in the decrypted token. will throw BadSignature if invalid token and SignatureExpired if the token is expired.

AnonymousUser

We define a custom AnonymousUser class that represents a non-logged user. It extends the AnonymousUserMixing provided by flask-loginmanager we deny all permissions and affirm that this user is not an admin

class AnonymousUser(AnonymousUserMixin):
    def can(self, _):
        return False

    def is_admin(self):
        return False

login_manager.anonymous_user = AnonymousUser

We then register our custom AnonymousUser class as the default login_manager anonymous user class

@login_manager.user_loader
def load_user(user_id):
    return User.query.get(int(user_id))

This is the default user_loader method for login_manager. This method defines how to query for a user given a user_id from the user SESSION object. It is pretty straightforward, it will query the User table and find the user with ID equal to the user_id provided in the user SESSION

Models

Permission class

Role class