edx-completion 5.1.0__py3-none-any.whl

completion/__init__.py

@@ -0,0 +1,7 @@
+"""
+Completion App
+"""
+
+from importlib.metadata import version
+
+__version__ = version("edx-completion")

completion/api/permissions.py

@@ -0,0 +1,47 @@
+"""
+Permissions classes for the API.
+"""
+
+
+from django.http import Http404
+from rest_framework.permissions import BasePermission
+
+
+class IsStaffOrOwner(BasePermission):
+    """
+    Permission that allows access to admin users or the owner of an object.
+    The owner is considered the User object represented by obj.user.
+
+    Copied from edx-platform/openedx/core/lib/api/permissions.py
+    """
+
+    def has_object_permission(self, request, view, obj):
+        return request.user.is_staff or obj.user == request.user
+
+    def has_permission(self, request, view):
+        user = request.user
+        return user.is_staff \
+            or (user.username == request.GET.get('username')) \
+            or (user.username == getattr(request, 'data', {}).get('username')) \
+            or (user.username == getattr(request, 'data', {}).get('user')) \
+            or (user.username == getattr(view, 'kwargs', {}).get('username'))
+
+
+class IsUserInUrl(BasePermission):
+    """
+    Permission that checks to see if the request user matches the user in the URL.
+    """
+
+    def has_permission(self, request, view):
+        """
+        Returns true if the current request is by the user themselves.
+
+        Note: a 404 is returned for non-staff instead of a 403. This is to prevent
+        users from being able to detect the existence of accounts.
+        """
+        url_username = request.parser_context.get('kwargs', {}).get('username', '')
+        if request.user.username.lower() != url_username.lower():
+            if request.user.is_staff:
+                return False  # staff gets 403
+            raise Http404()
+        return True

completion/api/urls.py

@@ -0,0 +1,11 @@
+"""
+Api URLs.
+"""
+
+from django.urls import include  # pragma: no cover
+from django.urls import path
+
+app_name = 'completion'  # pylint: disable=invalid-name
+urlpatterns = [
+    path('v1/', include('completion.api.v1.urls')),
+]

completion/api/v1/urls.py

@@ -0,0 +1,18 @@
+"""
+API v1 URLs.
+"""
+from django.urls import path, re_path
+
+from . import views
+
+app_name = 'v1'  # pylint: disable=invalid-name
+urlpatterns = [
+    path('completion-batch', views.CompletionBatchView.as_view(), name='completion-batch'),
+    re_path(r'^subsection-completion/{username}/{course_key}/{subsection_id}'.format(  # pylint: disable=consider-using-f-string
+        username=r'(?P<username>[^/]*)',
+        course_key=r'(?P<course_key>[^/+]+(/|\+)[^/+]+(/|\+)[^/?]+)',
+        subsection_id=r'(?P<subsection_id>[^/]*)'
+    ),  # noqa
+        views.SubsectionCompletionView.as_view(),
+        name='subsection-completion')
+]

completion/api/v1/views.py

