feat: [FC-0074] use linter for openedx-filters classes definitions (#249

)

CHANGELOG.rst

@@ -13,8 +13,14 @@ Change Log
 
 Unreleased
 ----------
-* Configuration for automatic filters docs generation.
 
+[1.13.0] - 2025-01-31
+---------------------
+
+Added
+~~~~~
+
+* Use edx-lint linter for Open edX Filters classes docstrings validation.
 
 [1.12.0] - 2024-12-12
 ---------------------
@@ -40,6 +46,7 @@ Added
 ~~~~~
 
 * IDVPageURLRequested filter added which can be used to modify the URL for the ID verification process.
+* Configuration for automatic filters docs generation.
 
 [1.9.0] - 2024-06-14
 --------------------

docs/reference/documenting-filters-classes.rst

@@ -0,0 +1,38 @@
+Documenting Open edX Filters Classes
+====================================
+
+When creating a new filter, you should document the purpose of the filter in the docstring of the filter class. This will help other developers understand the purpose of the filter and how to use it.
+
+The docstring should comply with the following guidelines:
+
+- The docstring should be a triple-quoted string.
+- The docstring should be placed at the beginning of the class definition.
+- The docstring should include a brief description of what's supposed to do.
+- The docstring should describe the purpose of the filter.
+- The docstring should include the filter type ``filter_type``, which is the unique identifier for the filter.
+- The docstring should include the trigger information, which includes the repository, path, and function or method that triggers the filter. If for some reason the filter is triggered by multiple functions or methods, you should list them all. If it's not triggered by any function or method, you should use NA (Not Applicable).
+- The docstring should include any other relevant information about the filter (e.g., it works only for legacy views not MFEs).
+
+Consider the following example:
+
+.. code-block:: python
+
+    class AccountSettingsRenderStarted(OpenEdxPublicFilter):
+    """
+    Filter used to modify the rendering of the account settings page in the LMS.
+
+    Purpose:
+        This filter is triggered when a user visits the account settings page, just before the page is rendered allowing
+        the filter to modify the context and the template used to render the page.
+
+    Filter Type:
+        org.openedx.learning.student.settings.render.started.v1
+
+    Trigger:
+        - Repository: openedx/edx-platform
+        - Path: openedx/core/djangoapps/user_api/accounts/settings_views.py
+        - Function or Method: account_settings
+
+    Additional Information:
+        This filter doesn't work alongside the account MFE, only with the legacy account settings page.
+    """

docs/reference/index.rst

@@ -11,3 +11,4 @@ References
    django-plugins-and-filters
    real-life-use-cases
    architecture-subdomains
+   documenting-filters-classes

openedx_filters/__init__.py

@@ -3,4 +3,4 @@
 """
 from openedx_filters.filters import *
 
-__version__ = "1.12.0"
+__version__ = "1.13.0"

openedx_filters/course_authoring/filters.py

@@ -9,8 +9,9 @@ class LMSPageURLRequested(OpenEdxPublicFilter):
     """
     Filter used to modify the URL of the page requested by the user.
 
-    This filter is triggered when a user loads a page in Studio that references an LMS page, allowing the filter to
-    modify the URL of the page requested by the user.
+    Purpose:
+        This filter is triggered when a user loads a page in Studio that references an LMS page, allowing the filter to
+        modify the URL of the page requested by the user.
 
     Filter Type:
         org.openedx.course_authoring.lms.page.url.requested.v1

openedx_filters/learning/filters.py

@@ -17,8 +17,9 @@ class AccountSettingsRenderStarted(OpenEdxPublicFilter):
     """
     Filter used to modify the rendering of the account settings page in the LMS.
 
-    This filter is triggered when a user visits the account settings page, just before the page is rendered allowing
-    the filter to modify the context and the template used to render the page.
+    Purpose:
+        This filter is triggered when a user visits the account settings page, just before the page is rendered allowing
+        the filter to modify the context and the template used to render the page.
 
     Filter Type:
         org.openedx.learning.student.settings.render.started.v1
@@ -112,7 +113,11 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]:
 
 class StudentRegistrationRequested(OpenEdxPublicFilter, SensitiveDataManagementMixin):
     """
