learning-credentials 0.2.2rc2__py3-none-any.whl

learning_credentials/generators.py

@@ -0,0 +1,225 @@
+"""
+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, 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()
+    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).
+      - context_name_size: The font size of the context name on the credential. The default value is 28.
+      - 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

learning_credentials/migrations/0001_initial.py

@@ -0,0 +1,205 @@
+from django.db import migrations, models
+import django.utils.timezone
+import jsonfield.fields
+import model_utils.fields
+import opaque_keys.edx.django.models
+import uuid
+
+import learning_credentials.models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('django_celery_beat', '0019_alter_periodictasks_options'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ExternalCertificateAsset',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                (
+                    'created',
+                    model_utils.fields.AutoCreatedField(
+                        default=django.utils.timezone.now, editable=False, verbose_name='created'
+                    ),
+                ),
+                (
+                    'modified',
+                    model_utils.fields.AutoLastModifiedField(
+                        default=django.utils.timezone.now, editable=False, verbose_name='modified'
+                    ),
+                ),
+                ('description', models.CharField(blank=True, help_text='Description of the asset.', max_length=255)),
+                (
+                    'asset',
+                    models.FileField(
+                        help_text='Asset file. It could be a PDF template, image or font file.',
+                        max_length=255,
+                        upload_to=learning_credentials.models.CredentialAsset.template_assets_path,
+                    ),
+                ),
+                (
+                    'asset_slug',
+                    models.SlugField(
+                        help_text="Asset's unique slug. We can reference the asset in templates using this value.",
+                        max_length=255,
+                        unique=True,
+                    ),
+                ),
+            ],
+            options={
+                'get_latest_by': 'created',
+            },
+        ),
+        migrations.CreateModel(
+            name='ExternalCertificateType',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                (
+                    'created',
+                    model_utils.fields.AutoCreatedField(
+                        default=django.utils.timezone.now, editable=False, verbose_name='created'
+                    ),
+                ),
+                (
+                    'modified',
+                    model_utils.fields.AutoLastModifiedField(
+                        default=django.utils.timezone.now, editable=False, verbose_name='modified'
+                    ),
+                ),
+                ('name', models.CharField(help_text='Name of the certificate type.', max_length=255, unique=True)),
+                (
+                    'retrieval_func',
+                    models.CharField(help_text='A name of the function to retrieve eligible users.', max_length=200),
+                ),
+                (
+                    'generation_func',
+                    models.CharField(help_text='A name of the function to generate certificates.', max_length=200),
+                ),
+                (
+                    'custom_options',
+                    jsonfield.fields.JSONField(blank=True, default=dict, help_text='Custom options for the functions.'),
+                ),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='ExternalCertificate',
+            fields=[
+                (
+                    'created',
+                    model_utils.fields.AutoCreatedField(
+                        default=django.utils.timezone.now, editable=False, verbose_name='created'
+                    ),
+                ),
+                (
+                    'modified',
+                    model_utils.fields.AutoLastModifiedField(
+                        default=django.utils.timezone.now, editable=False, verbose_name='modified'
+                    ),
+                ),
+                (
+                    'uuid',
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        help_text='Auto-generated UUID of the certificate',
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ('user_id', models.IntegerField(help_text='ID of the user receiving the certificate')),
+                ('user_full_name', models.CharField(help_text='User receiving the certificate', max_length=255)),
+                (
+                    'course_id',
+                    opaque_keys.edx.django.models.CourseKeyField(
+                        help_text='ID of a course for which the certificate was issued', max_length=255
+                    ),
+                ),
+                ('certificate_type', models.CharField(help_text='Type of the certificate', max_length=255)),
+                (
+                    'status',
+                    models.CharField(
+                        choices=[
+                            ('generating', 'Generating'),
+                            ('available', 'Available'),
+                            ('error', 'Error'),
+                            ('invalidated', 'Invalidated'),
+                        ],
+                        default='generating',
+                        help_text='Status of the certificate generation task',
+                        max_length=32,
+                    ),
+                ),
+                (
+                    'download_url',
+                    models.URLField(blank=True, help_text='URL of the generated certificate PDF (e.g., to S3)'),
+                ),
+                (
+                    'legacy_id',
+                    models.IntegerField(
+                        help_text='Legacy ID of the certificate imported from another system', null=True
+                    ),
+                ),
+                ('generation_task_id', models.CharField(help_text='Task ID from the Celery queue', max_length=255)),
+            ],
+            options={
+                'unique_together': {('user_id', 'course_id', 'certificate_type')},
+            },
+        ),
+        migrations.CreateModel(
+            name='ExternalCertificateCourseConfiguration',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                (
+                    'created',
+                    model_utils.fields.AutoCreatedField(
+                        default=django.utils.timezone.now, editable=False, verbose_name='created'
+                    ),
+                ),
+                (
+                    'modified',
+                    model_utils.fields.AutoLastModifiedField(
+                        default=django.utils.timezone.now, editable=False, verbose_name='modified'
+                    ),
+                ),
+                (
+                    'course_id',
+                    opaque_keys.edx.django.models.CourseKeyField(help_text='The ID of the course.', max_length=255),
+                ),
+                (
+                    'custom_options',
+                    jsonfield.fields.JSONField(
+                        blank=True,
+                        default=dict,
+                        help_text='Custom options for the functions. If specified, they are merged with the options defined in the certificate type.',
+                    ),
+                ),
+                (
+                    'certificate_type',
+                    models.ForeignKey(
+                        help_text='Associated certificate type.',
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to='learning_credentials.externalcertificatetype',
+                    ),
+                ),
+                (
+                    'periodic_task',
+                    models.OneToOneField(
+                        help_text='Associated periodic task.',
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to='django_celery_beat.periodictask',
+                    ),
+                ),
+            ],
+            options={
+                'unique_together': {('course_id', 'certificate_type')},
+            },
+        ),
+    ]

learning_credentials/migrations/0002_migrate_to_learning_credentials.py

@@ -0,0 +1,40 @@
+from django.db import migrations
+
+
+def migrate_data_if_tables_exist(apps, schema_editor):
+    """Migrate data from openedx_certificates to learning_credentials tables if the source tables exist."""
+    connection = schema_editor.connection
+    cursor = connection.cursor()
+    table_names = connection.introspection.table_names(cursor)
+
+    tables_to_migrate = [
+        (
+            "openedx_certificates_externalcertificatetype",
+            "learning_credentials_externalcertificatetype",
+            "id, created, modified, name, retrieval_func, generation_func, custom_options",
+        ),
+        (
+            "openedx_certificates_externalcertificatecourseconfiguration",
+            "learning_credentials_externalcertificatecourseconfiguration",
+            "id, created, modified, course_id, custom_options, certificate_type_id, periodic_task_id",
+        ),
+        (
+            "openedx_certificates_externalcertificateasset",
+            "learning_credentials_externalcertificateasset",
+            "id, created, modified, description, asset, asset_slug",
+        ),
+        (
+            "openedx_certificates_externalcertificate",
+            "learning_credentials_externalcertificate",
+            "uuid, created, modified, user_id, user_full_name, course_id, certificate_type, status, download_url, legacy_id, generation_task_id",
+        ),
+    ]
+
+    for source_table, target_table, fields in tables_to_migrate:
+        if source_table in table_names:
+            cursor.execute(f"INSERT INTO {target_table} ({fields}) SELECT {fields} FROM {source_table};")
+
+
+class Migration(migrations.Migration):
+    dependencies = [("learning_credentials", "0001_initial")]
+    operations = [migrations.RunPython(migrate_data_if_tables_exist, migrations.RunPython.noop)]

learning_credentials/migrations/0003_rename_certificates_to_credentials.py

@@ -0,0 +1,128 @@
+from django.db import migrations, models
+import django.utils.timezone
+import jsonfield.fields
+import opaque_keys.edx.django.models
+import uuid
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('django_celery_beat', '0019_alter_periodictasks_options'),
+        ('learning_credentials', '0002_migrate_to_learning_credentials'),
+    ]
+
+    operations = [
+        migrations.RenameModel(
+            old_name='ExternalCertificateCourseConfiguration',
+            new_name='CredentialConfiguration',
+        ),
+        migrations.RenameModel(
+            old_name='ExternalCertificateAsset',
+            new_name='CredentialAsset',
+        ),
+        migrations.RenameModel(
+            old_name='ExternalCertificateType',
+            new_name='CredentialType',
+        ),
+        migrations.RenameModel(
+            old_name='ExternalCertificate',
+            new_name='Credential',
+        ),
+        migrations.RenameField(
+            model_name='Credential',
+            old_name='certificate_type',
+            new_name='credential_type',
+        ),
+        migrations.RenameField(
+            model_name='CredentialConfiguration',
+            old_name='certificate_type',
+            new_name='credential_type',
+        ),
+        migrations.AlterField(
+            model_name='credential',
+            name='course_id',
+            field=opaque_keys.edx.django.models.CourseKeyField(
+                help_text='ID of a course for which the credential was issued', max_length=255
+            ),
+        ),
+        migrations.AlterField(
+            model_name='credential',
+            name='credential_type',
+            field=models.CharField(help_text='Type of the credential', max_length=255),
+        ),
+        migrations.AlterField(
+            model_name='credential',
+            name='download_url',
+            field=models.URLField(blank=True, help_text='URL of the generated credential PDF (e.g., to S3)'),
+        ),
+        migrations.AlterField(
+            model_name='credential',
+            name='legacy_id',
+            field=models.IntegerField(help_text='Legacy ID of the credential imported from another system', null=True),
+        ),
+        migrations.AlterField(
+            model_name='credential',
+            name='status',
+            field=models.CharField(
+                choices=[
+                    ('generating', 'Generating'),
+                    ('available', 'Available'),
+                    ('error', 'Error'),
+                    ('invalidated', 'Invalidated'),
+                ],
+                default='generating',
+                help_text='Status of the credential generation task',
+                max_length=32,
+            ),
+        ),
+        migrations.AlterField(
+            model_name='credential',
+            name='user_full_name',
+            field=models.CharField(help_text='User receiving the credential', max_length=255),
+        ),
+        migrations.AlterField(
+            model_name='credential',
+            name='user_id',
+            field=models.IntegerField(help_text='ID of the user receiving the credential'),
+        ),
+        migrations.AlterField(
+            model_name='credential',
+            name='uuid',
+            field=models.UUIDField(
+                default=uuid.uuid4,
+                editable=False,
+                help_text='Auto-generated UUID of the credential',
+                primary_key=True,
+                serialize=False,
+            ),
+        ),
+        migrations.AlterField(
+            model_name='credentialconfiguration',
+            name='credential_type',
+            field=models.ForeignKey(
+                help_text='Associated credential type.',
+                on_delete=django.db.models.deletion.CASCADE,
+                to='learning_credentials.credentialtype',
+            ),
+        ),
+        migrations.AlterField(
+            model_name='credentialconfiguration',
+            name='custom_options',
+            field=jsonfield.fields.JSONField(
+                blank=True,
+                default=dict,
+                help_text='Custom options for the functions. If specified, they are merged with the options defined in the credential type.',
+            ),
+        ),
+        migrations.AlterField(
+            model_name='credentialtype',
+            name='generation_func',
+            field=models.CharField(help_text='A name of the function to generate credentials.', max_length=200),
+        ),
+        migrations.AlterField(
+            model_name='credentialtype',
+            name='name',
+            field=models.CharField(help_text='Name of the credential type.', max_length=255, unique=True),
+        ),
+    ]

learning_credentials/migrations/0004_replace_course_keys_with_learning_context_keys.py

@@ -0,0 +1,59 @@
+# Generated by Django 4.2.20 on 2025-03-27 17:36
+
+from django.db import migrations
+import opaque_keys.edx.django.models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('learning_credentials', '0003_rename_certificates_to_credentials'),
+    ]
+
+    operations = [
+        migrations.AlterUniqueTogether(
+            name='credential',
+            unique_together=set(),
+        ),
+        migrations.AlterUniqueTogether(
+            name='credentialconfiguration',
+            unique_together=set(),
+        ),
+
+        migrations.RenameField(
+            model_name='credential',
+            old_name='course_id',
+            new_name='learning_context_key',
+        ),
+        migrations.RenameField(
+            model_name='credentialconfiguration',
+            old_name='course_id',
+            new_name='learning_context_key',
+        ),
+
+        migrations.AlterField(
+            model_name='credential',
+            name='learning_context_key',
+            field=opaque_keys.edx.django.models.LearningContextKeyField(
+                help_text='ID of a learning context (e.g., a course or a Learning Path) for which the credential was issued',
+                max_length=255
+            ),
+        ),
+        migrations.AlterField(
+            model_name='credentialconfiguration',
+            name='learning_context_key',
+            field=opaque_keys.edx.django.models.LearningContextKeyField(
+                help_text='ID of a learning context (e.g., a course or a Learning Path).',
+                max_length=255
+            ),
+        ),
+
+        migrations.AlterUniqueTogether(
+            name='credential',
+            unique_together={('user_id', 'learning_context_key', 'credential_type')},
+        ),
+        migrations.AlterUniqueTogether(
+            name='credentialconfiguration',
+            unique_together={('learning_context_key', 'credential_type')},
+        ),
+    ]