gradescopeapi 1.3.1__py3-none-any.whl

gradescopeapi/__init__.py

@@ -0,0 +1 @@
+# empty on purpose

gradescopeapi/_config/config.py

@@ -0,0 +1,65 @@
+"""config.py
+Configuration file for FastAPI. Specifies the specific objects and data models used in our api
+"""
+
+import io
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class UserSession(BaseModel):
+    user_email: str
+    session_token: str
+
+
+class LoginRequestModel(BaseModel):
+    email: str
+    password: str
+
+
+class CourseID(BaseModel):
+    course_id: str
+
+
+class AssignmentID(BaseModel):
+    course_id: str
+    assignment_id: str
+
+
+class StudentSubmission(BaseModel):
+    student_email: str
+    course_id: str
+    assignment_id: str
+
+
+class ExtensionData(BaseModel):
+    course_id: str
+    assignment_id: str
+
+
+class UpdateExtensionData(BaseModel):
+    course_id: str
+    assignment_id: str
+    user_id: str
+    release_date: datetime | None = None
+    due_date: datetime | None = None
+    late_due_date: datetime | None = None
+
+
+class AssignmentDates(BaseModel):
+    course_id: str
+    assignment_id: str
+    release_date: datetime | None = None
+    due_date: datetime | None = None
+    late_due_date: datetime | None = None
+
+
+class FileUploadModel(BaseModel, arbitrary_types_allowed=True):
+    file: io.TextIOWrapper
+
+
+class AssignmentUpload(BaseModel):
+    course_id: str
+    assignment_id: str
+    leaderboard_name: str | None = None

gradescopeapi/api/api.py

