Add docstrings for the project.

6 files changed, 158 insertions, 4 deletions

diff --git a/account/views.py b/account/views.py
index 5fbb14a..4348842 100644
--- a/account/views.py
+++ b/account/views.py
@@ -12,6 +12,10 @@ from datetime import datetime
 # Create your views here.
 
 def index(req):
+    """ Renders the user web interface.
+        Input: s:request object.
+        Output: HttpResponse object returned by render() function for the given interface.
+    """
     if req.user.is_authenticated():
         return redirect(home)
     return render(req, "account/index.html")
@@ -20,6 +24,16 @@ def new():
     pass
 
 def create(req):
+    """ Creates a new user account.
+        Generate user alerts if:
+            Any of the fields is not entered.
+            Entered email-id is invalid.
+            Entered username or email-id is existing.
+            Alloted board id is -1, because of no boards being available online.
+            If the user credentials cross all checks and hence a successful account is created.
+        Input: s:request object.
+        Output: HttpResponseRedirect object returned by redirect() function.
+    """
     error = []
 
     name        = req.POST.get("name").strip()
@@ -85,6 +99,13 @@ def create(req):
     #     return redirect(index)
 
 def confirm(req, token):
+    """ Confirms a user's email-id.
+        Generate user alerts if:
+            User enters invalid confirmation token.
+            User's email-id gets confirmed.
+        Input: s:request object.
+        Output: HttpResponseRedirect object returned by redirect() function.
+    """
     try:
         email = simple_encrypt.decrypt(token)
         account = Account.objects.get(email=email)
@@ -97,6 +118,13 @@ def confirm(req, token):
     return redirect(index)
 
 def login(req):
+    """ Logs in an existing user.
+        Generate user alerts if:
+            Either of username or password do not match.
+            Account email-id is not activated yet.
+        Input: s:request object.
+        Output: HttpResponseRedirect object returned by redirect() function.
+    """
     username = req.POST.get('username')
     password = req.POST.get('password')
     #user = authenticate(username=username, password=password)
@@ -107,7 +135,7 @@ def login(req):
         messages.add_message(req, messages.ERROR, "Invalid username or password.")
         return redirect(index)
         
-    is_authenticated = user.check_password(password)
+    is_authenticated = user.check_password(password)+
 
     if is_authenticated:
         if user.is_active:
@@ -121,9 +149,17 @@ def login(req):
         return redirect(index)
 
 def logout(req):
+    """ Logs out a logged-in user.
+        Input: s:request object.
+        Output: HttpResponseRedirect object returned by redirect() function.
+    """
     LOGOUT(req)
     return redirect(index)
 
 @login_required(redirect_field_name=None)
 def home(req):
+    """ Redirects to the home page.
+        Input: s:request object.
+        Output: HttpResponse object returned by render() function for the given interface.
+    """
     return render(req, "account/home.html")
diff --git a/experiment/views.py b/experiment/views.py
index 3575094..c2424a1 100644
--- a/experiment/views.py
+++ b/experiment/views.py
@@ -10,10 +10,18 @@ from sbhs_server import settings
 # Create your views here.
 # 
 def check_connection(req):
+    """ Checks if the connection exists or not.
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     return HttpResponse("TESTOK")
 
 @csrf_exempt
 def initial_login(req):
+    """ Logs in an user for conducting the experiment on the specified board.
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     username = req.POST.get("username")
     rpi_ip = ''
     try:
@@ -28,6 +36,13 @@ def initial_login(req):
 # @login_required(redirect_field_name=None)
 @csrf_exempt
 def experiment(req):
+    """ Manages an ongoing experiment.
+        Alert the user when:
+            The slot has ended.
+            The slot wasn't booked.
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     try:
         server_start_ts = int(time.time() * 1000)
         from sbhs_server.settings import boards
@@ -86,6 +101,10 @@ def experiment(req):
 
 @csrf_exempt
 def reset(req):
+    """ Resets an experiment.
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     try:
         from sbhs_server.settings import boards
         user = req.user
@@ -110,10 +129,18 @@ def reset(req):
     return HttpResponse("")
 
 def client_version(req):
+    """ Input: req:request object.
+        Output: HttpResponse object.
+    """
     return HttpResponse("3")
 
 @login_required(redirect_field_name=None)
+    
 def logs(req):
