ed-api-client 0.1.0__py3-none-any.whl

ed_api_client/__init__.py

@@ -0,0 +1,9 @@
+from ed_api_client.slides import *
+from ed_api_client.users import *
+from ed_api_client.challenges import *
+from ed_api_client.quizzes import *
+from ed_api_client.assignments import *
+from ed_api_client.workspaces import *
+from ed_api_client.websockets import *
+from ed_api_client.client import *
+from ed_api_client.canvas import *

ed_api_client/assignments.py

@@ -0,0 +1,241 @@
+from dataclasses import dataclass, field
+from typing import List, Dict, Set
+import datetime
+import math
+
+from ed_api_client import Slide, ChallengeResult, User, QuizResult, Quiz
+from ed_api_client.challenges import ChallengeMarker, MarkType, Challenge
+
+
+@dataclass
+class Assignment:
+    """
+    An assignment against which students are graded
+
+    Attributes
+    ----------
+    name : int
+        The name of the assignment.
+    marks : int
+        The total available marks for this assignment
+    maxScore : int
+        The maximum score that users might achieve on this assignment. This depends on the gradeType:
+            For BY_CHALLENGE this should be the number of challenges.
+            For BY_TESTCASE this should be the number of test cases accross all challenges.
+            For BY_TESTCASE_SCORE this should be the sum of all scores for all test cases across all challenges
+    gradeType: GradeType
+        The approach used for calculating grades
+    deadline: datetime
+        The default deadline beyond which submissions will be penalised.
+    lessonIds: Set[int]
+        The ids of all lessons involved in this assignment (note this is populated automatically as slides are added)
+    slideIds: Set[int]
+        The ids of all slides involved in this assignment (note this is populated automatically as slides are added)
+    challengeIds: List[int]
+        The ids of all challenges involved in this assignment (note this is populated automatically as slides are added)
+    challengeNames: List[str]
+        The names of all challenges involved in this assignment (note this is populated automatically as slides are added)
+    extensionsByStudentId: Dict[int,datetime]
+        Associates ids of students with deadlines that have been given to them (i.e. as extensions)
+
+    Methods
+    ----------
+    add_slide (slide:Slide)
+        Adds a slide (usually a code challenge) to this assignment
+    add_extension (student: User, deadline:datetime)
+        Provides the given student with an extension, until the given deadline
+    get_deadline (student: Student) -> datetime
+        Returns the deadline for the given student
+    get_canvas_col ( ) -> str
+        Returns the name of the column that would match this assignment in an gradebook exported from canvas.
+
+    """
+
+    name: str
+    maxMarks: int
+    marker: ChallengeMarker
+    deadline: datetime.datetime
+    challenges: List[Challenge] = field(default_factory=list)
+    quizzes: List[Quiz] = field(default_factory=list)
+    extensionsByStudentId: Dict[int, datetime.datetime] = field(default_factory=dict)
+    dailyPenalty: float = 0.05
+
+    def add_challenge_slide(self, slide: Slide):
+
+        if slide.challengeId is None:
+            raise ValueError("This slide is not a code challenge")
+
+        self.challenges.append(Challenge(slide.challengeId, slide.id, slide.title))
+
+    def add_quiz_slide(self, slide: Slide, questions: list):
+
+        self.quizzes.append(Quiz(slide.id, slide.title, questions))
+
+    def add_multichoice_solution(self, questionId: int, solution: Set[int]):
+
+        for quiz in self.quizzes:
+
+            if quiz.add_multichoice_solution(questionId, solution):
+                return
+
+        print(f"could not locate multichoice question {questionId}")
+
+    def add_parsons_solution(self, questionId: int, solution: str):
+
+        for quiz in self.quizzes:
+
+            if quiz.add_parsons_solution(questionId, solution):
+                return
+
+        print(f"could not locate parsons question {questionId}")
+
+    def add_extension(self, student, deadline):
+        self.extensionsByStudentId[student.id] = deadline
+
+    def add_extensions(self, students, deadline):
+        for student in students:
+            self.extensionsByStudentId[student.id] = deadline
+
+    def get_deadline(self, student):
+        if student.id in self.extensionsByStudentId:
+            return self.extensionsByStudentId[student.id]
+
+        return self.deadline
+
+    def get_max_score(self):
+        maxScore = 0
+        for quiz in self.quizzes:
+            maxScore = maxScore + quiz.getMaxScore()
+
+        if self.marker.markType == MarkType.BY_CHALLENGE:
+            maxScore = maxScore + (
+                len(self.challenges) * self.marker.pointsPerChallenge
+            )
+        else:
+            maxScore = maxScore + self.marker.maxTestCaseScore
+
+        return maxScore
+
+    def get_canvas_col(self):
+        return "{} ({})".format(self.name, self.id)
+
+
+@dataclass
+class AssignmentResult:
+    """
+    Records the results of a student for an assignment.
+
+    Marks for the assignment include a 10% penalty per day if work is received late.
+    Late submissions are only considered if they improve the student's marks after the late penalty is applied.
+
+    Attributes
+    ----------
+    studentId : int
+        The id of the student
+    completed : bool
+        True if the student successfully completed this assignment, otherwise false.
+    score : int
+        The score recieved by this student
+    mark : float
+        The mark recieved by this student.
+    daysLate: int
+        The number of days past the deadline that work was received and considered.
+    challengeResults: Dict[int, ChallengeResult]
+        Associates ids of challenges with their individual results
+
+    Methods
+    ----------
+    add (submission:Submission,  student:Student, assignment:Assignment)
+        Updates this result based on a single submission
+    finalize (assignment:Assignment, crawler: EdCrawler)
+        To be called after all submissions have been added.
+    """
+
+    studentId: int
+    score: int = None
+    mark: float = None
+    daysLate: int = None
+    penalty: float = None
+    challengeResults: Dict[int, ChallengeResult] = field(default_factory=dict)
+    quizResults: Dict[int, QuizResult] = field(default_factory=dict)
+
+    def add_challenge_submission(self, submission, student, assignment):
+
+        deadline = assignment.get_deadline(student)
+
+        daysLate = 0
+        if submission.markedAt > deadline:
+            diff = submission.markedAt - deadline
+            daysLate = math.ceil(diff.total_seconds() / (60 * 60 * 24))
+
+        if submission.challengeId not in self.challengeResults:
+            self.challengeResults[submission.challengeId] = ChallengeResult()
+
+        self.challengeResults[submission.challengeId].add(submission, daysLate)
+
+    def add_quiz_result(self, quizResult: QuizResult):
+        self.quizResults[quizResult.quizId] = quizResult
+
+    def finalize(self, assignment: Assignment, crawler):
+
+        self.score = 0
+        self.mark = 0
+        self.daysLate = 0
+        self.penalty = 0
+
+        quizScore = 0
+        for quizResult in self.quizResults.values():
+            quizScore = quizScore + quizResult.score
+
+        if self.challengeResults is not None:
+            for challengeId, challenge in self.challengeResults.items():
+                challenge.finalize(assignment.marker, crawler)
+
+        dailyMarkPenalty = assignment.dailyPenalty * assignment.maxMarks
+
+        for daysLate in range(0, 6):
+            score = quizScore
+
+            for challengeId, challenge in self.challengeResults.items():
+                score = score + challenge.scoresByCalendarDaysLate[daysLate]
+
+            mark = assignment.maxMarks * (score / assignment.get_max_score())
+            penalty = daysLate * dailyMarkPenalty
+            mark = mark - penalty
+            if mark < 0:
+                mark = 0
+
+            if mark > self.mark:
+                self.score = score
+                self.mark = mark
+                self.daysLate = daysLate
+                self.penalty = penalty
+
+    def printSummary(self, student: User, assignment: Assignment):
+
+        msg = f"{student.name} got {self.mark:.1f}/{assignment.maxMarks} marks from {self.score}/{assignment.get_max_score()} points"
+
+        if self.daysLate > 0:
+            msg = f"{msg} and a penalty of {self.penalty:.1f} marks for submitting {self.daysLate} days late"
+
+        print(msg)
+
+        for quiz in assignment.quizzes:
+            quizResult = self.quizResults.get(quiz.id)
+
+            if quiz.id is None:
+                print(
+                    f"  0/{quiz.getMaxScore()} points for "
+                    + quiz.name
+                    + " due to no attempt"
+                )
+            else:
+                quizResult.print_summary(quiz)
+
+        for challenge in assignment.challenges:
+
+            challengeResult = self.challengeResults.get(challenge.id)
+            if challengeResult is None:
+                print(f"  0 points for " + challenge.name + " due to no attempt")
+            else:
+                challengeResult.print_summary(challenge, self.daysLate)