@@ -0,0 +1,373 @@
+from datetime import datetime
+
+from fastapi import Depends, FastAPI, HTTPException, status
+
+from gradescopeapi._config.config import FileUploadModel, LoginRequestModel
+from gradescopeapi.classes.account import Account
+from gradescopeapi.classes.assignments import Assignment, update_assignment_date
+from gradescopeapi.classes.connection import GSConnection
+from gradescopeapi.classes.courses import Course
+from gradescopeapi.classes.extensions import get_extensions, update_student_extension
+from gradescopeapi.classes.member import Member
+from gradescopeapi.classes.upload import upload_assignment
+
+app = FastAPI()
+
+# Create instance of GSConnection, to be used where needed
+connection = GSConnection()
+
+
+def get_gs_connection():
+    """
+    Returns the GSConnection instance
+
+    Returns:
+        connection (GSConnection): an instance of the GSConnection class,
+            containing the session object used to make HTTP requests,
+            a boolean defining True/False if the user is logged in, and
+            the user's Account object.
+    """
+    return connection
+
+
+def get_gs_connection_session():
+    """
+    Returns session of the the GSConnection instance
+
+    Returns:
+        connection.session (GSConnection.session): an instance of the GSConnection class' session object used to make HTTP requests
+    """
+    return connection.session
+
+
+def get_account():
+    """
+    Returns the user's Account object
+
+    Returns:
+        Account (Account): an instance of the Account class, containing
+            methods for interacting with the user's courses and assignments.
+    """
+    return Account(session=get_gs_connection_session)
+
+
+# Create instance of GSConnection, to be used where needed
+connection = GSConnection()
+
+account = None
+
+
+@app.get("/")
+def root():
+    return {"message": "Hello World"}
+
+
+@app.post("/login", name="login")
+def login(
+    login_data: LoginRequestModel,
+    gs_connection: GSConnection = Depends(get_gs_connection),
+):
+    """Login to Gradescope, with correct credentials
+
+    Args:
+        username (str): email address of user attempting to log in
+        password (str): password of user attempting to log in
+
+    Raises:
+        HTTPException: If the request to login fails, with a 404 Unauthorized Error status code and the error message "Account not found".
+    """
+    user_email = login_data.email
+    password = login_data.password
+
+    try:
+        connection.login(user_email, password)
+        global account
+        account = connection.account
+        return {"message": "Login successful", "status_code": status.HTTP_200_OK}
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=f"Account not found. Error {e}")
+
+
+@app.post("/courses", response_model=dict[str, dict[str, Course]])
+def get_courses():
+    """Get all courses for the user
+
+    Args:
+        account (Account): Account object containing the user's courses
+
+    Returns:
+        dict: dictionary of dictionaries
+
+    Raises:
+        HTTPException: If the request to get courses fails, with a 500 Internal Server Error status code and the error message.
+    """
+    try:
+        course_list = account.get_courses()
+        return course_list
+    except RuntimeError as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/course_users", response_model=list[Member])
+def get_course_users(course_id: str):
+    """Get all users for a course. ONLY FOR INSTRUCTORS.
+
+    Args:
+        course_id (str): The ID of the course.
+
+    Returns:
+        dict: dictionary of dictionaries
+
+    Raises:
+        HTTPException: If the request to get courses fails, with a 500 Internal Server Error status code and the error message.
+    """
+    try:
+        course_list = connection.account.get_course_users(course_id)
+        print(course_list)
+        return course_list
+    except RuntimeError as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/assignments", response_model=list[Assignment])
+def get_assignments(course_id: str):
+    """Get all assignments for a course. ONLY FOR INSTRUCTORS.
+        list: list of user emails
+
+    Raises:
+        HTTPException: If the request to get course users fails, with a 500 Internal Server Error status code and the error message.
+    """
+    try:
+        course_users = connection.account.get_assignments(course_id)
+        return course_users
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get course users. Error {e}"
+        )
+
+
+@app.post("/assignment_submissions", response_model=dict[str, list[str]])
+def get_assignment_submissions(
+    course_id: str,
+    assignment_id: str,
+):
+    """Get all assignment submissions for an assignment. ONLY FOR INSTRUCTORS.
+
+    Args:
+        course_id (str): The ID of the course.
+        assignment_id (str): The ID of the assignment.
+
+    Returns:
+        list: list of Assignment objects
+
+    Raises:
+        HTTPException: If the request to get assignments fails, with a 500 Internal Server Error status code and the error message.
+    """
+    try:
+        assignment_list = connection.account.get_assignment_submissions(
+            course_id=course_id, assignment_id=assignment_id
+        )
+        return assignment_list
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get assignments. Error: {e}"
+        )
+
+
+@app.post("/single_assignment_submission", response_model=list[str])
+def get_student_assignment_submission(
+    student_email: str, course_id: str, assignment_id: str
+):
+    """Get a student's assignment submission. ONLY FOR INSTRUCTORS.
+
+    Args:
+        student_email (str): The email address of the student.
+        course_id (str): The ID of the course.
+        assignment_id (str): The ID of the assignment.
+
+    Returns:
+        dict: dictionary containing a list of student emails and their corresponding submission IDs
+
+    Raises:
+        HTTPException: If the request to get assignment submissions fails, with a 500 Internal Server Error status code and the error message.
+    """
+    try:
+        assignment_submissions = connection.account.get_assignment_submission(
+            student_email=student_email,
+            course_id=course_id,
+            assignment_id=assignment_id,
+        )
+        return assignment_submissions
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get assignment submissions. Error: {e}"
+        )
+
+
+@app.post("/assignments/update_dates")
+def update_assignment_dates(
+    course_id: str,
+    assignment_id: str,
+    release_date: datetime,
+    due_date: datetime,
+    late_due_date: datetime,
+):
+    """
+    Update the release and due dates for an assignment. ONLY FOR INSTRUCTORS.
+
+    Args:
+        course_id (str): The ID of the course.
+        assignment_id (str): The ID of the assignment.
+        release_date (datetime): The release date of the assignment.
+        due_date (datetime): The due date of the assignment.
+        late_due_date (datetime): The late due date of the assignment.
+
+    Notes:
+        The timezone for dates used in Gradescope is specific to an institution. For example, for NYU, the timezone is America/New_York.
+        For datetime objects passed to this function, the timezone should be set to the institution's timezone.
+
+    Returns:
+        dict: A dictionary with a "message" key indicating if the assignment dates were updated successfully.
+
+    Raises:
+        HTTPException: If the assignment dates update fails, with a 400 Bad Request status code and the error message "Failed to update assignment dates".
+    """
+    try:
+        print(f"late due date {late_due_date}")
+        success = update_assignment_date(
+            session=connection.session,
+            course_id=course_id,
+            assignment_id=assignment_id,
+            release_date=release_date,
+            due_date=due_date,
+            late_due_date=late_due_date,
+        )
+        if success:
+            return {
+                "message": "Assignment dates updated successfully",
+                "status_code": status.HTTP_200_OK,
+            }
+        else:
+            raise HTTPException(
+                status_code=400, detail="Failed to update assignment dates"
+            )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/assignments/extensions", response_model=dict)
+def get_assignment_extensions(course_id: str, assignment_id: str):
+    """
+    Get all extensions for an assignment.
+
+    Args:
+        course_id (str): The ID of the course.
+        assignment_id (str): The ID of the assignment.
+
+    Returns:
+        dict: A dictionary containing the extensions, where the keys are user IDs and the values are Extension objects.
+
+    Raises:
+        HTTPException: If the request to get extensions fails, with a 500 Internal Server Error status code and the error message.
+    """
+    try:
+        extensions = get_extensions(
+            session=connection.session,
+            course_id=course_id,
+            assignment_id=assignment_id,
+        )
+        return extensions
+    except RuntimeError as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/assignments/extensions/update")
+def update_extension(
+    course_id: str,
+    assignment_id: str,
+    user_id: str,
+    release_date: datetime,
+    due_date: datetime,
+    late_due_date: datetime,
+):
+    """
+    Update the extension for a student on an assignment. ONLY FOR INSTRUCTORS.
+
+    Args:
+        course_id (str): The ID of the course.
+        assignment_id (str): The ID of the assignment.
+        user_id (str): The ID of the student.
+        release_date (datetime): The release date of the extension.
+        due_date (datetime): The due date of the extension.
+        late_due_date (datetime): The late due date of the extension.
+
+    Returns:
+        dict: A dictionary with a "message" key indicating if the extension was updated successfully.
+
+    Raises:
+        HTTPException: If the extension update fails, with a 400 Bad Request status code and the error message.
+        HTTPException: If a ValueError is raised (e.g., invalid date order), with a 400 Bad Request status code and the error message.
+        HTTPException: If any other exception occurs, with a 500 Internal Server Error status code and the error message.
+    """
+    try:
+        success = update_student_extension(
+            session=connection.session,
+            course_id=course_id,
+            assignment_id=assignment_id,
+            user_id=user_id,
+            release_date=release_date,
+            due_date=due_date,
+            late_due_date=late_due_date,
+        )
+        if success:
+            return {
+                "message": "Extension updated successfully",
+                "status_code": status.HTTP_200_OK,
+            }
+        else:
+            raise HTTPException(status_code=400, detail="Failed to update extension")
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/assignments/upload")
+def upload_assignment_files(
+    course_id: str, assignment_id: str, leaderboard_name: str, file: FileUploadModel
+):
+    """
+    Upload files for an assignment.
+
+    NOTE: This function within FastAPI is currently nonfunctional, as we did not
+    find the datatype for file, which would allow us to upload a file via
+    Postman. However, this functionality works correctly if a user
+    runs this as a Python package.
+
+    Args:
+        course_id (str): The ID of the course on Gradescope.
+        assignment_id (str): The ID of the assignment on Gradescope.
+        leaderboard_name (str): The name of the leaderboard.
+        file (FileUploadModel): The file object to upload.
+
+    Returns:
+        dict: A dictionary containing the submission link for the uploaded files.
+
+    Raises:
+        HTTPException: If the upload fails, with a 400 Bad Request status code and the error message "Upload unsuccessful".
+        HTTPException: If any other exception occurs, with a 500 Internal Server Error status code and the error message.
+    """
+    try:
+        submission_link = upload_assignment(
+            session=connection.session,
+            course_id=course_id,
+            assignment_id=assignment_id,
+            files=file,
+            leaderboard_name=leaderboard_name,
+        )
+        if submission_link:
+            return {"submission_link": submission_link}
+        else:
+            raise HTTPException(status_code=400, detail="Upload unsuccessful")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

