learning-credentials 0.5.0rc4__tar.gz → 0.5.1__tar.gz

{learning_credentials-0.5.0rc4 → learning_credentials-0.5.1}/CHANGELOG.rst

@@ -16,14 +16,46 @@ Unreleased
 
 *
 
+0.5.1 - 2026-03-17
+******************
+
+Added
+=====
+
+* Credential eligibility check endpoint (``GET /api/learning_credentials/v1/eligibility/<learning_context_key>/``)
+  with detailed progress information.
+
+Changed
+=======
+
+* Processor functions now return ``dict[int, dict[str, Any]]`` with detailed eligibility information instead of ``list[int]`` of eligible user IDs.
+* Processor functions now accept an optional ``user_id`` parameter for single-user eligibility checks.
+
 0.5.0 - 2026-01-29
 ******************
 
 Added
 =====
 
-* Frontend form and backend API endpoint for verifying credentials.
-* Option to invalidate issued credentials.
+* Credential validation and invalidation system with ``INVALIDATED`` status.
+* ``verify_uuid`` field on credentials — a separate UUID used for third-party verification, distinct from the primary key.
+* ``invalidated_at`` timestamp and ``invalidation_reason`` fields on the ``Credential`` model.
+* ``learning_context_name`` cached field on credentials for use in validation display.
+* Public API endpoint (``/api/learning_credentials/v1/metadata/<uuid>/``) to retrieve credential metadata by verification UUID.
+* "Reissue credential" admin action that invalidates the current credential and generates a new one.
+* ``{verify_uuid}`` placeholder support in PDF text elements.
+* Admin test suite (``test_admin.py``) and included it in test coverage.
+
+Changed
+=======
+
+* Replaced ``user_id`` (IntegerField) with a ``user`` ForeignKey to the User model.
+* Added ``configuration`` ForeignKey on ``Credential`` linking to ``CredentialConfiguration``, replacing ``credential_type`` and ``learning_context_key`` lookups.
+* Simplified ``generate_pdf_credential()`` signature to accept a ``Credential`` object instead of separate parameters.
+* Changed the PDF output directory from hardcoded ``external_certificates/`` to the configurable ``LEARNING_CREDENTIALS_OUTPUT_DIR`` setting.
+* Credential issue date on PDFs now uses the credential's creation date instead of the current time.
+* ``get_localized_credential_date()`` now accepts an explicit ``datetime`` parameter.
+* Disabled add and delete permissions for credentials in the Django admin.
 
 0.4.0 - 2026-01-28
 ******************

{learning_credentials-0.5.0rc4/learning_credentials.egg-info → learning_credentials-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learning-credentials
-Version: 0.5.0rc4
+Version: 0.5.1
 Summary: A pluggable service for preparing Open edX credentials.
 Author-email: OpenCraft <help@opencraft.com>
 License-Expression: AGPL-3.0-or-later
@@ -177,14 +177,46 @@ Unreleased
 
 *
 
+0.5.1 - 2026-03-17
+******************
+
+Added
+=====
+
+* Credential eligibility check endpoint (``GET /api/learning_credentials/v1/eligibility/<learning_context_key>/``)
+  with detailed progress information.
+
+Changed
+=======
+
+* Processor functions now return ``dict[int, dict[str, Any]]`` with detailed eligibility information instead of ``list[int]`` of eligible user IDs.
+* Processor functions now accept an optional ``user_id`` parameter for single-user eligibility checks.
+
 0.5.0 - 2026-01-29
 ******************
 
 Added
 =====
 
-* Frontend form and backend API endpoint for verifying credentials.
-* Option to invalidate issued credentials.
+* Credential validation and invalidation system with ``INVALIDATED`` status.
+* ``verify_uuid`` field on credentials — a separate UUID used for third-party verification, distinct from the primary key.
+* ``invalidated_at`` timestamp and ``invalidation_reason`` fields on the ``Credential`` model.
+* ``learning_context_name`` cached field on credentials for use in validation display.
+* Public API endpoint (``/api/learning_credentials/v1/metadata/<uuid>/``) to retrieve credential metadata by verification UUID.
+* "Reissue credential" admin action that invalidates the current credential and generates a new one.
+* ``{verify_uuid}`` placeholder support in PDF text elements.
+* Admin test suite (``test_admin.py``) and included it in test coverage.
+
+Changed
+=======
+
+* Replaced ``user_id`` (IntegerField) with a ``user`` ForeignKey to the User model.
+* Added ``configuration`` ForeignKey on ``Credential`` linking to ``CredentialConfiguration``, replacing ``credential_type`` and ``learning_context_key`` lookups.
+* Simplified ``generate_pdf_credential()`` signature to accept a ``Credential`` object instead of separate parameters.
+* Changed the PDF output directory from hardcoded ``external_certificates/`` to the configurable ``LEARNING_CREDENTIALS_OUTPUT_DIR`` setting.
+* Credential issue date on PDFs now uses the credential's creation date instead of the current time.
+* ``get_localized_credential_date()`` now accepts an explicit ``datetime`` parameter.
+* Disabled add and delete permissions for credentials in the Django admin.
 
 0.4.0 - 2026-01-28
 ******************

{learning_credentials-0.5.0rc4 → learning_credentials-0.5.1}/learning_credentials/admin.py

@@ -27,7 +27,7 @@ from .models import (
 )
 from .tasks import generate_credentials_for_config_task
 
-if TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:
     from collections.abc import Generator
 
     from django.http import HttpRequest
@@ -177,7 +177,7 @@ class CredentialConfigurationAdmin(DjangoObjectActions, ReverseModelAdmin):
     ]
     list_display = ('learning_context_key', 'credential_type', 'enabled', 'interval')
     search_fields = ('learning_context_key', 'credential_type__name')
