From 70de77328c7b22b0ea2b6b35a6f7e67a2ebd3f9c Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Tue, 7 Jan 2025 10:43:59 +0100 Subject: [PATCH 1/8] docs: enrich docstrings following a template with more details --- openedx_filters/course_authoring/filters.py | 15 +- openedx_filters/learning/filters.py | 766 ++++++++++++++------ requirements/base.in | 2 +- requirements/base.txt | 12 + requirements/dev.txt | 17 +- requirements/doc.txt | 13 + requirements/quality.txt | 17 +- requirements/test.txt | 23 +- 8 files changed, 634 insertions(+), 231 deletions(-) diff --git a/openedx_filters/course_authoring/filters.py b/openedx_filters/course_authoring/filters.py index fd8c42b2..2aa4af2d 100644 --- a/openedx_filters/course_authoring/filters.py +++ b/openedx_filters/course_authoring/filters.py @@ -7,15 +7,24 @@ class LMSPageURLRequested(OpenEdxPublicFilter): """ - Custom class used to get lms page url filters and its custom methods. + Filter used to modify the URL of the page requested by the user. + + Filter Type: + org.openedx.course_authoring.lms.page.url.requested.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: cms/djangoapps/contentstore/asset_storage_handler.py + - Function: get_asset_json """ filter_type = "org.openedx.course_authoring.lms.page.url.requested.v1" @classmethod - def run_filter(cls, url, org): + def run_filter(cls, url: str, org: str) -> tuple[str, str]: """ - Execute a filter with the signature specified. + Process the input url and org using the configured pipeline steps to modify the URL of the page requested by the + user. Arguments: url (str): the URL of the page to be modified. diff --git a/openedx_filters/learning/filters.py b/openedx_filters/learning/filters.py index 9b4b79ca..8e700620 100644 --- a/openedx_filters/learning/filters.py +++ b/openedx_filters/learning/filters.py @@ -2,9 +2,11 @@ Package where filters related to the learning architectural subdomain are implemented. """ -from typing import Optional +from typing import Any, Optional from django.db.models.query import QuerySet +from django.http import HttpResponse +from opaque_keys.edx.keys import CourseKey from openedx_filters.exceptions import OpenEdxFilterException from openedx_filters.tooling import OpenEdxPublicFilter @@ -13,39 +15,62 @@ class AccountSettingsRenderStarted(OpenEdxPublicFilter): """ - Custom class used to create Account settings filters. + Filter used to modify the rendering of the account settings page in the LMS, triggered when a user + visits 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. """ filter_type = "org.openedx.learning.student.settings.render.started.v1" class RedirectToPage(OpenEdxFilterException): """ - Custom class used to redirect before the account settings rendering process. + Raise to trigger a redirect before the account settings page is rendered. + + This exception is propagated to the account settings view and handled by the view to redirect the user to + a new page. """ - def __init__(self, message, redirect_to=""): + def __init__(self, message: str, redirect_to: str) -> None: """ - Override init that defines specific arguments used in the account settings render process. + Initialize the exception with the message and the URL to redirect to. Arguments: - message: error message for the exception. - redirect_to: URL to redirect to. + - message: error message for the exception. + - redirect_to: URL to redirect to. """ super().__init__(message, redirect_to=redirect_to) class RenderInvalidAccountSettings(OpenEdxFilterException): """ - Custom class used to stop the account settings rendering process. + Raise to render a different template instead of the account settings page. + + This exception is propagated to the account settings view and handled by the view to render a different + template instead. """ - def __init__(self, message, account_settings_template="", template_context=None): + def __init__( + self, + message: str, + account_settings_template: str = "", + template_context: Optional[dict] = None + ) -> None: """ - Override init that defines specific arguments used in the account settings render process. + Initialize the exception with the message and the template path to render instead. Arguments: - message: error message for the exception. - account_settings_template: template path rendered instead. - template_context: context used to the new account settings template. + - message: error message for the exception. + - account_settings_template: template path rendered instead. + - template_context: context used to the new account settings template. """ super().__init__( message, @@ -55,27 +80,35 @@ def __init__(self, message, account_settings_template="", template_context=None) class RenderCustomResponse(OpenEdxFilterException): """ - Custom class used to stop the account settings rendering process and return a custom response. + Raise to return a custom response instead of the usual account settings page. + + This exception is propagated to the account settings view and handled by the view to return a custom response + instead. """ - def __init__(self, message, response=None): + def __init__(self, message: str, response: Optional[dict] = None) -> None: """ - Override init that defines specific arguments used in the account settings render process. + Initialize the exception with the message and the custom response to return. Arguments: - message: error message for the exception. - response: custom response which will be returned by the account settings view. + - message: error message for the exception. + - response: custom response which will be returned by the account settings view. """ super().__init__(message, response=response) @classmethod - def run_filter(cls, context, template_name): + def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: """ - Execute a filter with the signature specified. + Process the input context and template_name using the configured pipeline steps to modify the account settings + page. Arguments: - context (dict): template context for the account settings page. - template_name (str): template path used to render the account settings page. + - context (dict): template context for the account settings page. + - template_name (str): template path used to render the account settings page. + + Returns: + - dict: context dictionary for the account settings page, possibly modified. + - str: template name to be rendered by the account settings page, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -83,27 +116,45 @@ def run_filter(cls, context, template_name): class StudentRegistrationRequested(OpenEdxPublicFilter, SensitiveDataManagementMixin): """ - Custom class used to create registration filters and its custom methods. + Filter used to modify the registration process, triggered when a user begins registration in the LMS. + + Filter Type: + org.openedx.learning.student.registration.requested.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: openedx/core/djangoapps/user_authn/views/register.py + - Function or Method: RegistrationView.post """ filter_type = "org.openedx.learning.student.registration.requested.v1" sensitive_form_data = [ - "password", "newpassword", "new_password", "oldpassword", "old_password", "new_password1", "new_password2", + "password", + "newpassword", + "new_password", + "oldpassword", + "old_password", + "new_password1", + "new_password2", ] class PreventRegistration(OpenEdxFilterException): """ - Custom class used to stop the registration process. + Raise to prevent the registration process to continue. + + This exception is propagated to the registration view and handled by the view to stop the registration process. """ @classmethod - def run_filter(cls, form_data): + def run_filter(cls, form_data: dict) -> dict: """ - Execute a filter with the signature specified. + Process the registration form data using the configured pipeline steps to modify the registration process. Arguments: - form_data (QueryDict): contains the request.data submitted by the registration - form. + - form_data (QueryDict): contains the request.data submitted by the registration form. + + Returns: + - dict: form data dictionary, possibly modified. """ sensitive_data = cls.extract_sensitive_data(form_data) data = super().run_pipeline(form_data=form_data) @@ -114,29 +165,54 @@ def run_filter(cls, form_data): class StudentLoginRequested(OpenEdxPublicFilter): """ - Custom class used to create login filters and its custom methods. + Filter used to modify the login process, triggered when a user logins. + + Filter Type: + org.openedx.learning.student.login.requested.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: openedx/core/djangoapps/user_authn/views/login.py + - Function or Method: login_user """ filter_type = "org.openedx.learning.student.login.requested.v1" class PreventLogin(OpenEdxFilterException): """ - Custom class used to stop the login process. + Raise to prevent the login process to continue. + + This exception is propagated to the login view and handled by the view to stop the login process. """ - def __init__(self, message, redirect_to=None, error_code="", context=None): + def __init__( + self, + message: str, + redirect_to: str = "", + error_code: str = "", + context: dict = None + ) -> None: """ - Override init that defines specific arguments used in the login process. + Initialize the exception with the message and the URL to redirect to. + + Arguments: + - message: error message for the exception. + - redirect_to: URL to redirect to. + - error_code: error code for the exception. + - context: context dictionary to be used in the exception. """ super().__init__(message, redirect_to=redirect_to, error_code=error_code, context=context) @classmethod - def run_filter(cls, user): + def run_filter(cls, user: Any) -> Any: """ - Execute a filter with the signature specified. + Process the user object using the configured pipeline steps to modify the login process. Arguments: - user (User): is a Django User object. + - user (User): Django User object trying to log in. + + Returns: + - User: Django User object, possibly modified. """ data = super().run_pipeline(user=user) return data.get("user") @@ -144,25 +220,41 @@ def run_filter(cls, user): class CourseEnrollmentStarted(OpenEdxPublicFilter): """ - Custom class used to create enrollment filters and its custom methods. + Filter used to modify the course enrollment process, triggered when a user initiates the enrollment. + + Filter Type: + org.openedx.learning.course.enrollment.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: common/djangoapps/student/models/course_enrollment.py + - Function or Method: enroll """ filter_type = "org.openedx.learning.course.enrollment.started.v1" class PreventEnrollment(OpenEdxFilterException): """ - Custom class used to stop the enrollment process. + Raise to prevent the enrollment process to continue. + + This exception is propagated to the course enrollment model and handled by the model to stop the enrollment + process. All components using the enroll method handle this exception in the appropriate way. """ @classmethod - def run_filter(cls, user, course_key, mode): + def run_filter(cls, user: Any, course_key: CourseKey, mode: str) -> tuple[Any, CourseKey, str]: """ - Execute a filter with the signature specified. + Process the user, course_key, and mode using the configured pipeline steps to modify the enrollment process. Arguments: - user (User): is a Django User object. - course_key (CourseKey): course key associated with the enrollment. - mode (str): is a string specifying what kind of enrollment. + - user (User): Django User enrolling in the course. + - course_key (CourseKey): course key associated with the enrollment. + - mode (str): specifies what kind of enrollment. + + Returns: + - User: Django User object. + - CourseKey: course key associated with the enrollment. + - str: mode of the enrollment. """ data = super().run_pipeline( user=user, course_key=course_key, mode=mode, @@ -172,23 +264,37 @@ def run_filter(cls, user, course_key, mode): class CourseUnenrollmentStarted(OpenEdxPublicFilter): """ - Custom class used to create unenrollment filters and its custom methods. + Filter used to modify the course unenrollment process, triggered when a user initiates the unenrollment. + + Filter Type: + org.openedx.learning.course.unenrollment.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: common/djangoapps/student/models/course_enrollment.py + - Function or Method: unenroll """ filter_type = "org.openedx.learning.course.unenrollment.started.v1" class PreventUnenrollment(OpenEdxFilterException): """ - Custom class used to stop the unenrollment process. + Raised to prevent the unenrollment process to continue. + + This exception is propagated to the course enrollment model and handled by the model to stop the unenrollment + process. All components using the unenroll method handle this exception in the appropriate way. """ @classmethod - def run_filter(cls, enrollment): + def run_filter(cls, enrollment: Any) -> Any: """ - Execute a filter with the signature specified. + Process the enrollment object using the configured pipeline steps to modify the unenrollment process. Arguments: - enrollment (CourseEnrollment): edxapp object representing course enrollments. + - enrollment (CourseEnrollment): user's enrollment in the course. + + Returns: + - CourseEnrollment: user's enrollment in the course. """ data = super().run_pipeline(enrollment=enrollment) return data.get("enrollment") @@ -196,32 +302,60 @@ def run_filter(cls, enrollment): class CertificateCreationRequested(OpenEdxPublicFilter): """ - Custom class used to create certificate creation filters and its custom methods. + Filter used to modify the certificate creation process, triggered when a certificate starts to be generated. + + Usage: + - Modify certificate parameters in runtime. + - Stop the certificate creation given a specific condition. + - Etc. + + Filter Type: + org.openedx.learning.certificate.creation.requested.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: lms/djangoapps/certificates/generated_certificate.py + - Function or Method: _generate_certificate_task """ filter_type = "org.openedx.learning.certificate.creation.requested.v1" class PreventCertificateCreation(OpenEdxFilterException): """ - Custom class used to stop the certificate creation process. + Raise to prevent the certificate creation process to continue. + + This exception is propagated from the certificate generation function and handled by the caller to stop the + certificate creation process before starting the async task. """ @classmethod - def run_filter(cls, user, course_key, mode, status, grade, generation_mode): - """ - Execute a filter with the signature specified. + def run_filter( + cls: type, + user: Any, + course_key: CourseKey, + mode: str, + status: str, + grade: float, + generation_mode: str, + ) -> tuple[Any, CourseKey, str, str, float, str]: + """ + Process the user, course_key, mode, status, grade, and generation_mode using the configured pipeline steps to Arguments: - user (User): is a Django User object. - course_key (CourseKey): course key associated with the certificate. - mode (str): mode of the certificate. - status (str): status of the certificate. - grade (CourseGrade): user's grade in this course run. - generation_mode (str): Options are "self" (implying the user generated the cert themself) and "batch" - for everything else. + - user (User): Django User object. + - course_key (CourseKey): course key associated with the certificate. + - mode (str): specifies what kind of certificate. + - status (str): specifies the status of the certificate. + - grade (float): grade of the certificate. + - generation_mode (str): specifies the mode of generation. """ data = super().run_pipeline( - user=user, course_key=course_key, mode=mode, status=status, grade=grade, generation_mode=generation_mode, + user=user, + course_key=course_key, + mode=mode, + status=status, + grade=grade, + generation_mode=generation_mode, ) return ( data.get("user"), @@ -235,53 +369,69 @@ def run_filter(cls, user, course_key, mode, status, grade, generation_mode): class CertificateRenderStarted(OpenEdxPublicFilter): """ - Custom class used to create certificate render filters and its custom methods. + Filter used to modify the certificate rendering process, triggered when a user begins rendering a certificate. + + Filter Type: + org.openedx.learning.certificate.render.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: lms/djangoapps/certificates/views/webview.py + - Function or Method: render_html_view """ filter_type = "org.openedx.learning.certificate.render.started.v1" class RedirectToPage(OpenEdxFilterException): """ - Custom class used to stop the certificate rendering process. + Raise to redirect to a different page instead of rendering the certificate. + + This exception is propagated to the certificate view and handled by the view to redirect the user to a new page. """ - def __init__(self, message, redirect_to=""): + def __init__(self, message: str, redirect_to: str = "") -> None: """ - Override init that defines specific arguments used in the certificate render process. + Initialize the exception with the message and the URL to redirect to. Arguments: - message: error message for the exception. - redirect_to: URL to redirect to. + - message: error message for the exception. + - redirect_to: URL to redirect to. """ super().__init__(message, redirect_to=redirect_to) class RenderAlternativeInvalidCertificate(OpenEdxFilterException): """ - Custom class used to stop the certificate rendering process. + Raise to render a different certificate template instead of the default one. + + This exception is propagated to the certificate view and handled by the view to render a different template + instead. """ - def __init__(self, message, template_name=""): + def __init__(self, message: str, template_name: str = "") -> None: """ - Override init that defines specific arguments used in the certificate render process. + Initialize the exception with the message and the template path to render instead. Arguments: - message: error message for the exception. - template_name: template path of the new certificate. + - message: error message for the exception. + - template_name: template path of the new certificate. """ super().__init__(message, template_name=template_name) class RenderCustomResponse(OpenEdxFilterException): """ - Custom class used to stop the certificate rendering process. + Raise to stop the certificate rendering process and return a custom response. + + This exception is propagated to the certificate view and handled by the view to return a custom response + instead. """ - def __init__(self, message, response=None): + def __init__(self, message: str, response: HttpResponse) -> None: """ - Override init that defines specific arguments used in the certificate render process. + Initialize the exception with the message and the custom response to return. Arguments: - message: error message for the exception. - response: custom response which will be returned by the certificate view. + - message: error message for the exception. + - response: custom response which will be returned by the certificate view. """ super().__init__( message, @@ -289,14 +439,13 @@ def __init__(self, message, response=None): ) @classmethod - def run_filter(cls, context, custom_template): + def run_filter(cls, context: dict, custom_template: Any) -> tuple[dict, Any]: """ - Execute a filter with the signature specified. + Process the context and custom_template using the configured pipeline steps to modify the certificate rendering. Arguments: - context (dict): context dictionary for certificate template. - custom_template (CertificateTemplate): edxapp object representing custom web - certificate template. + - context (dict): context dictionary for certificate template. + - custom_template (CertificateTemplate): custom web certificate template. """ data = super().run_pipeline(context=context, custom_template=custom_template) return data.get("context"), data.get("custom_template") @@ -304,25 +453,35 @@ def run_filter(cls, context, custom_template): class CohortChangeRequested(OpenEdxPublicFilter): """ - Custom class used to create cohort change filters and its custom methods. + Filter used to modify the cohort change process, triggered when a user changes cohorts. + + Filter Type: + org.openedx.learning.cohort.change.requested.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: openedx/core/djangoapps/course_groups/models.py + - Function or Method: assign """ filter_type = "org.openedx.learning.cohort.change.requested.v1" class PreventCohortChange(OpenEdxFilterException): """ - Custom class used to stop the cohort change process. + Raise to prevent the cohort change process to continue. + + This exception is propagated to the assign method and handled by it to stop the cohort change process. """ @classmethod - def run_filter(cls, current_membership, target_cohort): + def run_filter(cls, current_membership: Any, target_cohort: Any) -> tuple[Any, Any]: """ - Execute a filter with the signature specified. + Process the current_membership and target_cohort using the configured pipeline steps to modify the cohort + change process. Arguments: - current_membership (CohortMembership): edxapp object representing the user's cohort - current membership object. - target_cohort (CourseUserGroup): edxapp object representing the new user's cohort. + - current_membership (CohortMembership): CohortMembership instance representing the current user's cohort. + - target_cohort (CourseUserGroup): CourseUserGroup instance representing the new user's cohort. """ data = super().run_pipeline(current_membership=current_membership, target_cohort=target_cohort) return data.get("current_membership"), data.get("target_cohort") @@ -330,24 +489,34 @@ def run_filter(cls, current_membership, target_cohort): class CohortAssignmentRequested(OpenEdxPublicFilter): """ - Custom class used to create cohort assignment filters and its custom methods. + Filter used to modify the cohort assignment process, triggered when a user is assigned to a new cohort. + + Filter Type: + org.openedx.learning.cohort.assignment.requested.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: openedx/core/djangoapps/course_groups/models.py + - Function or Method: assign """ filter_type = "org.openedx.learning.cohort.assignment.requested.v1" class PreventCohortAssignment(OpenEdxFilterException): """ - Custom class used to stop the cohort assignment process. + Raise to prevent the cohort assignment process to continue. + + This exception is propagated to the assign method and handled by it to stop the cohort assignment process. """ @classmethod - def run_filter(cls, user, target_cohort): + def run_filter(cls, user: Any, target_cohort: Any) -> tuple[Any, Any]: """ - Execute a filter with the signature specified. + Process the user and target_cohort using the configured pipeline steps to modify the cohort assignment process. Arguments: - user (User): is a Django User object to be added in the cohort. - target_cohort (CourseUserGroup): edxapp object representing the new user's cohort. + - user (User): Django User object representing the new user. + - target_cohort (CourseUserGroup): CourseUserGroup instance representing the new user's cohort. """ data = super().run_pipeline(user=user, target_cohort=target_cohort) return data.get("user"), data.get("target_cohort") @@ -355,39 +524,54 @@ def run_filter(cls, user, target_cohort): class CourseAboutRenderStarted(OpenEdxPublicFilter): """ - Custom class used to create course about render filters and its custom methods. + Filter used to modify the course about rendering process, triggered when a user requests to view the course about + page. + + Filter Type: + org.openedx.learning.course_about.render.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: lms/djangoapps/courseware/views/views.py + - Function or Method: course_about """ filter_type = "org.openedx.learning.course_about.render.started.v1" class RedirectToPage(OpenEdxFilterException): """ - Custom class used to stop the course about rendering process. + Raise to redirect to a different page instead of rendering the course about. + + This exception is propagated to the course about view and handled by the view to redirect the user to a new + page. """ - def __init__(self, message, redirect_to=""): + def __init__(self, message: str, redirect_to: str = "") -> None: """ - Override init that defines specific arguments used in the course about render process. + Initialize the exception with the message and the URL to redirect to. Arguments: - message: error message for the exception. - redirect_to: URL to redirect to. + - message: error message for the exception. + - redirect_to: URL to redirect to. """ super().__init__(message, redirect_to=redirect_to) class RenderInvalidCourseAbout(OpenEdxFilterException): """ - Custom class used to stop the course about rendering process. + Raise to render a different course about template instead of the default one. + + This exception is propagated to the course about view and handled by the view to render a different template + instead. """ - def __init__(self, message, course_about_template="", template_context=None): + def __init__(self, message: str, course_about_template: str = "", template_context: dict = None) -> None: """ - Override init that defines specific arguments used in the course about render process. + Initialize the exception with the message and the template to render instead. Arguments: - message: error message for the exception. - course_about_template: template path rendered instead. - template_context: context used to the new course_about_template. + - message: error message for the exception. + - course_about_template: template path rendered instead. + - template_context: context used to the new course_about_template. """ super().__init__( message, @@ -397,16 +581,19 @@ def __init__(self, message, course_about_template="", template_context=None): class RenderCustomResponse(OpenEdxFilterException): """ - Custom class used to stop the course about rendering process. + Raise to stop the course about rendering process and return a custom response. + + This exception is propagated to the course about view and handled by the view to return a custom response + instead. """ - def __init__(self, message, response=None): + def __init__(self, message: str, response: HttpResponse) -> None: """ - Override init that defines specific arguments used in the course about render process. + Initialize the exception with the message and the custom response to return. Arguments: - message: error message for the exception. - response: custom response which will be returned by the course about view. + - message: error message for the exception. + - response: custom response which will be returned by the course about view. """ super().__init__( message, @@ -414,13 +601,13 @@ def __init__(self, message, response=None): ) @classmethod - def run_filter(cls, context, template_name): + def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: """ - Execute a filter with the signature specified. + Process the context and template_name using the configured pipeline steps to modify the course about rendering. Arguments: - context (dict): context dictionary for course about template. - template_name (str): template name to be rendered by the course about. + - context (dict): context dictionary for course about template. + - template_name (str): template name to be rendered by the course about. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -428,39 +615,54 @@ def run_filter(cls, context, template_name): class DashboardRenderStarted(OpenEdxPublicFilter): """ - Custom class used to create dashboard render filters and its custom methods. + Filter used to modify the dashboard rendering process, triggered when a user requests to view the student dashboard. + + Filter Type: + org.openedx.learning.dashboard.render.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: common/djangoapps/student/views/dashboard.py + - Function or Method: student_dashboard + + Additional Information: + This filter doesn't work alongside the dashboard MFE, only with the legacy student dashboard. """ filter_type = "org.openedx.learning.dashboard.render.started.v1" class RedirectToPage(OpenEdxFilterException): """ - Custom class used to stop the dashboard rendering process. + Raise to redirect to a different page instead of rendering the dashboard. + + This exception is propagated to the dashboard view and handled by the view to redirect the user to a new page. """ - def __init__(self, message, redirect_to=""): + def __init__(self, message: str, redirect_to: str = "") -> None: """ - Override init that defines specific arguments used in the dashboard render process. + Initialize the exception with the message and the URL to redirect to. Arguments: - message: error message for the exception. - redirect_to: URL to redirect to. + - message: error message for the exception. + - redirect_to: URL to redirect to. """ super().__init__(message, redirect_to=redirect_to) class RenderInvalidDashboard(OpenEdxFilterException): """ - Custom class used to stop the dashboard render process. + Raise to render a different dashboard template instead of the default one. + + This exception is propagated to the dashboard view and handled by the view to render a different template """ - def __init__(self, message, dashboard_template="", template_context=None): + def __init__(self, message: str, dashboard_template: str = "", template_context: dict = None) -> None: """ - Override init that defines specific arguments used in the dashboard render process. + Initialize the exception with the message and the template to render instead. Arguments: - message: error message for the exception. - dashboard_template: template path rendered instead. - template_context: context used to the new dashboard_template. + - message: error message for the exception. + - dashboard_template: template path rendered instead. + - template_context: context used to the new dashboard_template. """ super().__init__( message, @@ -470,16 +672,18 @@ def __init__(self, message, dashboard_template="", template_context=None): class RenderCustomResponse(OpenEdxFilterException): """ - Custom class used to stop the dashboard rendering process. + Raise to stop the dashboard rendering process and return a custom response. + + This exception is propagated to the dashboard view and handled by the view to return a custom response instead. """ - def __init__(self, message, response=None): + def __init__(self, message: str, response: HttpResponse = None) -> None: """ - Override init that defines specific arguments used in the dashboard render process. + Initialize the exception with the message and the custom response to return. Arguments: - message: error message for the exception. - response: custom response which will be returned by the dashboard view. + - message: error message for the exception. + - response: custom response which will be returned by the dashboard view. """ super().__init__( message, @@ -487,13 +691,13 @@ def __init__(self, message, response=None): ) @classmethod - def run_filter(cls, context, template_name): + def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: """ - Execute a filter with the signature specified. + Process the context and template_name using the configured pipeline steps to modify the dashboard rendering. Arguments: - context (dict): context dictionary for student's dashboard template. - template_name (str): template name to be rendered by the student's dashboard. + - context (dict): context dictionary for student's dashboard template. + - template_name (str): template name to be rendered by the student's dashboard. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -501,24 +705,36 @@ def run_filter(cls, context, template_name): class VerticalBlockChildRenderStarted(OpenEdxPublicFilter): """ - Custom class used to create vertical block children's render filters. + Filter used to modify the rendering of a child block within a vertical block, triggered when a child block starts + rendering. + + Filter Type: + org.openedx.learning.vertical_block_child.render.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: xmodule/vertical_block.py + - Function or Method: VerticalBlock._student_or_public_view """ filter_type = "org.openedx.learning.vertical_block_child.render.started.v1" class PreventChildBlockRender(OpenEdxFilterException): """ - Custom class used to stop a particular child block from being rendered. + Raise to prevent a child block from rendering. + + This exception is propagated to the vertical block view and handled by the view to stop the rendering of the + child block. """ @classmethod - def run_filter(cls, block, context): + def run_filter(cls, block: Any, context: dict) -> tuple[Any, dict]: """ - Execute a filter with the signature specified. + Process the block and context using the configured pipeline steps to modify the rendering of a child block. Arguments: - block (XBlock): the XBlock that is about to be rendered into HTML - context (dict): rendering context values like is_mobile_app, show_title..etc + - block (XBlock): the XBlock that is about to be rendered into HTML + - context (dict): rendering context values like is_mobile_app, show_title..etc """ data = super().run_pipeline(block=block, context=context) return data.get("block"), data.get("context") @@ -526,23 +742,32 @@ def run_filter(cls, block, context): class CourseEnrollmentQuerysetRequested(OpenEdxPublicFilter): """ - Custom class used to create course enrollments queryset filters and its custom methods. + Filter used to modify the QuerySet of course enrollments. + + Filter Type: + org.openedx.learning.course_enrollment_queryset.requested.v1 + + Trigger: NA + + Additional Information: + This filter is not currently triggered by any specific function or method in any codebase. It should be + marked to be removed if it's not used. See openedx-filters#245 for more information. """ filter_type = "org.openedx.learning.course_enrollment_queryset.requested.v1" class PreventEnrollmentQuerysetRequest(OpenEdxFilterException): """ - Custom class used to stop the course enrollment queryset request process. + Raise to prevent the course enrollment queryset request to continue. """ @classmethod - def run_filter(cls, enrollments): + def run_filter(cls, enrollments: QuerySet) -> QuerySet: """ - Execute a filter with the signature specified. + Process the enrollments QuerySet using the configured pipeline steps to modify the course enrollment data. Arguments: - enrollments (QuerySet): data with all user's course enrollments + - enrollments (QuerySet): data with all user's course enrollments """ data = super().run_pipeline(enrollments=enrollments) return data.get("enrollments") @@ -551,23 +776,37 @@ def run_filter(cls, enrollments): class RenderXBlockStarted(OpenEdxPublicFilter): """ Filter in between context generation and rendering of XBlock scope. + + Filter Type: + org.openedx.learning.xblock.render.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: lms/djangoapps/courseware/views/views.py + - Function or Method: render_xblock """ filter_type = "org.openedx.learning.xblock.render.started.v1" class PreventXBlockBlockRender(OpenEdxFilterException): """ - Custom class used to prevent the XBlock from rendering for the user. + Raise to prevent the XBlock from rendering for the user. + + This exception is propagated to the XBlock render view and handled by the view to stop the rendering of the + XBlock. """ class RenderCustomResponse(OpenEdxFilterException): """ - Custom class used to stop the XBlock rendering process and return a custom response. + Raise to stop the XBlock rendering process by returning a custom response. + + This exception is propagated to the XBlock render view and handled by the view to return a custom response + instead. """ - def __init__(self, message, response=None): + def __init__(self, message: str, response: HttpResponse = None): """ - Override init that defines specific arguments used in the XBlock render process. + Initialize the exception with the message and the custom response to return. Arguments: message: error message for the exception. @@ -576,13 +815,14 @@ def __init__(self, message, response=None): super().__init__(message, response=response) @classmethod - def run_filter(cls, context, student_view_context): + def run_filter(cls, context: dict, student_view_context: dict): """ - Execute a filter with the specified signature. + Process the context and student_view_context using the configured pipeline steps to modify the rendering of an + XBlock. Arguments: - context (dict): rendering context values like is_mobile_app, show_title, etc. - student_view_context (dict): context passed to the student_view of the block context + - context (dict): rendering context values like is_mobile_app, show_title, etc. + - student_view_context (dict): context passed to the student_view of the block context """ data = super().run_pipeline(context=context, student_view_context=student_view_context) return data.get("context"), data.get("student_view_context") @@ -590,26 +830,38 @@ def run_filter(cls, context, student_view_context): class VerticalBlockRenderCompleted(OpenEdxPublicFilter): """ - Custom class used to create filters to act on vertical block rendering completed. + Filter used to act on vertical block rendering completed. + + Filter Type: + org.openedx.learning.vertical_block.render.completed.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: xmodule/vertical_block.py + - Function or Method: VerticalBlock._student_or_public_view """ filter_type = "org.openedx.learning.vertical_block.render.completed.v1" class PreventVerticalBlockRender(OpenEdxFilterException): """ - Custom class used to prevent the vertical block from rendering for the user. + Raise to prevent the vertical block from rendering for the user. + + This exception is propagated to the vertical block view and handled by the view to stop the rendering of the + vertical block. """ @classmethod - def run_filter(cls, block, fragment, context, view): + def run_filter(cls, block: Any, fragment: Any, context: dict, view: str) -> tuple[Any, Any, dict, str]: """ - Execute a filter with the specified signature. + Process the block, fragment, context, and view using the configured pipeline steps to modify the rendering of a + vertical block. Arguments: - block (VerticalBlock): The VeriticalBlock instance which is being rendered - fragment (web_fragments.Fragment): The web-fragment containing the rendered content of VerticalBlock - context (dict): rendering context values like is_mobile_app, show_title..etc., - view (str): the rendering view. Can be either 'student_view', or 'public_view' + - block (VerticalBlock): The VeriticalBlock instance which is being rendered. + - fragment (web_fragments.Fragment): The web-fragment containing the rendered content of VerticalBlock. + - context (dict): rendering context values like is_mobile_app, show_title..etc. + - view (str): the rendering view. Can be either 'student_view', or 'public_view'. """ data = super().run_pipeline(block=block, fragment=fragment, context=context, view=view) return data.get("block"), data.get("fragment"), data.get("context"), data.get("view") @@ -617,15 +869,23 @@ def run_filter(cls, block, fragment, context, view): class CourseHomeUrlCreationStarted(OpenEdxPublicFilter): """ - Custom class used to create filters to act on course home url creation. + Filter used to modify the course home url creation process. + + Filter Type: + org.openedx.learning.course.homepage.url.creation.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: openedx/features/course_experience/__init__.py + - Function or Method: course_home_url """ filter_type = "org.openedx.learning.course.homepage.url.creation.started.v1" @classmethod - def run_filter(cls, course_key, course_home_url): + def run_filter(cls, course_key: CourseKey, course_home_url: str) -> tuple[CourseKey, str]: """ - Execute a filter with the specified signature. + Process the course_key and course_home_url using the configured pipeline steps to modify the course home url. Arguments: course_key (CourseKey): The course key for which the home url is being requested. @@ -637,15 +897,24 @@ def run_filter(cls, course_key, course_home_url): class CourseEnrollmentAPIRenderStarted(OpenEdxPublicFilter): """ - Custom class used to create filters for enrollment data. + Filter used to modify the course enrollment API rendering process. + + Filter Type: + org.openedx.learning.home.enrollment.api.rendered.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: lms/djangoapps/learner_home/serializers.py + - Function or Method: EnrollmentSerializer.to_representation """ filter_type = "org.openedx.learning.home.enrollment.api.rendered.v1" @classmethod - def run_filter(cls, course_key, serialized_enrollment): + def run_filter(cls, course_key: CourseKey, serialized_enrollment: dict) -> tuple[CourseKey, dict]: """ - Execute a filter with the specified signature. + Process the course_key and serialized_enrollment using the configured pipeline steps to modify the course + enrollment data. Arguments: course_key (CourseKey): The course key for which isStarted is being modify. @@ -657,18 +926,26 @@ def run_filter(cls, course_key, serialized_enrollment): class CourseRunAPIRenderStarted(OpenEdxPublicFilter): """ - Custom class used to create filters for course run data. + Filter used to modify the course run API rendering process. + + Filter Type: + org.openedx.learning.home.courserun.api.rendered.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: lms/djangoapps/learner_home/serializers.py + - Function or Method: CourseRunSerializer.to_representation """ filter_type = "org.openedx.learning.home.courserun.api.rendered.started.v1" @classmethod - def run_filter(cls, serialized_courserun): + def run_filter(cls, serialized_courserun: dict) -> dict: """ - Execute a filter with the specified signature. + Process the serialized_courserun using the configured pipeline steps to modify the course run data. Arguments: - serialized_courserun (dict): courserun data + serialized_courserun (dict): courserun data. """ data = super().run_pipeline(serialized_courserun=serialized_courserun) return data.get("serialized_courserun") @@ -676,39 +953,53 @@ def run_filter(cls, serialized_courserun): class InstructorDashboardRenderStarted(OpenEdxPublicFilter): """ - Custom class used to create instructor dashboard filters and its custom methods. + Filter used to modify the instructor dashboard rendering process. + + Filter Type: + org.openedx.learning.instructor.dashboard.render.started.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: lms/djangoapps/instructor/views/instructor_dashboard.py + - Function or Method: instructor_dashboard_2 """ filter_type = "org.openedx.learning.instructor.dashboard.render.started.v1" class RedirectToPage(OpenEdxFilterException): """ - Custom class used to stop the instructor dashboard render by redirecting to a new page. + Raise to redirect to a different page instead of rendering the instructor dashboard. + + This exception is propagated to the instructor dashboard view and handled by the view to redirect the user to a + new page. """ - def __init__(self, message, redirect_to=""): + def __init__(self, message: str, redirect_to: str = ""): """ - Override init that defines specific arguments used in the instructor dashboard render process. + Initialize the exception with the message and the URL to redirect to. Arguments: - message: error message for the exception. - redirect_to: URL to redirect to. + - message: error message for the exception. + - redirect_to: URL to redirect to. """ super().__init__(message, redirect_to=redirect_to) class RenderInvalidDashboard(OpenEdxFilterException): """ - Custom class used to render a custom template instead of the instructor dashboard. + Raise to render a different instructor dashboard template instead of the default one. + + This exception is propagated to the instructor dashboard view and handled by the view to render a different + template instead. """ - def __init__(self, message, instructor_template="", template_context=None): + def __init__(self, message: str, instructor_template: str = "", template_context: dict = None): """ - Override init that defines specific arguments used in the instructor dashboard render process. + Initialize the exception with the message and the template to render instead. Arguments: - message: error message for the exception. - instructor_template: template path rendered instead. - template_context: context used to the new instructor_template. + - message: error message for the exception. + - instructor_template: template path rendered instead. + - template_context: context used to the new instructor_template. """ super().__init__( message, @@ -718,16 +1009,19 @@ def __init__(self, message, instructor_template="", template_context=None): class RenderCustomResponse(OpenEdxFilterException): """ - Custom class used to stop the instructor dashboard rendering by returning a custom response. + Raise to stop the instructor dashboard rendering process and return a custom response. + + This exception is propagated to the instructor dashboard view and handled by the view to return a custom + response instead. """ - def __init__(self, message, response=None): + def __init__(self, message: str, response: HttpResponse = None): """ - Override init that defines specific arguments used in the instructor dashboard render process. + Initialize the exception with the message and the custom response to return. Arguments: - message: error message for the exception. - response: custom response which will be returned by the dashboard view. + - message: error message for the exception. + - response: custom response which will be returned by the dashboard view. """ super().__init__( message, @@ -735,13 +1029,16 @@ def __init__(self, message, response=None): ) @classmethod - def run_filter(cls, context, template_name): + def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: """ - Execute a filter with the signature specified. + Process the context and template_name using the configured pipeline steps to modify the instructor dashboard. Arguments: - context (dict): context dictionary for instructor's tab template. - template_name (str): template name to be rendered by the instructor's tab. + - context (dict): context dictionary for instructor's tab template. + - template_name (str): template name to be rendered by the instructor's tab. + + Returns: + - tuple: context dictionary and template name. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -749,31 +1046,42 @@ def run_filter(cls, context, template_name): class ORASubmissionViewRenderStarted(OpenEdxPublicFilter): """ - Custom class used to create ORA submission view filters and its custom methods. + Filter used to modify the submission view rendering process. + + Filter Type: + org.openedx.learning.ora.submission_view.render.started.v1 + + Trigger: + - Repository: openedx/edx-ora2 + - Path: openassessment/xblock/ui_mixins/legacy/views/submission.py + - Function or Method: render_submission """ filter_type = "org.openedx.learning.ora.submission_view.render.started.v1" class RenderInvalidTemplate(OpenEdxFilterException): """ - Custom class used to stop the submission view render process. + Raise to render a different submission view template instead of the default one. + + This exception is propagated to the submission view and handled by the view to render a different template + instead. """ - def __init__(self, message: str, context: Optional[dict] = None, template_name: str = ""): + def __init__(self, message: str, context: Optional[dict] = None, template_name: str = "") -> None: """ - Override init that defines specific arguments used in the submission view render process. + Initialize the exception with the message and the template to render instead. Arguments: - message (str): error message for the exception. - context (dict): context used to the submission view template. - template_name (str): template path rendered instead. + - message (str): error message for the exception. + - context (dict): context used to the submission view template. + - template_name (str): template path rendered instead. """ super().__init__(message, context=context, template_name=template_name) @classmethod - def run_filter(cls, context: dict, template_name: str): + def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: """ - Execute a filter with the signature specified. + Process the context and template_name using the configured pipeline steps to modify the submission view. Arguments: context (dict): context dictionary for submission view template. @@ -785,18 +1093,26 @@ def run_filter(cls, context: dict, template_name: str): class IDVPageURLRequested(OpenEdxPublicFilter): """ - Custom class used to create filters to act on ID verification page URL requests. + Filter used to act on ID verification page URL requests. + + Filter Type: + org.openedx.learning.idv.page.url.requested.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: lms/djangoapps/verify_student/services.py + - Function or Method: XBlockVerificationService.get_verify_location """ filter_type = "org.openedx.learning.idv.page.url.requested.v1" @classmethod - def run_filter(cls, url: str): + def run_filter(cls, url: str) -> str: """ - Execute a filter with the specified signature. + Process the URL using the configured pipeline steps to modify the ID verification page URL. Arguments: - url (str): The url for the ID verification page to be modified. + - url (str): The url for the ID verification page to be modified. """ data = super().run_pipeline(url=url) return data.get("url") @@ -804,19 +1120,19 @@ def run_filter(cls, url: str): class CourseAboutPageURLRequested(OpenEdxPublicFilter): """ - Custom class used to get course about page url filters and its custom methods. + Filter used to act on course about page URL requests. """ filter_type = "org.openedx.learning.course_about.page.url.requested.v1" @classmethod - def run_filter(cls, url, org): + def run_filter(cls, url: str, org: str) -> tuple[str, str]: """ - Execute a filter with the specified signature. + Process the URL and org using the configured pipeline steps to modify the course about page URL. Arguments: - url (str): the URL of the page to be modified. - org (str): Course org filter used as context data to get LMS configurations. + - url (str): the URL of the page to be modified. + - org (str): Course org filter used as context data to get LMS configurations. """ data = super().run_pipeline(url=url, org=org) return data.get("url"), data.get("org") @@ -824,11 +1140,19 @@ def run_filter(cls, url, org): class ScheduleQuerySetRequested(OpenEdxPublicFilter): """ - Filter class designed to apply additional filtering to a given QuerySet of Schedules. + 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 + - 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 + + Trigger: + - Repository: openedx/edx-platform + - Path: openedx/core/djangoapps/schedules/resolvers.py + - Function or Method: BinnedSchedulesBaseResolver.get_schedules_with_target_date_by_bin_and_orgs """ filter_type = "org.openedx.learning.schedule.queryset.requested.v1" @@ -836,17 +1160,13 @@ class ScheduleQuerySetRequested(OpenEdxPublicFilter): @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. + Process the schedules QuerySet using the configured pipeline steps to modify the schedules data. Arguments: - schedules (QuerySet): The original QuerySet of schedules to be filtered. + - schedules (QuerySet): The original QuerySet of schedules to be filtered. Returns: - QuerySet: A refined QuerySet of schedules after applying the filter. + - QuerySet: A refined QuerySet of schedules after applying the filter. """ data = super().run_pipeline(schedules=schedules) return data.get("schedules") diff --git a/requirements/base.in b/requirements/base.in index 5742db52..7ef98f4f 100644 --- a/requirements/base.in +++ b/requirements/base.in @@ -2,4 +2,4 @@ -c constraints.txt django - +edx-opaque-keys[django] diff --git a/requirements/base.txt b/requirements/base.txt index 187925c8..d49dc21f 100644 --- a/requirements/base.txt +++ b/requirements/base.txt @@ -10,5 +10,17 @@ django==4.2.17 # via # -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt # -r requirements/base.in +dnspython==2.7.0 + # via pymongo +edx-opaque-keys[django]==2.11.0 + # via -r requirements/base.in +pbr==6.1.0 + # via stevedore +pymongo==4.10.1 + # via edx-opaque-keys sqlparse==0.5.3 # via django +stevedore==5.4.0 + # via edx-opaque-keys +typing-extensions==4.12.2 + # via edx-opaque-keys diff --git a/requirements/dev.txt b/requirements/dev.txt index 8081c73e..7ab495a7 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -86,12 +86,18 @@ django==4.2.17 # via # -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt # -r requirements/quality.txt +dnspython==2.7.0 + # via + # -r requirements/quality.txt + # pymongo docutils==0.21.2 # via # -r requirements/quality.txt # readme-renderer edx-lint==5.4.1 # via -r requirements/quality.txt +edx-opaque-keys[django]==2.11.0 + # via -r requirements/quality.txt filelock==3.16.1 # via # -r requirements/ci.txt @@ -232,6 +238,10 @@ pylint-plugin-utils==0.8.2 # -r requirements/quality.txt # pylint-celery # pylint-django +pymongo==4.10.1 + # via + # -r requirements/quality.txt + # edx-opaque-keys pyproject-api==1.8.0 # via # -r requirements/ci.txt @@ -299,6 +309,7 @@ stevedore==5.4.0 # via # -r requirements/quality.txt # code-annotations + # edx-opaque-keys text-unidecode==1.3 # via # -r requirements/quality.txt @@ -311,7 +322,11 @@ tox==4.23.2 # via -r requirements/ci.txt twine==6.0.1 # via -r requirements/quality.txt -urllib3==2.2.3 +typing-extensions==4.12.2 + # via + # -r requirements/quality.txt + # edx-opaque-keys +urllib3==2.3.0 # via # -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt # -r requirements/quality.txt diff --git a/requirements/doc.txt b/requirements/doc.txt index fe4939b5..f6fd943a 100644 --- a/requirements/doc.txt +++ b/requirements/doc.txt @@ -53,6 +53,10 @@ django==4.2.17 # via # -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt # -r requirements/test.txt +dnspython==2.7.0 + # via + # -r requirements/test.txt + # pymongo doc8==1.1.2 # via -r requirements/doc.in docutils==0.21.2 @@ -62,6 +66,8 @@ docutils==0.21.2 # readme-renderer # restructuredtext-lint # sphinx +edx-opaque-keys[django]==2.11.0 + # via -r requirements/test.txt h11==0.14.0 # via uvicorn idna==3.10 @@ -136,6 +142,10 @@ pygments==2.19.1 # readme-renderer # rich # sphinx +pymongo==4.10.1 + # via + # -r requirements/test.txt + # edx-opaque-keys pyproject-hooks==1.2.0 # via build pytest==8.3.4 @@ -221,6 +231,7 @@ stevedore==5.4.0 # -r requirements/test.txt # code-annotations # doc8 + # edx-opaque-keys text-unidecode==1.3 # via # -r requirements/test.txt @@ -229,7 +240,9 @@ twine==6.0.1 # via -r requirements/doc.in typing-extensions==4.12.2 # via + # -r requirements/test.txt # anyio + # edx-opaque-keys # pydata-sphinx-theme urllib3==2.2.3 # via diff --git a/requirements/quality.txt b/requirements/quality.txt index 399e313b..d63ff593 100644 --- a/requirements/quality.txt +++ b/requirements/quality.txt @@ -46,10 +46,16 @@ django==4.2.17 # via # -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt # -r requirements/test.txt +dnspython==2.7.0 + # via + # -r requirements/test.txt + # pymongo docutils==0.21.2 # via readme-renderer edx-lint==5.4.1 # via -r requirements/quality.in +edx-opaque-keys[django]==2.11.0 + # via -r requirements/test.txt idna==3.10 # via requests importlib-metadata==8.5.0 @@ -135,6 +141,10 @@ pylint-plugin-utils==0.8.2 # via # pylint-celery # pylint-django +pymongo==4.10.1 + # via + # -r requirements/test.txt + # edx-opaque-keys pytest==8.3.4 # via # -r requirements/test.txt @@ -178,6 +188,7 @@ stevedore==5.4.0 # via # -r requirements/test.txt # code-annotations + # edx-opaque-keys text-unidecode==1.3 # via # -r requirements/test.txt @@ -186,7 +197,11 @@ tomlkit==0.13.2 # via pylint twine==6.0.1 # via -r requirements/quality.in -urllib3==2.2.3 +typing-extensions==4.12.2 + # via + # -r requirements/test.txt + # edx-opaque-keys +urllib3==2.3.0 # via # -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt # requests diff --git a/requirements/test.txt b/requirements/test.txt index ceacf161..63c39f40 100644 --- a/requirements/test.txt +++ b/requirements/test.txt @@ -20,6 +20,12 @@ django==4.2.17 # via # -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt # -r requirements/base.txt +dnspython==2.7.0 + # via + # -r requirements/base.txt + # pymongo +edx-opaque-keys[django]==2.11.0 + # via -r requirements/base.txt iniconfig==2.0.0 # via pytest jinja2==3.1.5 @@ -29,9 +35,15 @@ markupsafe==3.0.2 packaging==24.2 # via pytest pbr==6.1.0 - # via stevedore + # via + # -r requirements/base.txt + # stevedore pluggy==1.5.0 # via pytest +pymongo==4.10.1 + # via + # -r requirements/base.txt + # edx-opaque-keys pytest==8.3.4 # via # pytest-cov @@ -49,6 +61,13 @@ sqlparse==0.5.3 # -r requirements/base.txt # django stevedore==5.4.0 - # via code-annotations + # via + # -r requirements/base.txt + # code-annotations + # edx-opaque-keys text-unidecode==1.3 # via python-slugify +typing-extensions==4.12.2 + # via + # -r requirements/base.txt + # edx-opaque-keys From 8158eabfba7dbf57cc66a3343c47e37743627763 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Wed, 8 Jan 2025 13:55:37 +0100 Subject: [PATCH 2/8] refactor: address quality issues --- openedx_filters/course_authoring/filters.py | 6 +- openedx_filters/learning/filters.py | 427 ++++++++++++-------- 2 files changed, 264 insertions(+), 169 deletions(-) diff --git a/openedx_filters/course_authoring/filters.py b/openedx_filters/course_authoring/filters.py index 2aa4af2d..57dfd104 100644 --- a/openedx_filters/course_authoring/filters.py +++ b/openedx_filters/course_authoring/filters.py @@ -9,6 +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. + Filter Type: org.openedx.course_authoring.lms.page.url.requested.v1 @@ -23,8 +26,7 @@ class LMSPageURLRequested(OpenEdxPublicFilter): @classmethod def run_filter(cls, url: str, org: str) -> tuple[str, str]: """ - Process the input url and org using the configured pipeline steps to modify the URL of the page requested by the - user. + Process the inputs using the configured pipeline steps to modify the URL of the page requested by the user. Arguments: url (str): the URL of the page to be modified. diff --git a/openedx_filters/learning/filters.py b/openedx_filters/learning/filters.py index 8e700620..8f3fdf8e 100644 --- a/openedx_filters/learning/filters.py +++ b/openedx_filters/learning/filters.py @@ -15,8 +15,10 @@ class AccountSettingsRenderStarted(OpenEdxPublicFilter): """ - Filter used to modify the rendering of the account settings page in the LMS, triggered when a user - visits the page. + 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. Filter Type: org.openedx.learning.student.settings.render.started.v1 @@ -38,16 +40,14 @@ class RedirectToPage(OpenEdxFilterException): This exception is propagated to the account settings view and handled by the view to redirect the user to a new page. + + Arguments: + - message: error message for the exception. + - redirect_to: URL to redirect to. """ def __init__(self, message: str, redirect_to: str) -> None: - """ - Initialize the exception with the message and the URL to redirect to. - - Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. - """ + """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) class RenderInvalidAccountSettings(OpenEdxFilterException): @@ -56,6 +56,11 @@ class RenderInvalidAccountSettings(OpenEdxFilterException): This exception is propagated to the account settings view and handled by the view to render a different template instead. + + Arguments: + - message: error message for the exception. + - account_settings_template: template path rendered instead. + - template_context: context used to the new account settings template. """ def __init__( @@ -64,14 +69,7 @@ def __init__( account_settings_template: str = "", template_context: Optional[dict] = None ) -> None: - """ - Initialize the exception with the message and the template path to render instead. - - Arguments: - - message: error message for the exception. - - account_settings_template: template path rendered instead. - - template_context: context used to the new account settings template. - """ + """Initialize the exception with the message and the template path to render instead.""" super().__init__( message, account_settings_template=account_settings_template, @@ -84,23 +82,20 @@ class RenderCustomResponse(OpenEdxFilterException): This exception is propagated to the account settings view and handled by the view to return a custom response instead. + + Arguments: + - message: error message for the exception. + - response: custom response which will be returned by the account settings view. """ def __init__(self, message: str, response: Optional[dict] = None) -> None: - """ - Initialize the exception with the message and the custom response to return. - - Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the account settings view. - """ + """Initialize the exception with the message and the custom response to return.""" super().__init__(message, response=response) @classmethod def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: """ - Process the input context and template_name using the configured pipeline steps to modify the account settings - page. + Process the input context and template_name using the configured pipeline steps to modify the account settings. Arguments: - context (dict): template context for the account settings page. @@ -165,7 +160,10 @@ def run_filter(cls, form_data: dict) -> dict: class StudentLoginRequested(OpenEdxPublicFilter): """ - Filter used to modify the login process, triggered when a user logins. + Filter used to modify the login process. + + 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 @@ -183,6 +181,12 @@ class PreventLogin(OpenEdxFilterException): Raise to prevent the login process to continue. This exception is propagated to the login view and handled by the view to stop the login process. + + Arguments: + - message: error message for the exception. + - redirect_to: URL to redirect to. + - error_code: error code for the exception. + - context: context dictionary to be used in the exception. """ def __init__( @@ -192,15 +196,7 @@ def __init__( error_code: str = "", context: dict = None ) -> None: - """ - Initialize the exception with the message and the URL to redirect to. - - Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. - - error_code: error code for the exception. - - context: context dictionary to be used in the exception. - """ + """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to, error_code=error_code, context=context) @classmethod @@ -220,7 +216,10 @@ def run_filter(cls, user: Any) -> Any: class CourseEnrollmentStarted(OpenEdxPublicFilter): """ - Filter used to modify the course enrollment process, triggered when a user initiates the enrollment. + Filter used to modify the course enrollment process. + + 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,7 +263,10 @@ 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, triggered when a user initiates the unenrollment. + Filter used to modify the course unenrollment process. + + 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 @@ -302,7 +304,10 @@ def run_filter(cls, enrollment: Any) -> Any: class CertificateCreationRequested(OpenEdxPublicFilter): """ - Filter used to modify the certificate creation process, triggered when a certificate starts to be generated. + Filter used to modify the certificate creation process. + + 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. @@ -339,7 +344,7 @@ def run_filter( generation_mode: str, ) -> tuple[Any, CourseKey, str, str, float, str]: """ - Process the user, course_key, mode, status, grade, and generation_mode using the configured pipeline steps to + Process the inputs using the configured pipeline steps to modify the certificate creation process. Arguments: - user (User): Django User object. @@ -348,6 +353,14 @@ def run_filter( - status (str): specifies the status of the certificate. - grade (float): grade of the certificate. - generation_mode (str): specifies the mode of generation. + + Returns: + - User: Django User object. + - CourseKey: course key associated with the certificate. + - str: mode of the certificate. + - str: status of the certificate. + - float: grade of the certificate. + - str: mode of generation. """ data = super().run_pipeline( user=user, @@ -369,7 +382,10 @@ def run_filter( class CertificateRenderStarted(OpenEdxPublicFilter): """ - Filter used to modify the certificate rendering process, triggered when a user begins rendering a certificate. + Filter used to modify the certificate rendering process. + + 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 @@ -387,16 +403,14 @@ class RedirectToPage(OpenEdxFilterException): Raise to redirect to a different page instead of rendering the certificate. This exception is propagated to the certificate view and handled by the view to redirect the user to a new page. + + Arguments: + - message: error message for the exception. + - redirect_to: URL to redirect to. """ def __init__(self, message: str, redirect_to: str = "") -> None: - """ - Initialize the exception with the message and the URL to redirect to. - - Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. - """ + """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) class RenderAlternativeInvalidCertificate(OpenEdxFilterException): @@ -405,16 +419,14 @@ class RenderAlternativeInvalidCertificate(OpenEdxFilterException): This exception is propagated to the certificate view and handled by the view to render a different template instead. + + Arguments: + - message: error message for the exception. + - template_name: template path of the new certificate. """ def __init__(self, message: str, template_name: str = "") -> None: - """ - Initialize the exception with the message and the template path to render instead. - - Arguments: - - message: error message for the exception. - - template_name: template path of the new certificate. - """ + """Initialize the exception with the message and the template path to render instead.""" super().__init__(message, template_name=template_name) class RenderCustomResponse(OpenEdxFilterException): @@ -423,16 +435,14 @@ class RenderCustomResponse(OpenEdxFilterException): This exception is propagated to the certificate view and handled by the view to return a custom response instead. + + Arguments: + - message: error message for the exception. + - response: custom response which will be returned by the certificate view. """ def __init__(self, message: str, response: HttpResponse) -> None: - """ - Initialize the exception with the message and the custom response to return. - - Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the certificate view. - """ + """Initialize the exception with the message and the custom response to return.""" super().__init__( message, response=response, @@ -446,6 +456,10 @@ def run_filter(cls, context: dict, custom_template: Any) -> tuple[dict, Any]: Arguments: - context (dict): context dictionary for certificate template. - custom_template (CertificateTemplate): custom web certificate template. + + Returns: + - dict: context dictionary for the certificate template, possibly modified. + - CertificateTemplate: custom web certificate template, possibly modified. """ data = super().run_pipeline(context=context, custom_template=custom_template) return data.get("context"), data.get("custom_template") @@ -453,7 +467,10 @@ def run_filter(cls, context: dict, custom_template: Any) -> tuple[dict, Any]: class CohortChangeRequested(OpenEdxPublicFilter): """ - Filter used to modify the cohort change process, triggered when a user changes cohorts. + 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. Filter Type: org.openedx.learning.cohort.change.requested.v1 @@ -476,12 +493,15 @@ class PreventCohortChange(OpenEdxFilterException): @classmethod def run_filter(cls, current_membership: Any, target_cohort: Any) -> tuple[Any, Any]: """ - Process the current_membership and target_cohort using the configured pipeline steps to modify the cohort - change process. + Process the inputs using the configured pipeline steps to modify the cohort change process. Arguments: - current_membership (CohortMembership): CohortMembership instance representing the current user's cohort. - target_cohort (CourseUserGroup): CourseUserGroup instance representing the new user's cohort. + + Returns: + - CohortMembership: CohortMembership instance representing the current user's cohort. + - CourseUserGroup: CourseUserGroup instance representing the new user's cohort. """ data = super().run_pipeline(current_membership=current_membership, target_cohort=target_cohort) return data.get("current_membership"), data.get("target_cohort") @@ -489,7 +509,10 @@ def run_filter(cls, current_membership: Any, target_cohort: Any) -> tuple[Any, A class CohortAssignmentRequested(OpenEdxPublicFilter): """ - Filter used to modify the cohort assignment process, triggered when a user is assigned to a new cohort. + 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. Filter Type: org.openedx.learning.cohort.assignment.requested.v1 @@ -515,8 +538,12 @@ def run_filter(cls, user: Any, target_cohort: Any) -> tuple[Any, Any]: Process the user and target_cohort using the configured pipeline steps to modify the cohort assignment process. Arguments: - - user (User): Django User object representing the new user. + - user (User): Django User object representing the user. - target_cohort (CourseUserGroup): CourseUserGroup instance representing the new user's cohort. + + Returns: + - User: Django User object representing the user. + - CourseUserGroup: CourseUserGroup instance representing the new user's cohort. """ data = super().run_pipeline(user=user, target_cohort=target_cohort) return data.get("user"), data.get("target_cohort") @@ -524,8 +551,10 @@ def run_filter(cls, user: Any, target_cohort: Any) -> tuple[Any, Any]: class CourseAboutRenderStarted(OpenEdxPublicFilter): """ - Filter used to modify the course about rendering process, triggered when a user requests to view the course about - page. + 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. Filter Type: org.openedx.learning.course_about.render.started.v1 @@ -544,16 +573,14 @@ class RedirectToPage(OpenEdxFilterException): This exception is propagated to the course about view and handled by the view to redirect the user to a new page. + + Arguments: + - message: error message for the exception. + - redirect_to: URL to redirect to. """ def __init__(self, message: str, redirect_to: str = "") -> None: - """ - Initialize the exception with the message and the URL to redirect to. - - Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. - """ + """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) class RenderInvalidCourseAbout(OpenEdxFilterException): @@ -562,17 +589,15 @@ class RenderInvalidCourseAbout(OpenEdxFilterException): This exception is propagated to the course about view and handled by the view to render a different template instead. + + Arguments: + - message: error message for the exception. + - course_about_template: template path rendered instead. + - template_context: context used to the new course_about_template. """ def __init__(self, message: str, course_about_template: str = "", template_context: dict = None) -> None: - """ - Initialize the exception with the message and the template to render instead. - - Arguments: - - message: error message for the exception. - - course_about_template: template path rendered instead. - - template_context: context used to the new course_about_template. - """ + """Initialize the exception with the message and the template to render instead.""" super().__init__( message, course_about_template=course_about_template, @@ -585,16 +610,14 @@ class RenderCustomResponse(OpenEdxFilterException): This exception is propagated to the course about view and handled by the view to return a custom response instead. + + Arguments: + - message: error message for the exception. + - response: custom response which will be returned by the course about view. """ def __init__(self, message: str, response: HttpResponse) -> None: - """ - Initialize the exception with the message and the custom response to return. - - Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the course about view. - """ + """Initialize the exception with the message and the custom response to return.""" super().__init__( message, response=response, @@ -608,6 +631,10 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: Arguments: - context (dict): context dictionary for course about template. - template_name (str): template name to be rendered by the course about. + + Returns: + - dict: context dictionary for the course about template, possibly modified. + - str: template name to be rendered by the course about, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -615,7 +642,10 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: class DashboardRenderStarted(OpenEdxPublicFilter): """ - Filter used to modify the dashboard rendering process, triggered when a user requests to view the student dashboard. + 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. Filter Type: org.openedx.learning.dashboard.render.started.v1 @@ -636,16 +666,14 @@ class RedirectToPage(OpenEdxFilterException): Raise to redirect to a different page instead of rendering the dashboard. This exception is propagated to the dashboard view and handled by the view to redirect the user to a new page. + + Arguments: + - message: error message for the exception. + - redirect_to: URL to redirect to. """ def __init__(self, message: str, redirect_to: str = "") -> None: - """ - Initialize the exception with the message and the URL to redirect to. - - Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. - """ + """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) class RenderInvalidDashboard(OpenEdxFilterException): @@ -653,17 +681,16 @@ class RenderInvalidDashboard(OpenEdxFilterException): Raise to render a different dashboard template instead of the default one. This exception is propagated to the dashboard view and handled by the view to render a different template + instead. + + Arguments: + - message: error message for the exception. + - dashboard_template: template path rendered instead. + - template_context: context used to the new dashboard_template. """ def __init__(self, message: str, dashboard_template: str = "", template_context: dict = None) -> None: - """ - Initialize the exception with the message and the template to render instead. - - Arguments: - - message: error message for the exception. - - dashboard_template: template path rendered instead. - - template_context: context used to the new dashboard_template. - """ + """Initialize the exception with the message and the template to render instead.""" super().__init__( message, dashboard_template=dashboard_template, @@ -675,16 +702,14 @@ class RenderCustomResponse(OpenEdxFilterException): Raise to stop the dashboard rendering process and return a custom response. This exception is propagated to the dashboard view and handled by the view to return a custom response instead. + + Arguments: + - message: error message for the exception. + - response: custom response which will be returned by the dashboard view. """ def __init__(self, message: str, response: HttpResponse = None) -> None: - """ - Initialize the exception with the message and the custom response to return. - - Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the dashboard view. - """ + """Initialize the exception with the message and the custom response to return.""" super().__init__( message, response=response, @@ -698,6 +723,10 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: Arguments: - context (dict): context dictionary for student's dashboard template. - template_name (str): template name to be rendered by the student's dashboard. + + Returns: + - dict: context dictionary for the student's dashboard template, possibly modified. + - str: template name to be rendered by the student's dashboard, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -705,8 +734,10 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: class VerticalBlockChildRenderStarted(OpenEdxPublicFilter): """ - Filter used to modify the rendering of a child block within a vertical block, triggered when a child block starts - rendering. + 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. Filter Type: org.openedx.learning.vertical_block_child.render.started.v1 @@ -735,6 +766,10 @@ def run_filter(cls, block: Any, context: dict) -> tuple[Any, dict]: Arguments: - block (XBlock): the XBlock that is about to be rendered into HTML - context (dict): rendering context values like is_mobile_app, show_title..etc + + Returns: + - XBlock: the XBlock that is about to be rendered into HTML + - dict: rendering context values like is_mobile_app, show_title..etc """ data = super().run_pipeline(block=block, context=context) return data.get("block"), data.get("context") @@ -767,7 +802,10 @@ def run_filter(cls, enrollments: QuerySet) -> QuerySet: Process the enrollments QuerySet using the configured pipeline steps to modify the course enrollment data. Arguments: - - enrollments (QuerySet): data with all user's course enrollments + - enrollments (QuerySet): data with all user's course enrollments. + + Returns: + - QuerySet: data with all user's course enrollments, possibly modified. """ data = super().run_pipeline(enrollments=enrollments) return data.get("enrollments") @@ -777,6 +815,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. + Filter Type: org.openedx.learning.xblock.render.started.v1 @@ -802,27 +843,28 @@ class RenderCustomResponse(OpenEdxFilterException): This exception is propagated to the XBlock render view and handled by the view to return a custom response instead. + + Arguments: + message: error message for the exception. + response: custom response which will be returned by the XBlock render view. """ def __init__(self, message: str, response: HttpResponse = None): - """ - Initialize the exception with the message and the custom response to return. - - Arguments: - message: error message for the exception. - response: custom response which will be returned by the XBlock render view. - """ + """Initialize the exception with the message and the custom response to return.""" super().__init__(message, response=response) @classmethod def run_filter(cls, context: dict, student_view_context: dict): """ - Process the context and student_view_context using the configured pipeline steps to modify the rendering of an - XBlock. + Process the inputs using the configured pipeline steps to modify the rendering of an XBlock. Arguments: - context (dict): rendering context values like is_mobile_app, show_title, etc. - - student_view_context (dict): context passed to the student_view of the block context + - student_view_context (dict): context passed to the student_view of the block context. + + Returns: + - dict: rendering context values like is_mobile_app, show_title, etc. + - dict: context passed to the student_view of the block context. """ data = super().run_pipeline(context=context, student_view_context=student_view_context) return data.get("context"), data.get("student_view_context") @@ -832,6 +874,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. + Filter Type: org.openedx.learning.vertical_block.render.completed.v1 @@ -854,14 +899,19 @@ class PreventVerticalBlockRender(OpenEdxFilterException): @classmethod def run_filter(cls, block: Any, fragment: Any, context: dict, view: str) -> tuple[Any, Any, dict, str]: """ - Process the block, fragment, context, and view using the configured pipeline steps to modify the rendering of a - vertical block. + Process the inputs using the configured pipeline steps to modify the rendering of a vertical block. Arguments: - block (VerticalBlock): The VeriticalBlock instance which is being rendered. - fragment (web_fragments.Fragment): The web-fragment containing the rendered content of VerticalBlock. - context (dict): rendering context values like is_mobile_app, show_title..etc. - view (str): the rendering view. Can be either 'student_view', or 'public_view'. + + Returns: + - VerticalBlock: The VeriticalBlock instance which is being rendered. + - web_fragments.Fragment: The web-fragment containing the rendered content of VerticalBlock. + - dict: rendering context values like is_mobile_app, show_title..etc. + - str: the rendering view. Can be either 'student_view', or 'public_view'. """ data = super().run_pipeline(block=block, fragment=fragment, context=context, view=view) return data.get("block"), data.get("fragment"), data.get("context"), data.get("view") @@ -871,6 +921,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. + Filter Type: org.openedx.learning.course.homepage.url.creation.started.v1 @@ -889,7 +942,11 @@ def run_filter(cls, course_key: CourseKey, course_home_url: str) -> tuple[Course Arguments: course_key (CourseKey): The course key for which the home url is being requested. - course_home_url (String): The url string for the course home + course_home_url (String): The url string for the course home. + + Returns: + CourseKey: The course key for which the home url is being requested. + str: The url string for the course home. """ data = super().run_pipeline(course_key=course_key, course_home_url=course_home_url) return data.get("course_key"), data.get("course_home_url") @@ -899,6 +956,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. + Filter Type: org.openedx.learning.home.enrollment.api.rendered.v1 @@ -913,12 +973,15 @@ class CourseEnrollmentAPIRenderStarted(OpenEdxPublicFilter): @classmethod def run_filter(cls, course_key: CourseKey, serialized_enrollment: dict) -> tuple[CourseKey, dict]: """ - Process the course_key and serialized_enrollment using the configured pipeline steps to modify the course - enrollment data. + Process the inputs using the configured pipeline steps to modify the course enrollment data. Arguments: - course_key (CourseKey): The course key for which isStarted is being modify. - serialized_enrollment (dict): enrollment data + - course_key (CourseKey): The course key for which isStarted is being modify. + - serialized_enrollment (dict): enrollment data. + + Returns: + - CourseKey: The course key for which isStarted is being modify. + - dict: enrollment data. """ data = super().run_pipeline(course_key=course_key, serialized_enrollment=serialized_enrollment) return data.get("course_key"), data.get("serialized_enrollment") @@ -928,6 +991,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. + Filter Type: org.openedx.learning.home.courserun.api.rendered.started.v1 @@ -946,6 +1012,9 @@ def run_filter(cls, serialized_courserun: dict) -> dict: Arguments: serialized_courserun (dict): courserun data. + + Returns: + dict: courserun data. """ data = super().run_pipeline(serialized_courserun=serialized_courserun) return data.get("serialized_courserun") @@ -955,6 +1024,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. + Filter Type: org.openedx.learning.instructor.dashboard.render.started.v1 @@ -972,16 +1044,14 @@ class RedirectToPage(OpenEdxFilterException): This exception is propagated to the instructor dashboard view and handled by the view to redirect the user to a new page. + + Arguments: + - message: error message for the exception. + - redirect_to: URL to redirect to. """ def __init__(self, message: str, redirect_to: str = ""): - """ - Initialize the exception with the message and the URL to redirect to. - - Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. - """ + """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) class RenderInvalidDashboard(OpenEdxFilterException): @@ -990,17 +1060,15 @@ class RenderInvalidDashboard(OpenEdxFilterException): This exception is propagated to the instructor dashboard view and handled by the view to render a different template instead. + + Arguments: + - message: error message for the exception. + - instructor_template: template path rendered instead. + - template_context: context used to the new instructor_template. """ def __init__(self, message: str, instructor_template: str = "", template_context: dict = None): - """ - Initialize the exception with the message and the template to render instead. - - Arguments: - - message: error message for the exception. - - instructor_template: template path rendered instead. - - template_context: context used to the new instructor_template. - """ + """Initialize the exception with the message and the template to render instead.""" super().__init__( message, instructor_template=instructor_template, @@ -1013,16 +1081,14 @@ class RenderCustomResponse(OpenEdxFilterException): This exception is propagated to the instructor dashboard view and handled by the view to return a custom response instead. + + Arguments: + - message: error message for the exception. + - response: custom response which will be returned by the dashboard view. """ def __init__(self, message: str, response: HttpResponse = None): - """ - Initialize the exception with the message and the custom response to return. - - Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the dashboard view. - """ + """Initialize the exception with the message and the custom response to return.""" super().__init__( message, response=response, @@ -1038,7 +1104,8 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: - template_name (str): template name to be rendered by the instructor's tab. Returns: - - tuple: context dictionary and template name. + - dict: context dictionary for the instructor's tab template, possibly modified. + - str: template name to be rendered by the instructor's tab, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -1048,6 +1115,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. + Filter Type: org.openedx.learning.ora.submission_view.render.started.v1 @@ -1065,17 +1135,15 @@ class RenderInvalidTemplate(OpenEdxFilterException): This exception is propagated to the submission view and handled by the view to render a different template instead. + + Arguments: + - message (str): error message for the exception. + - context (dict): context used to the submission view template. + - template_name (str): template path rendered instead. """ def __init__(self, message: str, context: Optional[dict] = None, template_name: str = "") -> None: - """ - Initialize the exception with the message and the template to render instead. - - Arguments: - - message (str): error message for the exception. - - context (dict): context used to the submission view template. - - template_name (str): template path rendered instead. - """ + """Initialize the exception with the message and the template to render instead.""" super().__init__(message, context=context, template_name=template_name) @classmethod @@ -1084,8 +1152,12 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: Process the context and template_name using the configured pipeline steps to modify the submission view. Arguments: - context (dict): context dictionary for submission view template. - template_name (str): template name to be rendered by the student's dashboard. + - context (dict): context dictionary for submission view template. + - template_name (str): template name to be rendered by the student's dashboard. + + Returns: + - dict: context dictionary for the submission view template, possibly modified. + - str: template name to be rendered by the submission view, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name, ) return data.get("context"), data.get("template_name") @@ -1095,6 +1167,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. + Filter Type: org.openedx.learning.idv.page.url.requested.v1 @@ -1113,6 +1188,9 @@ def run_filter(cls, url: str) -> str: Arguments: - url (str): The url for the ID verification page to be modified. + + Returns: + - str: The modified URL for the ID verification page. """ data = super().run_pipeline(url=url) return data.get("url") @@ -1121,6 +1199,17 @@ def run_filter(cls, url: str) -> str: 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. + + Filter Type: + org.openedx.learning.course_about.page.url.requested.v1 + + Trigger: + - Repository: openedx/edx-platform + - Path: common/djangoapps/util/course.py + - Function or Method: get_link_for_about_page """ filter_type = "org.openedx.learning.course_about.page.url.requested.v1" @@ -1133,6 +1222,10 @@ def run_filter(cls, url: str, org: str) -> tuple[str, str]: Arguments: - url (str): the URL of the page to be modified. - org (str): Course org filter used as context data to get LMS configurations. + + Returns: + - str: the modified URL of the page. + - str: Course org filter used as context data to get LMS configurations """ data = super().run_pipeline(url=url, org=org) return data.get("url"), data.get("org") From 7130a46958eedc026d62ae9044264b2db7c66d3f Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 13 Jan 2025 12:27:59 +0100 Subject: [PATCH 3/8] refactor: address PR reviews --- openedx_filters/course_authoring/filters.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openedx_filters/course_authoring/filters.py b/openedx_filters/course_authoring/filters.py index 57dfd104..6190f0fd 100644 --- a/openedx_filters/course_authoring/filters.py +++ b/openedx_filters/course_authoring/filters.py @@ -18,7 +18,7 @@ class LMSPageURLRequested(OpenEdxPublicFilter): Trigger: - Repository: openedx/edx-platform - Path: cms/djangoapps/contentstore/asset_storage_handler.py - - Function: get_asset_json + - Function or Method: get_asset_json """ filter_type = "org.openedx.course_authoring.lms.page.url.requested.v1" From 350dea3dea65f22683eb46ba28bc501d15c7850f Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 13 Jan 2025 17:10:02 +0100 Subject: [PATCH 4/8] refactor: address PR reviews --- openedx_filters/learning/filters.py | 135 ++++++++++++++++------------ 1 file changed, 77 insertions(+), 58 deletions(-) diff --git a/openedx_filters/learning/filters.py b/openedx_filters/learning/filters.py index 8f3fdf8e..5bf46d0b 100644 --- a/openedx_filters/learning/filters.py +++ b/openedx_filters/learning/filters.py @@ -42,8 +42,8 @@ class RedirectToPage(OpenEdxFilterException): a new page. Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. + - message (str): error message for the exception. + - redirect_to (str): URL to redirect to. """ def __init__(self, message: str, redirect_to: str) -> None: @@ -58,15 +58,15 @@ class RenderInvalidAccountSettings(OpenEdxFilterException): template instead. Arguments: - - message: error message for the exception. - - account_settings_template: template path rendered instead. - - template_context: context used to the new account settings template. + - message (str): error message for the exception. + - account_settings_template (str): template path rendered instead. + - template_context (dict): context used to the new account settings template. """ def __init__( self, message: str, - account_settings_template: str = "", + account_settings_template: Optional[str] = "", template_context: Optional[dict] = None ) -> None: """Initialize the exception with the message and the template path to render instead.""" @@ -84,11 +84,11 @@ class RenderCustomResponse(OpenEdxFilterException): instead. Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the account settings view. + - message (str): error message for the exception. + - response (HttpResponse): custom response which will be returned by the account settings view. """ - def __init__(self, message: str, response: Optional[dict] = None) -> None: + def __init__(self, message: str, response: Optional[HttpResponse] = None) -> None: """Initialize the exception with the message and the custom response to return.""" super().__init__(message, response=response) @@ -183,18 +183,18 @@ class PreventLogin(OpenEdxFilterException): This exception is propagated to the login view and handled by the view to stop the login process. Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. - - error_code: error code for the exception. - - context: context dictionary to be used in the exception. + - message (str): error message for the exception. + - redirect_to (str): URL to redirect to. + - error_code (str): error code for the exception. + - context (dict): context dictionary to be used in the exception. """ def __init__( self, message: str, - redirect_to: str = "", - error_code: str = "", - context: dict = None + redirect_to: Optional[str] = "", + error_code: Optional[str] = "", + context: Optional[dict] = None ) -> None: """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to, error_code=error_code, context=context) @@ -405,11 +405,11 @@ class RedirectToPage(OpenEdxFilterException): This exception is propagated to the certificate view and handled by the view to redirect the user to a new page. Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. + - message (str): error message for the exception. + - redirect_to (str): URL to redirect to. """ - def __init__(self, message: str, redirect_to: str = "") -> None: + def __init__(self, message: str, redirect_to: Optional[str] = "") -> None: """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) @@ -421,11 +421,11 @@ class RenderAlternativeInvalidCertificate(OpenEdxFilterException): instead. Arguments: - - message: error message for the exception. - - template_name: template path of the new certificate. + - message (str): error message for the exception. + - template_name (str): template path of the new certificate. """ - def __init__(self, message: str, template_name: str = "") -> None: + def __init__(self, message: str, template_name: Optional[str] = "") -> None: """Initialize the exception with the message and the template path to render instead.""" super().__init__(message, template_name=template_name) @@ -437,8 +437,8 @@ class RenderCustomResponse(OpenEdxFilterException): instead. Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the certificate view. + - message (str): error message for the exception. + - response (HttpResponse): custom response which will be returned by the certificate view. """ def __init__(self, message: str, response: HttpResponse) -> None: @@ -575,11 +575,11 @@ class RedirectToPage(OpenEdxFilterException): page. Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. + - message (str): error message for the exception. + - redirect_to (str): URL to redirect to. """ - def __init__(self, message: str, redirect_to: str = "") -> None: + def __init__(self, message: str, redirect_to: Optional[str] = "") -> None: """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) @@ -591,12 +591,17 @@ class RenderInvalidCourseAbout(OpenEdxFilterException): instead. Arguments: - - message: error message for the exception. - - course_about_template: template path rendered instead. - - template_context: context used to the new course_about_template. + - message (Str): error message for the exception. + - course_about_template (str): template path rendered instead. + - template_context (dict): context used to the new course_about_template. """ - def __init__(self, message: str, course_about_template: str = "", template_context: dict = None) -> None: + def __init__( + self, + message: str, + course_about_template: Optional[str] = "", + template_context: Optional[dict] = None + ) -> None: """Initialize the exception with the message and the template to render instead.""" super().__init__( message, @@ -612,8 +617,8 @@ class RenderCustomResponse(OpenEdxFilterException): instead. Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the course about view. + - message (str): error message for the exception. + - response (HttpResponse): custom response which will be returned by the course about view. """ def __init__(self, message: str, response: HttpResponse) -> None: @@ -668,11 +673,11 @@ class RedirectToPage(OpenEdxFilterException): This exception is propagated to the dashboard view and handled by the view to redirect the user to a new page. Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. + - message (str): error message for the exception. + - redirect_to (str): URL to redirect to. """ - def __init__(self, message: str, redirect_to: str = "") -> None: + def __init__(self, message: str, redirect_to: Optional[str] = "") -> None: """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) @@ -684,12 +689,17 @@ class RenderInvalidDashboard(OpenEdxFilterException): instead. Arguments: - - message: error message for the exception. - - dashboard_template: template path rendered instead. - - template_context: context used to the new dashboard_template. + - message (str): error message for the exception. + - dashboard_template (str): template path rendered instead. + - template_context (dict): context used to the new dashboard_template. """ - def __init__(self, message: str, dashboard_template: str = "", template_context: dict = None) -> None: + def __init__( + self, + message: str, + dashboard_template: Optional[str] = "", + template_context: Optional[dict] = None + ) -> None: """Initialize the exception with the message and the template to render instead.""" super().__init__( message, @@ -704,11 +714,11 @@ class RenderCustomResponse(OpenEdxFilterException): This exception is propagated to the dashboard view and handled by the view to return a custom response instead. Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the dashboard view. + - message (str): error message for the exception. + - response (HttpResponse): custom response which will be returned by the dashboard view. """ - def __init__(self, message: str, response: HttpResponse = None) -> None: + def __init__(self, message: str, response: Optional[HttpResponse] = None) -> None: """Initialize the exception with the message and the custom response to return.""" super().__init__( message, @@ -845,11 +855,11 @@ class RenderCustomResponse(OpenEdxFilterException): instead. Arguments: - message: error message for the exception. - response: custom response which will be returned by the XBlock render view. + message (str): error message for the exception. + response (HttpResponse): custom response which will be returned by the XBlock render view. """ - def __init__(self, message: str, response: HttpResponse = None): + def __init__(self, message: str, response: Optional[HttpResponse] = None): """Initialize the exception with the message and the custom response to return.""" super().__init__(message, response=response) @@ -942,7 +952,7 @@ def run_filter(cls, course_key: CourseKey, course_home_url: str) -> tuple[Course Arguments: course_key (CourseKey): The course key for which the home url is being requested. - course_home_url (String): The url string for the course home. + course_home_url (str): The url string for the course home. Returns: CourseKey: The course key for which the home url is being requested. @@ -1046,11 +1056,11 @@ class RedirectToPage(OpenEdxFilterException): new page. Arguments: - - message: error message for the exception. - - redirect_to: URL to redirect to. + - message (str): error message for the exception. + - redirect_to (str): URL to redirect to. """ - def __init__(self, message: str, redirect_to: str = ""): + def __init__(self, message: str, redirect_to: Optional[str] = ""): """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) @@ -1062,12 +1072,17 @@ class RenderInvalidDashboard(OpenEdxFilterException): template instead. Arguments: - - message: error message for the exception. - - instructor_template: template path rendered instead. - - template_context: context used to the new instructor_template. + - message (str): error message for the exception. + - instructor_template (str): template path rendered instead. + - template_context (dict): context used to the new instructor_template. """ - def __init__(self, message: str, instructor_template: str = "", template_context: dict = None): + def __init__( + self, + message: str, + instructor_template: Optional[str] = "", + template_context: Optional[dict] = None + ): """Initialize the exception with the message and the template to render instead.""" super().__init__( message, @@ -1083,11 +1098,11 @@ class RenderCustomResponse(OpenEdxFilterException): response instead. Arguments: - - message: error message for the exception. - - response: custom response which will be returned by the dashboard view. + - message (str): error message for the exception. + - response (HttpResponse): custom response which will be returned by the dashboard view. """ - def __init__(self, message: str, response: HttpResponse = None): + def __init__(self, message: str, response: Optional[HttpResponse] = None): """Initialize the exception with the message and the custom response to return.""" super().__init__( message, @@ -1142,7 +1157,11 @@ class RenderInvalidTemplate(OpenEdxFilterException): - template_name (str): template path rendered instead. """ - def __init__(self, message: str, context: Optional[dict] = None, template_name: str = "") -> None: + def __init__( + self, message: str, + context: Optional[dict] = None, + template_name: Optional[str] = "" + ) -> None: """Initialize the exception with the message and the template to render instead.""" super().__init__(message, context=context, template_name=template_name) From 35ffa69335153fc977cbcb7d2acde5be821cd71f Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Tue, 14 Jan 2025 10:36:47 +0100 Subject: [PATCH 5/8] refactor: address PR reviews --- openedx_filters/course_authoring/filters.py | 9 ++- openedx_filters/learning/filters.py | 71 ++++++++++++--------- 2 files changed, 49 insertions(+), 31 deletions(-) diff --git a/openedx_filters/course_authoring/filters.py b/openedx_filters/course_authoring/filters.py index 6190f0fd..e1202798 100644 --- a/openedx_filters/course_authoring/filters.py +++ b/openedx_filters/course_authoring/filters.py @@ -29,8 +29,13 @@ def run_filter(cls, url: str, org: str) -> tuple[str, str]: Process the inputs using the configured pipeline steps to modify the URL of the page requested by the user. Arguments: - url (str): the URL of the page to be modified. - org (str): Course org filter used as context data to get LMS configurations. + - url (str): the URL of the page to be modified. + - org (str): Course org filter used as context data to get LMS configurations. + + Returns: + tuple[str, str]: + - str: the modified URL of the page requested by the user. + - str: the course org. """ data = super().run_pipeline(url=url, org=org) return data.get("url"), data.get("org") diff --git a/openedx_filters/learning/filters.py b/openedx_filters/learning/filters.py index 5bf46d0b..3620a0fb 100644 --- a/openedx_filters/learning/filters.py +++ b/openedx_filters/learning/filters.py @@ -5,7 +5,7 @@ from typing import Any, Optional from django.db.models.query import QuerySet -from django.http import HttpResponse +from django.http import HttpResponse, QueryDict from opaque_keys.edx.keys import CourseKey from openedx_filters.exceptions import OpenEdxFilterException @@ -102,8 +102,9 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: - template_name (str): template path used to render the account settings page. Returns: - - dict: context dictionary for the account settings page, possibly modified. - - str: template name to be rendered by the account settings page, possibly modified. + tuple[dict, str]: + - dict: context dictionary for the account settings page, possibly modified. + - str: template name to be rendered by the account settings page, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -141,7 +142,7 @@ class PreventRegistration(OpenEdxFilterException): """ @classmethod - def run_filter(cls, form_data: dict) -> dict: + def run_filter(cls, form_data: QueryDict) -> QueryDict: """ Process the registration form data using the configured pipeline steps to modify the registration process. @@ -149,7 +150,7 @@ def run_filter(cls, form_data: dict) -> dict: - form_data (QueryDict): contains the request.data submitted by the registration form. Returns: - - dict: form data dictionary, possibly modified. + - QueryDict: form data dictionary, possibly modified. """ sensitive_data = cls.extract_sensitive_data(form_data) data = super().run_pipeline(form_data=form_data) @@ -458,8 +459,9 @@ def run_filter(cls, context: dict, custom_template: Any) -> tuple[dict, Any]: - custom_template (CertificateTemplate): custom web certificate template. Returns: - - dict: context dictionary for the certificate template, possibly modified. - - CertificateTemplate: custom web certificate template, possibly modified. + tuple[dict, CertificateTemplate]: + - dict: context dictionary for the certificate template, possibly modified. + - CertificateTemplate: custom web certificate template, possibly modified. """ data = super().run_pipeline(context=context, custom_template=custom_template) return data.get("context"), data.get("custom_template") @@ -500,8 +502,9 @@ def run_filter(cls, current_membership: Any, target_cohort: Any) -> tuple[Any, A - target_cohort (CourseUserGroup): CourseUserGroup instance representing the new user's cohort. Returns: - - CohortMembership: CohortMembership instance representing the current user's cohort. - - CourseUserGroup: CourseUserGroup instance representing the new user's cohort. + tuple[CohortMembership, CourseUserGroup]: + - CohortMembership: CohortMembership instance representing the current user's cohort. + - CourseUserGroup: CourseUserGroup instance representing the new user's cohort. """ data = super().run_pipeline(current_membership=current_membership, target_cohort=target_cohort) return data.get("current_membership"), data.get("target_cohort") @@ -542,8 +545,9 @@ def run_filter(cls, user: Any, target_cohort: Any) -> tuple[Any, Any]: - target_cohort (CourseUserGroup): CourseUserGroup instance representing the new user's cohort. Returns: - - User: Django User object representing the user. - - CourseUserGroup: CourseUserGroup instance representing the new user's cohort. + tuple[User, CourseUserGroup]: + - User: Django User object representing the user. + - CourseUserGroup: CourseUserGroup instance representing the new user's cohort. """ data = super().run_pipeline(user=user, target_cohort=target_cohort) return data.get("user"), data.get("target_cohort") @@ -638,8 +642,9 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: - template_name (str): template name to be rendered by the course about. Returns: - - dict: context dictionary for the course about template, possibly modified. - - str: template name to be rendered by the course about, possibly modified. + tuple[dict, str]: + - dict: context dictionary for the course about template, possibly modified. + - str: template name to be rendered by the course about, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -735,8 +740,9 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: - template_name (str): template name to be rendered by the student's dashboard. Returns: - - dict: context dictionary for the student's dashboard template, possibly modified. - - str: template name to be rendered by the student's dashboard, possibly modified. + tuple[dict, str]: + - dict: context dictionary for the student's dashboard template, possibly modified. + - str: template name to be rendered by the student's dashboard, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -778,8 +784,9 @@ def run_filter(cls, block: Any, context: dict) -> tuple[Any, dict]: - context (dict): rendering context values like is_mobile_app, show_title..etc Returns: - - XBlock: the XBlock that is about to be rendered into HTML - - dict: rendering context values like is_mobile_app, show_title..etc + tuple[XBlock, dict]: + - XBlock: the XBlock that is about to be rendered into HTML + - dict: rendering context values like is_mobile_app, show_title..etc """ data = super().run_pipeline(block=block, context=context) return data.get("block"), data.get("context") @@ -873,8 +880,9 @@ def run_filter(cls, context: dict, student_view_context: dict): - student_view_context (dict): context passed to the student_view of the block context. Returns: - - dict: rendering context values like is_mobile_app, show_title, etc. - - dict: context passed to the student_view of the block context. + tuple[dict, dict]: + - dict: rendering context values like is_mobile_app, show_title, etc. + - dict: context passed to the student_view of the block context. """ data = super().run_pipeline(context=context, student_view_context=student_view_context) return data.get("context"), data.get("student_view_context") @@ -955,8 +963,9 @@ def run_filter(cls, course_key: CourseKey, course_home_url: str) -> tuple[Course course_home_url (str): The url string for the course home. Returns: - CourseKey: The course key for which the home url is being requested. - str: The url string for the course home. + tuple[CourseKey, str]: + CourseKey: The course key for which the home url is being requested. + str: The url string for the course home. """ data = super().run_pipeline(course_key=course_key, course_home_url=course_home_url) return data.get("course_key"), data.get("course_home_url") @@ -990,8 +999,9 @@ def run_filter(cls, course_key: CourseKey, serialized_enrollment: dict) -> tuple - serialized_enrollment (dict): enrollment data. Returns: - - CourseKey: The course key for which isStarted is being modify. - - dict: enrollment data. + tuple[CourseKey, dict]: + - CourseKey: The course key for which isStarted is being modify. + - dict: enrollment data. """ data = super().run_pipeline(course_key=course_key, serialized_enrollment=serialized_enrollment) return data.get("course_key"), data.get("serialized_enrollment") @@ -1119,8 +1129,9 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: - template_name (str): template name to be rendered by the instructor's tab. Returns: - - dict: context dictionary for the instructor's tab template, possibly modified. - - str: template name to be rendered by the instructor's tab, possibly modified. + tuple[dict, str]: + - dict: context dictionary for the instructor's tab template, possibly modified. + - str: template name to be rendered by the instructor's tab, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name) return data.get("context"), data.get("template_name") @@ -1175,8 +1186,9 @@ def run_filter(cls, context: dict, template_name: str) -> tuple[dict, str]: - template_name (str): template name to be rendered by the student's dashboard. Returns: - - dict: context dictionary for the submission view template, possibly modified. - - str: template name to be rendered by the submission view, possibly modified. + tuple[dict, str]: + - dict: context dictionary for the submission view template, possibly modified. + - str: template name to be rendered by the submission view, possibly modified. """ data = super().run_pipeline(context=context, template_name=template_name, ) return data.get("context"), data.get("template_name") @@ -1243,8 +1255,9 @@ def run_filter(cls, url: str, org: str) -> tuple[str, str]: - org (str): Course org filter used as context data to get LMS configurations. Returns: - - str: the modified URL of the page. - - str: Course org filter used as context data to get LMS configurations + tuple[str, str]: + - str: the modified URL of the page. + - str: Course org filter used as context data to get LMS configurations. """ data = super().run_pipeline(url=url, org=org) return data.get("url"), data.get("org") From 0746c04c67cd0066643f42cebb321d307a2c26dd Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Tue, 14 Jan 2025 10:41:52 +0100 Subject: [PATCH 6/8] refactor: address PR reviews --- openedx_filters/learning/filters.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openedx_filters/learning/filters.py b/openedx_filters/learning/filters.py index 3620a0fb..f59a1c7b 100644 --- a/openedx_filters/learning/filters.py +++ b/openedx_filters/learning/filters.py @@ -1031,10 +1031,10 @@ def run_filter(cls, serialized_courserun: dict) -> dict: Process the serialized_courserun using the configured pipeline steps to modify the course run data. Arguments: - serialized_courserun (dict): courserun data. + - serialized_courserun (dict): courserun data. Returns: - dict: courserun data. + - dict: courserun data. """ data = super().run_pipeline(serialized_courserun=serialized_courserun) return data.get("serialized_courserun") From 76f55c978f716938087302b23a8e9ea7d0387481 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Wed, 15 Jan 2025 13:32:09 +0100 Subject: [PATCH 7/8] refactor: don't use optional when default is not none --- openedx_filters/learning/filters.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/openedx_filters/learning/filters.py b/openedx_filters/learning/filters.py index f59a1c7b..910b7106 100644 --- a/openedx_filters/learning/filters.py +++ b/openedx_filters/learning/filters.py @@ -66,7 +66,7 @@ class RenderInvalidAccountSettings(OpenEdxFilterException): def __init__( self, message: str, - account_settings_template: Optional[str] = "", + account_settings_template: str = "", template_context: Optional[dict] = None ) -> None: """Initialize the exception with the message and the template path to render instead.""" @@ -193,8 +193,8 @@ class PreventLogin(OpenEdxFilterException): def __init__( self, message: str, - redirect_to: Optional[str] = "", - error_code: Optional[str] = "", + redirect_to: str = "", + error_code: str = "", context: Optional[dict] = None ) -> None: """Initialize the exception with the message and the URL to redirect to.""" @@ -410,7 +410,7 @@ class RedirectToPage(OpenEdxFilterException): - redirect_to (str): URL to redirect to. """ - def __init__(self, message: str, redirect_to: Optional[str] = "") -> None: + def __init__(self, message: str, redirect_to: str = "") -> None: """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) @@ -426,7 +426,7 @@ class RenderAlternativeInvalidCertificate(OpenEdxFilterException): - template_name (str): template path of the new certificate. """ - def __init__(self, message: str, template_name: Optional[str] = "") -> None: + def __init__(self, message: str, template_name: str = "") -> None: """Initialize the exception with the message and the template path to render instead.""" super().__init__(message, template_name=template_name) @@ -583,7 +583,7 @@ class RedirectToPage(OpenEdxFilterException): - redirect_to (str): URL to redirect to. """ - def __init__(self, message: str, redirect_to: Optional[str] = "") -> None: + def __init__(self, message: str, redirect_to: str = "") -> None: """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) @@ -603,7 +603,7 @@ class RenderInvalidCourseAbout(OpenEdxFilterException): def __init__( self, message: str, - course_about_template: Optional[str] = "", + course_about_template: str = "", template_context: Optional[dict] = None ) -> None: """Initialize the exception with the message and the template to render instead.""" @@ -682,7 +682,7 @@ class RedirectToPage(OpenEdxFilterException): - redirect_to (str): URL to redirect to. """ - def __init__(self, message: str, redirect_to: Optional[str] = "") -> None: + def __init__(self, message: str, redirect_to: str = "") -> None: """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) @@ -702,7 +702,7 @@ class RenderInvalidDashboard(OpenEdxFilterException): def __init__( self, message: str, - dashboard_template: Optional[str] = "", + dashboard_template: str = "", template_context: Optional[dict] = None ) -> None: """Initialize the exception with the message and the template to render instead.""" @@ -1070,7 +1070,7 @@ class RedirectToPage(OpenEdxFilterException): - redirect_to (str): URL to redirect to. """ - def __init__(self, message: str, redirect_to: Optional[str] = ""): + def __init__(self, message: str, redirect_to: str = ""): """Initialize the exception with the message and the URL to redirect to.""" super().__init__(message, redirect_to=redirect_to) @@ -1090,7 +1090,7 @@ class RenderInvalidDashboard(OpenEdxFilterException): def __init__( self, message: str, - instructor_template: Optional[str] = "", + instructor_template: str = "", template_context: Optional[dict] = None ): """Initialize the exception with the message and the template to render instead.""" @@ -1171,7 +1171,7 @@ class RenderInvalidTemplate(OpenEdxFilterException): def __init__( self, message: str, context: Optional[dict] = None, - template_name: Optional[str] = "" + template_name: str = "" ) -> None: """Initialize the exception with the message and the template to render instead.""" super().__init__(message, context=context, template_name=template_name) From 1a01f5b5f4ecaf00e52f281795aa6de5e5c6466d Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Wed, 15 Jan 2025 13:42:42 +0100 Subject: [PATCH 8/8] refactor: address PR review --- openedx_filters/learning/filters.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openedx_filters/learning/filters.py b/openedx_filters/learning/filters.py index 910b7106..00409e1d 100644 --- a/openedx_filters/learning/filters.py +++ b/openedx_filters/learning/filters.py @@ -862,8 +862,8 @@ class RenderCustomResponse(OpenEdxFilterException): instead. Arguments: - message (str): error message for the exception. - response (HttpResponse): custom response which will be returned by the XBlock render view. + - message (str): error message for the exception. + - response (HttpResponse): custom response which will be returned by the XBlock render view. """ def __init__(self, message: str, response: Optional[HttpResponse] = None):