feat: pass editor data and uploads to package

Author: MHajoha

pyproject.toml

@@ -7,7 +7,7 @@ name = "questionpy-server"
 description = "QuestionPy application server"
 license = { file = "LICENSE.md" }
 urls = { homepage = "https://questionpy.org" }
-version = "0.8.0"
+version = "0.9.0"
 authors = [
     { name = "TU Berlin innoCampus" },
     { email = "[email protected]" }

questionpy_common/api/files.py

@@ -0,0 +1,54 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BaseModel, ByteSize, ConfigDict, StringConstraints
+
+
+class UserUploadedFile(BaseModel, ABC):
+    """Metadata about a file uploaded by a user to the LMS."""
+
+    path: Annotated[str, StringConstraints(pattern=r"^/(.+/)?$")]
+    """The folder path of this file. Must begin and end in `/`. Top-level files have a path of `/`."""
+
+    filename: str
+
+    file_ref: str
+    """An opaque reference that can be used to retrieve the file content from the LMS."""
+
+    uploaded_at: datetime
+
+    mime_type: str
+
+    size: ByteSize
+
+    @property
+    @abstractmethod
+    def uri(self) -> str:
+        """Builds a URI that can be used to embed the file in a question."""
+
+
+class ResponseFile(UserUploadedFile):
+    @property
+    def uri(self) -> str:
+        return f"qpy://response/{self.file_ref}"
+
+
+class OptionsFile(UserUploadedFile):
+    @property
+    def uri(self) -> str:
+        return f"qpy://options/{self.file_ref}"
+
+
+class EditorData[FileT: UserUploadedFile](BaseModel):
+    """Data submitted by rich text editors."""
+
+    # The LMS may send and expect to receive back again additional properties. They must begin with _, though we don't
+    # check that restriction yet.
+    model_config = ConfigDict(extra="allow")
+
+    text: str
+    """The text content of the editor, in whichever markup format the LMS uses."""
+
+    files: list[FileT] = []
+    """Files referenced by the markup."""

questionpy_common/api/question.py

@@ -19,6 +19,8 @@
     "SubquestionModel",
 ]
 
+from .files import EditorData, ResponseFile
+
 
 class ScoringMethod(Enum):
     ALWAYS_MANUAL_SCORING_REQUIRED = "ALWAYS_MANUAL_SCORING_REQUIRED"