+    """ Renders experimental log files to the user interface.
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     bookings         = Booking.objects.only("id").filter(account__id=req.user.id)
     deleted_bookings = Booking.trash.only("id").filter(account__id=req.user.id)
     bookings = list(bookings) + list(deleted_bookings)
@@ -125,6 +152,10 @@ def logs(req):
 
 @login_required(redirect_field_name=None)
 def download_log(req, experiment_id, fn):
+    """ Downloads the experimental log file.
+        Input: req: request object, experiment_id: experimental id, fn: filename.
+        Output: HttpResponse object
+    """
     try:
         experiment_data = Experiment.objects.select_related("booking", "booking__account").get(id=experiment_id)
         assert req.user.id == experiment_data.booking.account.id
@@ -136,6 +167,9 @@ def download_log(req, experiment_id, fn):
         return HttpResponse("Requested log file doesn't exist.")
 
 def log_data(sbhs, mid, experiment_id, heat=None, fan=None, temp=None):
+    """ Update the experimental log file.
+        Input: sbhs:board object, mid: machine-id of the SBHS, experiment_id: experimental id, heat: heater value, fan: fan value, temp: temperature.
+    """
     if heat is None:
         heat = sbhs.getHeat()
     if fan is None:
@@ -151,6 +185,10 @@ def log_data(sbhs, mid, experiment_id, heat=None, fan=None, temp=None):
         experiment_loghandler.write(data) 
 
 def validate_log_file(req):
+    """ Validates the experimental log file.
+        Input: req: request object.
+        Output: HttpResponse object.
+    """
     import hashlib
     data = req.POST.get("data")
     data = data.strip().split("\n")
diff --git a/maintenance/health_monitor.py b/maintenance/health_monitor.py
index 87946b2..95b7a8e 100644
--- a/maintenance/health_monitor.py
+++ b/maintenance/health_monitor.py
@@ -3,17 +3,25 @@ from time import sleep
 from sbhs_server.credentials import ADMIN_EMAIL
 from sbhs_server.helpers import mailer 
 
+#Setting default device parameters
 MAX_PORTS = 256
 MIN_TEMP = 10
 MAX_TEMP = 70
 
 def write_to_port(s, com, arg):
+    """ Sets fan/heater value based on input command code and entered parameter.
+        Inputs: s:serial port object, com: number that distinguishes commands, arg: value to be set for that parameter.
+    """
     s.write(chr(int(com)))
     sleep(0.5)
     s.write(chr(int(arg)))
     sleep(0.5)
 
 def read_from_port(s, com):
+    """ Reads mid/temperature based on input command code.
+        Inputs: s:serial port object, com: number that distinguishes commands.
+        Output: result: temperature if com=255, mid if com=252, and -1 in case of invalid command code.
+    """
     s.write(chr(int(com)))
     sleep(0.5)
     if com == 255:
@@ -26,6 +34,10 @@ def read_from_port(s, com):
     return result
 
 def create_message(check_mids, defective_ports):
+    """ Creates message to be sent to the admin for monitoring ports and devices.
+        Inputs: check_mids: list of mids for devices to be checked, defective_ports: list of defective ports.
+        Output: msg: message with list of mids of devices to be checked and defective ports that is to be mailed to the admin.
+    """
     msg = ''
     if len(check_mids) != 0:
         msg += 'Please check the following machine ids :\n'
@@ -38,6 +50,18 @@ def create_message(check_mids, defective_ports):
     return msg
 
 def main():
+    """ Attempts to open serial port object on existing USB paths, and then read the mid of the device using read_from port() function.
+        Sets fan and heater value to 100 and 0 respectively using write_to_port() function,
+        and reads the temperature of the same device using read_from port() function.
+        if the serial port opens but the mid returned is less than zero
+            append it to the list of defective ports.
+        if an exception occurs while reading or writing but the port opens successfully and returns a valid mid
+            then add it to the list of offline mids.
+        if the ports opens successfully, returns a valid mid and temperature, and encounters no exceptions
+            then add it to the list of present_online_mids
+        The difference between the sets of online_mids and present_online_mids gives the list of mids of devices to be checked.
+        Calls the create_message function and mails the returned message to the admin.
+    """
     present_online_mids, offline_mids, defective_ports = [], [], []
     for i in range(0,MAX_PORTS):
         path = '/dev/ttyUSB' + str(i)
diff --git a/sbhs_server/settings.py b/sbhs_server/settings.py
index 4e9873f..ba6a19e 100644
--- a/sbhs_server/settings.py
+++ b/sbhs_server/settings.py
@@ -32,6 +32,8 @@ DEBUG = not is_production
 
 TEMPLATE_DEBUG = not is_production
 
+#IPs allowed to host the server
+
 ALLOWED_HOSTS = [
     "localhost",
     "127.0.0.1",
diff --git a/slot/views.py b/slot/views.py
index 5d22ac2..74b6a65 100644
--- a/slot/views.py
+++ b/slot/views.py
@@ -4,10 +4,16 @@ from django.contrib import messages
 from sbhs_server.tables.models import Account, Slot, Booking
 import datetime
 
+#Defines an upper limit for the number of slots that can be booked by an user in advance.
 LIMIT = 2
 
 @login_required(redirect_field_name=None)
 def new(req):
+    """ Shows currently available slots.
+    
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     cur_slots = Slot.current_slots(req.user.board.mid)
     all_slots = Slot.get_free_slots(req.user.board.mid)
     date = (datetime.datetime.now()).strftime("%Y-%m-%d")
