learning-paths-plugin 0.2.3__py2.py3-none-any.whl

learning_paths/api/v1/views.py

@@ -0,0 +1,341 @@
+"""
+Views for LearningPath.
+"""
+
+import logging
+from datetime import datetime, timezone
+from uuid import UUID
+
+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.shortcuts import get_object_or_404
+from rest_framework import generics, status, viewsets
+from rest_framework.pagination import PageNumberPagination
+from rest_framework.permissions import IsAdminUser, IsAuthenticated
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from learning_paths.api.v1.serializers import (
+    LearningPathAsProgramSerializer,
+    LearningPathEnrollmentSerializer,
+    LearningPathGradeSerializer,
+    LearningPathProgressSerializer,
+)
+from learning_paths.models import (
+    LearningPath,
+    LearningPathEnrollment,
+    LearningPathEnrollmentAllowed,
+)
+
+from .filters import AdminOrSelfFilterBackend
+from .permissions import IsAdminOrSelf
+from .utils import get_aggregate_progress
+
+logger = logging.getLogger(__name__)
+
+User = get_user_model()
+
+
+class LearningPathAsProgramViewSet(viewsets.ReadOnlyModelViewSet):
+    """
+    This viewset exposes LearningPaths as Programs to be ingested
+    by the course-discovery's refresh_course_metadata command.
+    URL is: GET <LMS_URL>/api/v1/programs
+    The command makes use of the ProgramsApiDataLoader.
+    https://github.com/openedx/course-discovery/blob/d6a57fd69479b3d5f5afb682d2668b58503a6af6/course_discovery/apps/course_metadata/data_loaders/api.py#L843
+    """
+
+    queryset = LearningPath.objects.all()
+    permission_classes = (IsAuthenticated,)
+    serializer_class = LearningPathAsProgramSerializer
+    pagination_class = PageNumberPagination
+
+
+class LearningPathUserProgressView(APIView):
+    """
+    API view to return the aggregate progress of a user in a learning path.
+    """
+
+    permission_classes = (IsAuthenticated,)
+
+    def get(self, request, learning_path_uuid):
+        """
+        Fetch the learning path progress
+        """
+        learning_path = get_object_or_404(LearningPath, uuid=learning_path_uuid)
+
+        progress = get_aggregate_progress(request.user, learning_path)
+        required_completion = None
+        try:
+            grading_criteria = learning_path.grading_criteria
+            required_completion = grading_criteria.required_completion
+        except ObjectDoesNotExist:
+            pass
+
+        data = {
+            "learning_path_id": learning_path.uuid,
+            "progress": progress,
+            "required_completion": required_completion,
+        }
+
+        serializer = LearningPathProgressSerializer(data=data)
+        if serializer.is_valid():
+            return Response(serializer.data, status=status.HTTP_200_OK)
+        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
+
+
+class LearningPathUserGradeView(APIView):
+    """
+    API view to return the aggregate grade of a user in a learning path.
+    """
+
+    permission_classes = (IsAuthenticated,)
+
+    def get(self, request, learning_path_uuid):
+        """
+        Fetch learning path grade
+        """
+
+        learning_path = get_object_or_404(LearningPath, uuid=learning_path_uuid)
+
+        try:
+            grading_criteria = learning_path.grading_criteria
+        except ObjectDoesNotExist:
+            return Response(
+                {"detail": "Grading criteria not found for this learning path."},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+
+        grade = grading_criteria.calculate_grade(request.user)
+
+        data = {
+            "learning_path_id": learning_path_uuid,
+            "grade": grade,
+            "required_grade": grading_criteria.required_grade,
+        }
+
+        serializer = LearningPathGradeSerializer(data=data)
+        if serializer.is_valid():
+            return Response(serializer.data, status=status.HTTP_200_OK)
+        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
+
+
+class LearningPathEnrollmentView(APIView):
+    """
+    API View to handle changes to LearningPathEnrollment model
+    """
+
+    permission_classes = [IsAuthenticated, IsAdminOrSelf]
+
+    def get(self, request, learning_path_id):
+        """Get the learning path of users.
+
+        Staff/Admin can get all the active enrollments of the learning path.
+        Learners can get their enrollments only.
+
+        Query params:
+            username (optional): When provided it returns the enrollment for
+                the specified user.
+        """
+        learning_path = get_object_or_404(LearningPath, uuid=learning_path_id)
+
+        enrollments = LearningPathEnrollment.objects.filter(
+            learning_path=learning_path, is_active=True
+        )
+
+        if request.user.is_staff:
+            if username := request.query_params.get("username"):
+                enrollments = enrollments.filter(user__username=username)
+        else:
+            enrollments = enrollments.filter(user=request.user)
+
+        serializer = LearningPathEnrollmentSerializer(enrollments.all(), many=True)
+        return Response(serializer.data)
+
+    def post(self, request, learning_path_id):
+        """Enroll learners in Learning Paths.
+
+        Staff/Admin can enroll anyone with the username query param.
+        Learners can enroll only themselves.
+
+        Example payload::
+
+            {
+                "username": "user_1"
+            }
+
+        """
+        learning_path = get_object_or_404(LearningPath, uuid=learning_path_id)
+        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
+        )
+        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
+            )
+
+        enrollment.is_active = True
+        enrollment.enrolled_at = datetime.now(timezone.utc)
+        enrollment.save()
+        return Response(LearningPathEnrollmentSerializer(enrollment).data)
+
+    def delete(self, request, learning_path_id):
+        """
+        Unenroll a learner from a learning path.
+
+        Staff/admin can unenroll anyone with the username query param.
+        Learners can self-unenroll if settings.LEARNING_PATHS_ALLOW_SELF_UNENROLLMENT is True.
+
+        Example payload::
+
+            {
+                "username": "user_1"
+            }
+
+        """
+        learning_path = get_object_or_404(LearningPath, uuid=learning_path_id)
+        username = request.data.get("username")
+        user = get_object_or_404(User, username=username) if username else request.user
+
+        enrollment = get_object_or_404(
+            LearningPathEnrollment,
+            learning_path=learning_path,
+            is_active=True,
+            user=user,
+        )
+
+        if (
+            not request.user.is_staff
+            and not settings.LEARNING_PATHS_ALLOW_SELF_UNENROLLMENT
+        ):
+            raise PermissionDenied
+
+        enrollment.is_active = False
+        enrollment.save()
+        return Response(
+            LearningPathEnrollmentSerializer(enrollment).data,
+            status=status.HTTP_204_NO_CONTENT,
+        )
+
+
+class ListEnrollmentsView(generics.ListAPIView):
+    """
+    List Learning Path Enrollments.
+
+    For staff, this returns enrollments from all learning paths for all users.
+    For non-staff, this returns all enrollments for the current user.
+    """
+
+    permission_classes = [IsAuthenticated]
+    queryset = LearningPathEnrollment.objects.all()
+    serializer_class = LearningPathEnrollmentSerializer
+    filter_backends = [AdminOrSelfFilterBackend]
+
+
+class BulkEnrollView(APIView):
+    """
+    Bulk enrollment API for LearningPathEnrollment.
+
+    """
+
+    permission_classes = [IsAdminUser]
+
+    def post(self, request, *args, **kwargs):
+        """
+        Bulk Enroll learners in Learning Paths.
+
+        The "bulk enroll" API provides a way for the staff to enroll multiple learners
+        in multiple learning paths at once.
+
+        Example payload::
+
+            {
+                "learning_paths": "learning_path_1,learning_path_2",
+                "emails": "user_1@example.com,user_2@example.com"
+            }
+
+        `learning_paths` (str): A comma separated list of learning path IDs.
+        `emails` (str): A comma separated list of email addresses.
+
+        * For existing users, it creates a new LearningPathEnrollment record, automatically
+          enrolling them in the learning path. It also creates a LearningPathAllowed record
+          to store the meta-data for audit later.
+        * For non-existing users, it creates a new LearningPathEnrollmentAllowed record
+          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:
+                UUID(key)
+            except ValueError:
+                logger.warning("BulkEnrollView: Invalid learning path key: %s", key)
+                continue
+            valid_learning_paths_keys.append(key)
+
+        learning_paths = LearningPath.objects.filter(
+            uuid__in=valid_learning_paths_keys
+        ).all()
+
+        existing_users = User.objects.filter(email__in=emails).all()
+        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)
+                    enrolled_now = True
+                enrollment.save()
+                if enrolled_now:
+                    enrollments_created.append(enrollment)
+
+            # Create LearningPathEnrollmentAllowed for non-existing users
+            for email in non_existing_emails:
+                try:
+                    validate_email(email)
+                except ValidationError:
+                    logger.warning("BulkEnrollView: Invalid email: %s", email)
+                    continue
+                allowed, created = LearningPathEnrollmentAllowed.objects.get_or_create(
+                    email=email, learning_path=learning_path
+                )
+                if created:
+                    enrollment_allowed_created.append(allowed)
+
+        return Response(
+            {
+                "enrollments_created": len(enrollments_created),
+                "enrollment_allowed_created": len(enrollment_allowed_created),
+            },
+            status=status.HTTP_201_CREATED,
+        )

learning_paths/apps.py

@@ -0,0 +1,52 @@
+"""
+learning_paths Django application initialization.
+"""
+
+from django.apps import AppConfig
+from edx_django_utils.plugins.constants import PluginSettings, PluginSignals, PluginURLs
+
+
+class LearningPathsConfig(AppConfig):
+    """
+    Configuration for the learning_paths Django application.
+    """
+
+    name = "learning_paths"
+
+    plugin_app = {
+        # Configuration setting for Plugin URLs for this app.
+        PluginURLs.CONFIG: {
+            "lms.djangoapp": {
+                # The namespace to provide to django's urls.include.
+                PluginURLs.NAMESPACE: "learning_paths",
+                # The application namespace to provide to django's urls.include.
+                # Optional; Defaults to None.
+                PluginURLs.APP_NAME: "learning_paths",
+                # The regex to provide to django's urls.url.
+                # Optional; Defaults to r''.
+                # PluginURLs.REGEX: r'^api/learning_paths/',
+                # The python path (relative to this app) to the URLs module to be plugged into the project.
+                # Optional; Defaults to 'urls'.
+                # PluginURLs.RELATIVE_PATH: 'api.urls',
+            }
+        },
+        PluginSettings.CONFIG: {
+            "lms.djangoapp": {
+                "common": {
+                    PluginSettings.RELATIVE_PATH: "settings",
+                }
+            }
+        },
+        PluginSignals.CONFIG: {
+            "lms.djangoapp": {
+                PluginSignals.RELATIVE_PATH: "receivers",
+                PluginSignals.RECEIVERS: [
+                    {
+                        PluginSignals.RECEIVER_FUNC_NAME: "process_pending_enrollments",
+                        PluginSignals.SIGNAL_PATH: "django.db.models.signals.post_save",
+                        PluginSignals.SENDER_PATH: "django.contrib.auth.models.User",
+                    }
+                ],
+            }
+        },
+    }

learning_paths/compat.py

@@ -0,0 +1,48 @@
+"""
+Compatibility layer for testing without Open edX.
+"""
+
+from django.contrib.auth.models import AbstractBaseUser
+from opaque_keys.edx.keys import CourseKey
+
+
+def get_user_course_grade(user: AbstractBaseUser, course_key: CourseKey):
+    """
+    Retrieve the CourseGrade object for a user in a specific course.
+    """
+    # pylint: disable=import-outside-toplevel, import-error
+    from lms.djangoapps.grades.course_grade_factory import CourseGradeFactory
+
+    course_grade = CourseGradeFactory().read(user, course_key=course_key)
+    return course_grade
+
+
+def get_catalog_api_client(user: AbstractBaseUser):
+    """
+    Retrieve the api client for user.
+    """
+    # pylint: disable=import-outside-toplevel, import-error
+    from openedx.core.djangoapps.catalog.utils import (
+        get_catalog_api_client as api_client,
+    )
+
+    return api_client(user)
+
+
+def get_course_keys_with_outlines():
+    """
+    Retrieve course keys.
+    """
+    # pylint: disable=import-outside-toplevel, import-error
+    from openedx.core.djangoapps.content.learning_sequences.api import (
+        get_course_keys_with_outlines as course_keys_with_outlines,
+    )
+
+    return course_keys_with_outlines()
+
+
+__all__ = [
+    "get_course_keys_with_outlines",
+    "get_catalog_api_client",
+    "get_user_course_grade",
+]

learning_paths/migrations/0001_initial.py

@@ -0,0 +1,93 @@
+# Generated by Django 3.2.23 on 2024-01-23 12:16
+
+from django.db import migrations, models
+import django.db.models.deletion
+import django.utils.timezone
+import model_utils.fields
+import opaque_keys.edx.django.models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='LearningPath',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('slug', models.SlugField(help_text='Custom unique code identifying this Learning Path.', unique=True)),
+                ('display_name', models.CharField(max_length=255)),
+                ('description', models.TextField(blank=True)),
+                ('image_url', models.CharField(blank=True, help_text='URL to an image representing this Learning Path.', max_length=200, verbose_name='Image URL')),
+                ('level', models.CharField(blank=True, choices=[('beginner', 'Beginner'), ('intermediate', 'Intermediate'), ('advanced', 'Advanced')], max_length=255)),
+                ('duration_in_days', models.PositiveIntegerField(blank=True, help_text='Approximate time (in days) it should take to complete this Learning Path.', null=True, verbose_name='Duration (days)')),
+                ('sequential', models.BooleanField(help_text='Whether the courses in this Learning Path are meant to be taken sequentially.', verbose_name='Is sequential')),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='Skill',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('display_name', models.CharField(max_length=255)),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='RequiredSkill',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('level', models.PositiveIntegerField(help_text='The skill level associated with this course.')),
+                ('learning_path', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='learning_paths.learningpath')),
+                ('skill', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='learning_paths.skill')),
+            ],
+            options={
+                'abstract': False,
+                'unique_together': {('learning_path', 'skill')},
+            },
+        ),
+        migrations.CreateModel(
+            name='LearningPathStep',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('course_key', opaque_keys.edx.django.models.CourseKeyField(max_length=255)),
+                ('relative_due_date_in_days', models.PositiveIntegerField(blank=True, help_text='Used to calculate the due date from the starting date of the course.', null=True, verbose_name='Due date (days)')),
+                ('order', models.PositiveIntegerField(blank=True, help_text='Ordinal position of this step in the sequence of the Learning Path, if applicable.', null=True, verbose_name='Sequential order')),
+                ('learning_path', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='steps', to='learning_paths.learningpath')),
+            ],
+            options={
+                'unique_together': {('learning_path', 'course_key')},
+            },
+        ),
+        migrations.CreateModel(
+            name='AcquiredSkill',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('level', models.PositiveIntegerField(help_text='The skill level associated with this course.')),
+                ('learning_path', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='learning_paths.learningpath')),
+                ('skill', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='learning_paths.skill')),
+            ],
+            options={
+                'abstract': False,
+                'unique_together': {('learning_path', 'skill')},
+            },
+        ),
+    ]

learning_paths/migrations/0002_learningpath_uuid.py

@@ -0,0 +1,19 @@
+# Generated by Django 3.2.23 on 2024-01-24 10:48
+
+from django.db import migrations, models
+import uuid
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('learning_paths', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='learningpath',
+            name='uuid',
+            field=models.UUIDField(blank=True, default=uuid.uuid4, editable=False, unique=True),
+        ),
+    ]

learning_paths/migrations/0003_learningpath_subtitle.py

@@ -0,0 +1,18 @@
+# Generated by Django 3.2.23 on 2024-01-31 17:52
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('learning_paths', '0002_learningpath_uuid'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='learningpath',
+            name='subtitle',
+            field=models.CharField(max_length=255),
+        ),
+    ]

learning_paths/migrations/0004_auto_20240207_1633.py

@@ -0,0 +1,36 @@
+# Generated by Django 3.2.21 on 2024-02-07 16:33
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+import django.utils.timezone
+import model_utils.fields
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('learning_paths', '0003_learningpath_subtitle'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='LearningPathEnrollment',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('learning_path', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='learning_paths.learningpath')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'unique_together': {('user', 'learning_path')},
+            },
+        ),
+        migrations.AddField(
+            model_name='learningpath',
+            name='enrolled_users',
+            field=models.ManyToManyField(through='learning_paths.LearningPathEnrollment', to=settings.AUTH_USER_MODEL),
+        ),
+    ]

learning_paths/migrations/0005_learningpathstep_weight_learningpathgradingcriteria.py

@@ -0,0 +1,29 @@
+# Generated by Django 4.2.16 on 2024-12-05 14:02
+
+import django.core.validators
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('learning_paths', '0004_auto_20240207_1633'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='learningpathstep',
+            name='weight',
+            field=models.FloatField(default=1.0, help_text="Weight of this course in the learning path's aggregate grade.Specify as a floating point number between 0 and 1, where 1 represents 100%.", validators=[django.core.validators.MinValueValidator(0.0), django.core.validators.MaxValueValidator(1.0)]),
+        ),
+        migrations.CreateModel(
+            name='LearningPathGradingCriteria',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('required_completion', models.FloatField(default=0.8, help_text='The minimum average completion (0.0-1.0) across all steps in the learning path required to mark it as completed.')),
+                ('required_grade', models.FloatField(default=0.75, help_text='Minimum weighted arithmetic mean grade (0.0-1.0) required across all steps to pass this learning path. The weight of each step is determined by its `weight` field.')),
+                ('learning_path', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='grading_criteria', to='learning_paths.learningpath')),
+            ],
+        ),
+    ]