Add public leaderboard data endpoint (#154)

New public endpoint that returns the full leaderboard with per-homework
and per-project score breakdowns, including learning in public links.

Usage:
  GET /data/<course_slug>/leaderboard.yaml

Example:
  curl https://courses.datatalks.club/data/de-zoomcamp-2026/leaderboard.yaml

No authentication required. Response is YAML with:
- Position, display name, and total score for each participant
- Per-homework breakdown: questions_score, faq_score, learning_in_public_score
- Per-project breakdown: project_score, peer_review_score, LiP scores, passed
- Learning in public links for each submission

The response is cached for 1 hour and automatically invalidated
whenever the leaderboard is recalculated (homework/project scoring).

A link to the endpoint is shown at the bottom of the leaderboard page.

Closes #154

Author: alexeygrigorev

courses/scoring.py

@@ -346,9 +346,9 @@ def update_leaderboard(course: Course):
         ["total_score", "position_on_leaderboard"],
     )
 
-    # Invalidate the leaderboard cache
-    cache_key = f"leaderboard:{course.id}"
-    cache.delete(cache_key)
+    # Invalidate the leaderboard caches
+    cache.delete(f"leaderboard:{course.id}")
+    cache.delete(f"leaderboard_data:{course.id}")
     logger.info(f"Invalidated cache for leaderboard of course {course.id}")
 
     t1 = time()

courses/templates/courses/leaderboard.html

@@ -39,4 +39,10 @@ <h2>Your Record</h2>
     </div>
   {% endfor %}
 
+  <div class="mt-4 text-center text-muted">
+    <small>
+      <a href="{% url 'data_leaderboard' course_slug=course.slug %}">Leaderboard data (YAML)</a>
+    </small>
+  </div>
+
 {% endblock %}

data/tests/test_leaderboard.py

@@ -0,0 +1,193 @@
+"""Tests for the public leaderboard data endpoint."""
+
+import yaml
+
+from django.test import TestCase, Client
+from django.urls import reverse
+from django.utils import timezone
+from django.core.cache import cache
+
+from accounts.models import CustomUser, Token
+from courses.models import (
+    Course,
+    Enrollment,
+    Homework,
+    Submission,
+    Project,
+    ProjectSubmission,
+)
+from courses.models.homework import HomeworkState
+from courses.models.project import ProjectState
+
+
+class LeaderboardDataViewTestCase(TestCase):
+
+    def setUp(self):
+        self.client = Client()
+        self.course = Course.objects.create(
+            title="Test Course",
+            slug="test-course",
+            description="Test",
+        )
+        self.url = reverse(
+            "data_leaderboard",
+            kwargs={"course_slug": self.course.slug},
+        )
+
+        self.user1 = CustomUser.objects.create(
+            username="user1", email="user1@example.com", password="pw",
+        )
+        self.user2 = CustomUser.objects.create(
+            username="user2", email="user2@example.com", password="pw",
+        )
+        self.enrollment1 = Enrollment.objects.create(
+            student=self.user1,
+            course=self.course,
+            display_name="Alice",
+            total_score=100,
+            position_on_leaderboard=1,
+        )
+        self.enrollment2 = Enrollment.objects.create(
+            student=self.user2,
+            course=self.course,
+            display_name="Bob",
+            total_score=50,
+            position_on_leaderboard=2,
+        )
+
+    def tearDown(self):
+        cache.clear()
+
+    def test_returns_yaml(self):
+        response = self.client.get(self.url)
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(
+            response["Content-Type"], "text/plain; charset=utf-8"
+        )
+        data = yaml.safe_load(response.content)
+        self.assertEqual(data["course"], "test-course")
+
+    def test_no_auth_required(self):
+        """Endpoint is public, no token needed."""
+        response = self.client.get(self.url)
+        self.assertEqual(response.status_code, 200)
+
+    def test_leaderboard_ordering(self):
+        response = self.client.get(self.url)
+        data = yaml.safe_load(response.content)
+        leaderboard = data["leaderboard"]
+        self.assertEqual(len(leaderboard), 2)
+        self.assertEqual(leaderboard[0]["display_name"], "Alice")
+        self.assertEqual(leaderboard[0]["total_score"], 100)
+        self.assertEqual(leaderboard[0]["position"], 1)
+        self.assertEqual(leaderboard[1]["display_name"], "Bob")
+
+    def test_includes_scored_homework_submissions(self):
+        hw = Homework.objects.create(
+            course=self.course,
+            title="HW1",
+            slug="hw1",
+            description="",
+            due_date=timezone.now(),
+            state=HomeworkState.SCORED.value,
+        )
+        Submission.objects.create(
+            homework=hw,
+            student=self.user1,
+            enrollment=self.enrollment1,
+            questions_score=5,
+            faq_score=1,
+            learning_in_public_score=2,
+            total_score=8,
+        )
+
+        response = self.client.get(self.url)
+        data = yaml.safe_load(response.content)
+        alice = data["leaderboard"][0]
+        self.assertIn("homeworks", alice)
+        self.assertEqual(len(alice["homeworks"]), 1)
+        self.assertEqual(alice["homeworks"][0]["homework"], "HW1")
+        self.assertEqual(alice["homeworks"][0]["questions_score"], 5)
+        self.assertEqual(alice["homeworks"][0]["faq_score"], 1)
+        self.assertEqual(alice["homeworks"][0]["learning_in_public_score"], 2)
+        self.assertEqual(alice["homeworks"][0]["total_score"], 8)
+
+    def test_excludes_unscored_homework(self):
+        hw = Homework.objects.create(
+            course=self.course,
+            title="Open HW",
+            slug="open-hw",
+            description="",
+            due_date=timezone.now(),
+            state=HomeworkState.OPEN.value,
+        )
+        Submission.objects.create(
+            homework=hw,
+            student=self.user1,
+            enrollment=self.enrollment1,
+            total_score=5,
+        )
+
+        response = self.client.get(self.url)
+        data = yaml.safe_load(response.content)
+        alice = data["leaderboard"][0]
+        self.assertNotIn("homeworks", alice)
+
+    def test_includes_completed_project_submissions(self):
+        proj = Project.objects.create(
+            course=self.course,
+            title="Project 1",
+            slug="project-1",
+            description="",
+            submission_due_date=timezone.now(),
+            peer_review_due_date=timezone.now(),
+            state=ProjectState.COMPLETED.value,
+        )
+        ProjectSubmission.objects.create(
+            project=proj,
+            student=self.user1,
+            enrollment=self.enrollment1,
+            project_score=80,
+            peer_review_score=9,
+            project_learning_in_public_score=3,
+            peer_review_learning_in_public_score=1,
+            project_faq_score=1,
+            total_score=94,
+            passed=True,
+        )
+
+        response = self.client.get(self.url)
+        data = yaml.safe_load(response.content)
+        alice = data["leaderboard"][0]
+        self.assertIn("projects", alice)
+        self.assertEqual(len(alice["projects"]), 1)
+        self.assertEqual(alice["projects"][0]["project_score"], 80)
+        self.assertTrue(alice["projects"][0]["passed"])
+
+    def test_response_is_cached(self):
+        self.client.get(self.url)
+
+        # Modify data - cached response should still be old
+        self.enrollment1.display_name = "Alice Changed"
+        self.enrollment1.save()
+
+        response = self.client.get(self.url)
+        data = yaml.safe_load(response.content)
+        self.assertEqual(data["leaderboard"][0]["display_name"], "Alice")
+
+    def test_cache_invalidation(self):
+        self.client.get(self.url)
+
+        # Simulate what update_leaderboard does
+        cache.delete(f"leaderboard_data:{self.course.id}")
+
+        self.enrollment1.display_name = "Alice Changed"
+        self.enrollment1.save()
+
+        response = self.client.get(self.url)
+        data = yaml.safe_load(response.content)
+        self.assertEqual(data["leaderboard"][0]["display_name"], "Alice Changed")
+
+    def test_nonexistent_course(self):
+        response = self.client.get("/data/nonexistent/leaderboard.yaml")
+        self.assertEqual(response.status_code, 404)

data/urls.py

@@ -18,6 +18,13 @@
         name="course_criteria_yaml",
     ),
 
+    # Leaderboard data (public, no auth required)
+    path(
+        "<slug:course_slug>/leaderboard.yaml",
+        data_views.leaderboard_data_view,
+        name="data_leaderboard",
+    ),
+
     # Data API endpoints (require auth)
     path(
         "<slug:course_slug>/homework/<slug:homework_slug>",

data/views/__init__.py

@@ -9,6 +9,7 @@
 from .course import course_criteria_yaml_view
 from .enrollment import graduates_data_view, update_enrollment_certificate_view
 from .health import health_view
+from .leaderboard import leaderboard_data_view
 
 __all__ = [
     "homework_data_view",
@@ -17,4 +18,5 @@
     "graduates_data_view",
     "update_enrollment_certificate_view",
     "health_view",
+    "leaderboard_data_view",
 ]

data/views/leaderboard.py

@@ -0,0 +1,129 @@
+"""
+Public leaderboard data API view.
+
+Returns the full leaderboard with per-homework and per-project score breakdowns.
+Cached and invalidated when the leaderboard is recalculated.
+"""
+
+import logging
+
+import yaml
+
+from django.http import HttpResponse
+from django.shortcuts import get_object_or_404
+from django.core.cache import cache
+from django.db.models import Prefetch
+from django.db.models.functions import Coalesce
+from django.db.models import Value
+
+from courses.models import (
+    Course,
+    Enrollment,
+    Submission,
+    ProjectSubmission,
+)
+from courses.models.homework import HomeworkState
+from courses.models.project import ProjectState
+
+logger = logging.getLogger(__name__)
+
+LEADERBOARD_DATA_CACHE_TTL = 3600  # 1 hour
+
+
+def _build_leaderboard_data(course):
+    """Build the full leaderboard JSON structure with score breakdowns."""
+    enrollments = (
+        Enrollment.objects.filter(course=course)
+        .select_related("student")
+        .prefetch_related(
+            Prefetch(
+                "submission_set",
+                queryset=Submission.objects.filter(
+                    homework__state=HomeworkState.SCORED.value,
+                ).select_related("homework").order_by("homework__id"),
+                to_attr="scored_submissions",
+            ),
+            Prefetch(
+                "projectsubmission_set",
+                queryset=ProjectSubmission.objects.filter(
+                    project__state=ProjectState.COMPLETED.value,
+                ).select_related("project").order_by("project__id"),
+                to_attr="completed_project_submissions",
+            ),
+        )
+        .order_by(
+            Coalesce("position_on_leaderboard", Value(999999)),
+            "id",
+        )
+    )
+
+    results = []
+    for enrollment in enrollments:
+        hw_data = []
+        for sub in enrollment.scored_submissions:
+            hw_entry = {
+                "homework": sub.homework.title,
+                "homework_slug": sub.homework.slug,
+                "total_score": sub.total_score,
+                "questions_score": sub.questions_score,
+                "faq_score": sub.faq_score,
+                "learning_in_public_score": sub.learning_in_public_score,
+            }
+            if sub.learning_in_public_links:
+                hw_entry["learning_in_public_links"] = sub.learning_in_public_links
+            hw_data.append(hw_entry)
+
+        proj_data = []
+        for sub in enrollment.completed_project_submissions:
+            proj_entry = {
+                "project": sub.project.title,
+                "project_slug": sub.project.slug,
+                "total_score": sub.total_score,
+                "project_score": sub.project_score,
+                "peer_review_score": sub.peer_review_score,
+                "project_learning_in_public_score": sub.project_learning_in_public_score,
+                "peer_review_learning_in_public_score": sub.peer_review_learning_in_public_score,
+                "project_faq_score": sub.project_faq_score,
+                "passed": sub.passed,
+            }
+            if sub.learning_in_public_links:
+                proj_entry["learning_in_public_links"] = sub.learning_in_public_links
+            proj_data.append(proj_entry)
+
+        entry = {
+            "position": enrollment.position_on_leaderboard,
+            "display_name": enrollment.display_name,
+            "total_score": enrollment.total_score,
+        }
+        if hw_data:
+            entry["homeworks"] = hw_data
+        if proj_data:
+            entry["projects"] = proj_data
+
+        results.append(entry)
+
+    return results
+
+
+def leaderboard_data_view(request, course_slug: str):
+    """Public endpoint returning the full leaderboard with score breakdowns."""
+    course = get_object_or_404(Course, slug=course_slug)
+
+    cache_key = f"leaderboard_data:{course.id}"
+    data = cache.get(cache_key)
+
+    if data is None:
+        logger.info("Cache miss for leaderboard data of course %s", course.slug)
+        data = _build_leaderboard_data(course)
+        cache.set(cache_key, data, LEADERBOARD_DATA_CACHE_TTL)
+    else:
+        logger.info("Cache hit for leaderboard data of course %s", course.slug)
+
+    yaml_content = yaml.dump(
+        {"course": course.slug, "leaderboard": data},
+        default_flow_style=False,
+        allow_unicode=True,
+        sort_keys=False,
+    )
+
+    return HttpResponse(yaml_content, content_type="text/plain; charset=utf-8")