learning-credentials 0.3.0rc4__tar.gz → 0.3.1rc1__tar.gz

{learning_credentials-0.3.0rc4 → learning_credentials-0.3.1rc1}/CHANGELOG.rst

@@ -16,6 +16,38 @@ Unreleased
 
 *
 
+0.3.1 - 2025-12-15
+******************
+
+Added
+=====
+
+* 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.
+
+Modified
+========
+
+* Replaced ``template_two_lines`` with ``template_multiline``.
+
+0.3.0 - 2025-09-17
+******************
+
+Added
+=====
+
+* REST API endpoint to check if credentials are configured for a learning context.
+
+0.2.4 - 2025-09-07
+
+Added
+=====
+
+* Option to customize the learner's name size on the PDF certificate.
+
 0.2.3 - 2025-08-18
 
 Modified

{learning_credentials-0.3.0rc4 → learning_credentials-0.3.1rc1}/MANIFEST.in

@@ -1,6 +1,4 @@
 include CHANGELOG.rst
 include LICENSE.txt
 include README.rst
-include requirements/base.in
-include requirements/constraints.txt
 recursive-include learning_credentials *.html *.png *.gif *.js *.css *.jpg *.jpeg *.svg *.txt

{learning_credentials-0.3.0rc4/learning_credentials.egg-info → learning_credentials-0.3.1rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learning-credentials
-Version: 0.3.0rc4
+Version: 0.3.1rc1
 Summary: A pluggable service for preparing Open edX credentials.
 Author-email: OpenCraft <help@opencraft.com>
 License-Expression: AGPL-3.0-or-later
@@ -21,6 +21,8 @@ Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 Requires-Dist: django
 Requires-Dist: django-model-utils
+Requires-Dist: edx-api-doc-tools
+Requires-Dist: edx-django-utils
 Requires-Dist: edx-opaque-keys
 Requires-Dist: celery
 Requires-Dist: django-celery-beat
@@ -31,7 +33,6 @@ Requires-Dist: pypdf
 Requires-Dist: reportlab
 Requires-Dist: openedx-completion-aggregator
 Requires-Dist: edx_ace
-Requires-Dist: edx-api-doc-tools
 Requires-Dist: learning-paths-plugin>=0.3.4
 Dynamic: license-file
 
@@ -123,7 +124,7 @@ file in this repo.
 Reporting Security Issues
 *************************
 
-Please do not report security issues in public. Please email security@openedx.org.
+Please do not report security issues in public. Please email help@opencraft.com.
 
 .. |pypi-badge| image:: https://img.shields.io/pypi/v/learning-credentials.svg
     :target: https://pypi.python.org/pypi/learning-credentials/
@@ -175,6 +176,38 @@ Unreleased
 
 *
 
+0.3.1 - 2025-12-15
+******************
+
+Added
+=====
+
+* 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.
+
+Modified
+========
+
+* Replaced ``template_two_lines`` with ``template_multiline``.
+
+0.3.0 - 2025-09-17
+******************
+
+Added
+=====
+
+* REST API endpoint to check if credentials are configured for a learning context.
+
+0.2.4 - 2025-09-07
+
+Added
+=====
+
+* Option to customize the learner's name size on the PDF certificate.
+
 0.2.3 - 2025-08-18
 
 Modified

{learning_credentials-0.3.0rc4 → learning_credentials-0.3.1rc1}/README.rst

@@ -86,7 +86,7 @@ file in this repo.
 Reporting Security Issues
 *************************
 
-Please do not report security issues in public. Please email security@openedx.org.
+Please do not report security issues in public. Please email help@opencraft.com.
 
 .. |pypi-badge| image:: https://img.shields.io/pypi/v/learning-credentials.svg
     :target: https://pypi.python.org/pypi/learning-credentials/

learning_credentials-0.3.1rc1/learning_credentials/api/urls.py

@@ -0,0 +1,9 @@
+"""API URLs."""
+
+from django.urls import include, path
+
+from .v1 import urls as v1_urls
+
+urlpatterns = [
+    path("v1/", include((v1_urls, "learning_credentials_api_v1"), namespace="learning_credentials_api_v1")),
+]

learning_credentials-0.3.1rc1/learning_credentials/api/v1/permissions.py

@@ -0,0 +1,81 @@
+"""Django REST framework permissions."""
+
+from typing import TYPE_CHECKING
+
+from django.db.models import Q
+from learning_paths.models import LearningPath
+from opaque_keys import InvalidKeyError
+from opaque_keys.edx.keys import LearningContextKey
+from rest_framework.exceptions import NotFound, ParseError
+from rest_framework.permissions import BasePermission
+
+from learning_credentials.compat import get_course_enrollments
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User
+    from learning_paths.keys import LearningPathKey
+    from opaque_keys.edx.keys import CourseKey
+    from rest_framework.request import Request
+    from rest_framework.views import APIView
+
+
+class CanAccessLearningContext(BasePermission):
+    """Permission to allow access to learning context if the user is enrolled."""
+
+    def has_permission(self, request: "Request", view: "APIView") -> bool:
+        """Check if the user can access the learning context."""
+        try:
+            key = view.kwargs.get("learning_context_key") or request.query_params.get("learning_context_key")
+            learning_context_key = LearningContextKey.from_string(key)
+        except InvalidKeyError as e:
+            msg = "Invalid learning context key."
+            raise ParseError(msg) from e
+
+        if request.user.is_staff:
+            return True
+
+        if learning_context_key.is_course:
+            if self._can_access_course(learning_context_key, request.user):
+                return True
+
+            msg = "Course not found or user does not have access."
+            raise NotFound(msg)
+
+        # For learning paths, check enrollment or if it's not invite-only.
+        if self._can_access_learning_path(learning_context_key, request.user):
+            return True
+
+        msg = "Learning path not found or user does not have access."
+        raise NotFound(msg)
+
+    def _can_access_course(self, course_key: "CourseKey", user: "User") -> bool:
+        """Check if user can access a course."""
+        # Check if user is enrolled in the course.
+        if get_course_enrollments(course_key, user.id):  # ty: ignore[unresolved-attribute]
+            return True
+
+        # Check if the course is a part of a learning path the user can access.
+        return self._can_access_course_via_learning_path(course_key, user)
+
+    def _get_accessible_learning_paths_filter(self, user: "User") -> Q:
+        """Get Q filter for learning paths that the user can access."""
+        return Q(invite_only=False) | Q(learningpathenrollment__user=user, learningpathenrollment__is_active=True)
+
+    def _can_access_course_via_learning_path(self, course_key: "CourseKey", user: "User") -> bool:
+        """Check if user can access a course through learning path membership."""
+        accessible_paths = (
+            LearningPath.objects.filter(steps__course_key=course_key)
+            .filter(self._get_accessible_learning_paths_filter(user))
+            .distinct()
+        )
+
+        return accessible_paths.exists()
+
+    def _can_access_learning_path(self, learning_path_key: "LearningPathKey", user: "User") -> bool:
+        """Check if user can access a learning path."""
+        # Single query to check if learning path exists and user can access it
+        accessible_path = LearningPath.objects.filter(key=learning_path_key).filter(
+            self._get_accessible_learning_paths_filter(user)
+        )
+
+        return accessible_path.exists()

learning_credentials-0.3.1rc1/learning_credentials/api/v1/urls.py

@@ -0,0 +1,13 @@
+"""API v1 URLs."""
+
+from django.urls import path
+
+from .views import CredentialConfigurationCheckView
+
+urlpatterns = [
+    path(
+        'configured/<str:learning_context_key>/',
+        CredentialConfigurationCheckView.as_view(),
+        name='credential_configuration_check',
+    ),
+]

learning_credentials-0.3.1rc1/learning_credentials/api/v1/views.py

@@ -0,0 +1,83 @@
+"""API views for Learning Credentials."""
+
+from typing import TYPE_CHECKING
+
+import edx_api_doc_tools as apidocs
+from edx_api_doc_tools import ParameterLocation
+from rest_framework import status
+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 .permissions import CanAccessLearningContext
+
+if TYPE_CHECKING:
+    from rest_framework.request import Request
+
+
+class CredentialConfigurationCheckView(APIView):
+    """API view to check if any credentials are configured for a specific learning context."""
+
+    permission_classes = (IsAuthenticated, CanAccessLearningContext)
+
+    @apidocs.schema(
+        parameters=[
+            apidocs.string_parameter(
+                "learning_context_key",
+                ParameterLocation.PATH,
+                description=(
+                    "Learning context identifier. Can be a course key (course-v1:OpenedX+DemoX+DemoCourse) "
+                    "or learning path key (path-v1:OpenedX+DemoX+DemoPath+Demo)"
+                ),
+            ),
+        ],
+        responses={
+            200: "Boolean indicating if credentials are configured.",
+            400: "Invalid context key format.",
+            403: "User is not authenticated or does not have permission to access the learning context.",
+            404: "Learning context not found or user does not have access.",
+        },
+    )
+    def get(self, _request: "Request", learning_context_key: str) -> Response:
+        """
+        Check if any credentials are configured for the given learning context.
+
+        **Example Request**
+
+        ``GET /api/learning_credentials/v1/configured/course-v1:OpenedX+DemoX+DemoCourse/``
+
+        **Response Values**
+
+        - **200 OK**: Request successful, returns credential configuration status.
+        - **400 Bad Request**: Invalid learning context key format.
+        - **403 Forbidden**: User is not authenticated or does not have permission to access the learning context.
+        - **404 Not Found**: Learning context not found or user does not have access.
+
+        **Example Response**
+
+        .. code-block:: json
+
+            {
+              "has_credentials": true,
+              "credential_count": 2
+            }
+
+        **Response Fields**
+
+        - ``has_credentials``: Boolean indicating if any credentials are configured
+        - ``credential_count``: Number of credential configurations available
+
+        **Note**
+
+        This endpoint does not perform learning context existence validation, so it will not return 404 for staff users.
+        """
+        credential_count = CredentialConfiguration.objects.filter(learning_context_key=learning_context_key).count()
+
+        response_data = {
+            'has_credentials': credential_count > 0,
+            'credential_count': credential_count,
+        }
+
+        return Response(response_data, status=status.HTTP_200_OK)

{learning_credentials-0.3.0rc4 → learning_credentials-0.3.1rc1}/learning_credentials/apps.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import ClassVar
 
 from django.apps import AppConfig
+from edx_django_utils.plugins.constants import PluginSettings, PluginURLs
 
 
 class LearningCredentialsConfig(AppConfig):
@@ -15,20 +16,16 @@ class LearningCredentialsConfig(AppConfig):
 
     # 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]]] = {
-        'url_config': {
+        PluginURLs.CONFIG: {
             'lms.djangoapp': {
-                'namespace': 'learning_credentials',
-                'app_name': 'learning_credentials',
+                PluginURLs.NAMESPACE: name,
+                PluginURLs.APP_NAME: name,
             }
         },
-        'settings_config': {
+        PluginSettings.CONFIG: {
             'lms.djangoapp': {
-                'common': {'relative_path': 'settings.common'},
-                'production': {'relative_path': 'settings.production'},
+                'common': {PluginSettings.RELATIVE_PATH: 'settings.common'},
+                'production': {PluginSettings.RELATIVE_PATH: 'settings.production'},
             },
-            # 'cms.djangoapp': {
-            #     'common': {'relative_path': 'settings.common'},
-            #     'production': {'relative_path': 'settings.production'},
-            # },
         },
     }

{learning_credentials-0.3.0rc4 → learning_credentials-0.3.1rc1}/learning_credentials/compat.py

@@ -52,10 +52,13 @@ def get_course_grading_policy(course_id: CourseKey) -> dict:
 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
+    from openedx.core.djangoapps.content.course_overviews.api import get_course_overview_or_none
 
-    course_outline = get_course_outline(course_id)
-    return (course_outline and course_outline.title) or str(course_id)
+    name = str(course_id)
+    if course_overview := get_course_overview_or_none(course_id):
+        name = course_overview.cert_name_long or course_overview.display_name or name
+
+    return name
 
 
 def _get_learning_path_name(learning_path_key: LearningPathKey) -> str:
@@ -74,13 +77,7 @@ def get_learning_context_name(learning_context_key: LearningContextKey) -> str:
 
 
 def get_course_enrollments(course_id: CourseKey, user_id: int | None = None) -> list[User]:
-    """
-    Get the course enrollments from Open edX.
-
-    :param course_id: The course ID.
-    :param user_id: Optional. If provided, will filter the enrollments by user.
-    :return: A list of users enrolled in the course.
-    """
+    """Get the course enrollments from Open edX."""
     # noinspection PyUnresolvedReferences,PyPackageRequirements
     from common.djangoapps.student.models import CourseEnrollment
 

{learning_credentials-0.3.0rc4 → learning_credentials-0.3.1rc1}/learning_credentials/generators.py

@@ -19,9 +19,9 @@ 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 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
@@ -33,6 +33,7 @@ if TYPE_CHECKING:  # pragma: no cover
 
     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:
@@ -45,25 +46,29 @@ def _get_user_name(user: User) -> str:
     return user.profile.name or f"{user.first_name} {user.last_name}"
 
 
-def _register_font(options: dict[str, Any]) -> str:
+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 options: A dictionary containing the font.
-    :returns: The font name.
+    :param font_name: The name of the font to register.
+    :returns: The font name if registered successfully, otherwise None.
     """
-    if font := options.get('font'):
-        pdfmetrics.registerFont(TTFont(font, CredentialAsset.get_asset_by_slug(font)))
+    if not font_name:
+        return None
 
-    return font or 'Helvetica'
+    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: any, font: str, username: str, context_name: str, options: dict[str, Any]) -> any:
+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 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.
@@ -86,20 +91,26 @@ def _write_text_on_template(template: any, font: str, username: str, context_nam
         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))
+    pdf_canvas = Canvas(io.BytesIO(), pagesize=(template_width, template_height))
+    font = _register_font(options.get('font')) or 'Helvetica'
 
     # Write the learner name.
-    # TODO: Add tests.
-    pdf_canvas.setFont(font, options.get('name_size', 32))
+    if options.get('name_uppercase', getattr(settings, 'LEARNING_CREDENTIALS_NAME_UPPERCASE', False)):
+        username = username.upper()
+
+    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.
-    pdf_canvas.setFont(font, options.get('context_name_size', 28))
+    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))
 
@@ -114,13 +125,22 @@ def _write_text_on_template(template: any, font: str, username: str, context_nam
 
     # Write the issue date.
     issue_date = get_localized_credential_date()
-    pdf_canvas.setFont(font, 12)
+    if options.get('issue_date_uppercase', getattr(settings, 'LEARNING_CREDENTIALS_ISSUE_DATE_UPPERCASE', False)):
+        issue_date = issue_date.upper()
+
+    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)
+
+    issue_date_char_space = options.get(
+        'issue_date_char_space', getattr(settings, 'LEARNING_CREDENTIALS_ISSUE_DATE_CHAR_SPACE', 0)
+    )
+
+    pdf_canvas.drawString(issue_date_x, issue_date_y, issue_date, charSpace=issue_date_char_space)
 
     return pdf_canvas
 
@@ -169,7 +189,7 @@ def generate_pdf_credential(
     credential_uuid: UUID,
     options: dict[str, Any],
 ) -> str:
-    """
+    r"""
     Generate a PDF credential.
 
     :param learning_context_key: The ID of the course or learning path the credential is for.
@@ -180,33 +200,48 @@ def generate_pdf_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.
+      - template_multiline: The path to the PDF template file for multiline context names.
+        A multiline context name is specified by using '\n' or ';' 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.
-      - context_name: Specify the custom course or Learning Path name.
+      - name_font: The font of the name on the credential. It overrides the `font` option.
+      - name_uppercase: If set to true (without quotes), the name will be converted to uppercase.
+        The default value is False, unless specified otherwise in the instance settings.
+      - 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.
+      - issue_date_char_space: The character spacing of the issue date on the credential
+        (default is 0.0, unless specified otherwise in the instance settings).
+      - issue_date_uppercase: If set to true (without quotes), the issue date will be converted to uppercase.
+        The default value is False, unless specified otherwise in the instance settings.
     """
     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)
+    template_path = options.get('template')
 
-    # 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'])
+    # Handle multiline context name (we support semicolon as a separator to preserve backward compatibility).
+    context_name = context_name.replace(';', '\n').replace(r'\n', '\n')
+    if '\n' in context_name:
+        # `template_two_lines` is kept for backward compatibility.
+        template_path = options.get('template_multiline', options.get('template_two_lines', template_path))
+
+    if not template_path:
+        msg = "Template path must be specified in options."
+        raise ValueError(msg)
 
-    font = _register_font(options)
+    # Get template from the CredentialAsset.
+    template_file = CredentialAsset.get_asset_by_slug(template_path)
 
     # Load the PDF template.
     with template_file.open('rb') as template_file:
@@ -215,7 +250,7 @@ def generate_pdf_credential(
         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)
+        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])