learning-credentials 0.4.1rc6__tar.gz → 0.5.0rc3__tar.gz

{learning_credentials-0.4.1rc6 → learning_credentials-0.5.0rc3}/CHANGELOG.rst

@@ -16,7 +16,16 @@ Unreleased
 
 *
 
-0.4.1 - 2025-12-31
+0.5.0 - 2026-01-29
+******************
+
+Added
+=====
+
+* Frontend form and backend API endpoint for verifying credentials.
+* Option to invalidate issued credentials.
+
+0.4.0 - 2026-01-28
 ******************
 
 Added

{learning_credentials-0.4.1rc6/learning_credentials.egg-info → learning_credentials-0.5.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learning-credentials
-Version: 0.4.1rc6
+Version: 0.5.0rc3
 Summary: A pluggable service for preparing Open edX credentials.
 Author-email: OpenCraft <help@opencraft.com>
 License-Expression: AGPL-3.0-or-later
@@ -11,6 +11,7 @@ Keywords: Python,edx,credentials,django
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
 Classifier: Intended Audience :: Developers
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
@@ -176,7 +177,16 @@ Unreleased
 
 *
 
-0.4.1 - 2025-12-31
+0.5.0 - 2026-01-29
+******************
+
+Added
+=====
+
+* Frontend form and backend API endpoint for verifying credentials.
+* Option to invalidate issued credentials.
+
+0.4.0 - 2026-01-28
 ******************
 
 Added

{learning_credentials-0.4.1rc6 → learning_credentials-0.5.0rc3}/learning_credentials/admin.py

@@ -6,9 +6,12 @@ import importlib
 import inspect
 from typing import TYPE_CHECKING
 
+import django
 from django import forms
-from django.contrib import admin
+from django.contrib import admin, messages
 from django.core.exceptions import ValidationError
+from django.db.models import URLField
+from django.urls import reverse
 from django.utils.html import format_html
 from django_object_actions import DjangoObjectActions, action
 from django_reverse_admin import ReverseModelAdmin
@@ -225,31 +228,49 @@ class CredentialConfigurationAdmin(DjangoObjectActions, ReverseModelAdmin):
 
 
 @admin.register(Credential)
-class CredentialAdmin(admin.ModelAdmin):  # noqa: D101
+class CredentialAdmin(DjangoObjectActions, admin.ModelAdmin):  # noqa: D101
     list_display = (
-        'user_id',
+        'user',
         'user_full_name',
-        'learning_context_key',
-        'credential_type',
+        'configuration',
         'status',
         'url',
         'created',
         'modified',
     )
     readonly_fields = (
-        'user_id',
+        'uuid',
+        'verify_uuid',
+        'user',
+        'configuration',
         'created',
         'modified',
         'user_full_name',
-        'learning_context_key',
-        'credential_type',
+        'learning_context_name',
         '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")
+    search_fields = (
+        "configuration__learning_context_key",
+        "user_full_name",
+        "user__username",
+        "user__email",
+        "uuid",
+        "verify_uuid",
+    )
+    list_filter = ("configuration__learning_context_key", "configuration__credential_type", "status")
+    change_actions = ('reissue_credential',)
+
+    def save_model(self, request: HttpRequest, obj: Credential, _form: forms.ModelForm, _change: bool):  # noqa: FBT001
+        """Display validation errors as messages in the admin interface."""
+        try:
+            obj.save()
+        except ValidationError as e:
+            self.message_user(request, e.message or "Invalid data", level=messages.ERROR)
+            # Optionally, redirect to the change form with the error message
+            return
 
     def get_form(self, request: HttpRequest, obj: Credential | None = None, **kwargs) -> forms.ModelForm:
         """Hide the download_url field."""
@@ -263,3 +284,31 @@ class CredentialAdmin(admin.ModelAdmin):  # noqa: D101
         if obj.download_url:
             return format_html("<a href='{url}'>{url}</a>", url=obj.download_url)
         return "-"
+
+    @action(label="Reissue credential", description="Reissue the credential for the user.")
+    def reissue_credential(self, request: HttpRequest, obj: Credential):
+        """Reissue the credential for the user."""
+        new_credential = obj.reissue()
+        admin_url = reverse('admin:learning_credentials_credential_change', args=[new_credential.pk])
+        message = format_html(
+            'The credential has been reissued as <a href="{}">{}</a>.', admin_url, new_credential.uuid
+        )
+        messages.success(request, message)
+
+    def has_add_permission(self, _request: HttpRequest) -> bool:
+        """Hide the "Add" button in the admin interface."""
+        return False
+
+    def has_delete_permission(self, _request: HttpRequest, _obj: Credential | None = None) -> bool:
+        """Hide the "Delete" button in the admin interface."""
+        return False
+
+    def formfield_for_dbfield(self, db_field, request, **kwargs):  # noqa: ANN001, ANN201
+        """
+        Assume HTTPS for scheme-less domains pasted into URLFields.
+
+        This method can be removed when support for Django versions below 5.0 is dropped.
+        """
+        if django.VERSION[0] > 4 and isinstance(db_field, URLField):  # pragma: no cover
+            kwargs["assume_scheme"] = "https"
+        return super().formfield_for_dbfield(db_field, request, **kwargs)

learning_credentials-0.5.0rc3/learning_credentials/api/v1/serializers.py

@@ -0,0 +1,13 @@
+"""API serializers for learning credentials."""
+
+from rest_framework import serializers
+
+from learning_credentials.models import Credential
+
+
+class CredentialSerializer(serializers.ModelSerializer):
+    """Serializer that returns credential metadata."""
+
+    class Meta:  # noqa: D106
+        model = Credential
+        fields = ('user_full_name', 'created', 'learning_context_name', 'status', 'invalidation_reason')

{learning_credentials-0.4.1rc6 → learning_credentials-0.5.0rc3}/learning_credentials/api/v1/urls.py

@@ -2,7 +2,7 @@
 
 from django.urls import path
 
-from .views import CredentialConfigurationCheckView
+from .views import CredentialConfigurationCheckView, CredentialMetadataView
 
 urlpatterns = [
     path(
@@ -10,4 +10,5 @@ urlpatterns = [
         CredentialConfigurationCheckView.as_view(),
         name='credential_configuration_check',
     ),
+    path('metadata/<uuid:uuid>/', CredentialMetadataView.as_view(), name='credential-metadata'),
 ]

{learning_credentials-0.4.1rc6 → learning_credentials-0.5.0rc3}/learning_credentials/api/v1/views.py

@@ -9,9 +9,10 @@ from rest_framework.permissions import IsAuthenticated
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
-from learning_credentials.models import CredentialConfiguration
+from learning_credentials.models import Credential, CredentialConfiguration
 
 from .permissions import CanAccessLearningContext
+from .serializers import CredentialSerializer
 
 if TYPE_CHECKING:
     from rest_framework.request import Request
@@ -81,3 +82,62 @@ class CredentialConfigurationCheckView(APIView):
         }
 
         return Response(response_data, status=status.HTTP_200_OK)
+
+
+class CredentialMetadataView(APIView):
+    """API view to retrieve credential metadata by UUID."""
+
+    @apidocs.schema(
+        parameters=[
+            apidocs.string_parameter(
+                "uuid",
+                ParameterLocation.PATH,
+                description="The UUID of the credential to retrieve.",
+            ),
+        ],
+        responses={
+            200: "Successfully retrieved the credential metadata.",
+            404: "Credential not found or not valid.",
+        },
+    )
+    def get(self, _request: "Request", uuid: str) -> Response:
+        """
+        Retrieve credential metadata by its UUID.
+
+        **Example Request**
+
+        ``GET /api/learning_credentials/v1/metadata/123e4567-e89b-12d3-a456-426614174000/``
+
+        **Response Values**
+
+        - **200 OK**: Successfully retrieved the credential metadata.
+        - **404 Not Found**: Credential not found or not valid.
+
+        **Example Response**
+
+        .. code-block:: json
+
+            {
+                "user_full_name": "John Doe",
+                "created": "2023-01-01",
+                "learning_context_name": "Demo Course",
+                "status": "available",
+                "invalidation_reason": ""
+            }
+
+
+            {
+                "user_full_name": "John Doe",
+                "created": "2023-01-01",
+                "learning_context_name": "Demo Course",
+                "status": "invalidated",
+                "invalidation_reason": "Reissued due to name change."
+            }
+        """
+        try:
+            credential = Credential.objects.get(verify_uuid=uuid)
+        except Credential.DoesNotExist:
+            return Response({'error': 'Credential not found.'}, status=status.HTTP_404_NOT_FOUND)
+
+        serializer = CredentialSerializer(credential)
+        return Response(serializer.data, status=status.HTTP_200_OK)

{learning_credentials-0.4.1rc6 → learning_credentials-0.5.0rc3}/learning_credentials/compat.py

@@ -10,7 +10,6 @@ It also simplifies running tests outside edx-platform's environment by stubbing
 from __future__ import annotations
 
 from contextlib import contextmanager
-from datetime import datetime
 from typing import TYPE_CHECKING
 
 import pytz
@@ -18,7 +17,9 @@ from celery import Celery
 from django.conf import settings
 from learning_paths.models import LearningPath
 
-if TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:
+    from datetime import datetime
+
     from django.contrib.auth.models import User
     from learning_paths.keys import LearningPathKey
     from opaque_keys.edx.keys import CourseKey, LearningContextKey
@@ -33,7 +34,7 @@ def get_celery_app() -> Celery:
     # noinspection PyUnresolvedReferences,PyPackageRequirements
     from lms import CELERY_APP
 
-    return CELERY_APP  # pragma: no cover
+    return CELERY_APP
 
 
 def get_default_storage_url() -> str:
@@ -116,10 +117,15 @@ def get_course_grade(user: User, course_id: CourseKey):  # noqa: ANN201
     return CourseGradeFactory().read(user, course_key=course_id)
 
 
-def get_localized_credential_date() -> str:
-    """Get the localized date from Open edX."""
+def get_localized_credential_date(date: datetime) -> str:
+    """
+    Get the localized date from Open edX.
+
+    :param date: The datetime to format.
+    :returns: The formatted date string.
+    """
     # 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)
+    localized_date = date.astimezone(pytz.timezone(settings.TIME_ZONE))
+    return strftime_localized(localized_date, settings.CERTIFICATE_DATE_FORMAT)

{learning_credentials-0.4.1rc6 → learning_credentials-0.5.0rc3}/learning_credentials/generators.py

@@ -25,7 +25,7 @@ from reportlab.pdfbase.pdfmetrics import FontError, FontNotFoundError, registerF
 from reportlab.pdfbase.ttfonts import TTFError, TTFont
 from reportlab.pdfgen.canvas import Canvas
 
-from .compat import get_default_storage_url, get_learning_context_name, get_localized_credential_date
+from .compat import get_default_storage_url, get_localized_credential_date
 from .exceptions import AssetNotFoundError
 from .models import CredentialAsset
 
@@ -34,10 +34,10 @@ 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
     from pypdf import PageObject
 
+    from learning_credentials.models import Credential
+
 
 def _get_defaults() -> tuple[dict[str, Any], dict[str, dict[str, Any]]]:
     """
@@ -81,16 +81,6 @@ def _get_defaults() -> tuple[dict[str, Any], dict[str, dict[str, Any]]]:
     return default_styling, default_text_elements
 
 
-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(pdf_canvas: Canvas, font_name: str) -> str:
     """
     Register a custom font if not already available.
@@ -246,11 +236,12 @@ def _render_text_element(
         pdf_canvas.drawString(line_x, line_y, line, charSpace=char_space)
 
 
-def _write_text_on_template(
+def _write_text_on_template(  # noqa: PLR0913
     template: PageObject,
     username: str,
     context_name: str,
     issue_date: str,
+    verify_uuid: str,
     options: dict[str, Any],
 ) -> Canvas:
     """
@@ -260,6 +251,7 @@ def _write_text_on_template(
     :param username: The name of the user to generate the credential for.
     :param context_name: The name of the learning context.
     :param issue_date: The formatted issue date string.
+    :param verify_uuid: The verification UUID of the credential.
     :param options: A dictionary documented in the ``generate_pdf_credential`` function.
     :returns: A canvas with written data.
     """
@@ -271,6 +263,7 @@ def _write_text_on_template(
         'name': username,
         'context_name': context_name,
         'issue_date': issue_date,
+        'verify_uuid': verify_uuid,
     }
 
     # Build and render text elements.
@@ -282,26 +275,73 @@ def _write_text_on_template(
     return pdf_canvas
 
 
-def _save_credential(credential: PdfWriter, credential_uuid: UUID) -> str:
+def _get_credential_paths(credential_uuid: UUID) -> tuple[str, str]:
+    """
+    Get the original and archive paths for a credential.
+
+    :param credential_uuid: The UUID of the credential.
+    :returns: A tuple of (original_path, archive_path).
+    """
+    output_dir = getattr(settings, 'LEARNING_CREDENTIALS_OUTPUT_DIR', 'learning_credentials')
+    original_path = f'{output_dir}/{credential_uuid}.pdf'
+    archive_path = f'{output_dir}_invalidated/{credential_uuid}.pdf'
+    return original_path, archive_path
+
+
+def _invalidate_credential(credential_uuid: UUID) -> str | None:
+    """
+    Invalidate a PDF credential by moving it to an archive location and restricting access.
+
+    For S3 storage: moves file to archive path and sets ACL to private.
+    For other backends: moves file to archive path.
+
+    :param credential_uuid: The UUID of the credential to invalidate.
+    :returns: The archive path if successful, None if file didn't exist.
+    """
+    original_path, archive_path = _get_credential_paths(credential_uuid)
+
+    if not default_storage.exists(original_path):
+        log.warning("Credential file %s does not exist, nothing to invalidate", original_path)
+        return None
+
+    with default_storage.open(original_path, 'rb') as original_file:
+        default_storage.save(archive_path, ContentFile(original_file.read()))
+    log.info("Archived credential to %s", archive_path)
+
+    default_storage.delete(original_path)
+    log.info("Deleted original credential file %s", original_path)
+
+    # Set ACL to private if S3 (django-storages S3Boto3Storage exposes the bucket).
+    if hasattr(default_storage, 'bucket'):
+        try:
+            obj = default_storage.bucket.Object(archive_path)
+            obj.Acl().put(ACL='private')
+            log.info("Set ACL to private for archived file %s", archive_path)
+        except Exception:
+            log.exception("Failed to set ACL to private for %s", archive_path)
+
+    return archive_path
+
+
+def _save_credential(pdf_writer: PdfWriter, credential_uuid: UUID) -> str:
     """
     Save the final PDF file to BytesIO and upload it using Django default storage.
 
-    :param credential: Pdf credential.
+    :param pdf_writer: The PdfWriter instance containing the 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'
+    output_path, _ = _get_credential_paths(credential_uuid)
 
     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_writer.encrypt('', secrets.token_hex(32), permissions_flag=view_print_extract_permission, algorithm='AES-256')
 
     pdf_bytes = io.BytesIO()
-    credential.write(pdf_bytes)
+    pdf_writer.write(pdf_bytes)
     pdf_bytes.seek(0)  # Rewind to start.
     # Upload with Django default storage.
     credential_file = ContentFile(pdf_bytes.read())
@@ -320,20 +360,15 @@ def _save_credential(credential: PdfWriter, credential_uuid: UUID) -> str:
     return url
 
 
-def generate_pdf_credential(
-    learning_context_key: CourseKey,
-    user: User,
-    credential_uuid: UUID,
-    options: dict[str, Any],
-) -> str:
+def generate_pdf_credential(credential: Credential, options: dict[str, Any], *, invalidate: bool = False) -> str:
     r"""
-    Generate a PDF credential.
+    Generate or invalidate 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 credential: The Credential instance to generate or invalidate the PDF for.
     :param options: The custom options for the credential.
-    :returns: The URL of the saved credential.
+    :param invalidate: If True, invalidates the credential instead of generating it.
+        The PDF is moved to an archive location and made inaccessible.
+    :returns: The URL of the saved credential, or empty string if invalidated.
 
     Options:
 
@@ -372,12 +407,17 @@ def generate_pdf_credential(
         }
       }
     """
-    log.info("Starting credential generation for user %s", user.id)
+    if invalidate:
+        log.info("Invalidating credential %s for user %s", credential.uuid, credential.user.id)
+        _invalidate_credential(credential.uuid)
+        return ''
+
+    log.info("Starting credential generation for user %s", credential.user.id)
 
-    username = _get_user_name(user)
+    username = credential.user_full_name
 
     # Handle multiline context name.
-    context_name = get_learning_context_name(learning_context_key)
+    context_name = credential.learning_context_name
     custom_context_name = ''
     custom_context_text_element = options.get('text_elements', {}).get('context', {})
     if isinstance(custom_context_text_element, dict):
@@ -395,22 +435,24 @@ def generate_pdf_credential(
     template_file = CredentialAsset.get_asset_by_slug(template_path)
 
     # Get the issue date.
-    issue_date = get_localized_credential_date()
+    issue_date = get_localized_credential_date(credential.created)
 
     # Load the PDF template.
     with template_file.open('rb') as template_file:
         template = PdfReader(template_file).pages[0]
 
-        credential = PdfWriter()
+        pdf_writer = PdfWriter()
 
         # Create a new canvas, prepare the page and write the data.
-        pdf_canvas = _write_text_on_template(template, username, context_name, issue_date, options)
+        pdf_canvas = _write_text_on_template(
+            template, username, context_name, issue_date, str(credential.verify_uuid), options
+        )
 
         overlay_pdf = PdfReader(io.BytesIO(pdf_canvas.getpdfdata()))
         template.merge_page(overlay_pdf.pages[0])
-        credential.add_page(template)
+        pdf_writer.add_page(template)
 
-        url = _save_credential(credential, credential_uuid)
+        url = _save_credential(pdf_writer, credential.uuid)
 
         log.info("Credential saved to %s", url)
     return url