ed-api-client 0.1.0__tar.gz → 0.1.2__tar.gz

{ed_api_client-0.1.0 → ed_api_client-0.1.2}/PKG-INFO

@@ -1,26 +1,23 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: ed-api-client
-Version: 0.1.0
+Version: 0.1.2
 Summary: A client for interacting with the Ed LMS
 License: MIT
 Author: David Milne
 Author-email: d.n.milne@gmail.com
-Requires-Python: >=3.6,<4.0
+Requires-Python: >=3.10,<4.0
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: DateTime (>=5.1,<6.0)
-Requires-Dist: dataclasses (==0.6)
 Requires-Dist: pylcs (>=0.1.1,<0.2.0)
 Requires-Dist: python-dateutil (>=2.9.0,<3.0.0)
 Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: websocket-client (>=1.6,<2.0)
 Description-Content-Type: text/markdown
 
 # ed-api-client

{ed_api_client-0.1.0 → ed_api_client-0.1.2}/ed_api_client/__init__.py

@@ -1,9 +1,10 @@
 from ed_api_client.slides import *
 from ed_api_client.users import *
+from ed_api_client.threads 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 *
+from ed_api_client.canvas import *

ed_api_client-0.1.2/ed_api_client/assignments.py

@@ -0,0 +1,382 @@
+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 : str
+        The name of the assignment.
+    max_marks : int
+        The total available marks for this assignment
+    marker : ChallengeMarker
+        The approach used for calculating grades
+    deadline : datetime
+        The default deadline beyond which submissions will be penalised.
+    challenges : List[Challenge]
+        The challenges involved in this assignment
+    quizzes : List[Quiz]
+        The quizzes involved in this assignment
+    extensions_by_student_id : Dict[int, datetime]
+        Associates ids of students with deadlines that have been given to them (i.e. as extensions)
+    max_days_late : int
+        The maximum number of days late that will be considered for marking
+    daily_penalty : float
+        The fraction of max_marks deducted per day late
+
+    Methods
+    ----------
+    add_challenge_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: User) -> datetime
+        Returns the deadline for the given student
+    get_max_score() -> int
+        Returns the maximum possible score across all challenges and quizzes
+    get_canvas_col() -> str
+        Returns the name of the column that would match this assignment in a gradebook exported from Canvas.
+
+    """
+
+    name: str
+    max_marks: int
+    marker: ChallengeMarker
+    deadline: datetime.datetime
+    challenges: List[Challenge] = field(default_factory=list)
+    quizzes: List[Quiz] = field(default_factory=list)
+    extensions_by_student_id: Dict[int, datetime.datetime] = field(default_factory=dict)
+    max_days_late: int = 7
+    daily_penalty: float = 0.05
+
+    def add_challenge_slide(self, slide: Slide):
+        """
+        Add a code challenge slide to this assignment.
+
+        Parameters
+        ----------
+        slide : Slide
+            The slide to add. Must be a code challenge (``slide.challenge_id`` must not be None).
+
+        Raises
+        ------
+        ValueError
+            If the slide is not a code challenge.
+        """
+        if slide.challenge_id is None:
+            raise ValueError("This slide is not a code challenge")
+
+        self.challenges.append(Challenge(slide.challenge_id, slide.id, slide.title))
+
+    def add_quiz_slide(self, slide: Slide, questions: list):
+        """
+        Add a quiz slide to this assignment.
+
+        Parameters
+        ----------
+        slide : Slide
+            The quiz slide to add.
+        questions : list
+            The questions for this quiz, typically fetched via ``EdClient.get_questions``.
+        """
+        self.quizzes.append(Quiz(slide.id, slide.title, questions))
+
+    def add_multichoice_solution(self, question_id: int, solution: Set[int]):
+        """
+        Add an accepted answer to a multiple-choice question across all quizzes in this assignment.
+
+        Parameters
+        ----------
+        question_id : int
+            The id of the question to update.
+        solution : Set[int]
+            A set of option indices that constitute a correct answer.
+        """
+
+        for quiz in self.quizzes:
+
+            if quiz.add_multichoice_solution(question_id, solution):
+                return
+
+        print(f"could not locate multichoice question {question_id}")
+
+    def add_parsons_solution(self, question_id: int, solution: str):
+        """
+        Add an accepted arrangement to a Parsons question across all quizzes in this assignment.
+
+        Parameters
+        ----------
+        question_id : int
+            The id of the question to update.
+        solution : str
+            The accepted code arrangement as a string.
+        """
+
+        for quiz in self.quizzes:
+
+            if quiz.add_parsons_solution(question_id, solution):
+                return
+
+        print(f"could not locate parsons question {question_id}")
+
+    def add_extension(self, student, deadline):
+        """
+        Grant a deadline extension to a single student.
+
+        Parameters
+        ----------
+        student : User
+            The student receiving the extension.
+        deadline : datetime
+            The new deadline for this student.
+        """
+        self.extensions_by_student_id[student.id] = deadline
+
+    def add_extensions(self, students, deadline):
+        """
+        Grant the same deadline extension to multiple students.
+
+        Parameters
+        ----------
+        students : List[User]
+            The students receiving the extension.
+        deadline : datetime
+            The new deadline for all listed students.
+        """
+        for student in students:
+            self.extensions_by_student_id[student.id] = deadline
+
+    def get_deadline(self, student):
+        """
+        Return the effective deadline for a student, accounting for any extension.
+
+        Parameters
+        ----------
+        student : User
+            The student to look up.
+
+        Returns
+        -------
+        datetime
+            The student's personal extension deadline if one exists, otherwise
+            the assignment's default deadline.
+        """
+        if student.id in self.extensions_by_student_id:
+            return self.extensions_by_student_id[student.id]
+
+        return self.deadline
+
+    def get_max_score(self):
+        """
+        Return the maximum possible score across all challenges and quizzes.
+
+        Returns
+        -------
+        int
+            The total points available in this assignment.
+        """
+        max_score = 0
+        for quiz in self.quizzes:
+            max_score = max_score + quiz.get_max_score()
+
+        if self.marker.mark_type == MarkType.BY_CHALLENGE:
+            max_score = max_score + (
+                len(self.challenges) * self.marker.points_per_challenge
+            )
+        else:
+            max_score = max_score + self.marker.max_test_case_score
+
+        return max_score
+
+    def get_canvas_col(self):
+        """
+        Return the column header that matches this assignment in a Canvas gradebook export.
+
+        Returns
+        -------
+        str
+        """
+        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
+    ----------
+    student_id : int
+        The id of the student
+    completed : bool
+        True if the student successfully completed this assignment, otherwise false.
+    score : int
+        The score received by this student
+    mark : float
+        The mark received by this student.
+    days_late : int
+        The number of days past the deadline that work was received and considered.
+    challenge_results : Dict[int, ChallengeResult]
+        Associates ids of challenges with their individual results
+
+    Methods
+    ----------
+    add_challenge_submission(submission, student, assignment)
+        Updates this result based on a single challenge submission
+    add_quiz_result(quiz_result)
+        Records the result for a quiz
+    finalize(assignment, crawler)
+        To be called after all submissions have been added.
+    print_summary(student, assignment)
+        Print a human-readable summary of the student's mark
+    """
+
+    student_id: int
+    score: int = None
+    mark: float = None
+    days_late: int = None
+    penalty: float = None
+    challenge_results: Dict[int, ChallengeResult] = field(default_factory=dict)
+    quiz_results: Dict[int, QuizResult] = field(default_factory=dict)
+
+    def add_challenge_submission(self, submission, student, assignment):
+        """
+        Record a challenge submission for this student.
+
+        Calculates days late relative to the student's effective deadline and
+        updates the per-challenge result. Call this for every submission before
+        calling ``finalize``.
+
+        Parameters
+        ----------
+        submission : Submission
+            The submission to record.
+        student : User
+            The student who made the submission.
+        assignment : Assignment
+            The assignment being graded (used to look up the student's deadline).
+        """
+
+        deadline = assignment.get_deadline(student)
+
+        days_late = 0
+        if submission.marked_at > deadline:
+            diff = submission.marked_at - deadline
+            days_late = math.ceil(diff.total_seconds() / (60 * 60 * 24))
+
+        if submission.challenge_id not in self.challenge_results:
+            self.challenge_results[submission.challenge_id] = ChallengeResult()
+
+        self.challenge_results[submission.challenge_id].add(submission, days_late)
+
+    def add_quiz_result(self, quiz_result: QuizResult):
+        """
+        Record the result for a quiz.
+
+        Parameters
+        ----------
+        quiz_result : QuizResult
+            The graded quiz result to store.
+        """
+        self.quiz_results[quiz_result.quiz_id] = quiz_result
+
+    def finalize(self, assignment: Assignment, crawler):
+        """
+        Calculate the student's final mark. Call after all submissions and quiz results have been added.
+
+        Finds the number of days late that maximises the student's mark after
+        applying the late penalty, and stores the result in ``mark``, ``score``,
+        ``days_late``, and ``penalty``.
+
+        Parameters
+        ----------
+        assignment : Assignment
+            The assignment being graded.
+        crawler : EdClient
+            Used to fetch full submission detail when the marker type is
+            ``BY_TESTCASE_SCORE``. May be None for other mark types.
+        """
+
+        self.score = 0
+        self.mark = 0
+        self.days_late = 0
+        self.penalty = 0
+
+        quiz_score = 0
+        for quiz_result in self.quiz_results.values():
+            quiz_score = quiz_score + quiz_result.score
+
+        if self.challenge_results is not None:
+            for challenge in self.challenge_results.values():
+                challenge.finalize(assignment.marker, crawler)
+
+        daily_mark_penalty = assignment.daily_penalty * assignment.max_marks
+
+        for days_late in range(0, assignment.max_days_late + 1):
+            score = quiz_score
+
+            for challenge in self.challenge_results.values():
+                score = score + challenge.scores_by_calendar_days_late[days_late]
+
+            mark = assignment.max_marks * (score / assignment.get_max_score())
+            penalty = days_late * daily_mark_penalty
+            mark = mark - penalty
+            if mark < 0:
+                mark = 0
+
+            if mark > self.mark:
+                self.score = score
+                self.mark = mark
+                self.days_late = days_late
+                self.penalty = penalty
+
+    def print_summary(self, student: User, assignment: Assignment):
+        """
+        Print a human-readable summary of the student's mark and per-challenge breakdown.
+
+        Parameters
+        ----------
+        student : User
+            The student whose result is being summarised.
+        assignment : Assignment
+            The assignment being summarised.
+        """
+
+        msg = f"{student.name} got {self.mark:.1f}/{assignment.max_marks} marks from {self.score}/{assignment.get_max_score()} points"
+
+        if self.days_late > 0:
+            msg = f"{msg} and a penalty of {self.penalty:.1f} marks for submitting {self.days_late} days late"
+
+        print(msg)
+
+        for quiz in assignment.quizzes:
+            quiz_result = self.quiz_results.get(quiz.id)
+
+            if quiz.id is None:
+                print(
+                    f"  0/{quiz.get_max_score()} points for "
+                    + quiz.name
+                    + " due to no attempt"
+                )
+            else:
+                quiz_result.print_summary(quiz)
+
+        for challenge in assignment.challenges:
+
+            challenge_result = self.challenge_results.get(challenge.id)
+            if challenge_result is None:
+                print(f"  0 points for " + challenge.name + " due to no attempt")
+            else:
+                challenge_result.print_summary(challenge, self.days_late)

