openedx-plugin-sample 3.0.0__py2.py3-none-any.whl

openedx_plugin_sample/__init__.py

@@ -0,0 +1,7 @@
+"""
+A sample backend plugin for the Open edX Platform.
+"""
+
+from importlib.metadata import version as get_version
+
+__version__ = get_version(__package__)

openedx_plugin_sample/apps.py

@@ -0,0 +1,134 @@
+"""
+openedx_plugin_sample Django application initialization.
+"""
+
+from django.apps import AppConfig
+from edx_django_utils.plugins.constants import PluginSettings, PluginURLs
+
+
+class SamplePluginConfig(AppConfig):
+    """
+    Django App Plugin configuration for Open edX platform integration.
+
+    This class demonstrates the complete Django App Plugin pattern, which allows
+    you to add new functionality to edx-platform without modifying core code.
+
+    Key Features Demonstrated:
+    - URL configuration for both LMS and CMS
+    - Settings integration across environments (common, test, production)
+    - Signal handler registration for Open edX Events
+    - Proper plugin app structure following Open edX patterns
+
+    Official Documentation:
+    - Plugin Creation: https://docs.openedx.org/projects/edx-django-utils/en/latest/plugins/how_tos/how_to_create_a_plugin_app.html
+    - Plugin Overview: https://docs.openedx.org/projects/edx-django-utils/en/latest/plugins/readme.html
+    - Hooks Framework: https://docs.openedx.org/en/latest/developers/concepts/hooks_extension_framework.html
+
+    Real-World Usage:
+    This pattern is used when you need to:
+    - Add new models and database tables
+    - Provide new REST API endpoints
+    - Integrate with external systems via events
+    - Modify platform behavior with filters
+    - Add custom business logic
+
+    Entry Point Configuration:
+    This plugin is registered in pyproject.toml as::
+
+        [project.entry-points."lms.djangoapp"]
+        openedx_plugin_sample = "openedx_plugin_sample.apps:SamplePluginConfig"
+
+        [project.entry-points."cms.djangoapp"]
+        openedx_plugin_sample = "openedx_plugin_sample.apps:SamplePluginConfig"
+
+    The platform automatically discovers and loads plugins registered in these entry points.
+    """  # pylint: disable=line-too-long # noqa: E501
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "openedx_plugin_sample"
+    plugin_app = {
+        "url_config": {
+            "lms.djangoapp": {
+                PluginURLs.NAMESPACE: "openedx_plugin_sample",
+                PluginURLs.REGEX: r"^sample-plugin/",
+                PluginURLs.RELATIVE_PATH: "urls",
+            },
+            "cms.djangoapp": {
+                PluginURLs.NAMESPACE: "openedx_plugin_sample",
+                PluginURLs.REGEX: r"^sample-plugin/",
+                PluginURLs.RELATIVE_PATH: "urls",
+            },
+        },
+        PluginSettings.CONFIG: {
+            "lms.djangoapp": {
+                "common": {
+                    PluginURLs.RELATIVE_PATH: "settings.common",
+                },
+                "test": {
+                    PluginURLs.RELATIVE_PATH: "settings.test",
+                },
+                "production": {
+                    PluginURLs.RELATIVE_PATH: "settings.production",
+                },
+            },
+            "cms.djangoapp": {
+                "common": {
+                    PluginURLs.RELATIVE_PATH: "settings.common",
+                },
+                "test": {
+                    PluginURLs.RELATIVE_PATH: "settings.test",
+                },
+                "production": {
+                    PluginURLs.RELATIVE_PATH: "settings.production",
+                },
+            },
+        },
+        # Alternative: PluginSignals.CONFIG
+        # You can define signal connections here instead of in ready(), but the
+        # ready() method approach is more flexible for complex signal handling.
+        #
+        # Example PluginSignals configuration:
+        # PluginSignals.CONFIG: {
+        #     "lms.djangoapp": {
+        #         "relative_path": "signals",
+        #         "receivers": [{
+        #             "receiver_func_name": "log_course_info_changed",
+        #             "signal_path": "openedx_events.content_authoring.signals.COURSE_CATALOG_INFO_CHANGED",
+        #         }]
+        #     }
+        # }
+        #
+        # Documentation:
+        # - PluginSignals: https://docs.openedx.org/projects/edx-django-utils/en/latest/plugins/how_tos/how_to_create_a_plugin_app.html#plugin-signals  # noqa: E501
+        # - Open edX Events: https://docs.openedx.org/projects/openedx-events/en/latest/
+    }
+
+    def ready(self):
+        """
+        Initialize the plugin when Django starts.
+
+        This method is called when Django initializes this app. It's the proper
+        place to import signal handlers, register filters, and perform other
+        startup tasks.
+
+        Key Responsibilities:
+        - Import signal handlers to register Open edX Event receivers
+        - Register Open edX Filters (if not done via settings)
+        - Initialize any plugin-specific configuration
+        - Perform validation checks
+
+        Django Documentation:
+        - AppConfig.ready(): https://docs.djangoproject.com/en/stable/ref/applications/#django.apps.AppConfig.ready
+
+        Open edX Documentation:
+        - Events: https://docs.openedx.org/projects/openedx-events/en/latest/how-tos/consume-an-event.html
+        - Filters: https://docs.openedx.org/projects/openedx-filters/en/latest/how-tos/using-filters.html
+
+        Why Import in ready():
+        Signal handlers must be imported for the @receiver decorators to register
+        with Django's signal dispatcher. Importing in ready() ensures this happens
+        when the app initializes, not when modules are first loaded.
+        """
+        # Import signal handlers to register Open edX Event receivers
+        # This import registers all @receiver decorated functions in signals.py
+        from . import signals  # pylint: disable=import-outside-toplevel,unused-import

openedx_plugin_sample/conf/locale/config.yaml

@@ -0,0 +1,85 @@
+# Configuration for i18n workflow.
+
+locales:
+    - en  # English - Source Language
+    - am  # Amharic
+    - ar  # Arabic
+    - az  # Azerbaijani
+    - bg_BG  # Bulgarian (Bulgaria)
+    - bn_BD  # Bengali (Bangladesh)
+    - bn_IN  # Bengali (India)
+    - bs  # Bosnian
+    - ca  # Catalan
+    - ca@valencia  # Catalan (Valencia)
+    - cs  # Czech
+    - cy  # Welsh
+    - da  # Danish
+    - de_DE  # German (Germany)
+    - el  # Greek
+    - en  # English
+    - en_GB  # English (United Kingdom)
+    # Don't pull these until we figure out why pages randomly display in these locales,
+    # when the user's browser is in English and the user is not logged in.
+    # - en@lolcat  # LOLCAT English
+    # - en@pirate  # Pirate English
+    - es_419  # Spanish (Latin America)
+    - es_AR  # Spanish (Argentina)
+    - es_EC  # Spanish (Ecuador)
+    - es_ES  # Spanish (Spain)
+    - es_MX  # Spanish (Mexico)
+    - es_PE  # Spanish (Peru)
+    - et_EE  # Estonian (Estonia)
+    - eu_ES  # Basque (Spain)
+    - fa  # Persian
+    - fa_IR  # Persian (Iran)
+    - fi_FI  # Finnish (Finland)
+    - fil  # Filipino
+    - fr  # French
+    - gl  # Galician
+    - gu  # Gujarati
+    - he  # Hebrew
+    - hi  # Hindi
+    - hr  # Croatian
+    - hu  # Hungarian
+    - hy_AM  # Armenian (Armenia)
+    - id  # Indonesian
+    - it_IT  # Italian (Italy)
+    - ja_JP  # Japanese (Japan)
+    - kk_KZ  # Kazakh (Kazakhstan)
+    - km_KH  # Khmer (Cambodia)
+    - kn  # Kannada
+    - ko_KR  # Korean (Korea)
+    - lt_LT  # Lithuanian (Lithuania)
+    - ml  # Malayalam
+    - mn  # Mongolian
+    - mr  # Marathi
+    - ms  # Malay
+    - nb  # Norwegian Bokmål
+    - ne  # Nepali
+    - nl_NL  # Dutch (Netherlands)
+    - or  # Oriya
+    - pl  # Polish
+    - pt_BR  # Portuguese (Brazil)
+    - pt_PT  # Portuguese (Portugal)
+    - ro  # Romanian
+    - ru  # Russian
+    - si  # Sinhala
+    - sk  # Slovak
+    - sl  # Slovenian
+    - sq  # Albanian
+    - sr  # Serbian
+    - ta  # Tamil
+    - te  # Telugu
+    - th  # Thai
+    - tr_TR  # Turkish (Turkey)
+    - uk  # Ukrainian
+    - ur  # Urdu
+    - uz  # Uzbek
+    - vi  # Vietnamese
+    - zh_CN  # Chinese (China)
+    - zh_HK  # Chinese (Hong Kong)
+    - zh_TW  # Chinese (Taiwan)
+
+# The locales used for fake-accented English, for testing.
+dummy_locales:
+    - eo

openedx_plugin_sample/migrations/0001_initial.py

