openedx-progress 1.0.0__py2.py3-none-any.whl

openedx_progress/__init__.py

@@ -0,0 +1,5 @@
+"""
+Progress tracking for Open edX students.
+"""
+
+__version__ = '1.0.0'

openedx_progress/apps.py

@@ -0,0 +1,51 @@
+"""
+openedx_progress Django application initialization.
+"""
+
+from django.apps import AppConfig
+from edx_django_utils.plugins.constants import PluginSettings, PluginURLs
+
+
+class OpenedxProgressConfig(AppConfig):
+    """
+    Configuration for the openedx_progress Django application.
+    """
+
+    name = 'openedx_progress'
+    verbose_name = 'Open edX Progress'
+    default_auto_field = 'django.db.models.AutoField'
+
+    plugin_app = {
+        PluginURLs.CONFIG: {
+            'cms.djangoapp': {
+                PluginURLs.NAMESPACE: 'openedx_progress',
+                PluginURLs.REGEX: r'^api/progress/',
+                PluginURLs.RELATIVE_PATH: 'urls',
+            },
+            'lms.djangoapp': {
+                PluginURLs.NAMESPACE: 'openedx_progress',
+                PluginURLs.REGEX: r'^api/progress/',
+                PluginURLs.RELATIVE_PATH: 'urls',
+            },
+        },
+        PluginSettings.CONFIG: {
+            'cms.djangoapp': {
+                'common': {
+                    PluginSettings.RELATIVE_PATH: 'settings.common',
+                },
+            },
+            'lms.djangoapp': {
+                'common': {
+                    PluginSettings.RELATIVE_PATH: 'settings.common',
+                },
+            },
+        },
+    }
+
+    def ready(self):
+        """
+        Register optional Open edX signal handlers when their apps are installed.
+        """
+        from openedx_progress.signals import register_signal_handlers  # pylint: disable=import-outside-toplevel
+
+        register_signal_handlers()

openedx_progress/management/__init__.py

@@ -0,0 +1,3 @@
+"""
+Management command package for openedx_progress.
+"""

openedx_progress/management/commands/__init__.py

@@ -0,0 +1,3 @@
+"""
+Management commands for openedx_progress.
+"""

openedx_progress/management/commands/backfill_course_completion_summaries.py

