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

openedx_progress/services.py

@@ -0,0 +1,155 @@
+"""
+Services for materializing Open edX learner course completion summaries.
+"""
+# pylint: disable=import-outside-toplevel,import-error
+import logging
+from decimal import ROUND_HALF_UP, Decimal
+
+from django.db import transaction
+from django.utils import timezone
+
+from openedx_progress.models import CourseCompletionSummary, CourseCompletionSummaryDirty
+
+PERCENT_COMPLETE_QUANT = Decimal('0.00001')
+log = logging.getLogger(__name__)
+
+
+def _course_id_for_storage(course_key):
+    """
+    Convert an opaque course key to its stable stored string form.
+    """
+    return str(course_key)
+
+
+def _user_id(user):
+    """
+    Return the integer primary key from a user object or user id value.
+    """
+    return int(getattr(user, 'id', user))
+
+
+def _get_course_blocks_completion_summary(course_key, user):
+    """
+    Load edx-platform's completion summary function lazily.
+    """
+    from lms.djangoapps.courseware.courses import get_course_blocks_completion_summary
+
+    return get_course_blocks_completion_summary(course_key, user)
+
+
+def _get_unfiltered_course_unit_count(course_key, user):
+    """
+    Return the number of course units before learner access transformers prune them.
+    """
+    from lms.djangoapps.course_blocks.api import get_course_blocks
+    from openedx.core.djangoapps.content.block_structure.transformers import BlockStructureTransformers
+    from xmodule.modulestore.django import modulestore
+
+    store = modulestore()
+    course_usage_key = store.make_course_usage_key(course_key)
+    block_data = get_course_blocks(
+        user,
+        course_usage_key,
+        transformers=BlockStructureTransformers([]),
+        allow_start_dates_in_future=True,
+    )
+
+    unit_count = 0
+    for section_key in block_data.get_children(course_usage_key):
+        for subsection_key in block_data.get_children(section_key):
+            unit_count += len(block_data.get_children(subsection_key))
+    return unit_count
+
+
+def calculate_locked_count(summary_locked_count, complete_count, incomplete_count, course_key, user):
+    """
+    Calculate locked units, including units removed by learner access filtering.
+    """
+    locked_count = int(summary_locked_count)
+    try:
+        total_unit_count = _get_unfiltered_course_unit_count(course_key, user)
+    except ImportError:
+        return locked_count
+    except Exception:  # pylint: disable=broad-except
+        log.exception('Unable to calculate unfiltered course unit count for %s.', course_key)
+        return locked_count
+
+    derived_locked_count = max(total_unit_count - complete_count - incomplete_count, 0)
+    return max(locked_count, derived_locked_count)
+
+
+def calculate_percent_complete(complete_count, incomplete_count):
+    """
+    Calculate complete / (complete + incomplete), excluding locked blocks.
+    """
+    denominator = complete_count + incomplete_count
+    if denominator == 0:
+        return None
+
+    return (
+        Decimal(complete_count) / Decimal(denominator)
+    ).quantize(PERCENT_COMPLETE_QUANT, rounding=ROUND_HALF_UP)
+
+
+def compute_completion_summary(course_key, user):
+    """
+    Return persisted completion summary values for a learner and course.
+    """
+    summary = _get_course_blocks_completion_summary(course_key, user)
+    complete_count = int(summary['complete_count'])
+    incomplete_count = int(summary['incomplete_count'])
+    locked_count = calculate_locked_count(
+        summary['locked_count'],
+        complete_count,
+        incomplete_count,
+        course_key,
+        user,
+    )
+
+    return {
+        'course_id': _course_id_for_storage(course_key),
+        'user_id': _user_id(user),
+        'complete_count': complete_count,
+        'incomplete_count': incomplete_count,
+        'locked_count': locked_count,
+        'percent_complete': calculate_percent_complete(complete_count, incomplete_count),
+        'computed_at': timezone.now(),
+    }
+
+
+def upsert_completion_summary(course_key, user):
+    """
+    Compute and persist the summary row for a learner and course.
+    """
+    values = compute_completion_summary(course_key, user)
+    course_id = values.pop('course_id')
+    user_id = values.pop('user_id')
+
+    summary, _created = CourseCompletionSummary.objects.update_or_create(
+        course_id=course_id,
+        user_id=user_id,
+        defaults=values,
+    )
+    return summary
+
+
+def mark_completion_summary_dirty(course_key, user, reason=''):
+    """
+    Mark a learner/course summary for later recomputation.
+    """
+    dirty, _created = CourseCompletionSummaryDirty.objects.update_or_create(
+        course_id=_course_id_for_storage(course_key),
+        user_id=_user_id(user),
+        defaults={
+            'reason': reason,
+            'last_error': '',
+        },
+    )
+    return dirty
+
+
+def mark_completion_summary_dirty_on_commit(course_key, user, reason=''):
+    """
+    Mark a learner/course summary dirty after the current transaction commits.
+    """
+    transaction.on_commit(lambda: mark_completion_summary_dirty(course_key, user, reason=reason))

