feat: add GradeEventContextRequested filter for grade analytics enrichment

CHANGELOG.rst

@@ -43,6 +43,14 @@ See the fragment files in the `changelog.d directory`_.
 .. _changelog.d directory: https://github.com/openedx/openedx-filters/tree/master/changelog.d
 .. scriv-insert-here
 
+[3.2.0] - 2025-04-13
+--------------------
+
+Changed
+~~~~~~~
+
+* Added GradeEventContextRequested filter
+
 [3.1.0] - 2025-04-06
 --------------------
 

openedx_filters/__init__.py

@@ -3,4 +3,4 @@
 """
 from openedx_filters.filters import *
 
-__version__ = "3.1.0"
+__version__ = "3.2.0"

openedx_filters/learning/filters.py

@@ -1468,7 +1468,7 @@ class AccountSettingsReadOnlyFieldsRequested(OpenEdxPublicFilter):
     filter_type = "org.openedx.learning.account.settings.read_only_fields.requested.v1"
 
     @classmethod
-    def run_filter(cls, readonly_fields: set, user: Any) -> tuple[Any, Any]:
+    def run_filter(cls, readonly_fields: set, user: Any) -> tuple[set, Any]:
         """
         Process the readonly_fields set using the configured pipeline steps.
 
@@ -1484,4 +1484,43 @@ def run_filter(cls, readonly_fields: set, user: Any) -> tuple[Any, Any]:
                 Any: the Django User object.
         """
         data = super().run_pipeline(readonly_fields=readonly_fields, user=user)
-        return (data.get("readonly_fields"), data.get("user"))
+        return (data["readonly_fields"], data["user"])
+
+
+class GradeEventContextRequested(OpenEdxPublicFilter):
+    """
+    Filter used to enrich the context for grade events.
+
+    Purpose:
+        This filter is triggered when a grade event context is requested, allowing
+        pipeline steps to enrich the context dictionary with additional data.
+
+    Filter Type:
+        org.openedx.learning.grade.context.requested.v1
+
+    Trigger:
+        - Repository: openedx/openedx-platform
+        - Path: lms/djangoapps/grades/events.py
+        - Function or Method: course_grade_passed_first_time
+    """
+
+    filter_type = "org.openedx.learning.grade.context.requested.v1"
+
+    @classmethod
+    def run_filter(cls, context: dict, user_id: int, course_id: str) -> tuple[dict, int, str]:
+        """
+        Process the context dict using the configured pipeline steps.
+
+        Arguments:
+            context (dict): The grade event context to be enriched.
+            user_id (int): The ID of the user associated with the grade event.
+            course_id (str): The identifier of the course.
+
+        Returns:
+            tuple[dict, int, str]:
+                dict: The enriched grade event context.
+                int: The user ID.
+                str: The course identifier.
+        """
+        data = super().run_pipeline(context=context, user_id=user_id, course_id=course_id)
+        return data["context"], data["user_id"], data["course_id"]

openedx_filters/learning/tests/test_filters.py

@@ -23,6 +23,7 @@
     CourseRunAPIRenderStarted,
     CourseUnenrollmentStarted,
     DashboardRenderStarted,
+    GradeEventContextRequested,
     IDVPageURLRequested,
     InstructorDashboardRenderStarted,
     ORASubmissionViewRenderStarted,
@@ -804,6 +805,44 @@ def test_schedule_requested(self):
         self.assertEqual(schedules, result)
 
 
+class TestGradeEventContextRequestedFilter(TestCase):
+    """
+    Tests for the GradeEventContextRequested filter.
+    """
+
+    def test_run_filter_returns_context_unchanged_when_no_pipeline(self):
+        """
+        When no pipeline steps are configured, run_filter returns all original inputs unchanged.
+        """
+        context = {"course_id": "course-v1:org+course+run"}
+        user_id = 42
+        course_id = "course-v1:org+course+run"
+
+        with patch.object(
+            GradeEventContextRequested,
+            "run_pipeline",
+            return_value={"context": context, "user_id": user_id, "course_id": course_id},
+        ):
+            result_context, result_user_id, result_course_id = GradeEventContextRequested.run_filter(
+                context=context,
+                user_id=user_id,
+                course_id=course_id,
+            )
+
+        self.assertEqual(result_context, context)
+        self.assertEqual(result_user_id, user_id)
+        self.assertEqual(result_course_id, course_id)
+
+    def test_filter_type(self):
+        """
+        Confirm the filter type string is correct.
+        """
+        self.assertEqual(
+            GradeEventContextRequested.filter_type,
+            "org.openedx.learning.grade.context.requested.v1",
+        )
+
+
 class TestAccountSettingsReadOnlyFieldsRequestedFilter(TestCase):
     """
     Tests for the AccountSettingsReadOnlyFieldsRequested filter.