chore: address PR review

lms/djangoapps/ora_staff_grader/ora_api.py

@@ -13,6 +13,9 @@
 """
 import json
 from http import HTTPStatus
+
+from rest_framework.request import Request
+
 from lms.djangoapps.ora_staff_grader.errors import (
     LockContestedError,
     XBlockInternalError,
@@ -34,12 +37,23 @@ def get_submissions(request, usage_id):
     return json.loads(response.content)
 
 
-def get_assessments_given(request, usage_id, submission_uuid):
+def get_assessments_to(request: Request, usage_id: str, submission_uuid: str):
     """
-    Get a list of assessments given from the ORA's 'list_assessments_given' XBlock.json_handler
+    Get a list of assessments given from ORA `list_assessments_to` XBlock.json_handler.
+
+    Lists all assessments given by a user (according to their submissionUUID)
+    in an ORA assignment. Assessments can be Self, Peer and Staff.
+
+    Args:
+        request (Request): The request object
+        usage_id (str): Usage ID of the XBlock for running the handler
+        submission_uuid (str): The ORA submission UUID
     """
-    handler_name = "list_assessments_given"
-    data = {"item_id": usage_id, "submission_uuid": submission_uuid}
+    handler_name = "list_assessments_to"
+    data = {
+        "item_id": usage_id,
+        "submission_uuid": submission_uuid,
+    }
 
     response = call_xblock_json_handler(request, usage_id, handler_name, data)
 
@@ -49,12 +63,22 @@ def get_assessments_given(request, usage_id, submission_uuid):
     return json.loads(response.content)
 
 
-def get_assessments_received(request, usage_id, submission_uuid):
+def get_assessments_from(request: Request, usage_id: str, submission_uuid: str):
     """
-    Get a list of assessments received from the ORA's 'list_assessments_received' XBlock.json_handler
+    Get a list of assessments received from ORA `list_assessments_from` XBlock.json_handler
+
+    Lists all assessments received by a user (according to their submissionUUID)
+    in an ORA assignment. Assessments can be Self, Peer and Staff.
+
+    Args:
+        request (Request): The request object
+        usage_id (str): Usage ID of the XBlock for running the handler
+        submission_uuid (str): The ORA submission UUID
     """
-    handler_name = "list_assessments_received"
-    data = {"submission_uuid": submission_uuid}
+    handler_name = "list_assessments_from"
+    data = {
+        "submission_uuid": submission_uuid,
+    }
 
     response = call_xblock_json_handler(request, usage_id, handler_name, data)
 

lms/djangoapps/ora_staff_grader/serializers.py

@@ -169,9 +169,9 @@ class Meta:
 
 class AssessmentScoresSerializer(serializers.Serializer):
     """
-    Score information associated with a specific assessment.
+    Serializer for score information associated with a specific assessment.
 
-    This serializer was intended for displaying assessment information in the Enhanced Staff Grader (ESG).
+    This serializer is included in the `AssessmentSerializer` as a `ListField`
     """
     criterion_name = serializers.CharField()
     score_earned = serializers.IntegerField()
@@ -188,16 +188,17 @@ class Meta:
 
 class AssessmentSerializer(serializers.Serializer):
     """
