openedx-plugin-sample 3.8.0__py3-none-any.whl

openedx_plugin_sample/settings/production.py

@@ -0,0 +1,16 @@
+"""
+Production settings for the openedx_plugin_sample application.
+"""
+
+from openedx_plugin_sample.settings.common import plugin_settings as common_settings
+
+
+def plugin_settings(settings):
+    """
+    Set up production-specific settings.
+
+    Args:
+        settings (dict): Django settings object
+    """
+    # Apply common settings
+    common_settings(settings)

openedx_plugin_sample/settings/test.py

@@ -0,0 +1,17 @@
+"""
+Test settings for the openedx_plugin_sample application.
+"""
+
+from openedx_plugin_sample.settings.common import plugin_settings as common_settings
+
+
+def plugin_settings(settings):
+    """
+    Set up test-specific settings.
+
+    Args:
+        settings (dict): Django settings object
+    """
+
+    # Apply common settings
+    common_settings(settings)

openedx_plugin_sample/signals.py

@@ -0,0 +1,66 @@
+"""
+Open edX Events signal handlers for the openedx_plugin_sample application.
+
+This module demonstrates how to consume Open edX Events to react to platform
+activity. Events are part of the Hooks Extension Framework and provide a
+stable way to extend Open edX without modifying core code.
+
+Key Concepts:
+- Events are fired at specific points in the platform lifecycle
+- Each event delivers a structured data object (defined in openedx-events)
+- Event handlers can take action but cannot modify the event payload
+- Handlers must be imported from apps.py ready() so @receiver registers them
+
+Official Documentation:
+- Events Overview: https://docs.openedx.org/projects/openedx-events/en/latest/
+- Available Events: https://docs.openedx.org/projects/openedx-events/en/latest/reference/events.html
+- Consuming Events: https://docs.openedx.org/projects/openedx-events/en/latest/how-tos/consume-an-event.html
+- Event Data Objects: https://docs.openedx.org/projects/openedx-events/en/latest/reference/data.html
+"""
+
+import logging
+
+from django.dispatch import receiver
+from openedx_events.learning.data import CourseEnrollmentData
+from openedx_events.learning.signals import COURSE_ENROLLMENT_CHANGED
+
+from .models import CourseArchiveStatus
+
+logger = logging.getLogger(__name__)
+
+
+@receiver(COURSE_ENROLLMENT_CHANGED)
+def unarchive_on_verified_upgrade(
+    signal, sender, enrollment: CourseEnrollmentData, **kwargs
+):  # pylint: disable=unused-argument
+    """
+    Unarchive a course on the learner's dashboard when they upgrade to verified.
+
+    If a learner has previously archived a course (CourseArchiveStatus.is_archived=True)
+    and then upgrades to the verified track, the course shouldn't stay tucked away
+    in their "Archived" section -- their renewed investment in the course is a
+    strong signal that they want it back in their active list.
+
+    This is intentionally a one-time nudge, not a continuous rule: if the learner
+    re-archives the course later, we respect that choice. That's why we react to
+    the enrollment-change *event* rather than computing `isArchivedByLearner`
+    from enrollment mode in the filter pipeline.
+
+    Event reference:
+    https://docs.openedx.org/projects/openedx-events/en/latest/reference/events.html#openedx_events.learning.signals.COURSE_ENROLLMENT_CHANGED
+    """
+    if not enrollment.is_active or enrollment.mode != "verified":
+        return
+
+    updated = CourseArchiveStatus.objects.filter(
+        user_id=enrollment.user.id,
+        course_run__course_key=enrollment.course.course_key,
+        is_archived=True,
+    ).update(is_archived=False, archive_date=None)
+
+    if updated:
+        logger.info(
+            "Unarchived course %s for user %s after verified upgrade",
+            enrollment.course.course_key,
+            enrollment.user.id,
+        )

openedx_plugin_sample/templates/openedx_plugin_sample/base.html

@@ -0,0 +1,26 @@
+
+
+{% load i18n %}
+{% trans "Dummy text to generate a translation (.po) source file. It is safe to delete this line. It is also safe to delete (load i18n) above if there are no other (trans) tags in the file" %}
+
+{% comment %}
+As the developer of this package, don't place anything here if you can help it
+since this allows developers to have interoperability between your template
+structure and their own.
+
+Example: Developer melding the 2SoD pattern to fit inside with another pattern::
+
+    {% extends "base.html" %}
+    {% load static %}
+
+    <!-- Their site uses old school block layout -->
+    {% block extra_js %}
+
+        <!-- Your package using 2SoD block layout -->
+        {% block javascript %}
+            <script src="{% static 'js/ninja.js' %}" type="text/javascript"></script>
+        {% endblock javascript %}
+
+    {% endblock extra_js %}
+{% endcomment %}
+

