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

openedx_plugin_sample/settings/common.py

@@ -0,0 +1,135 @@
+"""
+Common settings for the openedx_plugin_sample application.
+
+This module demonstrates how Django App Plugins integrate with the platform's
+settings system. Plugin settings are merged with the main settings during
+platform initialization.
+
+Plugin Settings Integration:
+The plugin_settings function is called during Django startup and receives
+the main settings object. You can modify this object to add plugin-specific
+configuration that integrates seamlessly with the platform.
+
+Official Documentation:
+- Plugin Settings: https://docs.openedx.org/projects/edx-django-utils/en/latest/plugins/how_tos/how_to_create_a_plugin_app.html#plugin-settings
+- Django Settings: https://docs.djangoproject.com/en/stable/topics/settings/
+
+Settings Organization:
+- common.py: Settings for all environments
+- production.py: Production-specific overrides
+- test.py: Test environment optimizations
+
+Integration Points:
+- OPEN_EDX_FILTERS_CONFIG: Register filters with the platform
+- API rate limiting and throttling configuration
+- Database connection settings for plugin models
+- External service integration parameters
+- Feature flags and environment-specific toggles
+"""  # noqa: E501
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def plugin_settings(settings):
+    """
+    Configure plugin-specific Django settings.
+
+    This function is called during Django startup to merge plugin settings
+    with the main platform configuration. All settings added here become
+    available throughout the Django application.
+
+    Args:
+        settings (dict): Main Django settings object to modify
+
+    Common Settings Patterns:
+
+    # Plugin-specific configuration
+    settings.SAMPLE_PLUGIN_API_RATE_LIMIT = "60/minute"
+    settings.SAMPLE_PLUGIN_ARCHIVE_RETENTION_DAYS = 365
+
+    # External service integration
+    settings.SAMPLE_PLUGIN_EXTERNAL_API_URL = "https://api.example.com"
+    settings.SAMPLE_PLUGIN_API_KEY = "your-api-key"
+
+    # Feature flags
+    settings.SAMPLE_PLUGIN_ENABLE_ARCHIVING = True
+    settings.SAMPLE_PLUGIN_ENABLE_NOTIFICATIONS = False
+
+    Environment-Specific Settings:
+    Different environment files can override these settings:
+    - production.py: Stricter rate limits, external API endpoints
+    - test.py: Faster timeouts, mock services, in-memory databases
+    - development.py: Debug logging, local service endpoints
+
+    Security Considerations:
+    - Never commit API keys or secrets to version control
+    - Use environment variables for sensitive configuration
+    - Validate setting values to prevent configuration errors
+    """
+    # Plugin is configured but no additional settings needed for this basic example
+    # Uncomment and modify the examples below for your use case:
+
+    # Plugin-specific configuration
+    # settings.SAMPLE_PLUGIN_API_RATE_LIMIT = "60/minute"
+    # settings.SAMPLE_PLUGIN_ARCHIVE_RETENTION_DAYS = 365
+
+    # Register Open edX Filters (additive approach)
+    _configure_openedx_filters(settings)
+
+
+def _configure_openedx_filters(settings):
+    """
+    Configure Open edX Filters for the sample plugin.
+
+    This function demonstrates the proper way to register filters by:
+    1. Preserving existing filter configuration from other plugins
+    2. Adding our filter configuration additively
+    3. Avoiding duplicate pipeline steps
+    4. Logging configuration state for debugging
+
+    Args:
+        settings (dict): Django settings object
+    """
+    # Get existing filter configuration (may be from other plugins or platform)
+    filters_config = getattr(settings, 'OPEN_EDX_FILTERS_CONFIG', {})
+
+    # Filter we want to register
+    filter_name = "org.openedx.learning.course_about.page.url.requested.v1"
+    our_pipeline_step = "openedx_plugin_sample.pipeline.ChangeCourseAboutPageUrl"
+
+    # Check if this filter already has configuration
+    if filter_name in filters_config:
+        logger.debug(f"Filter {filter_name} already configured, adding our pipeline step")
+
+        # Get existing pipeline steps
+        existing_pipeline = filters_config[filter_name].get("pipeline", [])
+
+        # Check if our pipeline step is already registered
+        if our_pipeline_step in existing_pipeline:
+            logger.info(
+                f"Pipeline step {our_pipeline_step} already registered for filter {filter_name}. "
+                "This may indicate the plugin is being loaded multiple times or another plugin "
+                "has registered the same pipeline step."
+            )
+        else:
+            # Add our pipeline step to existing configuration
+            existing_pipeline.append(our_pipeline_step)
+            filters_config[filter_name]["pipeline"] = existing_pipeline
+            logger.debug(f"Added {our_pipeline_step} to existing filter configuration")
+    else:
+        # Create new filter configuration
+        logger.debug(f"Creating new filter configuration for {filter_name}")
+        filters_config[filter_name] = {
+            "pipeline": [our_pipeline_step],
+            "fail_silently": False,
+        }
+
+    # Update the settings object
+    settings.OPEN_EDX_FILTERS_CONFIG = filters_config
+
+    logger.debug(
+        f"Final filter configuration for {filter_name}: "
+        f"{filters_config.get(filter_name, {})}"
+    )

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,132 @@
+"""
+Open edX Events signal handlers for the openedx_plugin_sample application.
+
+This module demonstrates how to consume Open edX Events (signals) to react to
+platform activities and integrate with external systems. Events are part of
+the Hooks Extension Framework and provide a stable way to extend Open edX.
+
+What Are Open edX Events?
+Events are signals sent when specific actions occur in the platform. Unlike
+traditional Django signals, Open edX Events have standardized data structures
+and are designed for external consumption.
+
+Key Concepts:
+- Events are fired at specific points in the platform lifecycle
+- Each event includes structured data (defined in openedx-events)
+- Event handlers can perform actions but cannot modify the event data
+- Events support both internal processing and external event bus integration
+
+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
+- Hooks Framework: https://docs.openedx.org/en/latest/developers/concepts/hooks_extension_framework.html
+
+Registration Process:
+1. Import the event signal from openedx-events
+2. Create handler function with correct signature
+3. Decorate with @receiver
+4. Import this module in apps.py ready() method
+
+Event Data Structure:
+Each event defines specific data attributes. Check the event definition in the
+official documentation to understand available data:
+- Signal Reference: https://docs.openedx.org/projects/openedx-events/en/latest/reference/events.html
+- Data Objects: https://docs.openedx.org/projects/openedx-events/en/latest/reference/data.html
+- Example: COURSE_CATALOG_INFO_CHANGED provides catalog_info: CourseCatalogData
+
+Common Use Cases:
+- Integration with external systems (CRM, analytics, notifications)
+- Custom logging and audit trails
+- Triggering workflows in other services
+- Synchronizing data with external databases
+"""
+
+import logging
+
+from django.dispatch import receiver
+from openedx_events.content_authoring.data import CourseCatalogData
+from openedx_events.content_authoring.signals import COURSE_CATALOG_INFO_CHANGED
+
+logger = logging.getLogger(__name__)
+
+
+@receiver(COURSE_CATALOG_INFO_CHANGED)
+def log_course_info_changed(signal, sender, catalog_info: CourseCatalogData, **kwargs):  # pylint: disable=unused-argument # noqa: E501
+    """
+    Handle course catalog information changes.
+
+    This function demonstrates how to consume the COURSE_CATALOG_INFO_CHANGED event,
+    which is fired whenever course catalog information is updated in the platform.
+
+    Event Trigger Conditions:
+    - Course metadata is modified (name, description, etc.)
+    - Course schedule is updated
+    - Course visibility settings change
+    - Other catalog-related modifications
+
+    Args:
+        signal: The signal instance that triggered this handler
+        sender: The model class that sent the signal
+        catalog_info (CourseCatalogData): Structured data about the course
+        **kwargs: Additional context parameters
+
+    CourseCatalogData Attributes:
+    Based on the official data structure documentation:
+    https://docs.openedx.org/projects/openedx-events/en/latest/reference/data.html#openedx_events.content_authoring.data.CourseCatalogData
+
+    - course_key (CourseKey): Unique course identifier
+    - name (str): Course display name
+    - schedule (CourseScheduleData): Start/end dates and pacing
+    - hidden (bool): Course visibility status
+
+    Real-World Use Cases:
+    - Sync course metadata with external systems (CRM, marketing sites)
+    - Update search indexes when course information changes
+    - Trigger email notifications to administrators
+    - Log changes for audit and compliance
+    - Update analytics dashboards with new course information
+
+    Example Implementation::
+
+        # Send to external CRM system
+        external_api.update_course(
+            course_id=str(catalog_info.course_key),
+            name=catalog_info.name,
+            is_hidden=catalog_info.hidden
+        )
+
+        # Update internal tracking
+        CourseChangeLog.objects.create(
+            course_key=catalog_info.course_key,
+            change_type='catalog_updated',
+            timestamp=timezone.now()
+        )
+
+    Performance Considerations:
+    - Keep processing lightweight (events should not block platform operations)
+    - Use asynchronous tasks for heavy processing (Celery, etc.)
+    - Handle exceptions gracefully to prevent platform disruption
+    """
+    logging.info(f"Course catalog updated: {catalog_info.course_key}")
+
+    # Access available data from the event
+    logging.debug(f"Course name: {catalog_info.name}")
+    logging.debug(f"Course hidden: {catalog_info.hidden}")
+
+    # Example: Integrate with external systems
+    # try:
+    #     # Send to external system
+    #     external_system.notify_course_update(
+    #         course_id=str(catalog_info.course_key),
+    #         course_name=catalog_info.name,
+    #         is_hidden=catalog_info.hidden
+    #     )
+    # except Exception as e:
+    #     logging.error(f"Failed to notify external system: {e}")
+
+    # Example: Update internal tracking
+    # from .models import CourseArchiveStatus
+    # CourseArchiveStatus.objects.filter(
+    #     course_id=catalog_info.course_key
+    # ).update(last_catalog_update=timezone.now())

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,241 @@
+"""
+Views for the openedx_plugin_sample app.
+"""
+
+import logging
+
+from django.utils import timezone
+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 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_fields = ["course_id", "user", "is_archived"]
+    ordering_fields = [
+        "course_id",
+        "user",
+        "is_archived",
+        "archive_date",
+        "created_at",
+        "updated_at",
+    ]
+    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
+        base_queryset = CourseArchiveStatus.objects.select_related("user")
+
+        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_id,
+            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_id,
+            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_id,
+            instance.user.username,
+            self.request.user.username,
+        )
+
+        # Delete the instance
+        return super().perform_destroy(instance)