From 2d6597988c27daea54310aa26be6661ed9dc16f6 Mon Sep 17 00:00:00 2001
From: coolneng <akasroua@gmail.com>
Date: Wed, 25 Nov 2020 13:44:07 +0100
Subject: [PATCH] Document notifier and crud modules

---
 app/notifier.py  | 16 +++++++++++++---
 database/crud.py | 26 +++++++++++++++++++++-----
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/app/notifier.py b/app/notifier.py
index 848e27e..7128107 100644
--- a/app/notifier.py
+++ b/app/notifier.py
@@ -1,18 +1,25 @@
 from email.message import EmailMessage
 from secrets import token_hex
 from smtplib import SMTP_SSL
+from typing import Tuple
 
 from constants import DOMAIN, PASSWORD, USERNAME
 from database.crud import save_attribute
 
 
-def initialize_smtp(domain, username, password):
+def initialize_smtp(domain, username, password) -> SMTP_SSL:
+    """
+    Creates the SMTP connection to the mail server
+    """
     server = SMTP_SSL(domain)
     server.login(username, password)
     return server
 
 
-def format_message(sender, recipient):
+def format_message(sender, recipient) -> Tuple[EmailMessage, str]:
+    """
+    Creates the email message and formats it accordingly
+    """
     code = token_hex(4)
     body = "La clave es {}. Envíele esta clave al bot.".format()
     message = EmailMessage()
@@ -23,7 +30,10 @@ def format_message(sender, recipient):
     return message, code
 
 
-def send_mail(recipient):
+def send_mail(recipient) -> None:
+    """
+    Sends an email to the specified recipient
+    """
     server = initialize_smtp(domain=DOMAIN, username=USERNAME, password=PASSWORD)
     message, code = format_message(sender=USERNAME, recipient=recipient)
     save_attribute(attribute="codigo", data=code)
diff --git a/database/crud.py b/database/crud.py
index 7ce31c1..3b9e9e1 100644
--- a/database/crud.py
+++ b/database/crud.py
@@ -1,4 +1,5 @@
 from sqlalchemy import or_
+from sqlalchemy.orm import Query
 
 from database import SessionLocal, engine, models
 from database.models import Users
@@ -6,20 +7,29 @@ from database.models import Users
 db = SessionLocal()
 
 
-def search_database(id):
+def search_database(id) -> Query:
+    """
+    Returns the user associated with the id argument
+    """
     return db.query(Users).filter(
         or_(Users.correo_institucional == id, Users.numero_de_documento == id)
     )
 
 
-def insert_data(data):
+def insert_data(data) -> None:
+    """
+    Inserts a new user into the database
+    """
     item = Users(**data)
     db.add(item)
     db.commit()
     db.refresh(item)
 
 
-def create_database(data):
+def create_database(data) -> None:
+    """
+    Creates the SQL database from scratch and populates it
+    """
     models.Base.metadata.create_all(bind=engine)
     existing_row = search_database(data["correo_institucional"])
     if existing_row:
@@ -27,14 +37,20 @@ def create_database(data):
     insert_data(data)
 
 
-def save_attribute(attribute, data):
+def save_attribute(attribute, data) -> None:
+    """
+    Updates the attribute value with the content of data
+    """
     key = eval("Users." + attribute)
     db.query(Users).filter(
         or_(Users.correo_institucional == id, Users.numero_de_documento == id)
     ).update({key: data})
 
 
-def verify_code(id, code):
+def verify_code(id, code) -> bool:
+    """
+    Verifies that two-factor authentification code matches the database record
+    """
     db_record = search_database(id=id)
     valid_code = code == db_record
     if valid_code: