Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion CHANGELOG.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,14 @@ Change Log

Unreleased
----------
* Configuration for automatic filters docs generation.

[1.13.0] - 2025-01-30
---------------------

Added
~~~~~

* Use edx-lint linter for Open edX Filters classes docstrings validation.

[1.12.0] - 2024-12-12
---------------------
Expand All @@ -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
--------------------
Expand Down
38 changes: 38 additions & 0 deletions docs/reference/documenting-filters-classes.rst
Original file line number Diff line number Diff line change
@@ -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.
"""
1 change: 1 addition & 0 deletions docs/reference/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,4 @@ References
filters
django-plugins-and-filters
real-life-use-cases
documenting-filters-classes
2 changes: 1 addition & 1 deletion openedx_filters/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@
"""
from openedx_filters.filters import *

__version__ = "1.12.0"
__version__ = "1.13.0"
5 changes: 3 additions & 2 deletions openedx_filters/course_authoring/filters.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
129 changes: 79 additions & 50 deletions openedx_filters/learning/filters.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading