learning-credentials 0.2.2__py3-none-any.whl

learning_credentials/__init__.py

@@ -0,0 +1 @@
+"""A pluggable service for preparing Open edX credentials."""

learning_credentials/admin.py

@@ -0,0 +1,265 @@
+"""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',
+    )
+    search_fields = ("learning_context_key", "user_id", "user_full_name")
+    list_filter = ("learning_context_key", "credential_type", "status")
+
+    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,119 @@
+"""
+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.
+"""
+
+# ruff: noqa: PLC0415
+
+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/conf/locale/config.yaml

@@ -0,0 +1,85 @@
+# Configuration for i18n workflow.
+
+locales:
+    - en  # English - Source Language
+    - am  # Amharic
+    - ar  # Arabic
+    - az  # Azerbaijani
+    - bg_BG  # Bulgarian (Bulgaria)
+    - bn_BD  # Bengali (Bangladesh)
+    - bn_IN  # Bengali (India)
+    - bs  # Bosnian
+    - ca  # Catalan
+    - ca@valencia  # Catalan (Valencia)
+    - cs  # Czech
+    - cy  # Welsh
+    - da  # Danish
+    - de_DE  # German (Germany)
+    - el  # Greek
+    - en  # English
+    - en_GB  # English (United Kingdom)
+    # Don't pull these until we figure out why pages randomly display in these locales,
+    # when the user's browser is in English and the user is not logged in.
+    # - en@lolcat  # LOLCAT English
+    # - en@pirate  # Pirate English
+    - es_419  # Spanish (Latin America)
+    - es_AR  # Spanish (Argentina)
+    - es_EC  # Spanish (Ecuador)
+    - es_ES  # Spanish (Spain)
+    - es_MX  # Spanish (Mexico)
+    - es_PE  # Spanish (Peru)
+    - et_EE  # Estonian (Estonia)
+    - eu_ES  # Basque (Spain)
+    - fa  # Persian
+    - fa_IR  # Persian (Iran)
+    - fi_FI  # Finnish (Finland)
+    - fil  # Filipino
+    - fr  # French
+    - gl  # Galician
+    - gu  # Gujarati
+    - he  # Hebrew
+    - hi  # Hindi
+    - hr  # Croatian
+    - hu  # Hungarian
+    - hy_AM  # Armenian (Armenia)
+    - id  # Indonesian
+    - it_IT  # Italian (Italy)
+    - ja_JP  # Japanese (Japan)
+    - kk_KZ  # Kazakh (Kazakhstan)
+    - km_KH  # Khmer (Cambodia)
+    - kn  # Kannada
+    - ko_KR  # Korean (Korea)
+    - lt_LT  # Lithuanian (Lithuania)
+    - ml  # Malayalam
+    - mn  # Mongolian
+    - mr  # Marathi
+    - ms  # Malay
+    - nb  # Norwegian Bokmål
+    - ne  # Nepali
+    - nl_NL  # Dutch (Netherlands)
+    - or  # Oriya
+    - pl  # Polish
+    - pt_BR  # Portuguese (Brazil)
+    - pt_PT  # Portuguese (Portugal)
+    - ro  # Romanian
+    - ru  # Russian
+    - si  # Sinhala
+    - sk  # Slovak
+    - sl  # Slovenian
+    - sq  # Albanian
+    - sr  # Serbian
+    - ta  # Tamil
+    - te  # Telugu
+    - th  # Thai
+    - tr_TR  # Turkish (Turkey)
+    - uk  # Ukranian
+    - ur  # Urdu
+    - uz  # Uzbek
+    - vi  # Vietnamese
+    - zh_CN  # Chinese (China)
+    - zh_HK  # Chinese (Hong Kong)
+    - zh_TW  # Chinese (Taiwan)
+
+# The locales used for fake-accented English, for testing.
+dummy_locales:
+    - eo

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."""