-    list_filter = ('learning_context_key', 'credential_type')
+    list_filter = ('learning_context_key', 'credential_type', 'periodic_task__enabled')
 
     def get_inline_instances(
         self,
@@ -263,14 +263,12 @@ class CredentialAdmin(DjangoObjectActions, admin.ModelAdmin):  # noqa: D101
     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_change_actions(self, request: HttpRequest, object_id: str, form_url: str) -> list[str]:
+        """Hide the reissue button when the credential is already invalidated."""
+        actions = list(super().get_change_actions(request, object_id, form_url))
+        if self.model.objects.filter(pk=object_id, status=Credential.Status.INVALIDATED).exists():
+            actions.remove('reissue_credential')
+        return actions
 
     def get_form(self, request: HttpRequest, obj: Credential | None = None, **kwargs) -> forms.ModelForm:
         """Hide the download_url field."""

{learning_credentials-0.5.0rc4 → learning_credentials-0.5.1}/learning_credentials/api/v1/permissions.py

@@ -19,6 +19,23 @@ if TYPE_CHECKING:
     from rest_framework.views import APIView
 
 
+class IsAdminOrSelf(BasePermission):
+    """
+    Permission to allow only admins or the user themselves to access the API.
+
+    Non-staff users cannot pass a ``username`` that is not their own.
+    """
+
+    def has_permission(self, request: "Request", view: "APIView") -> bool:  # noqa: ARG002
+        """Check if the user is admin or accessing their own data."""
+        if request.user.is_staff:
+            return True
+
+        if username := request.query_params.get("username"):
+            return request.user.username == username
+        return True
+
+
 class CanAccessLearningContext(BasePermission):
     """Permission to allow access to learning context if the user is enrolled."""
 

learning_credentials-0.5.1/learning_credentials/api/v1/serializers.py

@@ -0,0 +1,48 @@
+"""API serializers for learning credentials."""
+
+from typing import Any
+
+from rest_framework import serializers
+
+from learning_credentials.models import Credential
+
+
+class CredentialSerializer(serializers.ModelSerializer):
+    """Serializer that returns credential metadata (for the public verification endpoint)."""
+
+    class Meta:
+        """Serializer metadata."""
+
+        model = Credential
+        fields = ('user_full_name', 'created', 'learning_context_name', 'status', 'invalidation_reason')
+
+
+class CredentialEligibilitySerializer(serializers.Serializer):
+    """Serializer for credential eligibility information with dynamic fields."""
+
+    credential_type_id = serializers.IntegerField()
+    name = serializers.CharField()
+    is_generation_enabled = serializers.BooleanField()
+    is_eligible = serializers.BooleanField()
+    existing_credential = serializers.UUIDField(required=False, allow_null=True)
+    existing_credential_url = serializers.URLField(required=False, allow_blank=True, allow_null=True)
+
+    current_grades = serializers.DictField(required=False)
+    required_grades = serializers.DictField(required=False)
+
+    current_completion = serializers.FloatField(required=False, allow_null=True)
+    required_completion = serializers.FloatField(required=False, allow_null=True)
+
+    steps = serializers.DictField(required=False)
+
+    def to_representation(self, instance: dict) -> dict[str, Any]:
+        """Remove null/empty fields from representation."""
+        data = super().to_representation(instance)
+        return {key: value for key, value in data.items() if value is not None and value not in ({}, [])}
+
+
+class CredentialEligibilityResponseSerializer(serializers.Serializer):
+    """Serializer for the complete credential eligibility response."""
+
+    context_key = serializers.CharField()
+    credentials = CredentialEligibilitySerializer(many=True)

{learning_credentials-0.5.0rc4 → learning_credentials-0.5.1}/learning_credentials/api/v1/urls.py

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

learning_credentials-0.5.1/learning_credentials/api/v1/views.py

@@ -0,0 +1,277 @@
+"""API views for Learning Credentials."""
+
+from typing import TYPE_CHECKING
+
+import edx_api_doc_tools as apidocs
+from django.contrib.auth import get_user_model
+from django.shortcuts import get_object_or_404
+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 Credential, CredentialConfiguration
+
+from .permissions import CanAccessLearningContext, IsAdminOrSelf
+from .serializers import CredentialEligibilityResponseSerializer, CredentialSerializer
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User
+    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)
+
+
+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)
+
+
+class CredentialEligibilityView(APIView):
+    """
+    API view for credential eligibility checking and generation.
+
+    **GET**: Returns detailed eligibility info for all configured credentials in a learning context.
+
+    Staff users can operate on behalf of other users via the ``username`` parameter.
+    """
+
+    permission_classes = (IsAuthenticated, IsAdminOrSelf, CanAccessLearningContext)
+
+    def _get_eligibility_data(
+        self, user: "User", config: CredentialConfiguration, credentials_by_config_id: dict[int, Credential]
+    ) -> dict:
+        """Calculate eligibility data for a credential configuration."""
+        progress_data = config.get_user_eligibility_details(user_id=user.id)
+        existing_credential = credentials_by_config_id.get(config.id)
+
+        return {
+            'credential_type_id': config.credential_type.pk,
+            'name': config.credential_type.name,
+            'is_generation_enabled': config.periodic_task.enabled,
+            **progress_data,
+            'existing_credential': existing_credential.uuid if existing_credential else None,
+            'existing_credential_url': existing_credential.download_url if existing_credential else None,
+        }
+
+    @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)"
+                ),
+            ),
+            apidocs.string_parameter(
+                "retrieval_func",
+                ParameterLocation.QUERY,
+                description=(
+                    "Filter by credential type retrieval function "
+                    "(e.g. learning_credentials.processors.retrieve_subsection_grades)."
+                ),
+            ),
+            apidocs.string_parameter(
+                "username",
+                ParameterLocation.QUERY,
+                description=(
+                    "Operate on behalf of the specified user. "
+                    "Staff users may specify any username; non-staff users are limited to their own."
+                ),
+            ),
+        ],
+        responses={
+            200: CredentialEligibilityResponseSerializer,
+            400: "Invalid context key format.",
+            403: "User is not authenticated.",
+            404: "Learning context not found or user does not have access.",
+        },
+    )
+    def get(self, request: "Request", learning_context_key: str) -> Response:
+        """
+        Get credential eligibility for a learning context.
+
+        Returns detailed eligibility information for all configured credentials, including:
+
+        - Current grades and requirements for grade-based credentials
+        - Completion percentages for completion-based credentials
+        - Step-by-step progress for learning paths
+        - Existing credential info if already generated
+
+        **Query Parameters**
+
+        - ``username`` (staff only): View eligibility for a specific user.
+        - ``retrieval_func``: Filter by credential type retrieval function
+          (e.g. ``learning_credentials.processors.retrieve_subsection_grades``).
+
+        **Example Request**
+
+        ``GET /api/learning_credentials/v1/eligibility/course-v1:OpenedX+DemoX+DemoCourse/``
+
+        **Example Response**
+
+        .. code-block:: json
+
+            {
+              "context_key": "course-v1:OpenedX+DemoX+DemoCourse",
+              "credentials": [
+                {
+                  "credential_type_id": 1,
+                  "name": "Certificate of Achievement",
+                  "is_eligible": true,
+                  "existing_credential": null,
+                  "current_grades": {"final exam": 86, "total": 82},
+                  "required_grades": {"final exam": 65, "total": 80}
+                }
+              ]
+            }
+        """
+        username = request.query_params.get('username')
+        user = get_object_or_404(get_user_model(), username=username) if username else request.user
+
+        configurations = CredentialConfiguration.objects.filter(
+            learning_context_key=learning_context_key
+        ).select_related('credential_type', 'periodic_task')
+
+        retrieval_func = request.query_params.get('retrieval_func')
+        if retrieval_func:
+            configurations = configurations.filter(credential_type__retrieval_func=retrieval_func)
+
+        # Pre-fetch all credentials for this user and learning context to avoid N+1 queries in the loop below.
+        credentials = Credential.objects.filter(user_id=user.id, configuration__in=configurations).exclude(
+            status__in=[Credential.Status.ERROR, Credential.Status.INVALIDATED]
+        )
+        credentials_by_config_id = {credential.configuration_id: credential for credential in credentials}
+
+        eligibility_data = [
+            self._get_eligibility_data(user, config, credentials_by_config_id) for config in configurations
+        ]
+
+        response_data = {
+            'context_key': learning_context_key,
+            'credentials': eligibility_data,
+        }
+
+        serializer = CredentialEligibilityResponseSerializer(data=response_data)
+        serializer.is_valid(raise_exception=True)
+        return Response(serializer.data)