-    Data for displaying Assessment objects for the response from the assessment
-    feedback endpoint in Enhanced Staff Grader (ESG)
-    This serializer is included in the AssessmentFeedbackSerializer as a ListField
+    Serializer for the each assessment metadata in the response from the assessments
+    feedback endpoints (from/to) in Enhanced Staff Grader (ESG)
+
+    This serializer is included in the `AssessmentFeedbackSerializer` as a `ListField`
     """
     assessment_id = serializers.CharField()
     scorer_name = serializers.CharField(allow_null=True)
     scorer_username = serializers.CharField(allow_null=True)
     scorer_email = serializers.CharField(allow_null=True)
-    assesment_date = serializers.DateTimeField()
-    assesment_scores = serializers.ListField(child=AssessmentScoresSerializer())
+    assessment_date = serializers.DateTimeField()
+    assessment_scores = serializers.ListField(child=AssessmentScoresSerializer())
     problem_step = serializers.CharField(allow_null=True)
     feedback = serializers.CharField(allow_null=True)
 
@@ -207,8 +208,8 @@ class Meta:
             "scorer_name",
             "scorer_username",
             "scorer_email",
-            "assesment_date",
-            "assesment_scores",
+            "assessment_date",
+            "assessment_scores",
             "problem_step",
             "feedback",
         ]
@@ -244,14 +245,14 @@ def get_isEnabled(self, obj):
 
 class AssessmentFeedbackSerializer(serializers.Serializer):
     """
-    Serialize info for every assessment for the response from the assessment
-    feedback endpoint in Enhanced Staff Grader (ESG)
+    Serializer for a list of assessments for the response from the assessments
+    feedback endpoints (from/to) in Enhanced Staff Grader (ESG)
     """
 
     assessments = serializers.ListField(child=AssessmentSerializer())
 
     class Meta:
-        fields = ["assessments", ]
+        fields = ["assessments"]
         read_only_fields = fields
 
 

lms/djangoapps/ora_staff_grader/urls.py

@@ -13,8 +13,8 @@
     SubmissionLockView,
     SubmissionStatusFetchView,
     UpdateGradeView,
-    AssessmentGivenFeedbackView,
-    AssessmentReceivedFeedbackView,
+    AssessmentFeedbackToView,
+    AssessmentFeedbackFromView,
 )
 
 
@@ -24,8 +24,8 @@
 urlpatterns += [
     path("mock/", include("lms.djangoapps.ora_staff_grader.mock.urls")),
     path("initialize", InitializeView.as_view(), name="initialize"),
-    path("assessments/feedback/from", AssessmentReceivedFeedbackView.as_view(), name="assessment-received-feedback"),
-    path("assessments/feedback/to", AssessmentGivenFeedbackView.as_view(), name="assessment-given-feedback"),
+    path("assessments/feedback/from", AssessmentFeedbackFromView.as_view(), name="assessment-feedback-from"),
+    path("assessments/feedback/to", AssessmentFeedbackToView.as_view(), name="assessment-feedback-to"),
     path("submission/batch/unlock", SubmissionBatchUnlockView.as_view(), name="batch-unlock"),
     path("submission/files", SubmissionFilesFetchView.as_view(), name="fetch-files"),
     path(

lms/djangoapps/ora_staff_grader/views.py

@@ -43,8 +43,8 @@
     get_assessment_info,
     get_submission_info,
     get_submissions,
-    get_assessments_given,
-    get_assessments_received,
+    get_assessments_to,
+    get_assessments_from,
     submit_grade,
 )
 from lms.djangoapps.ora_staff_grader.serializers import (
@@ -150,31 +150,32 @@ def get(self, request, ora_location, *args, **kwargs):
             return UnknownErrorResponse()
 
 
-class AssessmentGivenFeedbackView(StaffGraderBaseView):
+class AssessmentFeedbackToView(StaffGraderBaseView):
     """
-    GET data about assessments given by a user in a submission
+    (GET) List all assessments given by a user (according to
+    their submissionUUID) in an ORA assignment.
 
-    * Query Params:
+    **Query Params**:
         - oraLocation (str): ORA location for XBlock handling