@@ -15,12 +21,28 @@ def new(req):
 
 @login_required(redirect_field_name=None)
 def show(req, date_string):
+    """ Shows all available slots.
+
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     date = datetime.datetime.strptime(date_string, "%Y-%m-%d")
     all_slots = Slot.get_free_slots_on(date, req.user.board.mid)
     return render(req, "slot/show.html", {"all_slots": all_slots})
 
 @login_required(redirect_field_name=None)
 def create(req):
+    """ Books a new slot for the user.
+
+        Shows user alters if:
+            Slot is booked succesfully.
+            User exceeds the limit of number of slots that can be booked in advance for a day.
+            User attmpts to book two consecutive slots in a day in advance.
+            Requested slot is already booked by another user.
+
+        Input: req:request object.
+        Output: HttpResponseRedirect object.
+    """
     slot = Slot.objects.get(id=req.POST.get("slot"))
     date_string = req.POST.get("date")
     date = datetime.date.today() if date_string == "CURRENT" else datetime.datetime.strptime(date_string, "%Y-%m-%d")
@@ -54,6 +76,11 @@ def create(req):
 
 @login_required(redirect_field_name=None)
 def index(req):
+    """ Shows indices of booked slots.
+
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     bookings = req.user.booking_set.select_related("slot").filter(trashed_at__isnull=True).order_by("booking_date")
 
     return render(req, "slot/index.html", {"bookings": reversed(bookings),
@@ -62,6 +89,16 @@ def index(req):
 
 @login_required(redirect_field_name=None)
 def delete(req, booking_id):
+    """ Deletes a previously booked slot.
+
+        Shows user alerts if:
+            Booked slot is deleted succesfully.
+            Slot cannot be deleted as it doesn't exist.
+            Slot cannot be deleted as it has expired.
+
+        Input: req:request object, booking_id: slot booking id.
+        Output: HttpResponseRedirect object.
+    """
     try:
         booking = Booking.objects.select_related("slot").get(id=booking_id)
         assert booking.account_id == req.user.id
diff --git a/webcam/views.py b/webcam/views.py
index 18f82f5..f6a1a81 100644
--- a/webcam/views.py
+++ b/webcam/views.py
@@ -5,10 +5,13 @@ from sbhs_server import settings
 from django.http import HttpResponse
 from myadmin.views import checkadmin
 from sbhs_server.tables.models import Board
-# Create your views here.
-# 
+
 
 def load_image(mid):
+    """ Displays the image of the SBHS onto the user screen.
+    
+        Input: mid: machine-id of the concerned SBHS.
+    """
 # for images on server 15, it will gstream the photos on reload
     if int(mid) in range(8,17):
     	command = "streamer -q -f jpeg -c /dev/video" + str(mid)
@@ -22,12 +25,21 @@ def load_image(mid):
         command = "curl -s %s > %s/image%d.jpeg" % (get_image_link, str(settings.WEBCAM_DIR), int(mid))
         os.system(command)
 def reload(req, mid):
-
+    """ Refreshes the image of the SBHS
+    
+        Input: req:request object, mid: machine-id of the concerned SBHS.
+        Output: HttpResponse object.
+    """
     load_image(mid)
     return HttpResponse("")
 
 @login_required(redirect_field_name=None)
 def show_video(req):
+    """ Shows the video of the SBHS.
+    
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     board = req.user.board
 
     image_link = board.image_link()
@@ -40,6 +52,11 @@ def show_video(req):
 
 @login_required(redirect_field_name=None)
 def show_video_to_admin(req, mid):
+    """ Shows the video of the SBHS to the admin.
+    
+        Input: req:request object.
+        Output: HttpResponse object.
+    """
     checkadmin(req)
     board = Board.objects.get(mid=int(mid))
     image_link = board.image_link()