feat: return enrollment date in the API instead of a boolean

Author: Agrendalath

CHANGELOG.rst

@@ -29,6 +29,7 @@ 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/api/v1/serializers.py

@@ -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 Meta:
             "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):

learning_paths/api/v1/tests/test_serializers.py

@@ -12,7 +12,6 @@
 from learning_paths.tests.factories import (
     LearningPathEnrollmentFactory,
     LearningPathFactory,
-    UserFactory,
 )
 
 
@@ -105,26 +104,24 @@ def test_list_serializer():
         "sequential": False,
         "steps": [],
         "required_completion": 0.8,
-        "is_enrolled": False,
+        "enrollment_date": None,
     }
     assert dict(serializer.data) == expected
 
 
 @pytest.mark.django_db
 @pytest.mark.parametrize("is_enrolled", [True, False], ids=["enrolled", "not_enrolled"])
-def test_list_serializer_enrollment(is_enrolled):
+def test_list_serializer_enrollment(user, learning_path, is_enrolled):
     """
-    Tests LearningPathListSerializer shows is_enrolled as True when a user is enrolled.
+    Tests LearningPathListSerializer shows enrollment_date when a user is enrolled.
     """
-    user = UserFactory()
-    learning_path = LearningPathFactory(invite_only=False)
-    LearningPathEnrollmentFactory(user=user, learning_path=learning_path, is_active=is_enrolled)
+    enrollment = LearningPathEnrollmentFactory(user=user, learning_path=learning_path, is_active=is_enrolled)
 
     # Get the annotated learning path with the enrollment status.
     learning_path = learning_path.__class__.objects.get_paths_visible_to_user(user).get(key=learning_path.key)
 
     serializer = LearningPathListSerializer(learning_path)
-    assert serializer.data["is_enrolled"] is is_enrolled
+    assert serializer.data["enrollment_date"] == (enrollment.created if is_enrolled else None)
 
 
 @pytest.mark.django_db
@@ -146,7 +143,7 @@ def test_detail_serializer():
         "required_skills": [],
         "acquired_skills": [],
         "steps": [],
-        "is_enrolled": False,
+        "enrollment_date": None,
         "required_completion": 0.8,
     }
     serializer = LearningPathDetailSerializer(learning_path)

learning_paths/api/v1/tests/test_views.py

@@ -219,8 +219,8 @@ def test_learning_path_list(self, authenticated_client, learning_paths_with_step
         assert "key" in first_item
         assert "display_name" in first_item
         assert "steps" in first_item
-        assert "is_enrolled" in first_item
-        assert first_item["is_enrolled"] is False
+        assert "enrollment_date" in first_item
+        assert first_item["enrollment_date"] is None
 
     def test_learning_path_retrieve(self, authenticated_client, learning_paths_with_steps):
         """Test that the retrieve endpoint returns the details of a learning path."""
@@ -232,8 +232,8 @@ def test_learning_path_retrieve(self, authenticated_client, learning_paths_with_
         assert "steps" in response.data
         assert "required_skills" in response.data
         assert "acquired_skills" in response.data
-        assert "is_enrolled" in response.data
-        assert response.data["is_enrolled"] is False
+        assert "enrollment_date" in response.data
+        assert response.data["enrollment_date"] is None
 
         if response.data["steps"]:
             first_step = response.data["steps"][0]
@@ -264,17 +264,17 @@ def test_learning_path_list_with_enrollment(self, authenticated_client, active_e
         assert response.status_code == status.HTTP_200_OK
         assert len(response.data) == 1
         first_item = response.data[0]
-        assert "is_enrolled" in first_item
-        assert first_item["is_enrolled"] is True
+        assert "enrollment_date" in first_item
+        assert first_item["enrollment_date"] is not None
 
     def test_learning_path_retrieve_with_enrollment(self, authenticated_client, active_enrollment, learning_path, user):
         """Test that the retrieve endpoint returns the details of a learning path with enrollment status."""
         url = reverse("learning-path-detail", args=[learning_path.key])
         response = authenticated_client.get(url)
 
         assert response.status_code == status.HTTP_200_OK
-        assert "is_enrolled" in response.data
-        assert response.data["is_enrolled"] is True
+        assert "enrollment_date" in response.data
+        assert response.data["enrollment_date"] is not None
 
     def test_learning_path_retrieve_with_inactive_enrollment(
         self, authenticated_client, inactive_enrollment, learning_path, user
@@ -284,8 +284,8 @@ def test_learning_path_retrieve_with_inactive_enrollment(
         response = authenticated_client.get(url)
 
         assert response.status_code == status.HTTP_200_OK
-        assert "is_enrolled" in response.data
-        assert response.data["is_enrolled"] is False
+        assert "enrollment_date" in response.data
+        assert response.data["enrollment_date"] is None
 
     def test_invite_only_learning_paths_hidden_from_non_enrolled_users(
         self, authenticated_client, learning_path_with_invite_only, learning_path

learning_paths/api/v1/views.py

@@ -516,7 +516,7 @@ def _get_enrolled_learning_path(self, learning_path_key_str: str) -> LearningPat
         :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/models.py

@@ -12,7 +12,7 @@
 from django.core.exceptions import ValidationError
 from django.core.validators import MaxValueValidator, MinValueValidator
 from django.db import models
-from django.db.models import Exists, OuterRef, Q
+from django.db.models import OuterRef, Q
 from django.utils.translation import gettext_lazy as _
 from model_utils import FieldTracker
 from model_utils.models import TimeStampedModel
@@ -38,27 +38,29 @@ class LearningPathManager(models.Manager):
 
     def get_paths_visible_to_user(self, user: User) -> models.QuerySet:
         """
-        Return only learning paths that should be visible to the given user with enrollment status.
+        Return only learning paths that should be visible to the given user with an enrollment date.
 
         For staff users: all learning paths.
         For non-staff: non-invite-only paths or invite-only paths they're enrolled in.
 
-        Each learning path in the queryset is annotated with `is_enrolled` indicating
-        whether the user has an active enrollment in that learning path.
+        Each learning path in the queryset is annotated with `enrollment_date` indicating
+        the date when the user enrolled in that learning path (None if not enrolled).
+        Results are ordered by enrollment date (the most recent first), with non-enrolled paths at the end.
         """
         queryset = self.get_queryset()
 
-        # Annotate each path with whether the user is enrolled.
-        enrollment_exists = LearningPathEnrollment.objects.filter(
+        # Annotate each path with the enrollment date.
+        enrollment_subquery = LearningPathEnrollment.objects.filter(
             learning_path=OuterRef("pk"), user=user, is_active=True
-        )
-        queryset = queryset.annotate(is_enrolled=Exists(enrollment_exists))
+        ).values("created")[:1]
+        queryset = queryset.annotate(enrollment_date=models.Subquery(enrollment_subquery))
 
         # Apply visibility filtering based on the user role.
         if not user.is_staff:
-            queryset = queryset.filter(Q(invite_only=False) | Q(is_enrolled=True))
+            queryset = queryset.filter(Q(invite_only=False) | Q(enrollment_date__isnull=False))
 
-        return queryset
+        # Order by enrollment date (the most recent first), with null values at the end.
+        return queryset.order_by(models.F("enrollment_date").desc(nulls_last=True))
 
 
 class LearningPath(TimeStampedModel):