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!
The Role class instatiates Role model. This is used for the creation of users such as a general user and an administrator
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
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 :)
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
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).
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
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
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
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
verify_password well...verifies a provided user plaintext password
against the password_hash in the user record. Uses the
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
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
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.
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.
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.
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