openedx_progress/settings/__init__.py

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

openedx_progress/settings/common.py

@@ -0,0 +1,12 @@
+"""
+Common settings for openedx_progress.
+"""
+
+
+def plugin_settings(settings):  # pylint: disable=unused-argument
+    """
+    Apply common Open edX settings for openedx_progress.
+
+    The plugin currently does not require runtime settings, but the hook is
+    registered so LMS and CMS can load the Django plugin consistently.
+    """

openedx_progress/signals.py

@@ -0,0 +1,89 @@
+"""
+Optional signal handlers for keeping completion summaries fresh.
+"""
+# pylint: disable=import-outside-toplevel
+from django.db import transaction
+from django.db.models.signals import post_delete, post_save
+
+from openedx_progress import services
+
+
+def _block_completion_model():
+    """
+    Return the Open edX BlockCompletion model when it is installed.
+    """
+    try:
+        from completion.models import BlockCompletion
+    except (ImportError, RuntimeError):
+        return None
+    return BlockCompletion
+
+
+def _course_key_from_completion(instance):
+    """
+    Extract a course key from a BlockCompletion instance.
+    """
+    context_key = getattr(instance, 'context_key', None)
+    if context_key is not None:
+        # BlockCompletion also supports non-course learning contexts (libraries).
+        if not getattr(context_key, 'is_course', True):
+            return None
+        return context_key
+
+    block_key = getattr(instance, 'block_key', None)
+    return getattr(block_key, 'course_key', None)
+
+
+def _user_id_from_completion(instance):
+    """
+    Extract a user id from a BlockCompletion instance.
+    """
+    return getattr(instance, 'user_id', None) or getattr(getattr(instance, 'user', None), 'id', None)
+
+
+def _mark_dirty_from_completion(instance, reason):
+    """
+    Queue a summary recomputation for a BlockCompletion change.
+    """
+    course_key = _course_key_from_completion(instance)
+    user_id = _user_id_from_completion(instance)
+    if course_key is None or user_id is None:
+        return
+
+    transaction.on_commit(
+        lambda: services.mark_completion_summary_dirty(course_key, user_id, reason=reason)
+    )
+
+
+def block_completion_saved(sender, instance, **kwargs):  # pylint: disable=unused-argument
+    """
+    Mark a learner/course summary dirty after a completion save.
+    """
+    _mark_dirty_from_completion(instance, 'block_completion_saved')
+
+
+def block_completion_deleted(sender, instance, **kwargs):  # pylint: disable=unused-argument
+    """
+    Mark a learner/course summary dirty after a completion delete.
+    """
+    _mark_dirty_from_completion(instance, 'block_completion_deleted')
+
+
+def register_signal_handlers():
+    """
+    Connect optional completion signals.
+    """
+    block_completion = _block_completion_model()
+    if block_completion is None:
+        return
+
+    post_save.connect(
+        block_completion_saved,
+        sender=block_completion,
+        dispatch_uid='openedx_progress.block_completion_saved',
+    )
+    post_delete.connect(
+        block_completion_deleted,
+        sender=block_completion,
+        dispatch_uid='openedx_progress.block_completion_deleted',
+    )

openedx_progress/templates/openedx_progress/base.html

@@ -0,0 +1,26 @@
+
+
+{% load i18n %}
+{% trans "Dummy text to generate a translation (.po) source file. It is safe to delete this line. It is also safe to delete (load i18n) above if there are no other (trans) tags in the file" %}
+
+{% comment %}
+As the developer of this package, don't place anything here if you can help it
+since this allows developers to have interoperability between your template
+structure and their own.
+
+Example: Developer melding the 2SoD pattern to fit inside with another pattern::
+
+    {% extends "base.html" %}
+    {% load static %}
+
+    <!-- Their site uses old school block layout -->
+    {% block extra_js %}
+
+        <!-- Your package using 2SoD block layout -->
+        {% block javascript %}
+            <script src="{% static 'js/ninja.js' %}" type="text/javascript"></script>
+        {% endblock javascript %}
+
+    {% endblock extra_js %}
+{% endcomment %}
+

openedx_progress/urls.py

@@ -0,0 +1,10 @@
+"""
+URLs for openedx_progress.
+"""
+from django.urls import re_path  # pylint: disable=unused-import
+from django.views.generic import TemplateView  # pylint: disable=unused-import
+
+urlpatterns = [
+    # TODO: Fill in URL patterns and views here.
+    # re_path(r'', TemplateView.as_view(template_name="openedx_progress/base.html")),
+]