@@ -0,0 +1,239 @@
+"""
+Backfill learner course completion summaries.
+"""
+# pylint: disable=import-outside-toplevel,import-error
+import time
+import traceback
+
+from django.contrib.auth import get_user_model
+from django.core.management.base import BaseCommand, CommandError
+
+from openedx_progress import services
+from openedx_progress.models import CourseCompletionSummary
+
+
+def parse_course_key(course_id):
+    """
+    Parse a course key when opaque-keys is available.
+    """
+    if not isinstance(course_id, str):
+        return course_id
+
+    try:
+        from opaque_keys.edx.keys import CourseKey
+    except ImportError:
+        return course_id
+
+    return CourseKey.from_string(course_id)
+
+
+def course_keys_from_overviews():
+    """
+    Return course keys for all courses known to CourseOverview.
+    """
+    try:
+        from openedx.core.djangoapps.content.course_overviews.models import CourseOverview
+    except ImportError as exc:
+        raise CommandError('CourseOverview is required when --course-id is omitted.') from exc
+
+    overviews = (
+        CourseOverview.get_all_courses()
+        if hasattr(CourseOverview, 'get_all_courses')
+        else CourseOverview.objects.all()
+    )
+    if hasattr(overviews, 'order_by') and hasattr(overviews, 'values_list'):
+        return overviews.order_by('id').values_list('id', flat=True)
+
+    return (getattr(course_overview, 'id', course_overview) for course_overview in overviews)
+
+
+def enrolled_users_for_course(course_key):
+    """
+    Return active users enrolled in a course.
+    """
+    from common.djangoapps.student.models import CourseEnrollment
+
+    manager = CourseEnrollment.objects
+    if hasattr(manager, 'users_enrolled_in'):
+        return manager.users_enrolled_in(course_key)
+
+    enrollments = manager.select_related('user').filter(course_id=str(course_key), is_active=True)
+    return get_user_model().objects.filter(id__in=enrollments.values('user_id'))
+
+
+def user_queryset_for_ids(user_ids):
+    """
+    Return users for explicit ids, preserving database batching behavior.
+    """
+    return get_user_model().objects.filter(id__in=user_ids).order_by('id')
+
+
+def batched(iterable, batch_size):
+    """
+    Yield lists of up to batch_size objects from iterable.
+    """
+    batch = []
+    for item in iterable:
+        batch.append(item)
+        if len(batch) == batch_size:
+            yield batch
+            batch = []
+    if batch:
+        yield batch
+
+
+class Command(BaseCommand):
+    """
+    Materialize course completion summaries for learners in a course.
+    """
+
+    help = 'Backfill learner course completion summaries for Open edX courses.'
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            '--course-id',
+            default=None,
+            help='Optional opaque course id, for example course-v1:Org+Num+Run.',
+        )
+        parser.add_argument(
+            '--user-id',
+            dest='user_ids',
+            action='append',
+            type=int,
+            default=None,
+            help='Optional learner user id. Can be supplied multiple times.',
+        )
+        parser.add_argument('--batch-size', type=int, default=500, help='Number of learners to process per batch.')
+        parser.add_argument('--sleep', type=float, default=0, help='Seconds to sleep between batches.')
+        parser.add_argument('--dry-run', action='store_true', help='Compute work without writing summary rows.')
+        parser.add_argument('--force', action='store_true', help='Recompute rows that already exist.')
+
+    def handle(self, *args, **options):
+        course_id = options['course_id']
+        batch_size = options['batch_size']
+        sleep_seconds = options['sleep']
+
+        if batch_size < 1:
+            raise CommandError('--batch-size must be greater than 0.')
+        if sleep_seconds < 0:
+            raise CommandError('--sleep cannot be negative.')
+
+        stats = {
+            'processed': 0,
+            'updated': 0,
+            'skipped': 0,
+            'failed': 0,
+        }
+
+        for course_key in self._course_keys_for_options(course_id):
+            if not course_id:
+                self.stdout.write('Processing course {}'.format(course_key))
+
+            course_stats = self._process_course(course_key, options)
+            for key, value in course_stats.items():
+                stats[key] += value
+
+        self.stdout.write(
+            'Done: processed={}, updated={}, skipped={}, failed={}'.format(
+                stats['processed'],
+                stats['updated'],
+                stats['skipped'],
+                stats['failed'],
+            )
+        )
+
+    def _course_keys_for_options(self, course_id):
+        """
+        Return the course keys requested by command options.
+        """
+        if course_id:
+            return [parse_course_key(course_id)]
+
+        return (parse_course_key(course_id) for course_id in course_keys_from_overviews())
+
+    def _process_course(self, course_key, options):
+        """
+        Process one course and return stats.
+        """
+        batch_size = options['batch_size']
+        sleep_seconds = options['sleep']
+        dry_run = options['dry_run']
+        force = options['force']
+        verbosity = options['verbosity']
+        users = self._users_for_options(course_key, options['user_ids'])
+        stats = {
+            'processed': 0,
+            'updated': 0,
+            'skipped': 0,
+            'failed': 0,
+        }
+
+        for batch_number, user_batch in enumerate(batched(self._iter_users(users, batch_size), batch_size), start=1):
+            for user in user_batch:
+                try:
+                    action = self._process_user(course_key, user, force=force, dry_run=dry_run)
+                except Exception as exc:  # pylint: disable=broad-except
+                    stats['failed'] += 1
+                    user_id = getattr(user, 'id', user)
+                    message = self._format_exception(exc)
+                    self.stderr.write('Failed user {}: {}'.format(user_id, message))
+                    if verbosity > 1:
+                        self.stderr.write(''.join(traceback.format_exception(type(exc), exc, exc.__traceback__)))
+                    continue
+
+                stats['processed'] += 1
+                stats[action] += 1
+
+            self.stdout.write(
+                'Batch {} complete: processed={}, updated={}, skipped={}, failed={}'.format(
+                    batch_number,
+                    stats['processed'],
+                    stats['updated'],
+                    stats['skipped'],
+                    stats['failed'],
+                )
+            )
+            if sleep_seconds:
+                time.sleep(sleep_seconds)
+
+        return stats
+
+    def _users_for_options(self, course_key, user_ids):
+        """
+        Return the user queryset or iterable requested by command options.
+        """
+        if user_ids:
+            return user_queryset_for_ids(user_ids)
+        return enrolled_users_for_course(course_key)
+
+    def _iter_users(self, users, batch_size):
+        """
+        Iterate users with database chunking when available.
+        """
+        if hasattr(users, 'iterator'):
+            return users.iterator(chunk_size=batch_size)
+        return iter(users)
+
+    def _process_user(self, course_key, user, force, dry_run):
+        """
+        Process one learner and return the stats bucket to increment.
+        """
+        exists = CourseCompletionSummary.objects.filter(course_id=str(course_key), user_id=user.id).exists()
+        if exists and not force:
+            return 'skipped'
+
+        if dry_run:
+            return 'updated'
+
+        services.upsert_completion_summary(course_key, user)
+        return 'updated'
+
+    def _format_exception(self, exc):
+        """
+        Return a compact exception description for command output.
+        """
+        exc_type = type(exc).__name__
+        message = str(exc)
+        if message:
+            return '{}: {}'.format(exc_type, message)
+        return exc_type

openedx_progress/management/commands/process_dirty_course_completion_summaries.py