@@ -0,0 +1,256 @@
+"""
+API v1 views.
+"""
+
+from rest_framework import permissions, status
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from django.contrib import auth
+from django.core.exceptions import ObjectDoesNotExist, ValidationError
+from django.db import DatabaseError
+from django.utils.translation import gettext as _
+
+# pylint: disable=ungrouped-imports
+try:
+    from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication
+except ImportError:
+    from edx_rest_framework_extensions.authentication import JwtAuthentication
+
+try:
+    from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser
+except ImportError:
+    from edx_rest_framework_extensions.authentication import SessionAuthenticationAllowInactiveUser
+# pylint: enable=ungrouped-imports
+
+from opaque_keys import InvalidKeyError
+from opaque_keys.edx.keys import LearningContextKey, UsageKey
+
+try:
+    from common.djangoapps.student.models import CourseEnrollment
+    from lms.djangoapps.course_api.blocks.api import get_blocks
+    from openedx.core.lib.api.authentication import BearerAuthenticationAllowInactiveUser
+except ImportError:
+    pass
+
+from completion import waffle
+from completion.api.permissions import IsStaffOrOwner, IsUserInUrl
+from completion.models import BlockCompletion
+
+User = auth.get_user_model()
+
+
+class CompletionBatchView(APIView):
+    """
+    Handles API requests to submit batch completions.
+    """
+    authentication_classes = (
+        JwtAuthentication, BearerAuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser,
+    )
+    permission_classes = (permissions.IsAuthenticated, IsStaffOrOwner,)
+    REQUIRED_KEYS = ['username', 'course_key', 'blocks']
+
+    def _validate_and_parse(self, batch_object):
+        """
+        Performs validation on the batch object to make sure it is in the proper format.
+
+        Parameters:
+            * batch_object: The data provided to a POST. The expected format is the following:
+            ```
+            {
+                "username": "username",
+                "course_key": "context-key",
+                "blocks": {
+                    "block_key1": 0.0,
+                    "block_key2": 1.0,
+                    "block_key3": 1.0,
+                }
+            }
+            ```
+
+        Return Value:
+            * tuple: (User, LearningContextKey, List of tuples (UsageKey, completion_float)
+
+        Raises:
+
+            django.core.exceptions.ValidationError:
+                If any aspect of validation fails a ValidationError is raised.
+
+            ObjectDoesNotExist:
+                If a database object cannot be found an ObjectDoesNotExist is raised.
+        """
+        if not waffle.ENABLE_COMPLETION_TRACKING_SWITCH.is_enabled():
+            raise ValidationError(
+                _("BlockCompletion.objects.submit_batch_completion should not be called when the feature is disabled.")
+            )
+
+        for key in self.REQUIRED_KEYS:
+            if key not in batch_object:
+                raise ValidationError(_("Key '{key}' not found.").format(key=key))
+
+        username = batch_object['username']
+        user = User.objects.get(username=username)
+
+        context_key_obj = self._validate_and_parse_context_key(batch_object['course_key'])
+
+        if context_key_obj.is_course and not CourseEnrollment.is_enrolled(user, context_key_obj):
+            raise ValidationError(_('User is not enrolled in course.'))
+
+        blocks = batch_object['blocks']
+        block_objs = []
+        for block_key in blocks:
+            block_key_obj = self._validate_and_parse_block_key(block_key, context_key_obj)
+            completion = float(blocks[block_key])
+            block_objs.append((block_key_obj, completion))
+
+        return user, block_objs
+
+    def _validate_and_parse_context_key(self, context_key):
+        """
+        Returns a validated parsed LearningContextKey deserialized from the given context_key.
+        """
+        try:
+            return LearningContextKey.from_string(context_key)
+        except InvalidKeyError as error:
+            raise ValidationError(_("Invalid learning context key: {}").format(context_key)) from error
+
+    def _validate_and_parse_block_key(self, block_key, context_key_obj):
+        """
+        Returns a validated, parsed UsageKey deserialized from the given block_key.
+        """
+        try:
+            block_key_obj = UsageKey.from_string(block_key)
+        except InvalidKeyError as error:
+            raise ValidationError(_("Invalid block key: {}").format(block_key)) from error
+
+        if block_key_obj.context_key.is_course and block_key_obj.context_key.run is None:
+            # block_key_obj is from an old mongo course and its context_key is missing run info:
+            block_key_obj = block_key_obj.replace(course_key=context_key_obj)
+
+        if block_key_obj.context_key != context_key_obj:
+            raise ValidationError(
+                _("Block with key: '{key}' is not in context {context}").format(key=block_key, context=context_key_obj)
+            )
+
+        return block_key_obj
+
+    def post(self, request, *args, **kwargs):  # pylint: disable=unused-argument
+        """
+        Inserts a batch of completions.
+
+        REST Endpoint Format:
+        ```
+        {
+          "username": "username",
+          "course_key": "course-key",
+          "blocks": {
+            "block_key1": 0.0,
+            "block_key2": 1.0,
+            "block_key3": 1.0,
+          }
+        }
+        ```
+
+        **Returns**
+
+        A Response object, with an appropriate status code.
+
+        If successful, status code is 200.
+        ```
+        {
+           "detail" : _("ok")
+        }
+        ```
+
+        Otherwise, a 400 or 404 may be returned, and the "detail" content will explain the error.
+
+        """
+        batch_object = request.data or {}
+        try:
+            user, blocks = self._validate_and_parse(batch_object)
+            BlockCompletion.objects.submit_batch_completion(user, blocks)
+        except ValidationError as exc:
+            return Response({
+                "detail": _(' ').join(str(msg) for msg in exc.messages),
+            }, status=status.HTTP_400_BAD_REQUEST)
+        except ValueError as exc:
+            return Response({
+                "detail": str(exc),
+            }, status=status.HTTP_400_BAD_REQUEST)
+        except ObjectDoesNotExist as exc:
+            return Response({
+                "detail": str(exc),
+            }, status=status.HTTP_404_NOT_FOUND)
+        except DatabaseError as exc:
+            return Response({
+                "detail": str(exc),
+            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
+
+        return Response({"detail": _("ok")}, status=status.HTTP_200_OK)
+
+
+class SubsectionCompletionView(APIView):
+    """
+    Handles API endpoints for the milestones experiments.
+    TODO: EDUCATOR-2358 Remove this class after the
+    milestones experiment is no longer running.
+    """
+    authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser,)
+    permission_classes = (permissions.IsAuthenticated, IsUserInUrl)
+
+    def get(self, request, username, course_key, subsection_id):
+        """
+        Returns completion for a (user, subsection, course).
+        """
+
+        def get_completion(course_completions, all_blocks, block_id):
+            """
+            Recursively get the aggregate completion for a subsection,
+            given the subsection block and a list of all blocks.
+
+            Parameters:
+                course_completions: a dictionary of completion values by block IDs
+                all_blocks: a dictionary of the block structure for a subsection
+                block_id: an ID of a block for which to get completion
+            """
+            block = all_blocks.get(block_id)
+            child_ids = block.get('children', [])
+            if not child_ids:
+                return course_completions.get(block.serializer.instance, 0)
+
+            completion = 0
+            total_children = 0
+            for child_id in child_ids:
+                completion += get_completion(course_completions, all_blocks, child_id)
+                total_children += 1
+
+            return int(completion == total_children)
+
+        user_id = User.objects.get(username=username).id
+        block_types_filter = [
+            'course',
+            'chapter',
+            'sequential',
+            'vertical',
+            'html',
+            'problem',
+            'video',
+            'discussion',
+            'drag-and-drop-v2'
+        ]
+
+        blocks = get_blocks(
+            request,
+            UsageKey.from_string(subsection_id),
+            nav_depth=2,
+            requested_fields=[
+                'children'
+            ],
+            block_types_filter=block_types_filter
+        )
+
+        course_key = LearningContextKey.from_string(course_key)
+        context_completions = BlockCompletion.get_learning_context_completions(user_id, course_key)
+        aggregated_completion = get_completion(context_completions, blocks['blocks'], blocks['root'])
+
+        return Response({"completion": aggregated_completion}, status=status.HTTP_200_OK)

completion/apps.py

@@ -0,0 +1,43 @@
+"""
+App Configuration for Completion
+"""
+
+
+from django.apps import AppConfig
+
+
+class CompletionAppConfig(AppConfig):
+    """
+    App Configuration for Completion
+    """
+    name = 'completion'
+    verbose_name = 'Completion'
+
+    plugin_app = {
+        'url_config': {
+            'lms.djangoapp': {
+                'namespace': 'completion',
+                'regex': r'^api/completion/',
+                'relative_path': 'api.urls',
+            },
+        },
+        'settings_config': {
+            'lms.djangoapp': {
+                'common': {
+                    'relative_path': 'settings.common',
+                },
+            },
+        },
+        'signals_config': {
+            'lms.djangoapp': {
+                'relative_path': 'handlers',
+                'receivers': [
+                    {
+                        'receiver_func_name': 'scorable_block_completion',
+                        'signal_path': 'lms.djangoapps.grades.signals.signals.PROBLEM_WEIGHTED_SCORE_CHANGED',
+                        'dispatch_uid': 'completion.handlers.scorable_block_completion',
+                    },
+                ],
+            },
+        },
+    }

completion/exceptions.py

@@ -0,0 +1,16 @@
+"""
+This file contains custom exceptions used by the completion repository.
+'''
+
+"""
+
+
+class UnavailableCompletionData(Exception):
+    """
+    UnavailableCompletionData should be raised when a method is unable to gather
+    completion data from BlockCompletion.
+    """
+
+    def __init__(self, context_key):
+        Exception.__init__(
+            self, f"The learner does not have completion data within learning context {context_key}")

completion/handlers.py

@@ -0,0 +1,53 @@
+"""
+Signal handlers to trigger completion updates.
+"""
+
+import logging
+
+from django.contrib import auth
+from opaque_keys import InvalidKeyError
+from opaque_keys.edx.keys import LearningContextKey, UsageKey
+from xblock.completable import XBlockCompletionMode
+from xblock.core import XBlock
+
+from . import waffle
+from .models import BlockCompletion
+
+log = logging.getLogger(__name__)
+User = auth.get_user_model()
+
+
+def scorable_block_completion(sender, **kwargs):  # pylint: disable=unused-argument
+    """
+    When a problem is scored, submit a new BlockCompletion for that block.
+    """
+    if not waffle.ENABLE_COMPLETION_TRACKING_SWITCH.is_enabled():
+        return
+    try:
+        block_key = UsageKey.from_string(kwargs['usage_id'])
+    except InvalidKeyError:
+        log.exception("Unable to parse XBlock usage_id for completion: %s", kwargs['usage_id'])
+        return
+
+    if block_key.context_key.is_course and block_key.context_key.run is None:
+        # In the case of old mongo courses, the context_key cannot be derived
+        # from the block key alone since it will be missing run info:
+        course_key_with_run = LearningContextKey.from_string(kwargs['course_id'])
+        block_key = block_key.replace(course_key=course_key_with_run)
+
+    block_cls = XBlock.load_class(block_key.block_type)
+    if XBlockCompletionMode.get_mode(block_cls) != XBlockCompletionMode.COMPLETABLE:
+        return
+    if getattr(block_cls, 'has_custom_completion', False):
+        return
+    user = User.objects.get(id=kwargs['user_id'])
+    if kwargs.get('score_deleted'):
+        completion = 0.0
+    else:
+        completion = 1.0
+    if not kwargs.get('grader_response'):
+        BlockCompletion.objects.submit_completion(
+            user=user,
+            block_key=block_key,
+            completion=completion,
+        )

completion/migrations/0001_initial.py

@@ -0,0 +1,41 @@
+from opaque_keys.edx.django.models import CourseKeyField, UsageKeyField
+
+import django.utils.timezone
+from django.conf import settings
+from django.db import migrations, models
+from django.db.models import BigAutoField
+
+import model_utils.fields
+
+from completion.models import validate_percent
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='BlockCompletion',
+            fields=[
+                ('created', model_utils.fields.AutoCreatedField(default=django.utils.timezone.now, verbose_name='created', editable=False)),
+                ('modified', model_utils.fields.AutoLastModifiedField(default=django.utils.timezone.now, verbose_name='modified', editable=False)),
+                ('id', BigAutoField(serialize=False, primary_key=True)),
+                ('course_key', CourseKeyField(max_length=255)),
+                ('block_key', UsageKeyField(max_length=255)),
+                ('block_type', models.CharField(max_length=64)),
+                ('completion', models.FloatField(validators=[validate_percent])),
+                ('user', models.ForeignKey(to=settings.AUTH_USER_MODEL, on_delete=models.CASCADE)),
+            ],
+        ),
+        migrations.AlterUniqueTogether(
+            name='blockcompletion',
+            unique_together={('course_key', 'block_key', 'user')},
+        ),
+        migrations.AlterIndexTogether(
+            name='blockcompletion',
+            index_together={('course_key', 'block_type', 'user'), ('user', 'course_key', 'modified')},
+        ),
+    ]

