learning-paths-plugin 0.3.3__tar.gz → 0.3.4rc8__tar.gz

{learning_paths_plugin-0.3.3 → learning_paths_plugin-0.3.4rc8}/CHANGELOG.rst

@@ -16,6 +16,21 @@ Unreleased
 
 *
 
+0.3.4 - 2025-05-23
+******************
+
+Added
+=====
+
+* Bulk unenrollment API.
+* Enrollment audit model that tracks the enrollment state transitions.
+
+Changed
+=======
+
+* The Learning Paths API includes start and end dates for its steps.
+* Return enrollment date in the API instead of a boolean.
+
 0.3.3 - 2025-05-23
 ******************
 

{learning_paths_plugin-0.3.3/learning_paths_plugin.egg-info → learning_paths_plugin-0.3.4rc8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learning-paths-plugin
-Version: 0.3.3
+Version: 0.3.4rc8
 Summary: Learning Paths plugin
 Home-page: https://github.com/open-craft/learning-paths-plugin
 Author: OpenCraft
@@ -18,7 +18,6 @@ Requires-Python: >=3.11
 License-File: LICENSE.txt
 Requires-Dist: Django
 Requires-Dist: django-model-utils
-Requires-Dist: django-simple-history==3.4.0
 Requires-Dist: djangorestframework
 Requires-Dist: edx-django-utils
 Requires-Dist: edx-opaque-keys
@@ -121,6 +120,21 @@ Unreleased
 
 *
 
+0.3.4 - 2025-05-23
+******************
+
+Added
+=====
+
+* Bulk unenrollment API.
+* Enrollment audit model that tracks the enrollment state transitions.
+
+Changed
+=======
+
+* The Learning Paths API includes start and end dates for its steps.
+* Return enrollment date in the API instead of a boolean.
+
 0.3.3 - 2025-05-23
 ******************
 

{learning_paths_plugin-0.3.3 → learning_paths_plugin-0.3.4rc8}/learning_paths/__init__.py

@@ -2,4 +2,4 @@
 Learning Paths plugin.
 """
 
-__version__ = "0.3.3"
+__version__ = "0.3.4-rc8"

{learning_paths_plugin-0.3.3 → learning_paths_plugin-0.3.4rc8}/learning_paths/admin.py

@@ -13,6 +13,8 @@ from .models import (
     AcquiredSkill,
     LearningPath,
     LearningPathEnrollment,
+    LearningPathEnrollmentAllowed,
+    LearningPathEnrollmentAudit,
     LearningPathGradingCriteria,
     LearningPathStep,
     RequiredSkill,
@@ -135,6 +137,7 @@ class BulkEnrollUsersForm(forms.ModelForm):
         return users
 
 
+@admin.register(LearningPath)
 class LearningPathAdmin(admin.ModelAdmin):
     """Admin for Learning Path."""
 
@@ -176,18 +179,85 @@ class LearningPathAdmin(admin.ModelAdmin):
                 LearningPathEnrollment.objects.get_or_create(user=user, learning_path=form.instance)
 
 
+@admin.register(Skill)
 class SkillAdmin(admin.ModelAdmin):
     """Admin for Learning Path generic skill."""
 
     model = Skill
 
 
+class EnrollmentAuditInline(admin.TabularInline):
+    """Inline admin for LearningPathEnrollmentAudit records."""
+
+    model = LearningPathEnrollmentAudit
+    fk_name = "enrollment"
+    extra = 0
+    exclude = ["enrollment_allowed"]
+    readonly_fields = [
+        "state_transition",
+        "enrolled_by",
+        "reason",
+        "org",
+        "role",
+        "created",
+    ]
+
+    def has_add_permission(self, request, obj=None):
+        """Disable manual creation of audit records."""
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        """Disable deletion of audit records."""
+        return False
+
+
+class EnrollmentAllowedAuditInline(admin.TabularInline):
+    """Inline admin for LearningPathEnrollmentAudit records related to enrollment allowed."""
+
+    model = LearningPathEnrollmentAudit
+    fk_name = "enrollment_allowed"
+    extra = 0
+    exclude = ["enrollment"]
+    readonly_fields = [
+        "state_transition",
+        "enrolled_by",
+        "reason",
+        "org",
+        "role",
+        "created",
+    ]
+
+    def has_add_permission(self, request, obj=None):
+        """Disable manual creation of audit records."""
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        """Disable deletion of audit records."""
+        return False
+
+
+@admin.register(LearningPathEnrollment)
 class EnrolledUsersAdmin(admin.ModelAdmin):
     """Admin for Learning Path enrollment."""
 
     model = LearningPathEnrollment
     raw_id_fields = ("user",)
     autocomplete_fields = ["learning_path"]
+    inlines = [EnrollmentAuditInline]
+
+    list_display = [
+        "id",
+        "user",
+        "learning_path",
+        "is_active",
+        "created",
+    ]
+
+    list_filter = [
+        "learning_path__key",
+        "created",
+        "is_active",
+    ]
 
     search_fields = [
         "id",
@@ -197,6 +267,103 @@ class EnrolledUsersAdmin(admin.ModelAdmin):
     ]
 
 
-admin.site.register(LearningPath, LearningPathAdmin)
-admin.site.register(Skill, SkillAdmin)
-admin.site.register(LearningPathEnrollment, EnrolledUsersAdmin)
+@admin.register(LearningPathEnrollmentAllowed)
+class EnrollmentAllowedAdmin(admin.ModelAdmin):
+    """Admin configuration for LearningPathEnrollmentAllowed model."""
+
+    list_display = [
+        "id",
+        "email",
+        "get_user",
+        "learning_path",
+        "created",
+    ]
+
+    list_filter = [
+        "learning_path",
+        "created",
+    ]
+
+    search_fields = [
+        "email",
+        "user__username",
+        "user__email",
+        "learning_path__key",
+    ]
+
+    readonly_fields = [
+        "user",
+        "created",
+        "modified",
+    ]
+
+    inlines = [EnrollmentAllowedAuditInline]
+
+    def get_user(self, obj):
+        """Get the associated user, if any."""
+        return obj.user.username if obj.user else "-"
+
+    get_user.short_description = "User"
+
+
+@admin.register(LearningPathEnrollmentAudit)
+class EnrollmentAuditAdmin(admin.ModelAdmin):
+    """Admin configuration for LearningPathEnrollmentAudit model."""
+
+    list_display = [
+        "id",
+        "state_transition",
+        "enrolled_by",
+        "get_enrollee",
+        "get_learning_path",
+        "created",
+        "org",
+        "role",
+    ]
+
+    list_filter = [
+        "state_transition",
+        "created",
+        "org",
+        "role",
+    ]
+
+    search_fields = [
+        "enrolled_by__username",
+        "enrolled_by__email",
+        "enrollment__user__username",
+        "enrollment__user__email",
+        "enrollment_allowed__email",
+        "enrollment__learning_path__key",
+        "enrollment_allowed__learning_path__key",
+        "reason",
+    ]
+
+    readonly_fields = [
+        "enrollment",
+        "enrollment_allowed",
+        "enrolled_by",
+        "state_transition",
+        "created",
+        "modified",
+    ]
+
+    def get_enrollee(self, obj):
+        """Get the enrollee (user or email)."""
+        if obj.enrollment:
+            return obj.enrollment.user.username
+        elif obj.enrollment_allowed:
+            return obj.enrollment_allowed.user.username if obj.enrollment_allowed.user else obj.enrollment_allowed.email
+        return "-"
+
+    get_enrollee.short_description = "Enrollee"
+
+    def get_learning_path(self, obj):
+        """Get the learning path title."""
+        if obj.enrollment:
+            return obj.enrollment.learning_path.key
+        elif obj.enrollment_allowed:
+            return obj.enrollment_allowed.learning_path.key
+        return "-"
+
+    get_learning_path.short_description = "Learning Path"

{learning_paths_plugin-0.3.3 → learning_paths_plugin-0.3.4rc8}/learning_paths/api/v1/serializers.py

@@ -97,7 +97,7 @@ class LearningPathGradeSerializer(serializers.Serializer):
 class LearningPathStepSerializer(serializers.ModelSerializer):
     class Meta:
         model = LearningPathStep
-        fields = ["order", "course_key", "due_date", "weight"]
+        fields = ["order", "course_key", "course_dates", "weight"]
 
 
 class LearningPathListSerializer(serializers.ModelSerializer):
@@ -105,7 +105,7 @@ class LearningPathListSerializer(serializers.ModelSerializer):
 
     steps = LearningPathStepSerializer(many=True, read_only=True)
     required_completion = serializers.FloatField(source="grading_criteria.required_completion", read_only=True)
-    is_enrolled = serializers.SerializerMethodField()
+    enrollment_date = serializers.SerializerMethodField()
     invite_only = serializers.BooleanField()
     image = serializers.ImageField(read_only=True)
 
@@ -118,17 +118,17 @@ class LearningPathListSerializer(serializers.ModelSerializer):
             "sequential",
             "steps",
             "required_completion",
-            "is_enrolled",
+            "enrollment_date",
             "invite_only",
         ]
 
-    def get_is_enrolled(self, obj):
+    def get_enrollment_date(self, obj):
         """
         Check if the current user is enrolled in this learning path.
         """
-        if hasattr(obj, "is_enrolled"):
-            return obj.is_enrolled
-        return False
+        if hasattr(obj, "enrollment_date"):
+            return obj.enrollment_date
+        return None
 
 
 class SkillSerializer(serializers.ModelSerializer):
@@ -183,4 +183,4 @@ class LearningPathDetailSerializer(LearningPathListSerializer):
 class LearningPathEnrollmentSerializer(serializers.ModelSerializer):
     class Meta:
         model = LearningPathEnrollment
-        fields = ("user", "learning_path", "is_active", "enrolled_at")
+        fields = ("user", "learning_path", "is_active", "created")

{learning_paths_plugin-0.3.3 → learning_paths_plugin-0.3.4rc8}/learning_paths/api/v1/views.py

@@ -3,12 +3,12 @@ Views for LearningPath.
 """
 
 import logging
-from datetime import datetime, timezone
 
 from django.conf import settings
 from django.contrib.auth import get_user_model
 from django.core.exceptions import ObjectDoesNotExist, PermissionDenied, ValidationError
 from django.core.validators import validate_email
+from django.db.models import QuerySet
 from django.shortcuts import get_object_or_404
 from opaque_keys import InvalidKeyError
 from opaque_keys.edx.keys import CourseKey
@@ -16,6 +16,7 @@ from rest_framework import generics, status, viewsets
 from rest_framework.exceptions import NotFound, ParseError
 from rest_framework.pagination import PageNumberPagination
 from rest_framework.permissions import IsAdminUser, IsAuthenticated
+from rest_framework.request import Request
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
@@ -33,6 +34,7 @@ from learning_paths.models import (
     LearningPath,
     LearningPathEnrollment,
     LearningPathEnrollmentAllowed,
+    LearningPathEnrollmentAudit,
 )
 
 from .filters import AdminOrSelfFilterBackend
@@ -239,7 +241,6 @@ class LearningPathEnrollmentView(APIView):
             return Response({"detail": "Enrollment exists."}, status=status.HTTP_409_CONFLICT)
 
         enrollment.is_active = True
-        enrollment.enrolled_at = datetime.now(timezone.utc)
         enrollment.save()
         return Response(LearningPathEnrollmentSerializer(enrollment).data)
 
@@ -295,13 +296,53 @@ class ListEnrollmentsView(generics.ListAPIView):
 
 class BulkEnrollView(APIView):
     """
-    Bulk enrollment API for LearningPathEnrollment.
-
+    Bulk enrollment/unenrollment API for LearningPathEnrollment.
     """
 
     permission_classes = [IsAdminUser]
 
-    def post(self, request, *args, **kwargs):
+    @staticmethod
+    def _process_input_data(request: Request) -> tuple[list[str], list[str]]:
+        """Extract and validate input data from request."""
+        data = request.data
+        learning_paths_keys = data.get("learning_paths", "").split(",")
+        emails = data.get("emails", "").split(",")
+
+        return learning_paths_keys, emails
+
+    @staticmethod
+    def _validate_learning_paths(learning_paths_keys: list[str]) -> QuerySet[LearningPath]:
+        """Validate learning path keys and return valid ones."""
+        valid_learning_paths_keys = []
+        for key in learning_paths_keys:
+            try:
+                LearningPathKey.from_string(key)
+                valid_learning_paths_keys.append(key)
+            except InvalidKeyError:
+                logger.warning("BulkEnrollView: Invalid learning path key: %s", key)
+
+        return LearningPath.objects.filter(key__in=valid_learning_paths_keys)
+
+    @staticmethod
+    def _create_audit_data(request: Request, state_transition: str) -> dict[str, str]:
+        """Create audit data dictionary."""
+        return {
+            "enrolled_by": request.user,
+            "reason": request.data.get("reason", ""),
+            "org": request.data.get("org", ""),
+            "role": request.data.get("role", ""),
+            "state_transition": state_transition,
+        }
+
+    def _setup_bulk_operation(self, request: Request) -> tuple[QuerySet[LearningPath], QuerySet[User], list[str]]:
+        """Common setup for bulk operations."""
+        learning_paths_keys, emails = self._process_input_data(request)
+        learning_paths = self._validate_learning_paths(learning_paths_keys)
+        existing_users = User.objects.filter(email__in=emails)
+
+        return learning_paths, existing_users, emails
+
+    def post(self, request: Request, *args, **kwargs) -> Response:
         """
         Bulk Enroll learners in Learning Paths.
 
@@ -312,11 +353,17 @@ class BulkEnrollView(APIView):
 
             {
                 "learning_paths": "learning_path_1,learning_path_2",
-                "emails": "user_1@example.com,user_2@example.com"
+                "emails": "user_1@example.com,user_2@example.com",
+                "reason": "Bulk enrollment for new cohort",
+                "org": "organization_name",
+                "role": "student"
             }
 
         `learning_paths` (str): A comma separated list of learning path IDs.
         `emails` (str): A comma separated list of email addresses.
+        `reason` (str, optional): Reason for enrollment, used for audit.
+        `org` (str, optional): Organization identifier, used for audit.
+        `role` (str, optional): User role, used for audit.
 
         * For existing users, it creates a new LearningPathEnrollment record, automatically
           enrolling them in the learning path. It also creates a LearningPathAllowed record
@@ -325,42 +372,30 @@ class BulkEnrollView(APIView):
           with just the email address, allowing them to get enrolled when they register.
 
         """
-        data = request.data
-        learning_paths_keys = data.get("learning_paths", "").split(",")
-        emails = data.get("emails", "").split(",")
-
-        valid_learning_paths_keys = []
-        for key in learning_paths_keys:
-            try:
-                LearningPathKey.from_string(key)
-                valid_learning_paths_keys.append(key)
-            except InvalidKeyError:
-                logger.warning("BulkEnrollView: Invalid learning path key: %s", key)
-
-        learning_paths = LearningPath.objects.filter(key__in=valid_learning_paths_keys)
-
-        existing_users = User.objects.filter(email__in=emails)
+        learning_paths, existing_users, emails = self._setup_bulk_operation(request)
         non_existing_emails = set(emails) - set(u.email for u in existing_users)
 
         enrollments_created = []
         enrollment_allowed_created = []
 
         for learning_path in learning_paths:
-
             # Create LearningPathEnrollment for existing users
             for user in existing_users:
                 enrollment = LearningPathEnrollment.objects.filter(user=user, learning_path=learning_path).first()
                 enrolled_now = False
-                if not enrollment:
-                    enrollment = LearningPathEnrollment(
-                        user=user,
-                        learning_path=learning_path,
-                    )
-                    enrolled_now = True
-                if not enrollment.is_active:
-                    enrollment.is_active = True
-                    enrollment.enrolled_at = datetime.now(timezone.utc)
+                audit_data = self._create_audit_data(request, LearningPathEnrollmentAudit.UNENROLLED_TO_ENROLLED)
+                if enrollment:
+                    if not enrollment.is_active:
+                        enrollment.is_active = True
+                        enrolled_now = True
+                    else:
+                        audit_data["state_transition"] = LearningPathEnrollmentAudit.ENROLLED_TO_ENROLLED
+                else:
+                    enrollment = LearningPathEnrollment(user=user, learning_path=learning_path)
                     enrolled_now = True
+
+                # Set enrollment audit data that will be used by the post_save receiver.
+                enrollment._audit = audit_data  # pylint: disable=protected-access
                 enrollment.save()
                 if enrolled_now:
                     enrollments_created.append(enrollment)
@@ -378,6 +413,10 @@ class BulkEnrollView(APIView):
                 if created:
                     enrollment_allowed_created.append(allowed)
 
+                audit_data = self._create_audit_data(request, LearningPathEnrollmentAudit.UNENROLLED_TO_ALLOWEDTOENROLL)
+                allowed._audit = audit_data  # pylint: disable=protected-access
+                allowed.save()
+
         return Response(
             {
                 "enrollments_created": len(enrollments_created),
@@ -386,6 +425,84 @@ class BulkEnrollView(APIView):
             status=status.HTTP_201_CREATED,
         )
 
+    def delete(self, request, *args, **kwargs) -> Response:
+        """
+        Bulk Unenroll learners from Learning Paths.
+
+        The "bulk unenroll" API provides a way for the staff to unenroll multiple learners
+        from multiple learning paths at once.
+
+        Example payload::
+
+            {
+                "learning_paths": "learning_path_1,learning_path_2",
+                "emails": "user_1@example.com,user_2@example.com",
+                "reason": "End of semester cleanup",
+                "org": "organization_name",
+                "role": "student"
+            }
+
+        `learning_paths` (str): A comma separated list of learning path IDs.
+        `emails` (str): A comma separated list of email addresses.
+        `reason` (str, optional): Reason for unenrollment, used for audit.
+        `org` (str, optional): Organization identifier, used for audit.
+        `role` (str, optional): User role, used for audit.
+
+        * For existing users, it deactivates their LearningPathEnrollment records.
+        * For emails with active LearningPathEnrollmentAllowed records, it deactivates those records.
+
+        """
+        learning_paths, existing_users, emails = self._setup_bulk_operation(request)
+
+        enrollments_unenrolled = []
+        enrollment_allowed_deactivated = []
+
+        for learning_path in learning_paths:
+            for user in existing_users:
+                enrollment = LearningPathEnrollment.objects.filter(user=user, learning_path=learning_path).first()
+
+                if enrollment:
+                    if enrollment.is_active:
+                        state_transition = LearningPathEnrollmentAudit.ENROLLED_TO_UNENROLLED
+                        enrollment.is_active = False
+                        enrollments_unenrolled.append(enrollment)
+                    else:
+                        state_transition = LearningPathEnrollmentAudit.UNENROLLED_TO_UNENROLLED
+                    audit_data = self._create_audit_data(request, state_transition)
+                    enrollment._audit = audit_data  # pylint: disable=protected-access
+                    enrollment.save()
+
+            for email in emails:
+                try:
+                    validate_email(email)
+                except ValidationError:
+                    logger.warning("BulkEnrollView: Invalid email: %s", email)
+                    continue
+
+                enrollment_allowed = LearningPathEnrollmentAllowed.objects.filter(
+                    email=email,
+                    learning_path=learning_path,
+                ).first()
+
+                if enrollment_allowed:
+                    if enrollment_allowed.is_active:
+                        state_transition = LearningPathEnrollmentAudit.ALLOWEDTOENROLL_TO_UNENROLLED
+                        enrollment_allowed.is_active = False
+                        enrollment_allowed_deactivated.append(enrollment_allowed)
+                    else:
+                        state_transition = LearningPathEnrollmentAudit.UNENROLLED_TO_UNENROLLED
+                    audit_data = self._create_audit_data(request, state_transition)
+                    enrollment_allowed._audit = audit_data  # pylint: disable=protected-access
+                    enrollment_allowed.save()
+
+        return Response(
+            {
+                "enrollments_unenrolled": len(enrollments_unenrolled),
+                "enrollment_allowed_deactivated": len(enrollment_allowed_deactivated),
+            },
+            status=status.HTTP_204_NO_CONTENT,
+        )
+
 
 class LearningPathCourseEnrollmentView(APIView):
     """API View to enroll a user in a course that's part of a learning path."""
@@ -399,7 +516,7 @@ class LearningPathCourseEnrollmentView(APIView):
         :raises: Http404 if the learning path is not found or the user does not have access.
         """
         return get_object_or_404(
-            LearningPath.objects.get_paths_visible_to_user(self.request.user).filter(is_enrolled=True),
+            LearningPath.objects.get_paths_visible_to_user(self.request.user).filter(enrollment_date__isnull=False),
             key=learning_path_key_str,
         )
 

{learning_paths_plugin-0.3.3 → learning_paths_plugin-0.3.4rc8}/learning_paths/compat.py

@@ -46,18 +46,16 @@ def get_course_keys_with_outlines() -> list[CourseKey]:
     return course_keys_with_outlines()
 
 
-def get_course_due_date(course_key: CourseKey) -> datetime | None:
-    """
-    Retrieve course end date.
-    """
+def get_course_dates(course_key: CourseKey) -> tuple[datetime | None, datetime | None]:
+    """Retrieve course start and end dates."""
     # pylint: disable=import-outside-toplevel, import-error
     from openedx.core.djangoapps.content.course_overviews.models import CourseOverview
 
     try:
         overview = CourseOverview.objects.get(id=course_key)
-        return overview.end
+        return overview.start, overview.end
     except CourseOverview.DoesNotExist:
-        return None
+        return None, None
 
 
 def enroll_user_in_course(user: AbstractBaseUser, course_key: CourseKey) -> bool:

learning_paths_plugin-0.3.4rc8/learning_paths/conftest.py

@@ -0,0 +1,51 @@
+"""Pytest fixtures."""
+
+# pylint: disable=redefined-outer-name
+
+import pytest
+from django.test import override_settings
+
+from learning_paths.tests.factories import (
+    LearningPathEnrollmentFactory,
+    LearningPathFactory,
+    UserFactory,
+)
+
+
+@pytest.fixture
+def user():
+    """Create a single user for testing."""
+    return UserFactory()
+
+
+@pytest.fixture
+def learning_path():
+    """Create a single learning path for testing."""
+    return LearningPathFactory(invite_only=False)
+
+
+@pytest.fixture
+def learning_path_with_invite_only():
+    """Create a learning path that is invite-only."""
+    return LearningPathFactory()
+
+
+@pytest.fixture
+def active_enrollment(user, learning_path):
+    """Create an active enrollment for the user in the learning path."""
+    return LearningPathEnrollmentFactory(user=user, learning_path=learning_path, is_active=True)
+
+
+@pytest.fixture
+def inactive_enrollment(user, learning_path):
+    """Create an inactive enrollment for the user in the learning path."""
+    return LearningPathEnrollmentFactory(user=user, learning_path=learning_path, is_active=False)
+
+
+@pytest.fixture
+def temp_media(tmpdir):
+    """Temporarily override MEDIA_ROOT to a pytest tmpdir."""
+    temp_dir = str(tmpdir.mkdir("media"))
+
+    with override_settings(MEDIA_ROOT=temp_dir):
+        yield temp_dir