Properly document the damn thing.

ib-clearance.py

@@ -14,12 +14,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 import sqlite3
 import time
 from os import name
 
-# Import getch from msvcrt if running on Windows.
+# Windows has standard library getch, use that.
 if name == "nt":
     from msvcrt import getch
 else:
@@ -27,18 +26,23 @@ else:
 
 
 def connect_database(file):
-    """
-    Creates and returns Connection object.
-    :param file: database file
+    """Get database connection object.
+
+    Connect to SQLite database and return a connection object.
+
+    :param file: SQLite database
     """
     conn = sqlite3.connect(file)
     return conn
 
 
 def get_data(conn):
-    """
-    Requests student ID and returns integer tuple (id, class) with valid
-    student id, corresponding class no. (1 or 2) and extra subject IDs.
+    """Get student data.
+
+    Request student ID.  Return integer tuple (id, class, other) with
+    valid student ID, corresponding class number and "other" subject
+    IDs.
+
     :param conn: Connection object
     """
     try:
@@ -46,12 +50,10 @@ def get_data(conn):
 
         cur = conn.cursor()
         cur.execute("SELECT id, student_class, other FROM students")
-        ids = cur.fetchall()
+        ids = cur.fetchall()  # ids is list of tuples.
 
         for tup in ids:
-            # ids is list of tuples
             if id == tup[0]:
-                # return tuple x with valid id, class and extra class IDs
                 lis = list(tup)
                 lis[2] = lis[2].split()
                 return lis
@@ -63,13 +65,17 @@ def get_data(conn):
 
 
 def select_final_time(conn, day, stuple):
-    """
-    Returns ending time of final lesson student must attend, or None.
+    """Select student finishing time.
+
+    Returns ending time (type struct_time) of final lesson student must
+    attend on given day, or None if no lessons.
+
     :param conn: Connection object
     :param day: current weekday, lowercase str
-    :param stuple: tuple with student ID no. and class no., int
+    :param stuple: student data tuple returned by get_data
     """
     cur = conn.cursor()
+    # Select finishing time of IB lessons.
     cur.execute("""
         SELECT end_time
         FROM timetable
@@ -84,13 +90,14 @@ def select_final_time(conn, day, stuple):
             AND lesson_class = ?
         ORDER BY end_time DESC
         LIMIT 1
-        """, (stuple[0], day, stuple[1]))
+        """, (stuple[0], day, stuple[1]))  # Queries return None if no matches.
     ib_finish = cur.fetchone()
     if ib_finish is not None:
         ib_finish = parse_time_string(ib_finish[0])
 
+    # Select finishing time of other lessons.
     others = []
-    for sub in stuple[2]:
+    for subject in stuple[2]:
         cur.execute("""
             SELECT end_time
             FROM timetable
@@ -100,10 +107,10 @@ def select_final_time(conn, day, stuple):
                 AND lesson_class = ?
             ORDER BY end_time DESC
             LIMIT 1
-            """, (sub, stuple[0], day, stuple[1]))
-        other_finish = cur.fetchone()
-        if other_finish is not None:
-            others.append(parse_time_string(other_finish[0]))
+            """, (subject, stuple[0], day, stuple[1]))
+        subject_finish = cur.fetchone()
+        if subject_finish is not None:
+            others.append(parse_time_string(subject_finish[0]))
     if not others:
         others_finish = None
     else:
@@ -125,8 +132,11 @@ def select_final_time(conn, day, stuple):
 
 
 def parse_time_string(timestring):
-    """
-    Parses given 24h time string of format "HH:MM" into struct_time.
+    """Convert time string to tuple.
+
+    Parses given 24h time string of format "HH:MM" into the struct_time
+    object provided by library time.
+
     :param timestring: time string "HH:MM"
     """
     structtime = time.strptime(timestring, "%H:%M")
@@ -141,7 +151,7 @@ def main():
 
     while True:
         student_data = get_data(conn)
-        day = time.strftime("%A").lower()
+        day = time.strftime("%A").lower()  # db days are also lowercase.
         finish_time = select_final_time(conn, day, student_data)
         current_time = parse_time_string(time.strftime("%H:%M"))
 
@@ -154,13 +164,12 @@ def main():
 
         print("\nPress X key to exit, other key to run again.")
         key = getch()
-        # msvcrt.getch returns type bytes, decode into str.
         if isinstance(key, bytes):
+            # msvcrt.getch returns type bytes, decode into str.
             key = key.decode()
         if key.upper() == "X":
             break
 
 
-# Run main() if script is run standalone.
 if __name__ == "__main__":
     main()