@@ -0,0 +1,78 @@
+# Generated by Django 4.2.20 on 2025-04-14 12:39
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+import opaque_keys.edx.django.models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="CourseArchiveStatus",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "course_id",
+                    opaque_keys.edx.django.models.CourseKeyField(
+                        db_index=True,
+                        help_text="The unique identifier for the course.",
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "is_archived",
+                    models.BooleanField(
+                        db_index=True,
+                        default=False,
+                        help_text="Whether the course is archived.",
+                    ),
+                ),
+                (
+                    "archive_date",
+                    models.DateTimeField(
+                        blank=True,
+                        help_text="The date and time when the course was archived.",
+                        null=True,
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "user",
+                    models.ForeignKey(
+                        help_text="The user who this archive status is for.",
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="course_archive_statuses",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Course Archive Status",
+                "verbose_name_plural": "Course Archive Statuses",
+                "ordering": ["-updated_at"],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name="coursearchivestatus",
+            constraint=models.UniqueConstraint(
+                fields=("course_id", "user"), name="unique_user_course_archive_status"
+            ),
+        ),
+    ]

openedx_plugin_sample/models.py

@@ -0,0 +1,65 @@
+"""
+Database models for openedx_plugin_sample.
+"""
+
+from django.contrib.auth import get_user_model
+from django.db import models
+from opaque_keys.edx.django.models import CourseKeyField
+
+
+class CourseArchiveStatus(models.Model):
+    """
+    Model to track the archive status of a course.
+
+    Stores information about whether a course has been archived and when it was archived.
+
+    .. no_pii: This model does not store PII directly, only references to users via foreign keys.
+    """
+
+    course_id = CourseKeyField(
+        max_length=255, db_index=True, help_text="The unique identifier for the course."
+    )
+
+    user = models.ForeignKey(
+        get_user_model(),
+        on_delete=models.CASCADE,
+        related_name="course_archive_statuses",
+        help_text="The user who this archive status is for.",
+    )
+
+    is_archived = models.BooleanField(
+        default=False,
+        db_index=True,  # Add index for performance on this frequently filtered field
+        help_text="Whether the course is archived.",
+    )
+
+    archive_date = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="The date and time when the course was archived.",
+    )
+
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    def __str__(self):
+        """
+        Return a string representation of the course archive status.
+        """
+        # pylint: disable=no-member
+        return f"{self.course_id} - {self.user.username} - {'Archived' if self.is_archived else 'Not Archived'}"
+
+    class Meta:
+        """
+        Meta options for the CourseArchiveStatus model.
+        """
+
+        verbose_name = "Course Archive Status"
+        verbose_name_plural = "Course Archive Statuses"
+        ordering = ["-updated_at"]
+        # Ensure combination of course_id and user is unique
+        constraints = [
+            models.UniqueConstraint(
+                fields=["course_id", "user"], name="unique_user_course_archive_status"
+            )
+        ]

openedx_plugin_sample/pipeline.py