@@ -68,23 +70,33 @@ def start_attempt(self, variant: int) -> AttemptStartedModel:
 
     @abstractmethod
     def get_attempt(
-        self, attempt_state: str, scoring_state: str | None = None, response: dict[str, JsonValue] | None = None
+        self,
+        attempt_state: str,
+        scoring_state: str | None = None,
+        response: dict[str, JsonValue] | None = None,
+        uploads: dict[str, list[ResponseFile]] | None = None,
+        editors: dict[str, EditorData] | None = None,
     ) -> AttemptModel:
         """Create an attempt object for a previously started attempt.
 
         Args:
             attempt_state: The `attempt_state` attribute of an attempt which was previously returned by
                            [start_attempt][].
             scoring_state: Not implemented.
-            response: The response currently entered by the student.
+            response: The response currently entered by the student, excluding uploads and editors.
+            uploads: Files uploaded by the student in file upload elements (files belonging to editors are passed in
+                     `editors`.)
+            editors: WYSIWYG editor responses entered by the student.
         """
 
     @abstractmethod
     def score_attempt(
         self,
         attempt_state: str,
-        scoring_state: str | None = None,
-        response: dict[str, JsonValue] | None = None,
+        scoring_state: str | None,
+        response: dict[str, JsonValue],
+        uploads: dict[str, list[ResponseFile]],
+        editors: dict[str, EditorData],
         *,
         compute_adjusted_score: bool = False,
         generate_hint: bool = False,
@@ -95,7 +107,10 @@ def score_attempt(
             attempt_state: The `attempt_state` attribute of an attempt which was previously returned by
                            [start_attempt][].
             scoring_state: Not implemented.
-            response: The response currently entered by the student.
+            response: The response currently entered by the student, excluding uploads and editors.
+            uploads: Files uploaded by the student in file upload elements (files belonging to editors are passed in
+                     `editors`.)
+            editors: WYSIWYG editor responses entered by the student.
             compute_adjusted_score: TBD
             generate_hint: TBD
         """

questionpy_server/models.py

@@ -3,11 +3,12 @@
 #  (c) Technische Universität Berlin, innoCampus <[email protected]>
 
 from enum import Enum
-from typing import Annotated, Any
+from typing import Annotated
 
-from pydantic import BaseModel, ByteSize, ConfigDict, Field
+from pydantic import BaseModel, ByteSize, ConfigDict, Field, JsonValue
 
 from questionpy_common.api.attempt import AttemptModel, AttemptScoredModel, AttemptStartedModel
+from questionpy_common.api.files import EditorData, ResponseFile
 from questionpy_common.api.question import LmsPermissions, QuestionModel
 from questionpy_common.elements import OptionsFormDefinition
 from questionpy_common.environment import LmsProvidedAttributes as EnvironmentLmsProvidedAttributes
@@ -95,11 +96,15 @@ class AttemptStartArguments(RequestBaseData, LmsProvidedAttributes):
 class AttemptViewArguments(RequestBaseData, LmsProvidedAttributes):
     attempt_state: str
     scoring_state: str | None = None
-    response: dict[str, Any] | None = None
+    response: dict[str, JsonValue] | None = None
+    uploads: dict[str, list[ResponseFile]] | None = None
+    editors: dict[str, EditorData[ResponseFile]] | None = None
 
 
 class AttemptScoreArguments(AttemptViewArguments):
-    response: dict[str, Any]
+    response: dict[str, JsonValue]
+    uploads: dict[str, list[ResponseFile]] = {}
+    editors: dict[str, EditorData[ResponseFile]] = {}
     generate_hint: bool
 
 

questionpy_server/web/_routes/_attempts.py

@@ -44,6 +44,8 @@ async def post_attempt_view(
             attempt_state=data.attempt_state,
             scoring_state=data.scoring_state,
             response=data.response,
+            uploads=data.uploads,
+            editors=data.editors,
         )
         packages = context.worker.get_loaded_packages()
 
@@ -63,6 +65,8 @@ async def post_attempt_score(
             attempt_state=data.attempt_state,
             scoring_state=data.scoring_state,
             response=data.response,
+            uploads=data.uploads,
+            editors=data.editors,
         )
         packages = context.worker.get_loaded_packages()
 

questionpy_server/worker/__init__.py

@@ -10,6 +10,7 @@
 from pydantic import BaseModel
 
 from questionpy_common.api.attempt import AttemptModel, AttemptScoredModel, AttemptStartedModel
+from questionpy_common.api.files import EditorData, ResponseFile
 from questionpy_common.api.question import LmsPermissions
 from questionpy_common.elements import OptionsFormDefinition
 from questionpy_common.environment import PackagePermissions, RequestInfo
@@ -170,6 +171,8 @@ async def get_attempt(
         attempt_state: str,
         scoring_state: str | None = None,
         response: dict | None = None,
+        uploads: dict[str, list[ResponseFile]] | None = None,
+        editors: dict[str, EditorData[ResponseFile]] | None = None,
     ) -> AttemptModel:
         """Create an attempt object for a previously started attempt.
 
@@ -178,8 +181,11 @@ async def get_attempt(
             question_state: The question the attempt belongs to.
             attempt_state: The `attempt_state` attribute of an attempt which was previously returned by
                            :meth:`start_attempt`.
-            scoring_state: Not implemented.
+            scoring_state: The scoring state returned by the package the last time this attempt was scored.
             response: The response currently entered by the student.
+            uploads: Files uploaded by the student in file upload elements (files belonging to editors are passed in
+                     `editors`.)
+            editors: The WYSIWYG editor responses are passed separately here. Validated to a model in the SDK.
 
         Returns:
             Metadata of the attempt.
@@ -194,8 +200,22 @@ async def score_attempt(
         attempt_state: str,
         scoring_state: str | None = None,
         response: dict,
+        uploads: dict[str, list[ResponseFile]],
+        editors: dict[str, EditorData[ResponseFile]],
     ) -> AttemptScoredModel:
-        """TODO: write docstring."""
+        """Score the given response in this attempt.
+
+        Args:
+            request_info: Information about the current request.
+            question_state: The question the attempt belongs to.
+            attempt_state: The `attempt_state` attribute of an attempt which was previously returned by
+                           :meth:`start_attempt`.
+            scoring_state: The scoring state returned by the package the last time this attempt was scored.
+            response: The response currently entered by the student.
+            uploads: Files uploaded by the student in file upload elements (files belonging to editors are passed in
+                     `editors`.)
+            editors: The WYSIWYG editor responses are passed separately here. Validated to a model in the SDK.
+        """
 
     @abstractmethod
     async def get_static_file(self, path: str) -> PackageFileData:

questionpy_server/worker/impl/_base.py

@@ -15,6 +15,7 @@
 from zipfile import ZipFile
 
 from questionpy_common.api.attempt import AttemptModel, AttemptScoredModel, AttemptStartedModel
+from questionpy_common.api.files import EditorData, ResponseFile
 from questionpy_common.api.question import LmsPermissions
 from questionpy_common.constants import DIST_DIR
 from questionpy_common.elements import OptionsFormDefinition
@@ -264,12 +265,16 @@ async def get_attempt(
         attempt_state: str,
         scoring_state: str | None = None,
         response: dict | None = None,
+        uploads: dict[str, list[ResponseFile]] | None = None,
+        editors: dict[str, EditorData[ResponseFile]] | None = None,
     ) -> AttemptModel:
         msg = ViewAttempt(
             question_state=question_state,
             attempt_state=attempt_state,
             scoring_state=scoring_state,
             response=response,
+            uploads=uploads,
+            editors=editors,
             request_info=request_info,
         )
         ret = await self.send_and_wait_for_response(msg, ViewAttempt.Response)
@@ -284,12 +289,16 @@ async def score_attempt(
         attempt_state: str,
         scoring_state: str | None = None,
         response: dict,
+        uploads: dict[str, list[ResponseFile]],
+        editors: dict[str, EditorData[ResponseFile]],
     ) -> AttemptScoredModel:
         msg = ScoreAttempt(
             question_state=question_state,
             attempt_state=attempt_state,
             scoring_state=scoring_state,
             response=response,
+            uploads=uploads,
+            editors=editors,
             request_info=request_info,
         )
         ret = await self.send_and_wait_for_response(msg, ScoreAttempt.Response)

questionpy_server/worker/runtime/manager.py

@@ -274,7 +274,9 @@ def on_msg_view_attempt(self, msg: ViewAttempt) -> ViewAttempt.Response:
 
         with self._with_request_info(msg, msg.request_info):
             question = self._question_type.create_question_from_state(msg.question_state)
-            attempt_model = question.get_attempt(msg.attempt_state, msg.scoring_state, msg.response)
+            attempt_model = question.get_attempt(
+                msg.attempt_state, msg.scoring_state, msg.response, msg.uploads, msg.editors
+            )
             return ViewAttempt.Response(attempt_model=attempt_model)
 
     def on_msg_score_attempt(self, msg: ScoreAttempt) -> ScoreAttempt.Response:
@@ -285,7 +287,9 @@ def on_msg_score_attempt(self, msg: ScoreAttempt) -> ScoreAttempt.Response:
 
         with self._with_request_info(msg, msg.request_info):
             question = self._question_type.create_question_from_state(msg.question_state)
-            attempt_scored_model = question.score_attempt(msg.attempt_state, msg.scoring_state, msg.response)
+            attempt_scored_model = question.score_attempt(
+                msg.attempt_state, msg.scoring_state, msg.response, msg.uploads, msg.editors
+            )
             return ScoreAttempt.Response(attempt_scored_model=attempt_scored_model)
 
     @staticmethod

questionpy_server/worker/runtime/messages.py

@@ -11,6 +11,7 @@
 from pydantic import BaseModel, JsonValue
 
 from questionpy_common.api.attempt import AttemptModel, AttemptScoredModel, AttemptStartedModel
+from questionpy_common.api.files import EditorData, ResponseFile
 from questionpy_common.api.qtype import InvalidQuestionStateError, OptionsFormValidationError
 from questionpy_common.api.question import QuestionModel
 from questionpy_common.elements import OptionsFormDefinition
@@ -188,6 +189,8 @@ class ViewAttempt(MessageToWorker):
     attempt_state: str
     scoring_state: str | None
     response: dict | None
+    uploads: dict[str, list[ResponseFile]] | None
+    editors: dict[str, EditorData[ResponseFile]] | None
 
     class Response(MessageToServer):
         message_id: ClassVar[MessageIds] = MessageIds.RETURN_VIEW_ATTEMPT
@@ -201,6 +204,8 @@ class ScoreAttempt(MessageToWorker):
     attempt_state: str
     scoring_state: str | None
     response: dict
+    uploads: dict[str, list[ResponseFile]]
+    editors: dict[str, EditorData[ResponseFile]]
 
     class Response(MessageToServer):
         message_id: ClassVar[MessageIds] = MessageIds.RETURN_SCORE_ATTEMPT