ed_api_client-0.1.2/ed_api_client/canvas.py

@@ -0,0 +1,124 @@
+import csv
+from typing import Dict
+
+from ed_api_client import Assignment, Users, AssignmentResult
+
+
+class CanvasExporter:
+    """
+    Builds a Canvas-compatible gradebook CSV from Ed assignment results.
+
+    Takes an exported Canvas gradebook as a template and fills in marks from Ed,
+    matching students by their SIS Login ID (email address).
+
+    Parameters
+    ----------
+    students : Users
+        The full collection of Ed users for the course, used to match Canvas
+        rows to Ed student ids.
+    """
+
+    def __init__(self, students: Users):
+        self.__students = students
+        self.__assignments_by_col = {}
+        self.__results_by_col = {}
+        self.__field_names = ["Student", "ID", "SIS User ID", "SIS Login ID", "Section"]
+
+    def add_assignment(
+        self,
+        assignment: Assignment,
+        column_name: str,
+        results: Dict[int, AssignmentResult],
+    ):
+        """
+        Register an assignment and its results to be included in the export.
+
+        Parameters
+        ----------
+        assignment : Assignment
+            The assignment to include.
+        column_name : str
+            The column header to use in the output CSV. Should match the
+            corresponding column in the source Canvas gradebook export.
+        results : Dict[int, AssignmentResult]
+            Maps Ed student ids to their graded results for this assignment.
+
+        Returns
+        -------
+        CanvasExporter
+            Returns self to allow method chaining.
+        """
+        self.__assignments_by_col[column_name] = assignment
+        self.__results_by_col[column_name] = results
+        self.__field_names.append(column_name)
+        return self
+
+    def generate_csv(self, source_csv, target_csv):
+        """
+        Generate the output gradebook CSV.
+
+        Reads the Canvas gradebook export at ``source_csv``, looks up each
+        student's Ed mark, and writes the result to ``target_csv``. Students
+        not found in the Ed user collection are skipped with a warning.
+
+        Parameters
+        ----------
+        source_csv : str
+            Path to the Canvas gradebook export CSV.
+        target_csv : str
+            Path to write the output CSV to.
+        """
+        with open(source_csv) as input:
+            reader = csv.DictReader(input)
+
+            with open(target_csv, "w") as output:
+                writer = csv.DictWriter(output, fieldnames=self.__field_names)
+                writer.writeheader()
+
+                for input_row in reader:
+
+                    output_row = self.handle_row(input_row)
+
+                    if output_row is None:
+                        continue
+
+                    writer.writerow(output_row)
+
+    def handle_row(self, input_row: dict):
+        """
+        Convert a single Canvas gradebook row into an output row with Ed marks.
+
+        Parameters
+        ----------
+        input_row : dict
+            A row from the Canvas gradebook CSV, keyed by column header.
+
+        Returns
+        -------
+        dict or None
+            The output row with Ed marks filled in, or None if the student
+            could not be matched (row is skipped).
+        """
+
+        student_email = input_row.get("SIS Login ID")
+        if student_email is None:
+            return None
+
+        student = self.__students.get_by_email(student_email.lower())
+        if student is None:
+            print(f"Could not locate student {student_email}")
+            return None
+
+        output_row = {}
+        for field in ["Student", "ID", "SIS User ID", "SIS Login ID", "Section"]:
+            output_row[field] = input_row[field]
+
+        for col, assignment in self.__assignments_by_col.items():
+
+            results = self.__results_by_col.get(col, {}).get(student.id)
+            if results is None:
+                output_row[col] = 0
+            else:
+                output_row[col] = round(results.mark, 3)
+
+        return output_row