ed_api_client/canvas.py

@@ -0,0 +1,67 @@
+import csv
+from typing import Dict
+
+from ed_api_client import Assignment, Users, AssignmentResult
+
+
+class CanvasExporter:
+    def __init__(self, students: Users):
+        self.__students = students
+        self.__assignmentsByCol = {}
+        self.__resultsByCol = {}
+        self.__fieldNames = ["Student", "ID", "SIS User ID", "SIS Login ID", "Section"]
+
+    def addAssignment(
+        self,
+        assignment: Assignment,
+        columnName: str,
+        results: Dict[int, AssignmentResult],
+    ):
+
+        self.__assignmentsByCol[columnName] = assignment
+        self.__resultsByCol[columnName] = results
+        self.__fieldNames.append(columnName)
+        return self
+
+    def generateCsv(self, sourceCsv, targetCsv):
+
+        with open(sourceCsv) as input:
+            reader = csv.DictReader(input)
+
+            with open(targetCsv, "w") as output:
+                writer = csv.DictWriter(output, fieldnames=self.__fieldNames)
+                writer.writeheader()
+
+                for inputRow in reader:
+
+                    outputRow = self.handleRow(inputRow)
+
+                    if outputRow is None:
+                        continue
+
+                    writer.writerow(outputRow)
+
+    def handleRow(self, inputRow: dict):
+
+        studentEmail = inputRow.get("SIS Login ID")
+        if studentEmail is None:
+            return None
+
+        student = self.__students.getByEmail(studentEmail.lower())
+        if student is None:
+            print(f"Could not locate student {studentEmail}")
+            return None
+
+        outputRow = {}
+        for field in ["Student", "ID", "SIS User ID", "SIS Login ID", "Section"]:
+            outputRow[field] = inputRow[field]
+
+        for col, assignment in self.__assignmentsByCol.items():
+
+            results = self.__resultsByCol.get(col, {}).get(student.id)
+            if results is None:
+                outputRow[col] = 0
+            else:
+                outputRow[col] = round(results.mark, 3)
+
+        return outputRow