@@ -0,0 +1,156 @@
+"""
+Open edX Filters implementation for the openedx_plugin_sample application.
+
+This module demonstrates how to use Open edX Filters to modify platform behavior
+without changing core code. Filters are part of the Hooks Extension Framework
+and allow you to intercept and modify data at specific points in the platform.
+
+What Are Open edX Filters?
+Filters are functions that can modify application behavior by altering input data
+or halting execution based on specific conditions. Unlike events (which only
+observe), filters can change what happens next in the platform.
+
+Key Concepts:
+- Filters receive data and return modified data
+- They run at specific pipeline steps during platform operations
+- Filters can halt execution by raising exceptions
+- Multiple filters can be chained together in a pipeline
+- Filters should be lightweight and handle errors gracefully
+
+Official Documentation:
+- Filters Overview: https://docs.openedx.org/projects/openedx-filters/en/latest/
+- Using Filters: https://docs.openedx.org/projects/openedx-filters/en/latest/how-tos/using-filters.html
+- Available Filters: https://docs.openedx.org/projects/openedx-filters/en/latest/reference/filters.html
+- Filter Tooling: https://docs.openedx.org/projects/openedx-filters/en/latest/reference/filters-tooling.html
+
+Registration Process:
+1. Create filter class inheriting from PipelineStep
+2. Implement run_filter() method with correct signature
+3. Register filter in Django settings OPEN_EDX_FILTERS_CONFIG
+4. Deploy and test the filter behavior
+
+Common Use Cases:
+- URL redirection and customization
+- Access control and permission checks
+- Data transformation and validation
+- Integration with external systems
+- Custom business logic implementation
+"""  # pylint: disable=line-too-long
+
+import logging
+import re
+
+from openedx_filters.filters import PipelineStep
+
+logger = logging.getLogger(__name__)
+
+
+class ChangeCourseAboutPageUrl(PipelineStep):
+    """
+    Filter to customize course about page URLs.
+
+    This filter demonstrates how to intercept and modify course about page URLs,
+    redirecting them to external sites or custom implementations.
+
+    Filter Hook Point:
+    This filter hooks into the course about page URL rendering process.
+    Register it for the filter: org.openedx.learning.course.about.render.started.v1
+
+    Registration Example (in settings/common.py)::
+
+        def plugin_settings(settings):
+            settings.OPEN_EDX_FILTERS_CONFIG = {
+                "org.openedx.learning.course.about.render.started.v1": {
+                    "pipeline": [
+                        "openedx_plugin_sample.pipeline.ChangeCourseAboutPageUrl"
+                    ],
+                    "fail_silently": False,
+                }
+            }
+
+    Filter Documentation:
+    - Available Filters: https://docs.openedx.org/projects/openedx-filters/en/latest/reference/filters.html
+    - PipelineStep: https://docs.openedx.org/projects/openedx-filters/en/latest/reference/filters-tooling.html#openedx_filters.filters.PipelineStep
+
+    Real-World Use Cases:
+    - Redirect to marketing site course pages
+    - Implement custom course discovery interfaces
+    - Add tracking parameters to URLs
+    - Route different course types to different platforms
+    - Implement A/B testing for course pages
+    """  # noqa: E501
+
+    def run_filter(self, url, org, **kwargs):  # pylint: disable=arguments-differ
+        """
+        Modify the course about page URL.
+
+        This method intercepts course about page URL generation and can modify
+        the destination URL based on business logic.
+
+        Args:
+            url (str): The original course about page URL
+            org (str): The organization/institution identifier
+            **kwargs: Additional context data from the platform
+
+        Returns:
+            dict: Dictionary with same parameter names as input
+                - url (str): Modified or original URL
+                - org (str): Organization identifier (usually unchanged)
+
+        Raises:
+            FilterException: If processing should be halted
+
+        Filter Requirements:
+        - Must return dictionary with keys matching input parameters
+        - Return None to skip this filter (let other filters run)
+        - Raise FilterException to halt pipeline execution
+        - Handle all input scenarios gracefully
+
+        URL Pattern Matching:
+        This implementation looks for Open edX course keys in the format:
+        course-v1:ORG+COURSE+RUN (e.g., course-v1:edX+DemoX+Demo_Course)
+
+        Documentation:
+        - run_filter method: https://docs.openedx.org/projects/openedx-filters/en/latest/reference/filters-tooling.html#openedx_filters.filters.PipelineStep.run_filter
+        """  # noqa: E501
+        # Extract course ID using Open edX course key pattern
+        # Course keys follow the format: course-v1:ORG+COURSE+RUN
+        pattern = r'(?P<course_id>course-v1:[^/]+)'
+
+        match = re.search(pattern, url)
+        if match:
+            course_id = match.group('course_id')
+
+            # Example: Redirect to external marketing site
+            new_url = f"https://example.com/new_about_page/{course_id}"
+
+            logger.debug(
+                f"Redirecting course about page for {course_id} from {url} to {new_url}"
+            )
+
+            # Return modified data
+            return {"url": new_url, "org": org}
+
+        # No course ID found - return original data unchanged
+        logger.debug(f"No course ID found in URL {url}, leaving unchanged")
+        return {"url": url, "org": org}
+
+        # Alternative patterns for different business logic:
+
+        # Organization-based routing:
+        # if org == "special_org":
+        #     new_url = f"https://special-site.com/courses/{course_id}"
+        #     return {"url": new_url, "org": org}
+
+        # Course type-based routing:
+        # if "MicroMasters" in course_id:
+        #     new_url = f"https://micromasters.example.com/{course_id}"
+        #     return {"url": new_url, "org": org}
+
+        # A/B testing implementation:
+        # import random
+        # if random.choice([True, False]):
+        #     new_url = f"https://variant-a.example.com/{course_id}"
+        # else:
+        #     new_url = f"https://variant-b.example.com/{course_id}"
+        # return {"url": new_url, "org": org}

openedx_plugin_sample/serializers.py

@@ -0,0 +1,39 @@
+"""
+Serializers for the openedx_plugin_sample app.
+"""
+
+from django.contrib.auth import get_user_model
+from rest_framework import serializers
+
+from openedx_plugin_sample.models import CourseArchiveStatus
+
+User = get_user_model()
+
+
+class CourseArchiveStatusSerializer(serializers.ModelSerializer):
+    """
+    Serializer for the CourseArchiveStatus model.
+    """
+
+    user = serializers.PrimaryKeyRelatedField(
+        queryset=User.objects.all(),
+        default=serializers.CurrentUserDefault(),
+        required=False,
+    )
+
+    class Meta:
+        """
+        Meta class for CourseArchiveStatusSerializer.
+        """
+
+        model = CourseArchiveStatus
+        fields = [
+            "id",
+            "course_id",
+            "user",
+            "is_archived",
+            "archive_date",
+            "created_at",
+            "updated_at",
+        ]
+        read_only_fields = ["id", "created_at", "updated_at", "archive_date"]