-    Filter used to modify the registration process, triggered when a user begins registration in the LMS.
+    Filter used to modify the registration process of a given user in the LMS.
+
+    Purpose:
+        This filter is triggered when a user tries to register, just before the registration process is completed
+        allowing the filter to act on the registration form data.
 
     Filter Type:
         org.openedx.learning.student.registration.requested.v1
@@ -161,10 +166,11 @@ def run_filter(cls, form_data: QueryDict) -> QueryDict:
 
 class StudentLoginRequested(OpenEdxPublicFilter):
     """
-    Filter used to modify the login process.
+    Filter used to modify the login process of a given user in the LMS.
 
-    This filter is triggered when a user tries to log in, just before the login process is completed allowing the filter
-    to act on the user object.
+    Purpose:
+        This filter is triggered when a user tries to log in, just before the login process is completed allowing the
+        filter to act on the user object.
 
     Filter Type:
         org.openedx.learning.student.login.requested.v1
@@ -217,10 +223,11 @@ def run_filter(cls, user: Any) -> Any:
 
 class CourseEnrollmentStarted(OpenEdxPublicFilter):
     """
-    Filter used to modify the course enrollment process.
+    Filter used to modify the enrollment process for a given user in a course.
 
-    This filter is triggered when a user initiates the enrollment process, just before the enrollment is completed
-    allowing the filter to act on the user, course key, and mode.
+    Purpose:
+        This filter is triggered when a user initiates the enrollment process, just before the enrollment is completed
+        allowing the filter to act on the user, course key, and mode.
 
     Filter Type:
         org.openedx.learning.course.enrollment.started.v1