@@ -0,0 +1,122 @@
+"""
+Process queued dirty learner course completion summaries.
+"""
+import time
+
+from django.contrib.auth import get_user_model
+from django.core.management.base import BaseCommand, CommandError
+
+from openedx_progress import services
+from openedx_progress.management.commands.backfill_course_completion_summaries import batched, parse_course_key
+from openedx_progress.models import CourseCompletionSummaryDirty
+
+
+class Command(BaseCommand):
+    """
+    Recompute summaries previously marked dirty by event hooks.
+    """
+
+    help = 'Process queued learner course completion summary recomputations.'
+
+    def add_arguments(self, parser):
+        parser.add_argument('--course-id', default=None, help='Optional course id to restrict processing.')
+        parser.add_argument(
+            '--user-id',
+            type=int,
+            default=None,
+            help='Optional learner user id to restrict processing.',
+        )
+        parser.add_argument('--limit', type=int, default=None, help='Maximum dirty rows to process.')
+        parser.add_argument(
+            '--batch-size',
+            type=int,
+            default=500,
+            help='Number of dirty rows to process per batch.',
+        )
+        parser.add_argument(
+            '--sleep',
+            type=float,
+            default=0,
+            help='Seconds to sleep between batches.',
+        )
+        parser.add_argument(
+            '--dry-run',
+            action='store_true',
+            help='Report queued rows without recomputing or deleting them.',
+        )
+
+    def handle(self, *args, **options):
+        batch_size = options['batch_size']
+        sleep_seconds = options['sleep']
+        if batch_size < 1:
+            raise CommandError('--batch-size must be greater than 0.')
+        if sleep_seconds < 0:
+            raise CommandError('--sleep cannot be negative.')
+
+        dirty_rows = self._dirty_rows(options)
+        stats = {
+            'processed': 0,
+            'updated': 0,
+            'failed': 0,
+        }
+
+        dirty_batches = batched(dirty_rows.iterator(chunk_size=batch_size), batch_size)
+        for batch_number, dirty_batch in enumerate(dirty_batches, start=1):
+            for dirty in dirty_batch:
+                try:
+                    if options['dry_run']:
+                        stats['updated'] += 1
+                    else:
+                        self._process_dirty_row(dirty)
+                        stats['updated'] += 1
+                except Exception as exc:  # pylint: disable=broad-except
+                    stats['failed'] += 1
+                    dirty.attempts += 1
+                    dirty.last_error = str(exc)
+                    dirty.save(update_fields=['attempts', 'last_error', 'modified'])
+                    self.stderr.write('Failed dirty row {}: {}'.format(dirty.id, exc))
+                    continue
+
+                stats['processed'] += 1
+
+            self.stdout.write(
+                'Batch {} complete: processed={}, updated={}, failed={}'.format(
+                    batch_number,
+                    stats['processed'],
+                    stats['updated'],
+                    stats['failed'],
+                )
+            )
+            if sleep_seconds:
+                time.sleep(sleep_seconds)
+
+        self.stdout.write(
+            'Done: processed={}, updated={}, failed={}'.format(
+                stats['processed'],
+                stats['updated'],
+                stats['failed'],
+            )
+        )
+        if stats['failed']:
+            raise CommandError('{} dirty row(s) failed while processing summaries.'.format(stats['failed']))
+
+    def _dirty_rows(self, options):
+        """
+        Return the queued rows matching command filters.
+        """
+        queryset = CourseCompletionSummaryDirty.objects.order_by('modified', 'id')
+        if options['course_id']:
+            queryset = queryset.filter(course_id=options['course_id'])
+        if options['user_id']:
+            queryset = queryset.filter(user_id=options['user_id'])
+        if options['limit']:
+            queryset = queryset[:options['limit']]
+        return queryset
+
+    def _process_dirty_row(self, dirty):
+        """
+        Recompute and remove one dirty queue row.
+        """
+        user = get_user_model().objects.get(id=dirty.user_id)
+        services.upsert_completion_summary(parse_course_key(dirty.course_id), user)
+        dirty.delete()

openedx_progress/migrations/0001_initial.py