completion/migrations/0001_squashed_0003_learning_context.py

@@ -0,0 +1,79 @@
+# Generated by Django 5.1.8 on 2025-04-10 08:24
+
+import completion.models
+import django.db.models.deletion
+import django.utils.timezone
+import model_utils.fields
+import opaque_keys.edx.django.models
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    replaces = [
+        ("completion", "0001_initial"),
+        ("completion", "0002_auto_20180125_1510"),
+        ("completion", "0003_learning_context"),
+    ]
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="BlockCompletion",
+            fields=[
+                (
+                    "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",
+                    ),
+                ),
+                ("id", models.BigAutoField(primary_key=True, serialize=False)),
+                (
+                    "context_key",
+                    opaque_keys.edx.django.models.LearningContextKeyField(
+                        db_column="course_key", max_length=255
+                    ),
+                ),
+                (
+                    "block_key",
+                    opaque_keys.edx.django.models.UsageKeyField(max_length=255),
+                ),
+                ("block_type", models.CharField(max_length=64)),
+                (
+                    "completion",
+                    models.FloatField(validators=[completion.models.validate_percent]),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "unique_together": {("context_key", "block_key", "user")},
+                "index_together": {
+                    ("context_key", "block_type", "user"),
+                    ("user", "context_key", "modified"),
+                },
+                "get_latest_by": "modified",
+            },
+        ),
+    ]