{learning_credentials-0.5.0rc4 → learning_credentials-0.5.1}/learning_credentials/generators.py

@@ -31,7 +31,7 @@ from .models import CredentialAsset
 
 log = logging.getLogger(__name__)
 
-if TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:
     from uuid import UUID
 
     from pypdf import PageObject

{learning_credentials-0.5.0rc4 → learning_credentials-0.5.1}/learning_credentials/models.py

@@ -7,7 +7,7 @@ import logging
 import uuid as uuid_lib
 from importlib import import_module
 from pathlib import Path
-from typing import TYPE_CHECKING, Self
+from typing import TYPE_CHECKING, Any, Self
 
 import jsonfield
 from django.conf import settings
@@ -26,7 +26,7 @@ from opaque_keys.edx.django.models import LearningContextKeyField
 from learning_credentials.compat import get_learning_context_name
 from learning_credentials.exceptions import AssetNotFoundError, CredentialGenerationError
 
-if TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:
     from django.core.files import File
     from django.db.models import QuerySet
 
@@ -183,11 +183,12 @@ class CredentialConfiguration(TimeStampedModel):
         filtered_user_ids_set = set(user_ids) - set(users_ids_with_credentials)
         return list(filtered_user_ids_set)
 
-    def get_eligible_user_ids(self) -> list[int]:
+    def _call_retrieval_func(self, user_id: int | None = None) -> dict[int, dict[str, Any]]:
         """
-        Get the list of eligible learners for the given course.
+        Call the retrieval function and return detailed results.
 
-        :return: A list of user IDs.
+        :param user_id: Optional. If provided, only check eligibility for this user.
+        :return: A dict mapping user IDs to their detailed progress information.
         """
         func_path = self.credential_type.retrieval_func
         module_path, func_name = func_path.rsplit('.', 1)
@@ -195,7 +196,27 @@ class CredentialConfiguration(TimeStampedModel):
         func = getattr(module, func_name)
 
         custom_options = _deep_merge(self.credential_type.custom_options, self.custom_options)
-        return func(self.learning_context_key, custom_options)
+        return func(self.learning_context_key, custom_options, user_id=user_id)
+
+    def get_eligible_user_ids(self, user_id: int | None = None) -> list[int]:
+        """
+        Get the list of eligible learners for the given learning context.
+
+        :param user_id: Optional. If provided, only check eligibility for this user.
+        :return: A list of eligible user IDs.
+        """
+        results = self._call_retrieval_func(user_id)
+        return [uid for uid, details in results.items() if details.get('is_eligible', False)]
+
+    def get_user_eligibility_details(self, user_id: int) -> dict[str, Any]:
+        """
+        Get detailed eligibility information for a specific user.
+
+        :param user_id: The user ID to check eligibility for.
+        :return: Dictionary containing eligibility details and progress information.
+        """
+        results = self._call_retrieval_func(user_id)
+        return results.get(user_id, {'is_eligible': False})
 
     def generate_credential_for_user(self, user_id: int, celery_task_id: int = 0) -> Credential:
         """