@@ -0,0 +1,130 @@
+# Generated by Django 4.2.30 on 2026-06-19 08:48
+
+from django.db import migrations, models
+import django.utils.timezone
+import model_utils.fields
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="CourseCompletionSummary",
+            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",
+                    ),
+                ),
+                ("user_id", models.PositiveIntegerField(db_index=True)),
+                ("course_id", models.CharField(db_index=True, max_length=255)),
+                ("complete_count", models.PositiveIntegerField(default=0)),
+                ("incomplete_count", models.PositiveIntegerField(default=0)),
+                ("locked_count", models.PositiveIntegerField(default=0)),
+                (
+                    "percent_complete",
+                    models.DecimalField(
+                        blank=True, decimal_places=5, max_digits=6, null=True
+                    ),
+                ),
+                ("computed_at", models.DateTimeField(db_index=True)),
+            ],
+        ),
+        migrations.CreateModel(
+            name="CourseCompletionSummaryDirty",
+            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",
+                    ),
+                ),
+                ("user_id", models.PositiveIntegerField(db_index=True)),
+                ("course_id", models.CharField(db_index=True, max_length=255)),
+                ("reason", models.CharField(blank=True, max_length=255)),
+                ("attempts", models.PositiveIntegerField(default=0)),
+                ("last_error", models.TextField(blank=True)),
+            ],
+            options={
+                "indexes": [
+                    models.Index(
+                        fields=["course_id", "user_id"], name="op_dirty_course_user_idx"
+                    ),
+                    models.Index(fields=["modified"], name="op_dirty_modified_idx"),
+                ],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name="coursecompletionsummarydirty",
+            constraint=models.UniqueConstraint(
+                fields=("course_id", "user_id"), name="op_unique_dirty_course_user"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="coursecompletionsummary",
+            index=models.Index(
+                fields=["course_id", "user_id"], name="op_course_user_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="coursecompletionsummary",
+            index=models.Index(
+                fields=["course_id", "computed_at"], name="op_course_computed_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="coursecompletionsummary",
+            index=models.Index(
+                fields=["user_id", "computed_at"], name="op_user_computed_idx"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="coursecompletionsummary",
+            constraint=models.UniqueConstraint(
+                fields=("course_id", "user_id"), name="op_unique_course_user_summary"
+            ),
+        ),
+    ]

openedx_progress/migrations/__init__.py

@@ -0,0 +1,3 @@
+"""
+Database migrations for openedx_progress.
+"""

openedx_progress/models.py

@@ -0,0 +1,91 @@
+"""
+Database models for openedx_progress.
+"""
+from django.db import models
+from model_utils.models import TimeStampedModel
+
+
+class CourseCompletionSummary(TimeStampedModel):
+    """
+    Materialized learner completion counts for a course.
+
+    .. pii: The user_id field stores an identifier linked to a learner.
+       The course_id and completion counts are educational records.
+    .. pii_types: id, other
+    .. pii_retirement: retained
+    """
+
+    user_id = models.PositiveIntegerField(db_index=True)
+    course_id = models.CharField(max_length=255, db_index=True)
+    complete_count = models.PositiveIntegerField(default=0)
+    incomplete_count = models.PositiveIntegerField(default=0)
+    locked_count = models.PositiveIntegerField(default=0)
+    percent_complete = models.DecimalField(
+        max_digits=6,
+        decimal_places=5,
+        null=True,
+        blank=True,
+    )
+    computed_at = models.DateTimeField(db_index=True)
+
+    def __str__(self):
+        """
+        Get a string representation of this model instance.
+        """
+        return '<CourseCompletionSummary, course_id: {}, user_id: {}>'.format(self.course_id, self.user_id)
+
+    class Meta:
+        """
+        Model metadata.
+        """
+
+        constraints = [
+            models.UniqueConstraint(
+                fields=['course_id', 'user_id'],
+                name='op_unique_course_user_summary',
+            ),
+        ]
+        indexes = [
+            models.Index(fields=['course_id', 'user_id'], name='op_course_user_idx'),
+            models.Index(fields=['course_id', 'computed_at'], name='op_course_computed_idx'),
+            models.Index(fields=['user_id', 'computed_at'], name='op_user_computed_idx'),
+        ]
+
+
+class CourseCompletionSummaryDirty(TimeStampedModel):
+    """
+    Queue entry for recomputing one learner's course completion summary.
+
+    .. pii: The user_id field stores an identifier linked to a learner.
+       The course_id and reason fields may reveal learning activity.
+    .. pii_types: id, other
+    .. pii_retirement: retained
+    """
+
+    user_id = models.PositiveIntegerField(db_index=True)
+    course_id = models.CharField(max_length=255, db_index=True)
+    reason = models.CharField(max_length=255, blank=True)
+    attempts = models.PositiveIntegerField(default=0)
+    last_error = models.TextField(blank=True)
+
+    def __str__(self):
+        """
+        Get a string representation of this model instance.
+        """
+        return '<CourseCompletionSummaryDirty, course_id: {}, user_id: {}>'.format(self.course_id, self.user_id)
+
+    class Meta:
+        """
+        Model metadata.
+        """
+
+        constraints = [
+            models.UniqueConstraint(
+                fields=['course_id', 'user_id'],
+                name='op_unique_dirty_course_user',
+            ),
+        ]
+        indexes = [
+            models.Index(fields=['course_id', 'user_id'], name='op_dirty_course_user_idx'),
+            models.Index(fields=['modified'], name='op_dirty_modified_idx'),
+        ]