learning-credentials 0.2.0rc1__py2.py3-none-any.whl

learning_credentials/__init__.py

@@ -0,0 +1,3 @@
+"""A pluggable service for preparing Open edX credentials."""
+
+__version__ = '0.2.0rc1'

learning_credentials/admin.py

@@ -0,0 +1,263 @@
+"""Admin page configuration for the learning-credentials app."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from typing import TYPE_CHECKING
+
+from django import forms
+from django.contrib import admin
+from django.core.exceptions import ValidationError
+from django.utils.html import format_html
+from django_object_actions import DjangoObjectActions, action
+from django_reverse_admin import ReverseModelAdmin
+from learning_paths.keys import LearningPathKey
+from opaque_keys import InvalidKeyError
+from opaque_keys.edx.keys import CourseKey
+
+from .models import (
+    Credential,
+    CredentialAsset,
+    CredentialConfiguration,
+    CredentialType,
+)
+from .tasks import generate_credentials_for_config_task
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Generator
+
+    from django.http import HttpRequest
+    from django_celery_beat.models import IntervalSchedule
+
+
+class DocstringOptionsMixin:
+    """A mixin to add the docstring of the function to the help text of the function field."""
+
+    @staticmethod
+    def _get_docstring_custom_options(func: str) -> str:
+        """
+        Get the docstring of the function and return the "Options:" section.
+
+        :param func: The function to get the docstring for.
+        :returns: The "Options:" section of the docstring.
+        """
+        try:
+            docstring = (
+                'Custom options:'
+                + inspect.getdoc(
+                    getattr(
+                        importlib.import_module(func.rsplit('.', 1)[0]),
+                        func.rsplit('.', 1)[1],
+                    ),
+                ).split("Options:")[1]
+            )
+        except IndexError:
+            docstring = (
+                'Custom options are not documented for this function. If you selected a different function, '
+                'you need to save your changes to see an updated docstring.'
+            )
+        # Use pre to preserve the newlines and indentation.
+        return f'<pre>{docstring}</pre>'
+
+
+class CredentialTypeAdminForm(forms.ModelForm, DocstringOptionsMixin):
+    """Generate a list of available functions for the function fields."""
+
+    retrieval_func = forms.ChoiceField(choices=[])
+    generation_func = forms.ChoiceField(choices=[])
+
+    @staticmethod
+    def _available_functions(module: str, prefix: str) -> Generator[tuple[str, str], None, None]:
+        """
+        Import a module and return all functions in it that start with a specific prefix.
+
+        :param module: The name of the module to import.
+        :param prefix: The prefix of the function names to return.
+
+        :return: A tuple containing the functions that start with the prefix in the module.
+        """
+        # TODO: Implement plugin support for the functions.
+        _module = importlib.import_module(module)
+        return (
+            (f'{obj.__module__}.{name}', f'{obj.__module__}.{name}')
+            for name, obj in inspect.getmembers(_module, inspect.isfunction)
+            if name.startswith(prefix)
+        )
+
+    def __init__(self, *args, **kwargs):
+        """Initializes the choices for the retrieval and generation function selection fields."""
+        super().__init__(*args, **kwargs)
+        self.fields['retrieval_func'].choices = self._available_functions(
+            'learning_credentials.processors',
+            'retrieve_',
+        )
+        if self.instance.retrieval_func:
+            self.fields['retrieval_func'].help_text = self._get_docstring_custom_options(self.instance.retrieval_func)
+        self.fields['generation_func'].choices = self._available_functions(
+            'learning_credentials.generators',
+            'generate_',
+        )
+        if self.instance.generation_func:
+            self.fields['generation_func'].help_text = self._get_docstring_custom_options(self.instance.generation_func)
+
+    class Meta:  # noqa: D106
+        model = CredentialType
+        fields = '__all__'  # noqa: DJ007
+
+
+@admin.register(CredentialType)
+class CredentialTypeAdmin(admin.ModelAdmin):  # noqa: D101
+    form = CredentialTypeAdminForm
+    list_display = ('name', 'retrieval_func', 'generation_func')
+
+
+@admin.register(CredentialAsset)
+class CredentialAssetAdmin(admin.ModelAdmin):  # noqa: D101
+    list_display = ('description', 'asset_slug')
+    prepopulated_fields = {"asset_slug": ("description",)}  # noqa: RUF012
+
+
+class CredentialConfigurationForm(forms.ModelForm, DocstringOptionsMixin):  # noqa: D101
+    class Meta:  # noqa: D106
+        model = CredentialConfiguration
+        fields = ('learning_context_key', 'credential_type', 'custom_options')
+
+    def __init__(self, *args, **kwargs):
+        """Initializes the choices for the retrieval and generation function selection fields."""
+        super().__init__(*args, **kwargs)
+        options = ''
+
+        if self.instance and getattr(self.instance, 'credential_type', None):
+            if self.instance.credential_type.generation_func:
+                generation_options = self._get_docstring_custom_options(self.instance.credential_type.generation_func)
+                options += generation_options.replace('Custom options:', '\nGeneration options:')
+            if self.instance.credential_type.retrieval_func:
+                retrieval_options = self._get_docstring_custom_options(self.instance.credential_type.retrieval_func)
+                options += retrieval_options.replace('Custom options:', '\nRetrieval options:')
+
+            self.fields['custom_options'].help_text += options
+
+    def clean_learning_context_key(self) -> str:
+        """Validate the learning_context_key field to ensure it is a valid CourseKey or LearningPathKey."""
+        learning_context_key = self.cleaned_data.get('learning_context_key')
+        try:
+            try:
+                CourseKey.from_string(learning_context_key)
+            except InvalidKeyError:
+                LearningPathKey.from_string(learning_context_key)
+        except InvalidKeyError as exc:
+            msg = (
+                "Invalid key format. Must be either a valid course key ('course-v1:{org}+{course}+{run}') "
+                "or a valid Learning Path key ('path-v1:{org}+{number}+{run}+{group}')."
+            )
+            raise ValidationError(msg) from exc
+        return learning_context_key
+
+
+@admin.register(CredentialConfiguration)
+class CredentialConfigurationAdmin(DjangoObjectActions, ReverseModelAdmin):
+    """
+    Admin page for the context-specific credential configuration for each credential type.
+
+    It manages the associations between configuration and its corresponding periodic task.
+    The reverse inline provides a way to manage the periodic task from the configuration page.
+    """
+
+    form = CredentialConfigurationForm
+    inline_type = 'stacked'
+    inline_reverse = [  # noqa: RUF012
+        (
+            'periodic_task',
+            {'fields': ['enabled', 'interval', 'crontab', 'clocked', 'start_time', 'expires', 'one_off']},
+        ),
+    ]
+    list_display = ('learning_context_key', 'credential_type', 'enabled', 'interval')
+    search_fields = ('learning_context_key', 'credential_type__name')
+    list_filter = ('learning_context_key', 'credential_type')
+
+    def get_inline_instances(
+        self,
+        request: HttpRequest,
+        obj: CredentialConfiguration = None,
+    ) -> list[admin.ModelAdmin]:
+        """
+        Hide inlines on the "Add" view in Django admin, and show them on the "Change" view.
+
+        It differentiates "add" and change "view" based on the requested path because the `obj` parameter can be `None`
+        in the "Change" view when rendering the inlines.
+
+        :param request: HttpRequest object
+        :param obj: The object being changed, None for add view
+        :return: A list of InlineModelAdmin instances to be rendered for add/changing an object
+        """
+        return super().get_inline_instances(request, obj) if '/add/' not in request.path else []
+
+    def enabled(self, obj: CredentialConfiguration) -> bool:
+        """Return the 'enabled' status of the periodic task."""
+        return obj.periodic_task.enabled
+
+    enabled.boolean = True
+
+    # noinspection PyMethodMayBeStatic
+    def interval(self, obj: CredentialConfiguration) -> IntervalSchedule:
+        """Return the interval of the credentialedential generation task."""
+        return obj.periodic_task.interval
+
+    def get_readonly_fields(self, _request: HttpRequest, obj: CredentialConfiguration = None) -> tuple:
+        """Make the learning_context_key field read-only."""
+        if obj:  # editing an existing object
+            return *self.readonly_fields, 'learning_context_key', 'credential_type'
+        return self.readonly_fields
+
+    @action(label="Generate credentials")
+    def generate_credentials(self, _request: HttpRequest, obj: CredentialConfiguration):
+        """
+        Custom action to generate credential for the current CredentialConfiguration instance.
+
+        Args:
+            _request: The request object.
+            obj: The CredentialConfiguration instance.
+        """
+        generate_credentials_for_config_task.delay(obj.id)
+
+    change_actions = ('generate_credentials',)
+
+
+@admin.register(Credential)
+class CredentialAdmin(admin.ModelAdmin):  # noqa: D101
+    list_display = (
+        'user_id',
+        'user_full_name',
+        'learning_context_key',
+        'credential_type',
+        'status',
+        'url',
+        'created',
+        'modified',
+    )
+    readonly_fields = (
+        'user_id',
+        'created',
+        'modified',
+        'user_full_name',
+        'learning_context_key',
+        'credential_type',
+        'status',
+        'url',
+        'legacy_id',
+        'generation_task_id',
+    )
+
+    def get_form(self, request: HttpRequest, obj: Credential | None = None, **kwargs) -> forms.ModelForm:
+        """Hide the download_url field."""
+        form = super().get_form(request, obj, **kwargs)
+        form.base_fields['download_url'].widget = forms.HiddenInput()
+        return form
+
+    # noinspection PyMethodMayBeStatic
+    def url(self, obj: Credential) -> str:
+        """Display the download URL as a clickable link."""
+        if obj.download_url:
+            return format_html("<a href='{url}'>{url}</a>", url=obj.download_url)
+        return "-"

learning_credentials/apps.py

@@ -0,0 +1,24 @@
+"""learning_credentials Django application initialization."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from django.apps import AppConfig
+
+
+class LearningCredentialsConfig(AppConfig):
+    """Configuration for the learning_credentials Django application."""
+
+    name = 'learning_credentials'
+    verbose_name = 'Learning Credentials'
+
+    # https://edx.readthedocs.io/projects/edx-django-utils/en/latest/plugins/how_tos/how_to_create_a_plugin_app.html
+    plugin_app: ClassVar[dict[str, dict[str, dict]]] = {
+        'settings_config': {
+            'lms.djangoapp': {
+                'common': {'relative_path': 'settings.common'},
+                'production': {'relative_path': 'settings.production'},
+            },
+        },
+    }