openedx_progress-1.0.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: openedx-progress
+Version: 1.0.0
+Summary: Progress tracking for Open edX students
+Home-page: https://github.com/aulasneo/openedx-progress
+Author: Andrés González
+Author-email: andres@aulasneo.com
+License: AGPL 3.0
+Keywords: Python edx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: Django<5.3,>=5.2.13
+Requires-Dist: django-model-utils<6.0,>=5.0.0
+Requires-Dist: edx-django-utils<9.0,>=8.0.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# openedx-progress
+
+Progress tracking for Open edX students.
+
+This Django plugin materializes learner course completion summaries for Open edX
+analytics. It stores one row per learner/course pair with the completion counts
+returned by `lms.djangoapps.courseware.courses.get_course_blocks_completion_summary`,
+derives locked units from the unfiltered course structure when available, and
+uses `computed_at` for when the values were last computed.
+
+## Compatibility
+
+Targets **Open edX Verawood**, using **Python 3.12+ and Django 5.2**.
+Runtime dependency ranges allow compatible patch updates; development lockfiles
+are not intended to replace the LMS requirements. Install the plugin into the
+platform environment using its constraints.
+
+See [the Verawood compatibility review](docs/verawood.md) for the checked
+upstream versions, integration points, release impacts, and deployment checks.
+
+## Why this exists
+
+In the LMS progress page, progress, also known as completion, is calculated at
+runtime as:
+
+```text
+units completed / (units completed + units incomplete)
+```
+
+The caveat is that these unit counts do not include units that are locked for
+that specific learner at that time. A unit can be locked because of visibility
+controls, dated gates, or other course access rules.
+
+Analytics add-ons such as Panorama often only have the total number of units
+that exist in the course. They do not have learner-specific detail about how many
+of those units are currently hidden or locked. As a result, analytics systems can
+show a completion percentage that differs from the percentage shown in the LMS
+progress page.
+
+This plugin stores the learner-specific `complete_count`, `incomplete_count`,
+and `locked_count` values in the summary table. By querying this table,
+analytics systems can count locked units separately and produce a completion
+calculation that more closely matches what the LMS knows about that learner at
+the time the summary was computed.
+
+For an LMS-style completion percentage, use:
+
+```text
+complete_count / (complete_count + incomplete_count)
+```
+
+If an analytics system starts from a course-wide `total_units` value, it can use
+`locked_count` to derive the learner-specific denominator:
+
+```text
+complete_count / (total_units - locked_count)
+```
+
+In practice, `total_units - locked_count` should correspond to
+`complete_count + incomplete_count` for the same course structure snapshot.
+
+## Database tables
+
+This plugin creates two tables.
+
+### `openedx_progress_coursecompletionsummary`
+
+Stores the latest materialized completion summary for each learner/course pair.
+There is one row per `course_id` and `user_id`.
+
+Columns:
+
+- `id`: primary key.
+- `created`: when the row was first created.
+- `modified`: when the row was last saved.
+- `user_id`: learner user id.
+- `course_id`: Open edX course key stored as a string.
+- `complete_count`: number of units completed by the learner.
+- `incomplete_count`: number of visible, unlocked units not yet completed by the
+  learner.
+- `locked_count`: number of units currently locked or hidden for that learner.
+- `percent_complete`: stored LMS-style completion ratio, calculated from
+  `complete_count / (complete_count + incomplete_count)`.
+- `computed_at`: when the completion summary was computed from edx-platform.
+
+The table has a unique constraint on `course_id` and `user_id`, so repeated
+backfills or dirty-queue processing update the existing learner/course summary
+instead of creating duplicate rows.
+
+### `openedx_progress_coursecompletionsummarydirty`
+
+Stores a lightweight queue of learner/course pairs that need their completion
+summary recomputed.
+
+Columns:
+
+- `id`: primary key.
+- `created`: when the queue row was first created.
+- `modified`: when the queue row was last saved.
+- `user_id`: learner user id.
+- `course_id`: Open edX course key stored as a string.
+- `reason`: short reason why the summary was marked dirty, such as a completion
+  signal.
+- `attempts`: number of processing attempts.
+- `last_error`: last processing error, if recomputation failed.
+
+The table has a unique constraint on `course_id` and `user_id`, so a learner can
+only have one pending recomputation row per course.
+
+## Course completion summaries
+
+`CourseCompletionSummary` stores:
+
+- `user_id`
+- `course_id`
+- `complete_count`
+- `incomplete_count`
+- `locked_count`
+- `percent_complete`
+- `computed_at`
+- `created` and `modified`
+
+The stored `percent_complete` is calculated as:
+
+```text
+complete_count / (complete_count + incomplete_count)
+```
+
+`locked_count` is intentionally excluded from the stored denominator to match the
+LMS progress page calculation. If the denominator is zero, `percent_complete` is
+stored as `NULL`.
+
+## Backfill command
+
+Run the backfill command inside an LMS environment where edx-platform apps are
+installed:
+
+```bash
+./manage.py lms backfill_course_completion_summaries
+```
+
+Useful options:
+
+- `--course-id course-v1:edX+DemoX+Demo_Course` restricts processing to one
+  course. When omitted, all courses from CourseOverview are processed.
+- `--user-id 123` can be repeated to process specific learners.
+- `--batch-size 500` controls database iteration batches.
+- `--sleep 0.5` pauses between batches.
+- `--dry-run` selects learners without writing rows.
+- `--force` recomputes rows that already exist.
+
+## Dirty queue
+
+When `completion.models.BlockCompletion` is importable, the plugin registers
+`post_save` and `post_delete` signal handlers that enqueue learner/course pairs
+in `CourseCompletionSummaryDirty` after transaction commit. Process queued rows
+with:
+
+```bash
+./manage.py lms process_dirty_course_completion_summaries
+```
+
+## Getting help
+
+For anything non-trivial, open an issue in this repository with as many details
+as you can provide:
+
+<https://github.com/aulasneo/openedx-progress/issues>
+
+## License
+
+The code in this repository is licensed under the AGPL 3.0 unless otherwise
+noted. See [LICENSE.txt](LICENSE.txt) for details.
+
+## Contributing
+
+This project is currently accepting all types of contributions, including bug
+fixes, security fixes, maintenance work, and new features. Please discuss new
+feature ideas with the maintainers before beginning development to maximize the
+chances of your change being accepted.
+
+## Security
+
+Please do not report security issues in public. Email support@aulasneo.com.
+
+## Disclaimer
+
+Part of this code was developed with the aid of AI tools.

