learning-credentials 0.4.0__tar.gz → 0.4.0rc2__tar.gz

{learning_credentials-0.4.0 → learning_credentials-0.4.0rc2}/CHANGELOG.rst

@@ -16,38 +16,16 @@ Unreleased
 
 *
 
-0.4.0 - 2026-01-28
+0.4.0 - 2025-11-03
 ******************
 
 Added
 =====
 
-* New ``text_elements`` format for PDF credential generation with flexible text positioning and placeholder support.
-* Support for custom text elements with ``{name}``, ``{context_name}``, and ``{issue_date}`` placeholders.
-* Global ``defaults`` configuration for font, color, and character spacing.
-
-Modified
-========
-
-* Migrated generator options from flat format (``name_y``, ``context_name_color``, etc.) to structured ``text_elements`` format.
-
-0.3.1 - 2025-12-15
-******************
-
-Added
-=====
-
-* Support for defining the course name using the ``cert_name_long`` field (in Studio's Advanced Settings).
+* Frontend form and backend API endpoint for verifying credentials.
+* Option to invalidate issued credentials.
+* Support for defining the course name using the `cert_name_long` field (in Studio's Advanced Settings).
 * Support for specifying individual fonts for PDF text elements.
-* Support for \n in learning context names in PDF certificates.
-* Options for uppercase name and issue date in PDF certificates.
-* Option for defining character spacing for issue date in PDF certificates.
-* Option for defining the horizontal offset of the issue date from its centered position (``issue_date_x``).
-
-Modified
-========
-
-* Replaced ``template_two_lines`` with ``template_multiline``.
 
 0.3.0 - 2025-09-17
 ******************

{learning_credentials-0.4.0/learning_credentials.egg-info → learning_credentials-0.4.0rc2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learning-credentials
-Version: 0.4.0
+Version: 0.4.0rc2
 Summary: A pluggable service for preparing Open edX credentials.
 Author-email: OpenCraft <help@opencraft.com>
 License-Expression: AGPL-3.0-or-later
@@ -11,7 +11,6 @@ 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
@@ -177,38 +176,16 @@ Unreleased
 
 *
 
-0.4.0 - 2026-01-28
+0.4.0 - 2025-11-03
 ******************
 
 Added
 =====
 
-* New ``text_elements`` format for PDF credential generation with flexible text positioning and placeholder support.
-* Support for custom text elements with ``{name}``, ``{context_name}``, and ``{issue_date}`` placeholders.
-* Global ``defaults`` configuration for font, color, and character spacing.
-
-Modified
-========
-
-* Migrated generator options from flat format (``name_y``, ``context_name_color``, etc.) to structured ``text_elements`` format.
-
-0.3.1 - 2025-12-15
-******************
-
-Added
-=====
-
-* Support for defining the course name using the ``cert_name_long`` field (in Studio's Advanced Settings).
+* Frontend form and backend API endpoint for verifying credentials.
+* Option to invalidate issued credentials.
+* Support for defining the course name using the `cert_name_long` field (in Studio's Advanced Settings).
 * Support for specifying individual fonts for PDF text elements.
-* Support for \n in learning context names in PDF certificates.
-* Options for uppercase name and issue date in PDF certificates.
-* Option for defining character spacing for issue date in PDF certificates.
-* Option for defining the horizontal offset of the issue date from its centered position (``issue_date_x``).
-
-Modified
-========
-
-* Replaced ``template_two_lines`` with ``template_multiline``.
 
 0.3.0 - 2025-09-17
 ******************

{learning_credentials-0.4.0 → learning_credentials-0.4.0rc2}/learning_credentials/admin.py

@@ -7,8 +7,9 @@ import inspect
 from typing import TYPE_CHECKING
 
 from django import forms
-from django.contrib import admin
+from django.contrib import admin, messages
 from django.core.exceptions import ValidationError
+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,7 +226,7 @@ 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_full_name',
@@ -237,19 +238,32 @@ class CredentialAdmin(admin.ModelAdmin):  # noqa: D101
         'modified',
     )
     readonly_fields = (
+        'uuid',
+        'verify_uuid',
         'user_id',
         'created',
         'modified',
         'user_full_name',
         'learning_context_key',
+        'learning_context_name',
         'credential_type',
         'status',
         'url',
         'legacy_id',
         'generation_task_id',
     )
-    search_fields = ("learning_context_key", "user_id", "user_full_name")
+    search_fields = ("learning_context_key", "user_id", "user_full_name", "uuid")
     list_filter = ("learning_context_key", "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 +277,16 @@ 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."""
+        try:
+            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)
+        except CredentialConfiguration.DoesNotExist:
+            messages.error(request, "The configuration does not exist.")

learning_credentials-0.4.0rc2/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.0 → learning_credentials-0.4.0rc2}/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.0 → learning_credentials-0.4.0rc2}/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.0rc2/learning_credentials/generators.py

@@ -0,0 +1,238 @@
+"""
+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.pdfmetrics import FontError, FontNotFoundError, registerFont
+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 .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
+    from pypdf import PageObject
+
+
+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(font_name: Any) -> str | None:  # noqa: ANN401
+    """
+    Register a custom font if specified in options. If not specified, use the default font (Helvetica).
+
+    :param font_name: The name of the font to register.
+    :returns: The font name if registered successfully, otherwise None.
+    """
+    if not font_name:
+        return None
+
+    try:
+        registerFont(TTFont(font_name, CredentialAsset.get_asset_by_slug(font_name)))
+    except (FontError, FontNotFoundError, TTFError):
+        log.exception("Error registering font %s", font_name)
+    else:
+        return font_name
+
+
+def _write_text_on_template(template: PageObject, username: str, context_name: str, options: dict[str, Any]) -> Canvas:
+    """
+    Prepare a new canvas and write the user and course name onto it.
+
+    :param template: Pdf template.
+    :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(io.BytesIO(), pagesize=(template_width, template_height))
+    font = _register_font(options.get('font')) or 'Helvetica'
+
+    # Write the learner name.
+    name_font = _register_font(options.get('name_font')) or font
+    pdf_canvas.setFont(name_font, options.get('name_size', 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.
+    context_name_font = _register_font(options.get('context_name_font')) or font
+    pdf_canvas.setFont(context_name_font, options.get('context_name_size', 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()
+    issue_date_font = _register_font(options.get('issue_date_font')) or font
+    pdf_canvas.setFont(issue_date_font, options.get('issue_date_size', 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. The default font is Helvetica.
+      - 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).
+      - name_size: The font size of the name on the credential. The default value is 32.
+      - name_font: The font of the name on the credential. It overrides the `font` option.
+      - context_name: Specify the custom course or Learning Path name. If not provided, it will be retrieved
+        automatically from the "cert_name_long" or "display_name" fields for courses, or from the Learning Path model.
+      - 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).
+      - context_name_size: The font size of the context name on the credential. The default value is 28.
+      - context_name_font: The font of the context name on the credential. It overrides the `font` option.
+      - 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).
+      - issue_date_size: The font size of the issue date on the credential. The default value is 12.
+      - issue_date_font: The font of the issue date on the credential. It overrides the `font` option.
+    """
+    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'])
+
+    # 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, 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

learning_credentials-0.4.0rc2/learning_credentials/migrations/0007_validation.py

@@ -0,0 +1,94 @@
+# Generated by Django 4.2.25 on 2025-10-31 17:43
+
+from django.db import migrations, models
+import uuid
+
+
+def backfill_credential_fields(apps, schema_editor):
+    """Generate verification UUIDs and backfill learning_context_name for all existing credentials."""
+    from learning_credentials.compat import get_learning_context_name
+
+    Credential = apps.get_model("learning_credentials", "Credential")
+    for credential in Credential.objects.all():
+        credential.verify_uuid = uuid.uuid4()
+        credential.learning_context_name = get_learning_context_name(credential.learning_context_key)
+        credential.save(update_fields=["verify_uuid", "learning_context_name"])
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("learning_credentials", "0006_cleanup_openedx_certificates_tables"),
+    ]
+
+    operations = [
+        migrations.AlterUniqueTogether(
+            name="credential",
+            unique_together=set(),
+        ),
+        migrations.AlterField(
+            model_name="credential",
+            name="user_full_name",
+            field=models.CharField(
+                editable=False,
+                help_text="User receiving the credential. This field is used for validation purposes.",
+                max_length=255,
+            ),
+        ),
+        migrations.AddField(
+            model_name="credential",
+            name="invalidated_at",
+            field=models.DateTimeField(
+                editable=False,
+                help_text="Timestamp when the credential was invalidated",
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="credential",
+            name="invalidation_reason",
+            field=models.CharField(
+                blank=True,
+                help_text="Reason for invalidating the credential",
+                max_length=255,
+            ),
+        ),
+        migrations.AddField(
+            model_name="credential",
+            name="learning_context_name",
+            field=models.CharField(
+                editable=False,
+                help_text="Name of the learning context for which the credential was issued. This field is used for validation purposes.",
+                max_length=255,
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="credential",
+            name="verify_uuid",
+            field=models.UUIDField(
+                default=uuid.uuid4,
+                editable=False,
+                help_text="UUID used for verifying the credential",
+                null=True,
+            ),
+        ),
+        migrations.RunPython(backfill_credential_fields, reverse_code=migrations.RunPython.noop),
+        migrations.AlterField(
+            model_name="credential",
+            name="learning_context_name",
+            field=models.CharField(
+                editable=False,
+                help_text="Name of the learning context for which the credential was issued. This field is used for validation purposes.",
+                max_length=255,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="credential",
+            name="verify_uuid",
+            field=models.UUIDField(
+                default=uuid.uuid4,
+                editable=False,
+                help_text="UUID used for verifying the credential",
+            ),
+        ),
+    ]