completion/migrations/0002_auto_20180125_1510.py

@@ -0,0 +1,15 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('completion', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name='blockcompletion',
+            options={'get_latest_by': 'modified'},
+        ),
+    ]

completion/migrations/0003_learning_context.py

@@ -0,0 +1,39 @@
+# Changes completion to track blocks for any learning context,
+# and not just for courses.
+#
+# This migration does not produce any database-level changes. You can verify
+# this with: ./manage.py lms sqlmigrate completion 0003
+
+from django.conf import settings
+from django.db import migrations
+import opaque_keys.edx.django.models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('completion', '0002_auto_20180125_1510'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='blockcompletion',
+            name='course_key',
+            field=opaque_keys.edx.django.models.LearningContextKeyField(db_column='course_key', max_length=255),
+            preserve_default=False,
+        ),
+        migrations.RenameField(
+            model_name='blockcompletion',
+            old_name='course_key',
+            new_name='context_key',
+        ),
+        migrations.AlterUniqueTogether(
+            name='blockcompletion',
+            unique_together={('context_key', 'block_key', 'user')},
+        ),
+        migrations.AlterIndexTogether(
+            name='blockcompletion',
+            index_together={('user', 'context_key', 'modified'), ('context_key', 'block_type', 'user')},
+        ),
+    ]

completion/migrations/0004_rename_indexes.py

@@ -0,0 +1,23 @@
+# Generated by Django 4.2.20 on 2025-04-03 05:37
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("completion", "0003_learning_context"),
+    ]
+
+    operations = [
+        migrations.RenameIndex(
+            model_name="blockcompletion",
+            new_name="completion__user_id_861fe5_idx",
+            old_fields=("user", "context_key", "modified"),
+        ),
+        migrations.RenameIndex(
+            model_name="blockcompletion",
+            new_name="completion__course__c6e6ad_idx",
+            old_fields=("context_key", "block_type", "user"),
+        ),
+    ]