learning-paths-plugin 0.3.2__tar.gz → 0.3.4rc1__tar.gz

{learning_paths_plugin-0.3.2 → learning_paths_plugin-0.3.4rc1}/CHANGELOG.rst

@@ -16,6 +16,22 @@ Unreleased
 
 *
 
+0.3.4 - 2025-05-23
+******************
+
+Added
+=====
+
+* Enrollment audit model that tracks the enrollment state transitions.
+
+0.3.3 - 2025-05-23
+******************
+
+Changed
+=======
+
+* Changed line length from 80 to 120 characters.
+
 0.3.2 - 2025-05-02
 ******************
 

{learning_paths_plugin-0.3.2/learning_paths_plugin.egg-info → learning_paths_plugin-0.3.4rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learning-paths-plugin
-Version: 0.3.2
+Version: 0.3.4rc1
 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,22 @@ Unreleased
 
 *
 
+0.3.4 - 2025-05-23
+******************
+
+Added
+=====
+
+* Enrollment audit model that tracks the enrollment state transitions.
+
+0.3.3 - 2025-05-23
+******************
+
+Changed
+=======
+
+* Changed line length from 80 to 120 characters.
+
 0.3.2 - 2025-05-02
 ******************
 

{learning_paths_plugin-0.3.2 → learning_paths_plugin-0.3.4rc1}/learning_paths/__init__.py

@@ -2,4 +2,4 @@
 Learning Paths plugin.
 """
 
-__version__ = "0.3.2"
+__version__ = "0.3.4-rc1"

{learning_paths_plugin-0.3.2 → learning_paths_plugin-0.3.4rc1}/learning_paths/admin.py

@@ -13,6 +13,8 @@ from .models import (
     AcquiredSkill,
     LearningPath,
     LearningPathEnrollment,
+    LearningPathEnrollmentAllowed,
+    LearningPathEnrollmentAudit,
     LearningPathGradingCriteria,
     LearningPathStep,
     RequiredSkill,
@@ -65,9 +67,7 @@ class LearningPathStepForm(forms.ModelForm):
         """Lazily fetch course keys to avoid calling compat code in all environments."""
         super().__init__(*args, **kwargs)
         self._course_keys = get_course_keys_with_outlines()
-        self.fields["course_key"].widget = CourseKeyDatalistWidget(
-            choices=self._course_keys
-        )
+        self.fields["course_key"].widget = CourseKeyDatalistWidget(choices=self._course_keys)
 
     course_key = forms.CharField(label=_("Course"))
 
@@ -77,9 +77,7 @@ class LearningPathStepForm(forms.ModelForm):
         valid_keys = {str(key).strip() for key in self._course_keys}
 
         if course_key not in valid_keys:
-            raise ValidationError(
-                _("Invalid course key. Please select a course from the suggestions.")
-            )
+            raise ValidationError(_("Invalid course key. Please select a course from the suggestions."))
 
         return course_key
 
@@ -135,9 +133,7 @@ class BulkEnrollUsersForm(forms.ModelForm):
         found_usernames = list(users.values_list("username", flat=True))
         invalid_usernames = set(usernames) - set(found_usernames)
         if invalid_usernames:
-            raise ValidationError(
-                f"The following usernames are not valid: {', '.join(invalid_usernames)}"
-            )
+            raise ValidationError(f"The following usernames are not valid: {', '.join(invalid_usernames)}")
         return users
 
 
@@ -179,9 +175,7 @@ class LearningPathAdmin(admin.ModelAdmin):
         super().save_related(request, form, formsets, change)
         with transaction.atomic():
             for user in form.cleaned_data["usernames"]:
-                LearningPathEnrollment.objects.get_or_create(
-                    user=user, learning_path=form.instance
-                )
+                LearningPathEnrollment.objects.get_or_create(user=user, learning_path=form.instance)
 
 
 class SkillAdmin(admin.ModelAdmin):
@@ -190,12 +184,63 @@ class SkillAdmin(admin.ModelAdmin):
     model = Skill
 
 
+class LearningPathEnrollmentAuditInline(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 LearningPathEnrollmentAllowedAuditInline(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
+
+
 class EnrolledUsersAdmin(admin.ModelAdmin):
     """Admin for Learning Path enrollment."""
 
     model = LearningPathEnrollment
     raw_id_fields = ("user",)
     autocomplete_fields = ["learning_path"]
+    inlines = [LearningPathEnrollmentAuditInline]
 
     search_fields = [
         "id",
@@ -205,6 +250,111 @@ class EnrolledUsersAdmin(admin.ModelAdmin):
     ]
 
 
+@admin.register(LearningPathEnrollmentAllowed)
+class LearningPathEnrollmentAllowedAdmin(admin.ModelAdmin):
+    """Admin configuration for LearningPathEnrollmentAllowed model."""
+
+    list_display = [
+        "id",
+        "email",
+        "get_user",
+        "learning_path",
+        "created",
+    ]
+
+    list_filter = [
+        "learning_path",
+        "user",
+        "created",
+    ]
+
+    search_fields = [
+        "email",
+        "user__username",
+        "user__email",
+        "learning_path__title",
+        "learning_path__key",
+    ]
+
+    readonly_fields = [
+        "user",
+        "created",
+        "modified",
+    ]
+
+    inlines = [LearningPathEnrollmentAllowedAuditInline]
+
+    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 LearningPathEnrollmentAuditAdmin(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",
+        "enrolled_by",
+    ]
+
+    search_fields = [
+        "enrolled_by__username",
+        "enrolled_by__email",
+        "enrollment__user__username",
+        "enrollment__user__email",
+        "enrollment_allowed__email",
+        "enrollment__learning_path__title",
+        "enrollment_allowed__learning_path__title",
+        "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"
+
+
 admin.site.register(LearningPath, LearningPathAdmin)
 admin.site.register(Skill, SkillAdmin)
 admin.site.register(LearningPathEnrollment, EnrolledUsersAdmin)

{learning_paths_plugin-0.3.2 → learning_paths_plugin-0.3.4rc1}/learning_paths/api/v1/serializers.py

@@ -104,9 +104,7 @@ class LearningPathListSerializer(serializers.ModelSerializer):
     """Serializer for the learning path list."""
 
     steps = LearningPathStepSerializer(many=True, read_only=True)
-    required_completion = serializers.FloatField(
-        source="grading_criteria.required_completion", read_only=True
-    )
+    required_completion = serializers.FloatField(source="grading_criteria.required_completion", read_only=True)
     is_enrolled = serializers.SerializerMethodField()
     invite_only = serializers.BooleanField()
     image = serializers.ImageField(read_only=True)
@@ -168,12 +166,8 @@ class LearningPathDetailSerializer(LearningPathListSerializer):
     Serializer for learning path details.
     """
 
-    required_skills = RequiredSkillSerializer(
-        source="requiredskill_set", many=True, read_only=True
-    )
-    acquired_skills = AcquiredSkillSerializer(
-        source="acquiredskill_set", many=True, read_only=True
-    )
+    required_skills = RequiredSkillSerializer(source="requiredskill_set", many=True, read_only=True)
+    acquired_skills = AcquiredSkillSerializer(source="acquiredskill_set", many=True, read_only=True)
 
     class Meta(LearningPathListSerializer.Meta):
         fields = LearningPathListSerializer.Meta.fields + [

{learning_paths_plugin-0.3.2 → learning_paths_plugin-0.3.4rc1}/learning_paths/api/v1/urls.py

@@ -16,9 +16,7 @@ from learning_paths.api.v1.views import (
 from learning_paths.keys import COURSE_KEY_URL_PATTERN, LEARNING_PATH_URL_PATTERN
 
 router = routers.SimpleRouter()
-router.register(
-    r"programs", LearningPathAsProgramViewSet, basename="learning-path-as-program"
-)
+router.register(r"programs", LearningPathAsProgramViewSet, basename="learning-path-as-program")
 router.register(r"learning-paths", LearningPathViewSet, basename="learning-path")
 
 urlpatterns = router.urls + [

{learning_paths_plugin-0.3.2 → learning_paths_plugin-0.3.4rc1}/learning_paths/api/v1/utils.py

@@ -29,9 +29,7 @@ def get_course_completion(username: str, course_key: CourseKey, client: Any) ->
         if err.response.status_code == 404:
             return 0.0
         else:
-            raise APIException(
-                f"Error fetching completion for course {course_id}: {err}"
-            ) from err
+            raise APIException(f"Error fetching completion for course {course_id}: {err}") from err
 
     if data and data.get("results"):
         return data["results"][0]["completion"]["percent"]
@@ -51,9 +49,7 @@ def get_aggregate_progress(user, learning_path):
     total_completion = 0.0
 
     for step in steps:
-        course_completion = get_course_completion(
-            user.username, step.course_key, client
-        )
+        course_completion = get_course_completion(user.username, step.course_key, client)
         total_completion += course_completion
 
     total_courses = len(steps)

{learning_paths_plugin-0.3.2 → learning_paths_plugin-0.3.4rc1}/learning_paths/api/v1/views.py

@@ -33,6 +33,7 @@ from learning_paths.models import (
     LearningPath,
     LearningPathEnrollment,
     LearningPathEnrollmentAllowed,
+    LearningPathEnrollmentAudit,
 )
 
 from .filters import AdminOrSelfFilterBackend
@@ -152,9 +153,7 @@ class LearningPathViewSet(viewsets.ReadOnlyModelViewSet):
         Get all learning paths and prefetch the related data.
         """
         user = self.request.user
-        queryset = LearningPath.objects.get_paths_visible_to_user(
-            user
-        ).prefetch_related(
+        queryset = LearningPath.objects.get_paths_visible_to_user(user).prefetch_related(
             "steps",
             "grading_criteria",
         )
@@ -203,9 +202,7 @@ class LearningPathEnrollmentView(APIView):
         """
         learning_path = self._get_learning_path(learning_path_key_str)
 
-        enrollments = LearningPathEnrollment.objects.filter(
-            learning_path=learning_path, is_active=True
-        )
+        enrollments = LearningPathEnrollment.objects.filter(learning_path=learning_path, is_active=True)
 
         if request.user.is_staff:
             if username := request.query_params.get("username"):
@@ -233,18 +230,14 @@ class LearningPathEnrollmentView(APIView):
         username = request.data.get("username")
         user = get_object_or_404(User, username=username) if username else request.user
 
-        enrollment, created = LearningPathEnrollment.objects.get_or_create(
-            learning_path=learning_path, user=user
-        )
+        enrollment, created = LearningPathEnrollment.objects.get_or_create(learning_path=learning_path, user=user)
         if created:
             return Response(
                 LearningPathEnrollmentSerializer(enrollment).data,
                 status=status.HTTP_201_CREATED,
             )
         if enrollment.is_active:
-            return Response(
-                {"detail": "Enrollment exists."}, status=status.HTTP_409_CONFLICT
-            )
+            return Response({"detail": "Enrollment exists."}, status=status.HTTP_409_CONFLICT)
 
         enrollment.is_active = True
         enrollment.enrolled_at = datetime.now(timezone.utc)
@@ -276,10 +269,7 @@ class LearningPathEnrollmentView(APIView):
             user=user,
         )
 
-        if (
-            not request.user.is_staff
-            and not settings.LEARNING_PATHS_ALLOW_SELF_UNENROLLMENT
-        ):
+        if not request.user.is_staff and not settings.LEARNING_PATHS_ALLOW_SELF_UNENROLLMENT:
             raise PermissionDenied
 
         enrollment.is_active = False
@@ -340,6 +330,14 @@ class BulkEnrollView(APIView):
         learning_paths_keys = data.get("learning_paths", "").split(",")
         emails = data.get("emails", "").split(",")
 
+        audit_data = {
+            "enrolled_by": request.user,
+            "reason": data.get("reason", ""),
+            "org": data.get("org", ""),
+            "role": data.get("role", ""),
+            "state_transition": LearningPathEnrollmentAudit.DEFAULT_TRANSITION_STATE,
+        }
+
         valid_learning_paths_keys = []
         for key in learning_paths_keys:
             try:
@@ -360,20 +358,22 @@ class BulkEnrollView(APIView):
 
             # Create LearningPathEnrollment for existing users
             for user in existing_users:
-                enrollment = LearningPathEnrollment.objects.filter(
-                    user=user, learning_path=learning_path
-                ).first()
+                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["state_transition"] = LearningPathEnrollmentAudit.UNENROLLED_TO_ENROLLED
+                if enrollment:
+                    if not enrollment.is_active:
+                        enrollment.is_active = True
+                        enrollment.enrolled_at = datetime.now(timezone.utc)
+                        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)
@@ -391,6 +391,10 @@ class BulkEnrollView(APIView):
                 if created:
                     enrollment_allowed_created.append(allowed)
 
+                audit_data["state_transition"] = LearningPathEnrollmentAudit.UNENROLLED_TO_ALLOWEDTOENROLL
+                allowed._audit = audit_data  # pylint: disable=protected-access
+                allowed.save()
+
         return Response(
             {
                 "enrollments_created": len(enrollments_created),
@@ -412,9 +416,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(is_enrolled=True),
             key=learning_path_key_str,
         )
 

{learning_paths_plugin-0.3.2 → learning_paths_plugin-0.3.4rc1}/learning_paths/compat.py

@@ -72,7 +72,5 @@ def enroll_user_in_course(user: AbstractBaseUser, course_key: CourseKey) -> bool
         CourseEnrollment.enroll(user, course_key)
         return True
     except CourseEnrollmentException as exc:
-        log.exception(
-            "Failed to enroll user %s in course %s: %s", user, course_key, exc
-        )
+        log.exception("Failed to enroll user %s in course %s: %s", user, course_key, exc)
         return False

learning_paths_plugin-0.3.4rc1/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

{learning_paths_plugin-0.3.2 → learning_paths_plugin-0.3.4rc1}/learning_paths/keys.py

@@ -12,15 +12,11 @@ from opaque_keys.edx.keys import LearningContextKey
 
 COURSE_KEY_NAMESPACE = "course-v1"
 COURSE_KEY_PATTERN = r"([^+]+)\+([^+]+)\+([^+]+)"
-COURSE_KEY_URL_PATTERN = (
-    rf"(?P<course_key_str>{COURSE_KEY_NAMESPACE}:{COURSE_KEY_PATTERN})"
-)
+COURSE_KEY_URL_PATTERN = rf"(?P<course_key_str>{COURSE_KEY_NAMESPACE}:{COURSE_KEY_PATTERN})"
 
 LEARNING_PATH_NAMESPACE = "path-v1"
 LEARNING_PATH_PATTERN = r"([^+]+)\+([^+]+)\+([^+]+)\+([^+]+)"
-LEARNING_PATH_URL_PATTERN = (
-    rf"(?P<learning_path_key_str>{LEARNING_PATH_NAMESPACE}:{LEARNING_PATH_PATTERN})"
-)
+LEARNING_PATH_URL_PATTERN = rf"(?P<learning_path_key_str>{LEARNING_PATH_NAMESPACE}:{LEARNING_PATH_PATTERN})"
 
 
 class LearningPathKey(LearningContextKey):
@@ -52,9 +48,7 @@ class LearningPathKey(LearningContextKey):
 
     def _to_string(self) -> str:
         """Return a string representing this key."""
-        return "+".join(
-            [self.org, self.number, self.run, self.group]  # pylint: disable=no-member
-        )
+        return "+".join([self.org, self.number, self.run, self.group])  # pylint: disable=no-member
 
 
 class LearningPathKeyField(LearningContextKeyField):

learning_paths_plugin-0.3.4rc1/learning_paths/migrations/0006_enrollment_models.py

@@ -0,0 +1,39 @@
+# Generated by Django 4.2.16 on 2025-03-28 09:54
+
+from django.conf import settings
+from django.db import migrations, models
+import django.utils.timezone
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('learning_paths', '0005_learningpathstep_weight_learningpathgradingcriteria'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='learningpathenrollment',
+            name='enrolled_at',
+            field=models.DateTimeField(auto_now_add=True, default=django.utils.timezone.now, help_text='Timestamp of enrollment or un-enrollment. To be explicitly set when performing a learner enrollment.'),
+            preserve_default=False,
+        ),
+        migrations.AddField(
+            model_name='learningpathenrollment',
+            name='is_active',
+            field=models.BooleanField(default=True, help_text='Indicates if the learner is enrolled or not in the Learning Path'),
+        ),
+        migrations.CreateModel(
+            name='LearningPathEnrollmentAllowed',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('email', models.EmailField(max_length=254)),
+                ('learning_path', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='learning_paths.learningpath')),
+                ('user', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'unique_together': {('email', 'learning_path')},
+            },
+        ),
+    ]