Update licensing and copyright

.gitignore

@@ -112,3 +112,4 @@ dmypy.json
 
 # database files (may contain sensitive student info)
 *.db
+.vscode

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2018 Abdulkadir Furkan Şanlı
+   Copyright 2018-2019 Abdulkadir Furkan Şanlı
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,64 +1,56 @@
 # ib-clearance
 
-ib-clearance is a program which helps schools manage the entrance and exiting of their IB students. Due to the unique nature of IB students' timetables, the program helps check individual timetables and give clearance to students who have finished for the day.
+ib-clearance is a program which helps schools manage the entrance and exiting of their IB Diploma Program students. Due to the unique nature of IB students' timetables, the program helps to automatically check individual timetables and give clearance to students who have finished for the day.
 
-### Building
+## Building & running
 
-The code is currently designed to run on Python 3.6.*.
+The code is currently designed to run on Python 3.6.* and requires the [`getch`](https://pypi.org/project/getch/) module on platforms other than Windows.
 
-I recommend building executables with `pyinstaller` with `pyinstaller --onefile ib-clearance.py`.
+Binaries can be built using [`pyinstaller`](https://pypi.org/project/PyInstaller/): `pyinstaller --onefile ib-clearance.py`
 
-### Lesson IDs
+## Database specification
 
-Equivalents of lesson names for use in class databases.
+The program requires a SQLite database `database.db` in the working directory, containing data for all school classes.
 
-- Academic Writing
+`database.db` must contain:
-    - 'aw'
+
-- Biology
+| Table       | Description                                                  |
-    - 'bi'
+| ----------- | ------------------------------------------------------------ |
-- Business Management
+| `students`  | Contains students' names, ID numbers and subject preferences |
-    - 'bm'
+| `timetable` | Timetable information (lessons)                              |
-- Chemistry
+
-    - 'ch'
+### `students`
-- Computer Science
+
-    - 'cs'
+| Column          | Data type | Description                                     |
-- Economics
+| --------------- | --------- | ----------------------------------------------- |
-    - 'ec'
+| `id`            | `INTEGER` | Student ID number used in program               |
-- English A
+| `student_class` | `INTEGER` | IB class number (e.g. `1`, `2`)                 |
-    - 'ena'
+| `name`          | `TEXT`    | Full name of student                            |
-- English B
+| `g1`            | `TEXT`    | Group 1 subject ID                              |
-    - 'enb'
+| `g2`            | `TEXT`    | Group 2 subject ID                              |
-- French
+| `g3`            | `TEXT`    | Group 3 subject ID                              |
-    - 'fr'
+| `g4`            | `TEXT`    | Group 4 subject ID                              |
-- Geography
+| `g5`            | `TEXT`    | Group 5 subject ID                              |
-    - 'ge'
+| `g6`            | `TEXT`    | Group 6 subject ID                              |
-- German
+| `other`         | `TEXT`    | ID(s) of other class(es) taken, space seperated |
-    - 'de'
+
-- Guidance
+### `timetable`
-    - 'gu'
+
-- Mathematical Studies
+| Column         | Data type | Description                                   |
-    - 'mst'
+| -------------- | --------- | --------------------------------------------- |
-- Mathematics HL
+| `lesson_class` | `INTEGER` | IB class which takes lesson (e.g. `1`)        |
-    - 'mhl'
+| `day`          | `TEXT`    | Day of the week (e.g. `monday`)               |
-- Mathematics SL
+| `end_time`     | `TEXT`    | Ending time of lesson (e.g. `09:55`, `13:05`) |
-    - 'msl'
+| `lesson_id`    | `TEXT`    | Subject ID of the lesson (e.g. `tok`)         |
-- Polish A
+
-    - 'pl'
+#### Subject IDs
-- Psychology
+
-    - 'ps'
+Subject IDs may be anything, as long as consistency is maintained throughout the tables.
-- Self-Taught Language A
-    - 'st'
-- Spanish
-    - 'es'
-- Theory of Knowledge
-    - 'tok'
-- Turkish A
-    - 'tr'
-- Visual Arts
-    - 'va'
 
 ## License
 
-Copyright (C) 2018  Abdulkadir Furkan Şanlı
-
 ib-clearance is made available under the Apache License 2.0.
+
+Copyright 2018-2019 Abdulkadir Furkan Şanlı
+
+Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.  This file is offered as-is, without any warranty.

TODO.md

@@ -0,0 +1,13 @@
+To-Do List
+==========
+
+## v0.2
+- [x] Error handling (when entering invalid data types)
+- [x] Make database contain data for all classes
+- [x] Flexible mandatory subjects
+- [x] Make script functional (sorta)
+- [x] Document the damn thing
+
+## v0.3
+- [ ] Usability and GUI
+- [ ] Timetable editor (add & remove lessons, view timetable)

ib-clearance.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright 2018 Abdulkadir Furkan Şanlı
+# Copyright 2018-2019 Abdulkadir Furkan Şanlı
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,54 +14,72 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 import sqlite3
 import time
+from os import name
+from sys import exit
+
+# Windows has standard library getch, use that.
+if name == "nt":
+    from msvcrt import getch
+else:
+    from getch import getch
 
 
 def connect_database(file):
-    """
+    """Get database connection object.
-    Create and return Connection object
+
-    :param file: database file
+    Connect to SQLite database and return a connection object.
+
+    :param file: SQLite database
     """
     conn = sqlite3.connect(file)
     return conn
 
 
-def get_lower_weekday():
+def get_data(conn):
-    """
+    """Get student data.
-    Return current weekday's name as lowercase string
-    """
-    day = time.strftime("%A")
-    lower_day = day.lower()
-    return lower_day
 
+    Request student ID.  Return tuple (id, class, other) with valid
+    student ID, corresponding class number and "other" subject IDs.
 
-def check_id(conn, id):
-    """
-    Return True if existing ID, False is not.
     :param conn: Connection object
-    :param id: ID of student, int
     """
+    try:
+        id = int(input("\nPlease enter student ID: "))
+
         cur = conn.cursor()
-    cur.execute("SELECT id FROM students")
+        cur.execute("""
-    ids = cur.fetchall()
+            SELECT id, student_class, other
+            FROM students
+            WHERE id = ?
+            """, (id,))
+        data = cur.fetchone()
 
-    for x in ids:
+        if data is not None:
-        if id == x[0]:
+            data = list(data)  # SQLite returns tuples.
-            return True
+            data[2] = data[2].split()
         else:
-        return False
+            raise ValueError
+
+        return data
+    except ValueError:
+        print("\nInvalid ID, try again.")
+        return get_data(conn)
 
 
-def select_final_time(conn, day, id):
+def select_final_time(conn, day, data):
-    """
+    """Select student finishing time.
-    Return ending time of final lesson student must attend, or None.
+
+    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 id: ID of student, int
+    :param data: student data tuple returned by get_data
     """
     cur = conn.cursor()
+    # Select finishing time of IB lessons.
     cur.execute("""
         SELECT end_time
         FROM timetable
@@ -71,55 +89,110 @@ def select_final_time(conn, day, id):
                 OR g4 = lesson_id
                 OR g5 = lesson_id
                 OR g6 = lesson_id
-                OR lesson_id = 'gu'
+        WHERE id = ?
-                OR lesson_id = 'to'
+            AND day = ?
-        WHERE id = ? AND day = ?
+            AND lesson_class = ?
         ORDER BY end_time DESC
         LIMIT 1
-        """, (id, day))
+        """, (data[0], day, data[1]))  # Queries return None if no matches.
-    finish = cur.fetchone()
+    ib_finish = cur.fetchone()
-    if str(type(finish)) == "<class 'tuple'>":
+    if ib_finish is not None:
-        return finish[0]
+        ib_finish = parse_time_string(ib_finish[0])
+
+    # Select finishing time of other lessons.
+    others = []
+    for subject in data[2]:
+        cur.execute("""
+            SELECT end_time
+            FROM timetable
+                INNER JOIN students ON ? = lesson_id
+            WHERE id = ?
+                AND day = ?
+                AND lesson_class = ?
+            ORDER BY end_time DESC
+            LIMIT 1
+            """, (subject, data[0], day, data[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:
+        others_finish = max(others)
+
+    if ib_finish is not None and others_finish is not None:
+        if ib_finish > others_finish:
+            finish = ib_finish
+        else:
+            finish = others_finish
+    elif ib_finish is not None:
+        finish = ib_finish
+    elif others_finish is not None:
+        finish = others_finish
+    else:
+        finish = None
+
     return finish
 
 
 def parse_time_string(timestring):
-    """
+    """Convert time string to tuple.
-    Parse given 24h time string of format "HH:MM" into time_struct
+
+    Parses given 24h time string of format "HH:MM" into the struct_time
+    object provided by library time.
+
     :param timestring: time string "HH:MM"
     """
-    timestruct = time.strptime(timestring, "%H:%M")
+    structtime = time.strptime(timestring, "%H:%M")
-    return timestruct
+    return structtime
+
+
+def clear(finish_time):
+    """Return clearance message.
+
+    Compare the current time with finishing time and return relevant
+    clearance message.
+
+    :param finish_time: finishing time, struct_time object
+    """
+    current_time = parse_time_string(time.strftime("%H:%M"))
+    if finish_time == None:
+        message = "Student has no lessons today, clear to leave."
+    elif finish_time < current_time:
+        message = "Student has finished for today, clear to leave."
+    else:
+        message = "Student still has lessons, clearance not granted."
+    return message
+
+
+def exit_sequence():
+    """Initiate exit sequence.
+
+    Asks user to enter character, and exits program if X is pressed.
+    """
+    print("Press X to exit.")
+    key = getch()
+    if isinstance(key, bytes):
+        # msvcrt.getch returns type bytes, decode into str.
+        key = key.decode()
+    if key.upper() == "X":
+        exit()
 
 
 def main():
-    db = input(
+    print("ib-clearance")
-        "Please enter name of database (located in the same folder as the program): ")
+    print("Copyright 2018-2019 Abdulkadir Furkan Şanlı")
 
-    y = "y"
+    conn = connect_database("database.db")
-    while y == "y":
-        conn = connect_database(db)
-        day = get_lower_weekday()
-        id = int(input("Please input the student ID number: "))
 
-        if check_id(conn, id):
+    while True:
-            raw = select_final_time(conn, day, id)
+        student_data = get_data(conn)
-            final = parse_time_string(raw) if raw != None else None
+        day = time.strftime("%A").lower()
+        finish_time = select_final_time(conn, day, student_data)
 
-            if final != None:
+        print("\n" + clear(finish_time) + "\n")
-                current_time = parse_time_string(time.strftime("%H:%M"))
 
-                if current_time > final:
+        exit_sequence()
-                    print("Clear to leave.")
-                else:
-                    print("Student does not have clearance.")
-            elif final == None:
-                print("Clear to leave.")
-        else:
-            print("Student does not exist in the database. Please try again.")
-
-        y = input("Press y and enter to run again.")
 
 
 if __name__ == "__main__":