@@ -264,10 +271,11 @@ def run_filter(cls, user: Any, course_key: CourseKey, mode: str) -> tuple[Any, C
 
 class CourseUnenrollmentStarted(OpenEdxPublicFilter):
     """
-    Filter used to modify the course unenrollment process.
+    Filter used to modify the unenrollment process for a given user from a course.
 
-    This filter is triggered when a user initiates the unenrollment process, just before the unenrollment is completed
-    allowing the filter to act on the user's enrollment in the course.
+    Purpose:
+        This filter is triggered when a user initiates the unenrollment process, just before the unenrollment is
+        completed allowing the filter to act on the user's enrollment in the course.
 
     Filter Type:
         org.openedx.learning.course.unenrollment.started.v1
@@ -305,10 +313,11 @@ def run_filter(cls, enrollment: Any) -> Any:
 
 class CertificateCreationRequested(OpenEdxPublicFilter):
     """
-    Filter used to modify the certificate creation process.
+    Filter used to modify the certificate creation process for a given user in a course.
 
-    This filter is triggered when a user requests a certificate, just before the certificate is created allowing the
-    filter to act on the user, course key, mode, status, grade, and generation mode.
+    Purpose:
+        This filter is triggered when a user requests a certificate, just before the certificate is created allowing the
+        filter to act on the user, course key, mode, status, grade, and generation mode.
 
     Usage:
         - Modify certificate parameters in runtime.
@@ -335,7 +344,7 @@ class PreventCertificateCreation(OpenEdxFilterException):
         """
 
     @classmethod
-    def run_filter(
+    def run_filter(  # pylint: disable=too-many-positional-arguments
         cls: type,
         user: Any,
         course_key: CourseKey,
@@ -383,10 +392,11 @@ def run_filter(
 
 class CertificateRenderStarted(OpenEdxPublicFilter):
     """
-    Filter used to modify the certificate rendering process.
+    Filter used to modify the rendering of a certificate.
 
-    This filter is triggered when a user requests to view the certificate, just before the certificate is rendered
-    allowing the filter to act on the context and the template used to render the certificate.
+    Purpose:
+        This filter is triggered when a user requests to view the certificate, just before the certificate is rendered
+        allowing the filter to act on the context and the template used to render the certificate.
 
     Filter Type:
         org.openedx.learning.certificate.render.started.v1
@@ -471,8 +481,9 @@ class CohortChangeRequested(OpenEdxPublicFilter):
     """
     Filter used to modify the cohort change process.
 
-    This filter is triggered when a user's cohort is changed, just before the change is completed allowing the filter
-    to act on the user and the target cohort.
+    Purpose:
+        This filter is triggered when a user's cohort is changed, just before the change is completed allowing the
+        filter to act on the user and the target cohort.
 
     Filter Type:
         org.openedx.learning.cohort.change.requested.v1
@@ -514,8 +525,9 @@ class CohortAssignmentRequested(OpenEdxPublicFilter):
     """
     Filter used to modify the cohort assignment process.
 
-    This filter is triggered when a user is assigned to a cohort, just before the assignment is completed allowing the
-    filter to act on the user and the target cohort.
+    Purpose:
+        This filter is triggered when a user is assigned to a cohort, just before the assignment is completed allowing
+        the filter to act on the user and the target cohort.
 
     Filter Type:
         org.openedx.learning.cohort.assignment.requested.v1
@@ -557,8 +569,9 @@ class CourseAboutRenderStarted(OpenEdxPublicFilter):
     """
     Filter used to modify the course about rendering process.
 
-    This filter is triggered when a user requests to view the course about page, just before the page is rendered
-    allowing the filter to act on the context and the template used to render the page.
+    Purpose:
+        This filter is triggered when a user requests to view the course about page, just before the page is rendered
+        allowing the filter to act on the context and the template used to render the page.
 
     Filter Type:
         org.openedx.learning.course_about.render.started.v1
@@ -654,8 +667,9 @@ class DashboardRenderStarted(OpenEdxPublicFilter):
     """
     Filter used to modify the dashboard rendering process.
 
-    This filter is triggered when a user requests to view the dashboard, just before the page is rendered allowing the
-    filter to act on the context and the template used to render the page.
+    Purpose:
+        This filter is triggered when a user requests to view the dashboard, just before the page is rendered allowing
+        the filter to act on the context and the template used to render the page.
 
     Filter Type:
         org.openedx.learning.dashboard.render.started.v1
@@ -752,8 +766,9 @@ class VerticalBlockChildRenderStarted(OpenEdxPublicFilter):
     """
     Filter used to modify the rendering of a child block within a vertical block.
 
-    This filter is triggered when a child block is about to be rendered within a vertical block, allowing the filter to
-    act on the block and the context used to render the child block.
+    Purpose:
+        This filter is triggered when a child block is about to be rendered within a vertical block, allowing the filter
+        to act on the block and the context used to render the child block.
 
     Filter Type:
         org.openedx.learning.vertical_block_child.render.started.v1
@@ -796,6 +811,10 @@ class CourseEnrollmentQuerysetRequested(OpenEdxPublicFilter):
     """
     Filter used to modify the QuerySet of course enrollments.
 
+    Purpose:
+        This filter is triggered when a QuerySet of course enrollments is requested, allowing the filter to act on the
+        enrollments data.
+
     Filter Type:
         org.openedx.learning.course_enrollment_queryset.requested.v1
 
@@ -832,8 +851,9 @@ class RenderXBlockStarted(OpenEdxPublicFilter):
     """
     Filter in between context generation and rendering of XBlock scope.
 
-    This filter is triggered when an XBlock is about to be rendered, just before the rendering process is completed
-    allowing the filter to act on the context and student_view_context used to render the XBlock.
+    Purpose:
+        This filter is triggered when an XBlock is about to be rendered, just before the rendering process is completed
+        allowing the filter to act on the context and student_view_context used to render the XBlock.
 
     Filter Type:
         org.openedx.learning.xblock.render.started.v1
@@ -892,8 +912,9 @@ class VerticalBlockRenderCompleted(OpenEdxPublicFilter):
     """
     Filter used to act on vertical block rendering completed.
 
-    This filter is triggered when a vertical block is rendered, just after the rendering process is completed allowing
-    the filter to act on the block, fragment, context, and view used to render the vertical block.
+    Purpose:
+        This filter is triggered when a vertical block is rendered, just after the rendering process is completed
+        allowing the filter to act on the block, fragment, context, and view used to render the vertical block.
 
     Filter Type:
         org.openedx.learning.vertical_block.render.completed.v1
@@ -939,8 +960,9 @@ class CourseHomeUrlCreationStarted(OpenEdxPublicFilter):
     """
     Filter used to modify the course home url creation process.
 
-    This filter is triggered when a course home url is being generated, just before the generation process is completed
-    allowing the filter to act on the course key and course home url.
+    Purpose:
+        This filter is triggered when a course home url is being generated, just before the generation process is
+        completed allowing the filter to act on the course key and course home url.
 
     Filter Type:
         org.openedx.learning.course.homepage.url.creation.started.v1
@@ -975,8 +997,9 @@ class CourseEnrollmentAPIRenderStarted(OpenEdxPublicFilter):
     """
     Filter used to modify the course enrollment API rendering process.
 
-    This filter is triggered when a user requests to view the course enrollment API, just before the API is rendered
-    allowing the filter to act on the course key and serialized enrollment data.
+    Purpose:
+        This filter is triggered when a user requests to view the course enrollment API, just before the API is rendered
+        allowing the filter to act on the course key and serialized enrollment data.
 
     Filter Type:
         org.openedx.learning.home.enrollment.api.rendered.v1
@@ -1011,8 +1034,9 @@ class CourseRunAPIRenderStarted(OpenEdxPublicFilter):
     """
     Filter used to modify the course run API rendering process.
 
-    This filter is triggered when a user requests to view the course run API, just before the API is rendered allowing
-    the filter to act on the serialized course run data.
+    Purpose:
+        This filter is triggered when a user requests to view the course run API, just before the API is rendered
+        allowing the filter to act on the serialized course run data.
 
     Filter Type:
         org.openedx.learning.home.courserun.api.rendered.started.v1
@@ -1044,8 +1068,9 @@ class InstructorDashboardRenderStarted(OpenEdxPublicFilter):
     """
     Filter used to modify the instructor dashboard rendering process.
 
-    This filter is triggered when an instructor requests to view the dashboard, just before the page is rendered
-    allowing the filter to act on the context and the template used to render the page.
+    Purpose:
+        This filter is triggered when an instructor requests to view the dashboard, just before the page is rendered
+        allowing the filter to act on the context and the template used to render the page.
 
     Filter Type:
         org.openedx.learning.instructor.dashboard.render.started.v1
@@ -1141,8 +1166,9 @@ class ORASubmissionViewRenderStarted(OpenEdxPublicFilter):
     """
     Filter used to modify the submission view rendering process.
 
-    This filter is triggered when a user requests to view the submission, just before the page is rendered allowing the
-    filter to act on the context and the template used to render the page.
+    Purpose:
+        This filter is triggered when a user requests to view the submission, just before the page is rendered allowing
+        the filter to act on the context and the template used to render the page.
 
     Filter Type:
         org.openedx.learning.ora.submission_view.render.started.v1
@@ -1198,8 +1224,9 @@ class IDVPageURLRequested(OpenEdxPublicFilter):
     """
     Filter used to act on ID verification page URL requests.
 
-    This filter is triggered when a user requests to view the ID verification page, just before the page is rendered
-    allowing the filter to act on the URL of the page.
+    Purpose:
+        This filter is triggered when a user requests to view the ID verification page, just before the page is rendered
+        allowing the filter to act on the URL of the page.
 
     Filter Type:
         org.openedx.learning.idv.page.url.requested.v1
@@ -1231,8 +1258,9 @@ class CourseAboutPageURLRequested(OpenEdxPublicFilter):
     """
     Filter used to act on course about page URL requests.
 
-    This filter is triggered when a user requests to view the course about page, just before the page is rendered
-    allowing the filter to act on the URL of the page and the course org.
+    Purpose:
+        This filter is triggered when a user requests to view the course about page, just before the page is rendered
+        allowing the filter to act on the URL of the page and the course org.
 
     Filter Type:
         org.openedx.learning.course_about.page.url.requested.v1
@@ -1267,9 +1295,10 @@ class ScheduleQuerySetRequested(OpenEdxPublicFilter):
     """
     Filter used 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
+    Purpose:
+        This filter is triggered when a QuerySet of Schedules is requested, allowing the filter to act on the schedules
+        data. If you want to know more about the Schedules feature, please refer to the official documentation:
+            - https://github.com/openedx/edx-platform/tree/master/openedx/core/djangoapps/schedules#readme
 
     Filter Type:
         org.openedx.learning.schedule.queryset.requested.v1