openedx_progress-1.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+openedx_progress/__init__.py,sha256=K9Nmmb7O9-3zMO7obQqjJcIgSAsLmk94-NNW7okKUpI,72
+openedx_progress/apps.py,sha256=Ro433qnbFmkhcP7tpKm4uiIpzuvlOWzFw698gO9m_z0,1539
+openedx_progress/models.py,sha256=dk8_g8yaNe_WrlVKthzoDicYf8cw6ddsaunTfpC7X8E,3012
+openedx_progress/services.py,sha256=2J4klW5baeiox5DQnkA1dsb_h2T2-v3JxYHH2-ZfFvw,5004
+openedx_progress/signals.py,sha256=W54Xfibg5yaJECcD0IaBoat_V0FnlOt2FLmz-bCljcs,2655
+openedx_progress/urls.py,sha256=56MREMo1jAd062a9d-hYqJfqjxJqaJ6EZ6Q64whTXHk,333
+openedx_progress/management/__init__.py,sha256=D2wnKQgkOSVIS4BdvQfh34vtTD5v4hzOZSdgiUBX3lk,57
+openedx_progress/management/commands/__init__.py,sha256=YQl1Jxh3wiFH2CYMheY-78Az4XiSVkXSOIS16Wyfzk4,50
+openedx_progress/management/commands/backfill_course_completion_summaries.py,sha256=vtv3EPVQGv04O12dUd2lXzJZF4Yd7En6L3RBMVJdA7A,7996
+openedx_progress/management/commands/process_dirty_course_completion_summaries.py,sha256=LNBGiWimuud985dqoAWBEp5ugf9a_SvYRL0lhNvr-9w,4408
+openedx_progress/migrations/0001_initial.py,sha256=6SBE_zfG8Rnxv6Q0OHUE89y6sRZOZ_S9xnPY-Yjv67g,4771
+openedx_progress/migrations/__init__.py,sha256=l4oScNBg8EJlkEVn2oMJiUkiC0z8K43YEWFcB7-JBaU,50
+openedx_progress/settings/__init__.py,sha256=KsucKRjkLY6NAbek3A3ey3gXyWPn6aHxcgTIjyNUJJg,47
+openedx_progress/settings/common.py,sha256=YcQ9b8XLVCieACBYQg0XZ6-4LPTODc5pif-V50WTwEw,335
+openedx_progress/templates/openedx_progress/base.html,sha256=NHmMV45xJTnPEKQltuhe5Ddw9MDZLIQD_rK8GRXhqrU,873
+openedx_progress-1.0.0.dist-info/licenses/LICENSE.txt,sha256=GDpsPnW_1NKhPvZpZL9imz25P2nIpbwJPEhrlq4vPAU,34523
+openedx_progress-1.0.0.dist-info/METADATA,sha256=UVltlpbaHuo4fajmEdzLBY7meN9nEAVEmUPSl38tvyE,7528
+openedx_progress-1.0.0.dist-info/WHEEL,sha256=4YBfCYNH4wlLpv3pzq1hbEuIlXA4WJabKLFurZ7eTL0,109
+openedx_progress-1.0.0.dist-info/entry_points.txt,sha256=EjfJAZ1LtaBeP7xZ4quMgtVXvcv9nAVDnI4qHxZlWgk,159
+openedx_progress-1.0.0.dist-info/top_level.txt,sha256=SfNQVAzyS14tJL4RIpo9uv4L3d6e5fLge_xUK2PRisg,17
+openedx_progress-1.0.0.dist-info/RECORD,,

openedx_progress-1.0.0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

openedx_progress-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[cms.djangoapp]
+openedx_progress = openedx_progress.apps:OpenedxProgressConfig
+
+[lms.djangoapp]
+openedx_progress = openedx_progress.apps:OpenedxProgressConfig