gradescopeapi/api/constants.py

@@ -0,0 +1,5 @@
+"""constants.py
+Constants file for FastAPI. Specifies any variable or other object which should remain the same across all environments.
+"""
+
+BASE_URL = "https://www.gradescope.com"

gradescopeapi/classes/_helpers/_assignment_helpers.py

@@ -0,0 +1,178 @@
+import json
+
+import dateutil.parser
+import requests
+
+from gradescopeapi.classes.assignments import Assignment
+
+
+def check_page_auth(session, endpoint):
+    """
+    raises Exception if user not logged in or doesn't have appropriate authorities
+    Returns response if otherwise good
+    """
+    submissions_resp = session.get(endpoint)
+    # check if page is valid, raise exception if not
+    if submissions_resp.status_code == requests.codes.unauthorized:
+        # check error type
+        # TODO: how should we handle errors so that our API can read them?
+        error_msg = [*json.loads(submissions_resp.text).values()][0]
+        if error_msg == "You are not authorized to access this page.":
+            raise Exception("You are not authorized to access this page.")
+        elif error_msg == "You must be logged in to access this page.":
+            raise Exception("You must be logged in to access this page.")
+    elif submissions_resp.status_code == requests.codes.not_found:
+        raise Exception("Page not Found")
+    elif submissions_resp.status_code == requests.codes.ok:
+        return submissions_resp
+
+
+def get_assignments_instructor_view(coursepage_soup):
+    assignments_list = []
+    element_with_props = coursepage_soup.find(
+        "div", {"data-react-class": "AssignmentsTable"}
+    )
+    if element_with_props:
+        # Extract the value of the data-react-props attribute
+        props_str = element_with_props["data-react-props"]
+        # Parse the JSON data
+        assignment_json = json.loads(props_str)
+
+        # Extract information for each assignment
+        for assignment in assignment_json["table_data"]:
+            assignment_obj = Assignment(
+                assignment_id=assignment["url"].split("/")[-1],
+                name=assignment["title"],
+                release_date=assignment["submission_window"]["release_date"],
+                due_date=assignment["submission_window"]["due_date"],
+                late_due_date=assignment["submission_window"].get("hard_due_date"),
+                submissions_status=None,
+                grade=None,
+                max_grade=str(float(assignment["total_points"])),
+            )
+
+            # convert to datetime objects
+            assignment_obj.release_date = (
+                dateutil.parser.parse(assignment_obj.release_date)
+                if assignment_obj.release_date
+                else assignment_obj.release_date
+            )
+
+            assignment_obj.due_date = (
+                dateutil.parser.parse(assignment_obj.due_date)
+                if assignment_obj.due_date
+                else assignment_obj.due_date
+            )
+
+            assignment_obj.late_due_date = (
+                dateutil.parser.parse(assignment_obj.late_due_date)
+                if assignment_obj.late_due_date
+                else assignment_obj.late_due_date
+            )
+
+            # Add the assignment dictionary to the list
+            assignments_list.append(assignment_obj)
+    return assignments_list
+
+
+def get_assignments_student_view(coursepage_soup):
+    # parse into list of lists: Assignments[row_elements[]]
+    assignment_table = []
+    for assignment_row in coursepage_soup.findAll("tr", role="row")[
+        1:-1
+    ]:  # Skip header row and tail row (dropzonePreview--fileNameHeader)
+        row = []
+        for th in assignment_row.findAll("th"):
+            row.append(th)
+        for td in assignment_row.findAll("td"):
+            row.append(td)
+        assignment_table.append(row)
+    assignment_info_list = []
+
+    # Iterate over the list of Tag objects
+    for assignment in assignment_table:
+        # Extract assignment ID and name
+        name = assignment[0].text
+        # 3 cases: 1. submitted -> href element, 2. not submitted, submittable -> button element, 3. not submitted, cant submit -> only text
+        assignment_a_href = assignment[0].find("a", href=True)
+        assignment_button = assignment[0].find("button", class_="js-submitAssignment")
+        if assignment_a_href:
+            assignment_id = assignment_a_href["href"].split("/")[4]
+        elif assignment_button:
+            assignment_id = assignment_button["data-assignment-id"]
+        else:
+            assignment_id = None
+
+        # Extract submission status, grade, max_grade
+        try:  # Points not guaranteed
+            points = assignment[1].text.split(" / ")
+            grade = float(points[0])
+            max_grade = float(points[1])
+            submission_status = "Submitted"
+        except (IndexError, ValueError):
+            grade = None
+            max_grade = None
+            submission_status = assignment[1].text
+
+        # Extract release date, due date, and late due date
+        release_date = due_date = late_due_date = None
+        try:  # release date, due date, and late due date not guaranteed to be available
+            release_obj = assignment[2].find(class_="submissionTimeChart--releaseDate")
+            release_date = release_obj["datetime"] if release_obj else None
+            # both due data and late due date have the same class
+            due_dates_obj = assignment[2].find_all(
+                class_="submissionTimeChart--dueDate"
+            )
+            if due_dates_obj:
+                due_date = due_dates_obj[0]["datetime"] if due_dates_obj else None
+                if len(due_dates_obj) > 1:
+                    late_due_date = (
+                        due_dates_obj[1]["datetime"] if due_dates_obj else None
+                    )
+        except IndexError:
+            pass
+
+        # convert to datetime objects
+        release_date = (
+            dateutil.parser.parse(release_date) if release_date else release_date
+        )
+        due_date = dateutil.parser.parse(due_date) if due_date else due_date
+        late_due_date = (
+            dateutil.parser.parse(late_due_date) if late_due_date else late_due_date
+        )
+
+        # Store the extracted information in a dictionary
+        assignment_obj = Assignment(
+            assignment_id=assignment_id,
+            name=name,
+            release_date=release_date,
+            due_date=due_date,
+            late_due_date=late_due_date,
+            submissions_status=submission_status,
+            grade=grade,
+            max_grade=max_grade,
+        )
+
+        # Append the dictionary to the list
+        assignment_info_list.append(assignment_obj)
+
+    return assignment_info_list
+
+
+def get_submission_files(session, course_id, assignment_id, submission_id):
+    ASSIGNMENT_ENDPOINT = (
+        f"https://www.gradescope.com/courses/{course_id}/assignments/{assignment_id}"
+    )
+
+    file_info_link = f"{ASSIGNMENT_ENDPOINT}/submissions/{submission_id}.json?content=react&only_keys[]=text_files&only_keys[]=file_comments"
+    file_info_resp = session.get(file_info_link)
+    if file_info_resp.status_code == requests.codes.ok:
+        file_info_json = json.loads(file_info_resp.text)
+        if file_info_json.get("text_files"):
+            aws_links = []
+            for file_data in file_info_json["text_files"]:
+                aws_links.append(file_data["file"]["url"])
+        else:
+            raise NotImplementedError("Image only submissions not yet supported")
+        # TODO add support for image questions
+    return aws_links