openedx_plugin_sample/urls.py

@@ -0,0 +1,21 @@
+"""
+URLs for openedx_plugin_sample.
+"""
+
+from django.urls import include, path
+from rest_framework.routers import DefaultRouter
+
+from openedx_plugin_sample.views import CourseArchiveStatusViewSet
+
+# Create a router and register our viewsets with it
+router = DefaultRouter()
+router.register(
+    r"course-archive-status",
+    CourseArchiveStatusViewSet,
+    basename="course-archive-status",
+)
+
+# The API URLs are now determined automatically by the router
+urlpatterns = [
+    path("api/v1/", include(router.urls)),
+]

openedx_plugin_sample/views.py

@@ -0,0 +1,268 @@
+"""
+Views for the openedx_plugin_sample app.
+"""
+
+import logging
+
+from django.utils import timezone
+from django_filters import rest_framework as django_filters
+from django_filters.rest_framework import DjangoFilterBackend
+from opaque_keys import InvalidKeyError
+from opaque_keys.edx.keys import CourseKey
+from rest_framework import filters, permissions, viewsets
+from rest_framework.exceptions import PermissionDenied, ValidationError
+from rest_framework.pagination import PageNumberPagination
+from rest_framework.throttling import UserRateThrottle
+
+from openedx_plugin_sample.models import CourseArchiveStatus
+from openedx_plugin_sample.serializers import CourseArchiveStatusSerializer
+
+logger = logging.getLogger(__name__)
+
+
+class IsOwnerOrStaffSuperuser(permissions.BasePermission):
+    """
+    Custom permission to only allow owners of an object or staff/superusers to view or edit it.
+    """
+
+    def has_permission(self, request, view):
+        """
+        Return True if permission is granted to the view.
+        """
+        # Allow authenticated users to list and create
+        return request.user and request.user.is_authenticated
+
+    def has_object_permission(self, request, view, obj):
+        """
+        Return True if permission is granted to the object.
+        """
+        # Allow if the object belongs to the requesting user
+        if obj.user == request.user:
+            return True
+
+        # Allow staff users and superusers
+        if request.user.is_staff or request.user.is_superuser:
+            return True
+
+        return False
+
+
+class CourseArchiveStatusPagination(PageNumberPagination):
+    """
+    Pagination class for CourseArchiveStatus.
+    """
+
+    page_size = 20
+    page_size_query_param = "page_size"
+    max_page_size = 100
+
+
+class CourseArchiveStatusThrottle(UserRateThrottle):
+    """
+    Throttle for the CourseArchiveStatus API.
+    """
+
+    rate = "60/minute"
+
+
+class CourseArchiveStatusFilterSet(django_filters.FilterSet):
+    """
+    FilterSet for CourseArchiveStatus.
+
+    The model stores a FK to CourseRun, but the public API filters and orders
+    by the course_key string (never by the internal CourseRun PK).
+    """
+
+    # Map ?course_id=course-v1:... onto the FK's course_key column.
+    course_id = django_filters.CharFilter(field_name="course_run__course_key")
+
+    # Expose ?ordering=course_id (and other fields) without leaking the
+    # double-underscore FK lookup path.
+    ordering = django_filters.OrderingFilter(
+        fields=(
+            ("course_run__course_key", "course_id"),
+            ("user", "user"),
+            ("is_archived", "is_archived"),
+            ("archive_date", "archive_date"),
+            ("created_at", "created_at"),
+            ("updated_at", "updated_at"),
+        )
+    )
+
+    class Meta:
+        """
+        FilterSet Meta options for CourseArchiveStatus.
+        """
+
+        model = CourseArchiveStatus
+        fields = ["course_id", "user", "is_archived"]
+
+
+class CourseArchiveStatusViewSet(viewsets.ModelViewSet):
+    """
+    API viewset for CourseArchiveStatus.
+
+    Allows users to view their own course archive statuses and staff/superusers to view all.
+    Pagination is applied with a default page size of 20 (max 100).
+    Filtering is available on course_id, user, and is_archived fields.
+    Ordering is available on all fields.
+    """
+
+    serializer_class = CourseArchiveStatusSerializer
+    permission_classes = [IsOwnerOrStaffSuperuser]
+    pagination_class = CourseArchiveStatusPagination
+    throttle_classes = [
+        CourseArchiveStatusThrottle,
+    ]
+    filter_backends = [DjangoFilterBackend, filters.OrderingFilter]
+    filterset_class = CourseArchiveStatusFilterSet
+    ordering = ["-updated_at"]
+
+    def get_queryset(self):
+        """
+        Return the queryset for this viewset.
+
+        Regular users can only see their own records.
+        Staff and superusers can see all records but with optimized queries.
+        """
+        user = self.request.user
+
+        # Validate query parameters to prevent injection
+        self._validate_query_params()
+
+        # Always use select_related to avoid N+1 queries when accessing
+        # related user and course_run (for course_key) fields.
+        base_queryset = CourseArchiveStatus.objects.select_related("user", "course_run")
+
+        if user.is_staff or user.is_superuser:
+            return base_queryset
+
+        # Regular users only see their own records
+        return base_queryset.filter(user=user)
+
+    def _validate_query_params(self):
+        """
+        Validate query parameters to prevent injection.
+        """
+        # Example validation for course_id format
+        course_id = self.request.query_params.get("course_id")
+        if course_id and not self._is_valid_course_id(course_id):
+            logger.warning(
+                "Invalid course_id in request: %s, user: %s",
+                course_id,
+                self.request.user.username,
+            )
+            raise ValidationError({"course_id": "Invalid course ID format."})
+
+    def _is_valid_course_id(self, course_id):
+        """
+        Check if the course_id is in a valid format.
+
+        This is a basic implementation - in production, you might use a more
+        sophisticated validator from the edx-platform.
+        """
+        try:
+            CourseKey.from_string(course_id)
+            return True
+        except InvalidKeyError:
+            return False
+
+    def perform_create(self, serializer):
+        """
+        Perform creation of a new CourseArchiveStatus.
+
+        Validates permission for user override and sets archive_date if needed.
+        """
+        # Check if user was explicitly provided and differs from current user
+        if "user" in self.request.data:
+            requested_user_id = self.request.data["user"]
+            if requested_user_id != self.request.user.id and not (
+                self.request.user.is_staff or self.request.user.is_superuser
+            ):
+                logger.warning(
+                    "Permission denied: User %s tried to create a record for user %s",
+                    self.request.user.username,
+                    requested_user_id,
+                )
+                raise PermissionDenied(
+                    "You do not have permission to create records for other users."
+                )
+
+        # Set archive_date if is_archived is True
+        data = {}
+        if serializer.validated_data.get("is_archived", False):
+            data["archive_date"] = timezone.now()
+
+        # Create the record
+        instance = serializer.save(**data)
+
+        # Log at debug level for normal operation
+        logger.debug(
+            "CourseArchiveStatus created: course_id=%s, user=%s, is_archived=%s",
+            instance.course_run.course_key,
+            instance.user.username,
+            instance.is_archived,
+        )
+
+        return instance
+
+    def perform_update(self, serializer):
+        """
+        Perform update of an existing CourseArchiveStatus.
+
+        Validates permission for user override and updates archive_date if needed.
+        """
+        instance = serializer.instance
+
+        # Check if user was explicitly provided and differs from current user
+        if "user" in self.request.data:
+            requested_user_id = self.request.data["user"]
+            if requested_user_id != self.request.user.id and not (
+                self.request.user.is_staff or self.request.user.is_superuser
+            ):
+                logger.warning(
+                    "Permission denied: User %s tried to update a record for user %s",
+                    self.request.user.username,
+                    requested_user_id,
+                )
+                raise PermissionDenied(
+                    "You do not have permission to update records for other users."
+                )
+
+        # Handle archive_date if is_archived changes
+        data = {}
+        if "is_archived" in serializer.validated_data:
+            # If changing from not archived to archived
+            if serializer.validated_data["is_archived"] and not instance.is_archived:
+                data["archive_date"] = timezone.now()
+            # If changing from archived to not archived
+            elif not serializer.validated_data["is_archived"] and instance.is_archived:
+                data["archive_date"] = None
+
+        # Update the record
+        updated_instance = serializer.save(**data)
+
+        # Log at debug level
+        logger.debug(
+            "CourseArchiveStatus updated: course_id=%s, user=%s, is_archived=%s",
+            updated_instance.course_run.course_key,
+            updated_instance.user.username,
+            updated_instance.is_archived,
+        )
+
+        return updated_instance
+
+    def perform_destroy(self, instance):
+        """
+        Perform deletion of an existing CourseArchiveStatus.
+        """
+        # Log at debug level before deletion
+        logger.debug(
+            "CourseArchiveStatus deleted: course_id=%s, user=%s, by=%s",
+            instance.course_run.course_key,
+            instance.user.username,
+            self.request.user.username,
+        )
+
+        # Delete the instance
+        return super().perform_destroy(instance)