-        - submissionUUID (str): A submission to get assessments for
+        - submissionUUID (str): The ORA submission UUID
 
     Response: {
         assessments (List[dict]): [
             {
-                "assessment_id: (str) assessment id
-                "scorer_name: (str) scorer name
-                "scorer_username: (str) scorer username
-                "scorer_email: (str) scorer email
-                "assessment_date: (str) assessment date
+                "assessment_id: (str) Assessment id
+                "scorer_name: (str) Scorer name
+                "scorer_username: (str) Scorer username
+                "scorer_email: (str) Scorer email
+                "assessment_date: (str) Assessment date
                 "assessment_scores (List[dict]) [
                     {
-                        "criterion_name: (str) criterion name
-                        "score_earned: (int) score earned
-                        "score_type: (str) score type
+                        "criterion_name: (str) Criterion name
+                        "score_earned: (int) Score earned
+                        "score_type: (str) Score type
                     }
                 ]
-                "problem_step (str) problem step (Self, Peer, or Staff)
-                "feedback: (str) feedback
+                "problem_step (str) Problem step (Self, Peer, or Staff)
+                "feedback: (str) Feedback of the assessment
             }
         ]
     }
@@ -187,9 +188,9 @@ class AssessmentGivenFeedbackView(StaffGraderBaseView):
     """
     @require_params([PARAM_ORA_LOCATION, PARAM_SUBMISSION_ID])
     def get(self, request, ora_location, submission_uuid, *args, **kwargs):
-        """ Get data about assessments given by a user"""
+        """Get assessments given by a user in an ORA assignment"""
         try:
-            assessments_data = {"assessments": get_assessments_given(request, ora_location, submission_uuid)}
+            assessments_data = {"assessments": get_assessments_to(request, ora_location, submission_uuid)}
             response_data = AssessmentFeedbackSerializer(assessments_data).data
             return Response(response_data)
 
@@ -206,31 +207,32 @@ def get(self, request, ora_location, submission_uuid, *args, **kwargs):
             return UnknownErrorResponse()
 
 
-class AssessmentReceivedFeedbackView(StaffGraderBaseView):
+class AssessmentFeedbackFromView(StaffGraderBaseView):
     """
-    GET data about assessments received by a user in a submission
+    (GET) List all assessments received by a user (according to
+    their submissionUUID) in an ORA assignment.
 
-    * Query Params:
+    **Query Params**:
         - oraLocation (str): ORA location for XBlock handling
-        - submissionUUID (str): A submission to get assessments for
+        - submissionUUID (str): The ORA submission UUID
 
     Response: {
         assessments (List[dict]): [
             {
-                "assessment_id: (str) assessment id
-                "scorer_name: (str) scorer name
-                "scorer_username: (str) scorer username
-                "scorer_email: (str) scorer email
-                "assessment_date: (str) assessment date
+                "assessment_id: (str) Assessment id
+                "scorer_name: (str) Scorer name
+                "scorer_username: (str) Scorer username
+                "scorer_email: (str) Scorer email
+                "assessment_date: (str) Assessment date
                 "assessment_scores (List[dict]) [
                     {
-                        "criterion_name: (str) criterion name
-                        "score_earned: (int) score earned
-                        "score_type: (str) score type
+                        "criterion_name: (str) Criterion name
+                        "score_earned: (int) Score earned
+                        "score_type: (str) Score type
                     }
                 ]
-                "problem_step (str) problem step (Self, Peer, or Staff)
-                "feedback: (str) feedback
+                "problem_step (str) Problem step (Self, Peer, or Staff)
+                "feedback: (str) Feedback of the assessment
             }
         ]
     }
@@ -244,9 +246,9 @@ class AssessmentReceivedFeedbackView(StaffGraderBaseView):
 
     @require_params([PARAM_ORA_LOCATION, PARAM_SUBMISSION_ID])
     def get(self, request, ora_location, submission_uuid, *args, **kwargs):
-        """Get data about assessments received by a user"""
+        """Get assessments received by a user in an ORA assignment"""
         try:
-            assessments_data = {"assessments": get_assessments_received(request, ora_location, submission_uuid)}
+            assessments_data = {"assessments": get_assessments_from(request, ora_location, submission_uuid)}
             response_data = AssessmentFeedbackSerializer(assessments_data).data
             return Response(response_data)