ed_api_client/challenges.py

@@ -0,0 +1,279 @@
+from dataclasses import dataclass, field
+from typing import List
+from enum import Enum
+import datetime
+import dateutil.parser
+
+
+@dataclass
+class Challenge:
+    id: int
+    slideId: int
+    name: str
+
+
+class MarkType(Enum):
+    """
+    Different approaches used for grading assignments
+
+    BY_CHALLENGE
+        user recieves a point for each challenge they complete
+    BY_TESTCASE
+        user recieves a point for each testcase they pass, across all challenges
+    BY_TESTCASE_SCORE
+        user recieves points for each testcase they pass, across all challenges.
+        The points recieved for each testcase is whatever score value was assigned
+        to the testcase
+    """
+
+    BY_CHALLENGE = 1
+    BY_TESTCASE = 2
+    BY_TESTCASE_SCORE = 3
+
+
+class ChallengeMarker:
+    def __init__(self, markType: MarkType):
+        self.markType = markType
+
+    def passFail(pointsPerChallenge: int = 1):
+        marker = ChallengeMarker(MarkType.BY_CHALLENGE)
+        marker.pointsPerChallenge = pointsPerChallenge
+        return marker
+
+    def perTestCase(maxTestCaseScore: int):
+        marker = ChallengeMarker(MarkType.BY_TESTCASE)
+        marker.maxTestCaseScore = maxTestCaseScore
+        return marker
+
+    def perScoredTestCase(maxTestCaseScore: int):
+        marker = ChallengeMarker(MarkType.BY_TESTCASE_SCORE)
+        marker.maxTestCaseScore = maxTestCaseScore
+        return marker
+
+
+@dataclass
+class TestCase:
+    """
+    A test case, that a user may or may not have passed
+
+    ...
+
+    Attributes
+    ----------
+    name : str
+        The  name of the test case
+    score : int
+        The points assigned to this test case
+    passed : bool
+        True if the user has passed the test case, otherwise false
+
+    """
+
+    name: str
+    score: int
+    passed: bool
+
+    def from_json(j: dict):
+        return TestCase(j["name"], j["score"], j["passed"])
+
+
+@dataclass
+class Submission:
+    """
+    A submission that a user has made towards a challenge
+
+    ...
+
+    Attributes
+    ----------
+    id : int
+        The unique id of the submission
+    userId : int
+        The id of the user who made the submission
+    challengeId : int
+        The id of the challenge this submission was made toward
+    status : bool
+        One of "passed", "failed", etc.
+    testCasesPassed: int
+        The number of test cases that this submission has passed
+    testCasesTotal: int
+        The number of test cases that this submission was tested against
+        (Note this may be smaller than the number of test cases provided by the
+        challenge, if the submission has compilation errors)
+    markedAt: datetime
+        A timestamp of when this submission was recieved and assessed
+    testcases: List[TestCase]
+        A list of details for each test case (Note this is only populated if you request
+        a specific submission from the api. It will be left unpopulated by any requests that
+        return multiple submissions)
+
+    """
+
+    id: int
+    userId: int
+    challengeId: int
+    workspaceId: str
+    status: str
+    testCasesPassed: int
+    testCasesTotal: int
+    markedAt: datetime.datetime
+    testcases: List[TestCase] = field(default_factory=list)
+
+    def from_json(j: dict):
+        submission = Submission(
+            j["id"],
+            j["user_id"],
+            j["challenge_id"],
+            j["workspace_id"],
+            j["status"],
+            j["testcase_pass_count"],
+            j["testcase_total_count"],
+            dateutil.parser.isoparse(j["marked_at"]),
+        )
+
+        for tc in j.get("result", {}).get("testcases", []):
+            submission.testcases.append(TestCase.from_json(tc))
+
+        return submission
+
+
+@dataclass
+class ChallengeResult:
+    """
+    Records the results of a student for a challenge within an assignment
+
+    Attributes
+    ----------
+    attempts : int
+        The number of attempts that the student submitted for this assignment.
+    completed : bool
+        True if the student successfully completed this challenge, otherwise false.
+    bestSubmissionByCalendarDaysLate : List[Submission]
+        The best submissions recieved by this student before and after the deadline.
+            The first element contains the best submission recieved before the deadline.
+            The second element contains the best submission recieved within one day after the deadline.
+            The third element contains the best submission recieved between one and two days after the deadline. etc.
+    scoresByCalendarDaysLate : List[int]
+        The best scores recieved by this student before and after the deadline.
+            The first element contains the best score recieved before the deadline.
+            The second element contains the best score recieved within one day after the deadline.
+            The third element contains the best score recieved between one and two days after the deadline. etc.
+    firstAttempt: datetime
+        A timestamp of this students first submission towards the assignment.
+    lastAttempt: datetime
+        A timestamp of this student's last submission towards the assignment.
+
+    Methods
+    ----------
+    add (submission:Submission,  daysLate:  int)
+        Updates this result based on a single submission
+    finalize (assignment:Assignment, crawler: EdCrawler)
+        To be called after all submissions have been added.
+    """
+    maxDaysLate: int = 7
+    attempts: int = 0
+    completed: bool = False
+    bestSubmissionByCalendarDaysLate: List[Submission] = None
+    scoresByCalendarDaysLate: List[int] = None
+    firstAttempt: datetime.datetime = None
+    lastAttempt: datetime.datetime = None
+
+    def add(self, submission: Submission, daysLate: int):
+
+        if self.bestSubmissionByCalendarDaysLate is None:
+            self.bestSubmissionByCalendarDaysLate = [None] * (self.maxDaysLate + 1)
+            self.scoresByCalendarDaysLate = [0] * (self.maxDaysLate + 1)
+
+        self.attempts += 1
+        if (
+            submission.status == "passed"
+            and submission.testCasesPassed == submission.testCasesTotal
+        ):
+            self.completed = True
+
+        if self.firstAttempt is None or self.firstAttempt > submission.markedAt:
+            self.firstAttempt = submission.markedAt
+        if self.lastAttempt is None or self.lastAttempt < submission.markedAt:
+            self.lastAttempt = submission.markedAt
+
+        if daysLate <= self.maxDaysLate:
+            if (
+                self.bestSubmissionByCalendarDaysLate[daysLate] is None
+                or self.bestSubmissionByCalendarDaysLate[daysLate].testCasesPassed
+                < submission.testCasesPassed
+            ):
+                self.bestSubmissionByCalendarDaysLate[daysLate] = submission
+
+    def finalize(self, marker: ChallengeMarker, crawler):
+        for daysLate in range(0, self.maxDaysLate+1):
+            submission = self.bestSubmissionByCalendarDaysLate[daysLate]
+            if submission is None:
+                continue
+
+            if marker.markType is MarkType.BY_CHALLENGE:
+                if (
+                    submission.status == "passed"
+                    and submission.testCasesPassed == submission.testCasesTotal
+                ):
+                    self.scoresByCalendarDaysLate[daysLate] = marker.pointsPerChallenge
+            elif marker.markType is MarkType.BY_TESTCASE:
+                self.scoresByCalendarDaysLate[daysLate] += submission.testCasesPassed
+            elif marker.markType is MarkType.BY_TESTCASE_SCORE:
+                # we have to fetch full submission details
+                s = crawler.get_submission(submission.id)
+                for test in s.testcases:
+                    # print(test)
+                    if test.passed:
+                        self.scoresByCalendarDaysLate[daysLate] = (
+                            self.scoresByCalendarDaysLate[daysLate] + test.score
+                        )
+            else:
+                raise Exception(f"Invalid marker type {marker.markType}")
+
+        # make sure scores can only go up
+        for daysLate in range(1, self.maxDaysLate+1):
+            if (
+                self.scoresByCalendarDaysLate[daysLate]
+                < self.scoresByCalendarDaysLate[daysLate - 1]
+            ):
+                self.scoresByCalendarDaysLate[daysLate] = self.scoresByCalendarDaysLate[
+                    daysLate - 1
+                ]
+
+    def __get_best_day(self, daysLate: int):
+
+        bestScore = 0
+        bestDay = 0
+
+        for day in range(0, daysLate + 1):
+            if self.scoresByCalendarDaysLate[day] > bestScore:
+                bestScore = self.scoresByCalendarDaysLate[day]
+                bestDay = day
+
+        return bestDay
+
+    def print_summary(self, challenge: Challenge, daysLate: int):
+
+        bestDay = self.__get_best_day(daysLate)
+        bestScore = self.scoresByCalendarDaysLate[bestDay]
+
+        print(
+            f"  {bestScore} points for {challenge.name} from the following submissions:"
+        )
+
+        for day in range(0, len(self.scoresByCalendarDaysLate)):
+            score = self.scoresByCalendarDaysLate[day]
+            submission = self.bestSubmissionByCalendarDaysLate[day]
+            if submission is None:
+                continue
+
+            submittedAt = submission.markedAt.strftime("%m/%d/%Y, %H:%M:%S")
+
+            msg = f"    {score} points from {submission.testCasesPassed}/{submission.testCasesTotal} test cases @ {day} days overdue ({submittedAt})"
+
+            if day < bestDay:
+                msg = f"{msg} - superseded by later submission"
+            elif day > bestDay:
+                msg = f"{msg} - ignored for not overcoming late penalty"
+
+            print(msg)