openedx_plugin_sample-3.8.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: openedx-plugin-sample
+Version: 3.8.0
+Summary: A sample backend plugin for the Open edX Platform
+Author-email: Open edX Project <oscm@openedx.org>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/openedx/sample-plugin
+Project-URL: Repository, https://github.com/openedx/sample-plugin
+Keywords: Python,edx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: Django
+Requires-Dist: djangorestframework
+Requires-Dist: django-filter
+Requires-Dist: edx-opaque-keys
+Requires-Dist: openedx-core
+Requires-Dist: openedx-events
+Requires-Dist: openedx-filters
+Requires-Dist: openedx-atlas
+Dynamic: license-file
+
+# backend-plugin-sample
+
+A Django app plugin for edx-platform that adds a small course-archiving feature: learners can mark courses as archived (hidden from their active list) and unarchive them later. It demonstrates three backend extension points working together:
+
+- A model + REST API (`CourseArchiveStatus`), consumed by [`frontend-plugin-sample`](../frontend-plugin-sample/)
+- An [Open edX Events](https://docs.openedx.org/projects/openedx-events/en/latest/) handler that auto-unarchives on verified upgrade
+- An [Open edX Filters](https://docs.openedx.org/projects/openedx-filters/en/latest/) pipeline step that rewrites the course-about URL
+
+## How to use it
+
+See the root [README](../README.md) for setup instructions. With Tutor, [`tutor-contrib-sample`](../tutor-contrib-sample/) installs this plugin automatically (or bind-mounts your local checkout if you `tutor mounts add` it). Without Tutor, `pip install -e .` into your edx-platform environment and run migrations.
+
+## How it works
+
+**Plugin registration.** [`apps.py`](./src/openedx_plugin_sample/apps.py) declares the Django app to edx-platform via the `plugin_app` config (URL routing, settings, signal registration). The entry points in [`pyproject.toml`](./pyproject.toml) make the platform discover the app automatically — no `INSTALLED_APPS` edit needed. See [How to create a plugin app](https://docs.openedx.org/projects/edx-django-utils/en/latest/plugins/how_tos/how_to_create_a_plugin_app.html).
+
+**Model.** [`models.py`](./src/openedx_plugin_sample/models.py) defines `CourseArchiveStatus(user, course_id, is_archived, archive_date)`, indexed for the lookups the API performs. Registered in Django admin via [`admin.py`](./src/openedx_plugin_sample/admin.py).
+
+**REST API.** [`views.py`](./src/openedx_plugin_sample/views.py) exposes the model as a DRF `ModelViewSet` at `/sample-plugin/api/v1/course-archive-status/`, with per-user permissions, throttling, and pagination. Serializer in [`serializers.py`](./src/openedx_plugin_sample/serializers.py); URLs in [`urls.py`](./src/openedx_plugin_sample/urls.py). Business logic (e.g. setting `archive_date` when `is_archived` becomes true) lives in `perform_create`/`perform_update` rather than in the serializer.
+
+**Event handler.** [`signals.py`](./src/openedx_plugin_sample/signals.py) listens for `COURSE_ENROLLMENT_CHANGED` and unarchives a learner's course when they upgrade to the verified track. An event (not a filter) is the right shape here because we want a one-time nudge at the moment of upgrade — if the learner re-archives the course later, we respect that. A filter would re-impose the rule on every render.
+
+**Filter.** [`pipeline.py`](./src/openedx_plugin_sample/pipeline.py) implements `ChangeCourseAboutPageUrl`, a `PipelineStep` for `org.openedx.learning.course.about.render.started.v1` that rewrites course-about URLs to an external host. Registered via `OPEN_EDX_FILTERS_CONFIG` in [`settings/common.py`](./src/openedx_plugin_sample/settings/common.py).
+
+**Settings.** Per-environment settings live in [`settings/`](./src/openedx_plugin_sample/settings/) (`common.py`, `production.py`, `test.py`). The plugin app loads these via its `plugin_app` config in `apps.py`.
+
+## Testing and quality
+
+```bash
+cd backend-plugin-sample
+make requirements   # install test deps
+make test           # pytest
+make quality        # lint
+```
+
+Tests live in [`tests/`](./tests/).

openedx_plugin_sample-3.8.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+openedx_plugin_sample/__init__.py,sha256=E9fmKelIlLZ45iHYCtDbKUrTE3-52gChGfskhKc70TA,154
+openedx_plugin_sample/admin.py,sha256=g0nbHkGT-SaFWxKbJXma1wJHBArThDyrFT7Hw_zSrc8,1838
+openedx_plugin_sample/apps.py,sha256=h2fvV2lnRJPeJJmdrYO7FC6Ty9jr1O6MMlEQ7_o-H1M,5595
+openedx_plugin_sample/models.py,sha256=e1Q-U1l_FHlTj1v7NTsX4KXyrp5bCF-JWl7hUXaW_7k,2220
+openedx_plugin_sample/pipeline.py,sha256=FkF5Kgh6CmLO84MKfPyO78MyH8VLWhFZRroadmhwTR4,3886
+openedx_plugin_sample/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openedx_plugin_sample/serializers.py,sha256=w_n2SWRk6P2zzmDD_yNnnNzq8oE6a1epe_66gcOPWu0,1851
+openedx_plugin_sample/signals.py,sha256=_j-ORn5Mo0WqJEt9LGXPb0_CBRN1tYCZkInL95YhJ0g,2815
+openedx_plugin_sample/urls.py,sha256=SY9POVN6X1jPYfR_WmqJAGI3BCX5qvLTnS77-20pXag,517
+openedx_plugin_sample/views.py,sha256=DW6R5XpB8LSLbuyuzl6hiXWJcqU8zj0GSTg5RacL-_Y,9233
+openedx_plugin_sample/conf/locale/config.yaml,sha256=Rbk0_bjc9HRZTRQvzO58sKsdMIeP7EmhyeOO30l7dQ8,2281
+openedx_plugin_sample/migrations/0001_initial.py,sha256=ZI9pSuPN7GuHFJmWMJnD5vaHj25WIq7ErUakHF0JAMA,1803
+openedx_plugin_sample/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openedx_plugin_sample/settings/common.py,sha256=RcMppJn0mmFS_ium1IxSHO5zMoO5X-VVJLqRnTNEDyY,5246
+openedx_plugin_sample/settings/production.py,sha256=R1_L0P9cbSjKxhbaezTkcd0dxZox2cEYhpE0v47D34U,364
+openedx_plugin_sample/settings/test.py,sha256=oYi7SuwG6K56IXGtR8GUfrajua7m2_2_sfHrgYYLop0,353
+openedx_plugin_sample/templates/openedx_plugin_sample/base.html,sha256=NHmMV45xJTnPEKQltuhe5Ddw9MDZLIQD_rK8GRXhqrU,873
+openedx_plugin_sample-3.8.0.dist-info/licenses/LICENSE.txt,sha256=_kYizHmx1l2Y2boQzMunfQZ7A1T8r_mzfiD83ObbafY,10177
+openedx_plugin_sample-3.8.0.dist-info/METADATA,sha256=f6VHn5NO5vKL6Uo6GSJt-zi-obBvILPJsYsYdsMoIII,4456
+openedx_plugin_sample-3.8.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+openedx_plugin_sample-3.8.0.dist-info/entry_points.txt,sha256=-h7tq5JL02glSCuvKRpX3lMI9tO8s7_SS6vIE5fxLJU,173
+openedx_plugin_sample-3.8.0.dist-info/top_level.txt,sha256=hRO3yIbde1yryAI7pdB_9dzMyQf138iKO0DBEjQFXUg,22
+openedx_plugin_sample-3.8.0.dist-info/RECORD,,

openedx_plugin_sample-3.8.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openedx_plugin_sample-3.8.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[cms.djangoapp]
+openedx_plugin_sample = openedx_plugin_sample.apps:SamplePluginConfig
+
+[lms.djangoapp]
+openedx_plugin_sample = openedx_plugin_sample.apps:SamplePluginConfig