learning_credentials/compat.py

@@ -0,0 +1,117 @@
+"""
+Proxies and compatibility code for edx-platform features.
+
+This module moderates access to all edx-platform features allowing for cross-version compatibility code.
+It also simplifies running tests outside edx-platform's environment by stubbing these functions in unit tests.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+import pytz
+from celery import Celery
+from django.conf import settings
+from learning_paths.models import LearningPath
+
+if TYPE_CHECKING:  # pragma: no cover
+    from django.contrib.auth.models import User
+    from learning_paths.keys import LearningPathKey
+    from opaque_keys.edx.keys import CourseKey, LearningContextKey
+
+
+def get_celery_app() -> Celery:
+    """Get Celery app to reuse configuration and queues."""
+    if getattr(settings, "TESTING", False):
+        # We can ignore this in the testing environment.
+        return Celery(task_always_eager=True)
+
+    # noinspection PyUnresolvedReferences,PyPackageRequirements
+    from lms import CELERY_APP
+
+    return CELERY_APP  # pragma: no cover
+
+
+def get_default_storage_url() -> str:
+    """Get the default storage URL from Open edX."""
+    return f"{settings.LMS_ROOT_URL}{settings.MEDIA_URL}"
+
+
+def get_course_grading_policy(course_id: CourseKey) -> dict:
+    """Get the course grading policy from Open edX."""
+    # noinspection PyUnresolvedReferences,PyPackageRequirements
+    from xmodule.modulestore.django import modulestore
+
+    return modulestore().get_course(course_id).grading_policy["GRADER"]
+
+
+def _get_course_name(course_id: CourseKey) -> str:
+    """Get the course name from Open edX."""
+    # noinspection PyUnresolvedReferences,PyPackageRequirements
+    from openedx.core.djangoapps.content.learning_sequences.api import get_course_outline
+
+    course_outline = get_course_outline(course_id)
+    return (course_outline and course_outline.title) or str(course_id)
+
+
+def _get_learning_path_name(learning_path_key: LearningPathKey) -> str:
+    """Get the Learning Path name from the plugin."""
+    try:
+        return LearningPath.objects.get(key=learning_path_key).display_name
+    except LearningPath.DoesNotExist:
+        return str(learning_path_key)
+
+
+def get_learning_context_name(learning_context_key: LearningContextKey) -> str:
+    """Get the learning context (course or Learning Path) name."""
+    if learning_context_key.is_course:
+        return _get_course_name(learning_context_key)
+    return _get_learning_path_name(learning_context_key)
+
+
+def get_course_enrollments(course_id: CourseKey) -> list[User]:
+    """Get the course enrollments from Open edX."""
+    # noinspection PyUnresolvedReferences,PyPackageRequirements
+    from common.djangoapps.student.models import CourseEnrollment
+
+    enrollments = CourseEnrollment.objects.filter(course_id=course_id, is_active=True).select_related('user')
+    return [enrollment.user for enrollment in enrollments]
+
+
+@contextmanager
+def prefetch_course_grades(course_id: CourseKey, users: list[User]):
+    """
+    Prefetch the course grades from Open edX.
+
+    This optimizes retrieving grades for multiple users.
+    """
+    # noinspection PyUnresolvedReferences,PyPackageRequirements
+    from lms.djangoapps.grades.api import clear_prefetched_course_grades, prefetch_course_and_subsection_grades
+
+    prefetch_course_and_subsection_grades(course_id, users)
+    try:
+        yield
+    finally:
+        # This uses `clear_prefetched_course_grades` instead of `clear_prefetched_course_and_subsection_grades` because
+        # these function names were accidentally swapped in the Open edX codebase.
+        # Ref: https://github.com/openedx/edx-platform/blob/1fe67d3f6b40233791d4599bae28df8c0ac91c4d/lms/djangoapps/grades/models_api.py#L30-L36
+        clear_prefetched_course_grades(course_id)
+
+
+def get_course_grade(user: User, course_id: CourseKey):  # noqa: ANN201
+    """Get the `CourseGrade` instance from Open edX."""
+    # noinspection PyUnresolvedReferences,PyPackageRequirements
+    from lms.djangoapps.grades.api import CourseGradeFactory
+
+    return CourseGradeFactory().read(user, course_key=course_id)
+
+
+def get_localized_credential_date() -> str:
+    """Get the localized date from Open edX."""
+    # noinspection PyUnresolvedReferences,PyPackageRequirements
+    from common.djangoapps.util.date_utils import strftime_localized
+
+    date = datetime.now(pytz.timezone(settings.TIME_ZONE))
+    return strftime_localized(date, settings.CERTIFICATE_DATE_FORMAT)

learning_credentials/exceptions.py

@@ -0,0 +1,9 @@
+"""Custom exceptions for the learning-credentials app."""
+
+
+class AssetNotFoundError(Exception):
+    """Raised when the asset_slug is not found in the CredentialAsset model."""
+
+
+class CredentialGenerationError(Exception):
+    """Raised when the credential generation Celery task fails."""

learning_credentials/generators.py

@@ -0,0 +1,224 @@
+"""
+This module provides functions to generate credentials.
+
+The functions prefixed with `generate_` are automatically detected by the admin page and are used to generate the
+credentials for the users.
+
+We will move this module to an external repository (a plugin).
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import secrets
+from typing import TYPE_CHECKING, Any
+
+from django.conf import settings
+from django.core.files.base import ContentFile
+from django.core.files.storage import FileSystemStorage, default_storage
+from pypdf import PdfReader, PdfWriter
+from pypdf.constants import UserAccessPermissions
+from reportlab.pdfbase import pdfmetrics
+from reportlab.pdfbase.ttfonts import TTFont
+from reportlab.pdfgen import canvas
+
+from .compat import get_default_storage_url, get_learning_context_name, get_localized_credential_date
+from .models import CredentialAsset
+
+log = logging.getLogger(__name__)
+
+if TYPE_CHECKING:  # pragma: no cover
+    from uuid import UUID
+
+    from django.contrib.auth.models import User
+    from opaque_keys.edx.keys import CourseKey
+
+
+def _get_user_name(user: User) -> str:
+    """
+    Retrieve the user's name.
+
+    :param user: The user to generate the credential for.
+    :return: Username.
+    """
+    return user.profile.name or f"{user.first_name} {user.last_name}"
+
+
+def _register_font(options: dict[str, Any]) -> str:
+    """
+    Register a custom font if specified in options. If not specified, use the default font (Helvetica).
+
+    :param options: A dictionary containing the font.
+    :returns: The font name.
+    """
+    if font := options.get('font'):
+        pdfmetrics.registerFont(TTFont(font, CredentialAsset.get_asset_by_slug(font)))
+
+    return font or 'Helvetica'
+
+
+def _write_text_on_template(template: any, font: str, username: str, context_name: str, options: dict[str, Any]) -> any:
+    """
+    Prepare a new canvas and write the user and course name onto it.
+
+    :param template: Pdf template.
+    :param font: Font name.
+    :param username: The name of the user to generate the credential for.
+    :param context_name: The name of the learning context.
+    :param options: A dictionary documented in the `generate_pdf_credential` function.
+    :returns: A canvas with written data.
+    """
+
+    def hex_to_rgb(hex_color: str) -> tuple[float, float, float]:
+        """
+        Convert a hexadecimal color code to an RGB tuple with floating-point values.
+
+        :param hex_color: A hexadecimal color string, which can start with '#' and be either 3 or 6 characters long.
+        :returns: A tuple representing the RGB color as (red, green, blue), with each value ranging from 0.0 to 1.0.
+        """
+        hex_color = hex_color.lstrip('#')
+        # Expand shorthand form (e.g. "158" to "115588")
+        if len(hex_color) == 3:
+            hex_color = ''.join([c * 2 for c in hex_color])
+
+        # noinspection PyTypeChecker
+        return tuple(int(hex_color[i : i + 2], 16) / 255 for i in range(0, 6, 2))
+
+    template_width, template_height = template.mediabox[2:]
+    pdf_canvas = canvas.Canvas(io.BytesIO(), pagesize=(template_width, template_height))
+
+    # Write the learner name.
+    pdf_canvas.setFont(font, 32)
+    name_color = options.get('name_color', '#000')
+    pdf_canvas.setFillColorRGB(*hex_to_rgb(name_color))
+
+    name_x = (template_width - pdf_canvas.stringWidth(username)) / 2
+    name_y = options.get('name_y', 290)
+    pdf_canvas.drawString(name_x, name_y, username)
+
+    # Write the learning context name.
+    pdf_canvas.setFont(font, 28)
+    context_name_color = options.get('context_name_color', '#000')
+    pdf_canvas.setFillColorRGB(*hex_to_rgb(context_name_color))
+
+    context_name_y = options.get('context_name_y', 220)
+    context_name_line_height = 28 * 1.1
+
+    # Split the learning context name into lines and write each of them in the center of the template.
+    for line_number, line in enumerate(context_name.split('\n')):
+        line_x = (template_width - pdf_canvas.stringWidth(line)) / 2
+        line_y = context_name_y - (line_number * context_name_line_height)
+        pdf_canvas.drawString(line_x, line_y, line)
+
+    # Write the issue date.
+    issue_date = get_localized_credential_date()
+    pdf_canvas.setFont(font, 12)
+    issue_date_color = options.get('issue_date_color', '#000')
+    pdf_canvas.setFillColorRGB(*hex_to_rgb(issue_date_color))
+
+    issue_date_x = (template_width - pdf_canvas.stringWidth(issue_date)) / 2
+    issue_date_y = options.get('issue_date_y', 120)
+    pdf_canvas.drawString(issue_date_x, issue_date_y, issue_date)
+
+    return pdf_canvas
+
+
+def _save_credential(credential: PdfWriter, credential_uuid: UUID) -> str:
+    """
+    Save the final PDF file to BytesIO and upload it using Django default storage.
+
+    :param credential: Pdf credential.
+    :param credential_uuid: The UUID of the credential.
+    :returns: The URL of the saved credential.
+    """
+    # Save the final PDF file to BytesIO.
+    output_path = f'external_certificates/{credential_uuid}.pdf'
+
+    view_print_extract_permission = (
+        UserAccessPermissions.PRINT
+        | UserAccessPermissions.PRINT_TO_REPRESENTATION
+        | UserAccessPermissions.EXTRACT_TEXT_AND_GRAPHICS
+    )
+    credential.encrypt('', secrets.token_hex(32), permissions_flag=view_print_extract_permission, algorithm='AES-256')
+
+    pdf_bytes = io.BytesIO()
+    credential.write(pdf_bytes)
+    pdf_bytes.seek(0)  # Rewind to start.
+    # Upload with Django default storage.
+    credential_file = ContentFile(pdf_bytes.read())
+    # Delete the file if it already exists.
+    if default_storage.exists(output_path):
+        default_storage.delete(output_path)
+    default_storage.save(output_path, credential_file)
+    if isinstance(default_storage, FileSystemStorage):
+        url = f"{get_default_storage_url()}{output_path}"
+    else:
+        url = default_storage.url(output_path)
+
+    if custom_domain := getattr(settings, 'LEARNING_CREDENTIALS_CUSTOM_DOMAIN', None):
+        url = f"{custom_domain}/{credential_uuid}.pdf"
+
+    return url
+
+
+def generate_pdf_credential(
+    learning_context_key: CourseKey,
+    user: User,
+    credential_uuid: UUID,
+    options: dict[str, Any],
+) -> str:
+    """
+    Generate a PDF credential.
+
+    :param learning_context_key: The ID of the course or learning path the credential is for.
+    :param user: The user to generate the credential for.
+    :param credential_uuid: The UUID of the credential to generate.
+    :param options: The custom options for the credential.
+    :returns: The URL of the saved credential.
+
+    Options:
+      - template: The path to the PDF template file.
+      - template_two_lines: The path to the PDF template file for two-line context names.
+        A two-line context name is specified by using a semicolon as a separator.
+      - font: The name of the font to use.
+      - name_y: The Y coordinate of the name on the credential (vertical position on the template).
+      - name_color: The color of the name on the credential (hexadecimal color code).
+      - context_name: Specify the custom course or Learning Path name.
+      - context_name_y: The Y coordinate of the context name on the credential (vertical position on the template).
+      - context_name_color: The color of the context name on the credential (hexadecimal color code).
+      - issue_date_y: The Y coordinate of the issue date on the credential (vertical position on the template).
+      - issue_date_color: The color of the issue date on the credential (hexadecimal color code).
+    """
+    log.info("Starting credential generation for user %s", user.id)
+
+    username = _get_user_name(user)
+    context_name = options.get('context_name') or get_learning_context_name(learning_context_key)
+
+    # Get template from the CredentialAsset.
+    # HACK: We support two-line strings by using a semicolon as a separator.
+    if ';' in context_name and (template_path := options.get('template_two_lines')):
+        template_file = CredentialAsset.get_asset_by_slug(template_path)
+        context_name = context_name.replace(';', '\n')
+    else:
+        template_file = CredentialAsset.get_asset_by_slug(options['template'])
+
+    font = _register_font(options)
+
+    # Load the PDF template.
+    with template_file.open('rb') as template_file:
+        template = PdfReader(template_file).pages[0]
+
+        credential = PdfWriter()
+
+        # Create a new canvas, prepare the page and write the data
+        pdf_canvas = _write_text_on_template(template, font, username, context_name, options)
+
+        overlay_pdf = PdfReader(io.BytesIO(pdf_canvas.getpdfdata()))
+        template.merge_page(overlay_pdf.pages[0])
+        credential.add_page(template)
+
+        url = _save_credential(credential, credential_uuid)
+
+        log.info("Credential saved to %s", url)
+    return url