diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 2ecc289d..d9da4b32 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -15,6 +15,15 @@ Unreleased ---------- * Configuration for automatic filters docs generation. + +[1.12.0] - 2024-12-12 +--------------------- + +Added +~~~~~ + +* ScheduleQuerySetRequested filter added which can be used to modify the Schedule QuerySet. + [1.11.0] - 2024-09-30 --------------------- diff --git a/docs/reference/real-life-use-cases.rst b/docs/reference/real-life-use-cases.rst index 316317a7..681962f2 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -73,6 +73,13 @@ Webfilters, as mentioned in `openedx-webhooks`_ is a type of webhook that allows More details on `Open edX Webhooks - Webfilters`_. +Schedules Filtering +******************* + +When a automatic email message is scheduled to be sent to students, a filter is executed to modify the schedule. This functionality allows you to define specific criteria to determine which students will receive the email. For example, filters can check whether students have opted to receive newsletters, assess their progress in the course, evaluate their activity, or consider other relevant conditions. + +More details on `Schedule Filtering`_. + Other Use Cases *************** @@ -106,3 +113,4 @@ Here are some additional use cases that can be implemented using Open edX Filter .. _IDV Integration with new Vendors: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/4307386369/Proposal+Add+Extensibility+Mechanisms+to+IDV+to+Enable+Integration+of+New+IDV+Vendor+Persona .. _Render Alternative Course About: https://github.com/lektorium-tutor/lektorium_main/blob/master/lektorium_main/tilda/pipeline.py#L15-L94 .. _Hide Course About from Users Without Memberships: https://github.com/academic-innovation/mogc-partnerships/blob/main/mogc_partnerships/pipeline.py#L53-L66 +.. _Schedule Filtering: https://github.com/fccn/nau-openedx-extensions/pull/56 diff --git a/openedx_filters/__init__.py b/openedx_filters/__init__.py index 46c47291..88ee1967 100644 --- a/openedx_filters/__init__.py +++ b/openedx_filters/__init__.py @@ -3,4 +3,4 @@ """ from openedx_filters.filters import * -__version__ = "1.11.0" +__version__ = "1.12.0" diff --git a/openedx_filters/learning/filters.py b/openedx_filters/learning/filters.py index 011d0149..9b4b79ca 100644 --- a/openedx_filters/learning/filters.py +++ b/openedx_filters/learning/filters.py @@ -4,6 +4,8 @@ from typing import Optional +from django.db.models.query import QuerySet + from openedx_filters.exceptions import OpenEdxFilterException from openedx_filters.tooling import OpenEdxPublicFilter from openedx_filters.utils import SensitiveDataManagementMixin @@ -818,3 +820,33 @@ def run_filter(cls, url, org): """ data = super().run_pipeline(url=url, org=org) return data.get("url"), data.get("org") + + +class ScheduleQuerySetRequested(OpenEdxPublicFilter): + """ + Filter class designed to apply additional filtering to a given QuerySet of Schedules. + + If you want to know more about the Schedules feature, please refer: + - https://github.com/openedx/edx-platform/tree/master/openedx/core/djangoapps/schedules#readme + - https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/manage_live_course/automatic_email.html + """ + + filter_type = "org.openedx.learning.schedule.queryset.requested.v1" + + @classmethod + def run_filter(cls, schedules: QuerySet) -> QuerySet: + """ + Execute the filtering logic for the given QuerySet of schedules. + + This method processes the input QuerySet using the configured pipeline steps + to applies additional filtering rules. It returns the filtered QuerySet for + further processing. + + Arguments: + schedules (QuerySet): The original QuerySet of schedules to be filtered. + + Returns: + QuerySet: A refined QuerySet of schedules after applying the filter. + """ + data = super().run_pipeline(schedules=schedules) + return data.get("schedules") diff --git a/openedx_filters/learning/tests/test_filters.py b/openedx_filters/learning/tests/test_filters.py index 41896ccb..a84e31dc 100644 --- a/openedx_filters/learning/tests/test_filters.py +++ b/openedx_filters/learning/tests/test_filters.py @@ -25,6 +25,7 @@ InstructorDashboardRenderStarted, ORASubmissionViewRenderStarted, RenderXBlockStarted, + ScheduleQuerySetRequested, StudentLoginRequested, StudentRegistrationRequested, VerticalBlockChildRenderStarted, @@ -776,3 +777,26 @@ def test_lms_page_url_requested(self): self.assertEqual(url, url_result) self.assertEqual(org, org_result) + + +@ddt +class TestScheduleFilters(TestCase): + """ + Test class to verify standard behavior of the schedule filters. + + You'll find test suites for: + - `ScheduleQuerySetRequested` + """ + + def test_schedule_requested(self): + """ + Test schedule requested filter. + + Expected behavior: + - The filter should return the filtered schedules. + """ + schedules = Mock() + + result = ScheduleQuerySetRequested.run_filter(schedules) + + self.assertEqual(schedules, result)