learning-credentials 0.2.3__py3-none-any.whl → 0.3.0rc1__py3-none-any.whl

learning_credentials/api/__init__.py

@@ -0,0 +1 @@
+"""Learning Credentials API package."""

learning_credentials/api/urls.py

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

learning_credentials/api/v1/__init__.py

@@ -0,0 +1 @@
+"""Learning Credentials API v1 package."""

learning_credentials/api/v1/permissions.py

@@ -0,0 +1,60 @@
+"""Django REST framework permissions."""
+
+from typing import TYPE_CHECKING
+
+from learning_paths.models import LearningPathEnrollment
+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 rest_framework.request import Request
+    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 "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
+
+        username = request.query_params.get("username") if request.method == "GET" else request.data.get("username")
+
+        # For learners, the username passed should match the logged in user.
+        if username:
+            return request.user.username == username
+        return True
+
+
+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 is enrolled in 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 learning_context_key.is_course:
+            if bool(get_course_enrollments(learning_context_key, request.user.id)):
+                return True
+            msg = "Course not found or user does not have access."
+            raise NotFound(msg)
+
+        if LearningPathEnrollment.objects.filter(learning_path__key=learning_context_key, user=request.user).exists():
+            return True
+
+        msg = "Learning path not found or user does not have access."
+        raise NotFound(msg)

learning_credentials/api/v1/serializers.py

@@ -0,0 +1,74 @@
+"""Serializers for the Learning Credentials API."""
+
+from typing import Any, ClassVar
+
+from rest_framework import serializers
+
+from learning_credentials.models import Credential
+
+
+class CredentialModelSerializer(serializers.ModelSerializer):
+    """Model serializer for Credential instances."""
+
+    credential_id = serializers.UUIDField(source='uuid', read_only=True)
+    credential_type = serializers.CharField(read_only=True)
+    context_key = serializers.CharField(source='learning_context_key', read_only=True)
+    created_date = serializers.DateTimeField(source='created', read_only=True)
+    download_url = serializers.URLField(read_only=True)
+
+    class Meta:
+        """Meta configuration for CredentialModelSerializer."""
+
+        model = Credential
+        fields: ClassVar[list[str]] = [
+            'credential_id',
+            'credential_type',
+            'context_key',
+            'status',
+            'created_date',
+            'download_url',
+        ]
+        read_only_fields: ClassVar[list[str]] = [
+            'credential_id',
+            'credential_type',
+            'context_key',
+            'status',
+            'created_date',
+            'download_url',
+        ]
+
+
+class CredentialEligibilitySerializer(serializers.Serializer):
+    """Serializer for credential eligibility information with dynamic fields."""
+
+    credential_type_id = serializers.IntegerField()
+    name = serializers.CharField()
+    is_eligible = serializers.BooleanField()
+    existing_credential = serializers.UUIDField(required=False, allow_null=True)
+    existing_credential_url = serializers.URLField(required=False, 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)
+
+
+class CredentialListResponseSerializer(serializers.Serializer):
+    """Serializer for credential list response."""
+
+    credentials = CredentialModelSerializer(many=True)

learning_credentials/api/v1/urls.py

@@ -0,0 +1,17 @@
+"""API v1 URLs."""
+
+from django.urls import path
+
+from .views import CredentialEligibilityView, CredentialListView
+
+urlpatterns = [
+    # Credential eligibility endpoints
+    path('eligibility/<str:learning_context_key>/', CredentialEligibilityView.as_view(), name='credential-eligibility'),
+    path(
+        'eligibility/<str:learning_context_key>/<int:credential_type_id>/',
+        CredentialEligibilityView.as_view(),
+        name='credential-generation',
+    ),
+    # Credential listing endpoints
+    path('credentials/', CredentialListView.as_view(), name='credential-list'),
+]

learning_credentials/api/v1/views.py

@@ -0,0 +1,357 @@
+"""API views for Learning Credentials."""
+
+import logging
+from typing import TYPE_CHECKING
+
+import edx_api_doc_tools as apidocs
+from django.contrib.auth.models import User
+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 learning_credentials.tasks import generate_credential_for_user_task
+
+from .permissions import CanAccessLearningContext, IsAdminOrSelf
+from .serializers import (
+    CredentialEligibilityResponseSerializer,
+    CredentialListResponseSerializer,
+    CredentialModelSerializer,
+)
+
+if TYPE_CHECKING:
+    from rest_framework.request import Request
+
+logger = logging.getLogger(__name__)
+
+
+class CredentialEligibilityView(APIView):
+    """
+    API view for credential eligibility and generation.
+
+    This endpoint manages credential eligibility checking and generation for users in specific learning contexts.
+
+    Supported Learning Contexts:
+    - Course keys: `course-v1:org+course+run`
+    - Learning path keys: `path-v1:org+path+run+group`
+    """
+
+    permission_classes = (IsAuthenticated, IsAdminOrSelf, CanAccessLearningContext)
+
+    def _get_eligibility_data(self, user: User, config: CredentialConfiguration) -> dict:
+        """Calculate eligibility data for a credential configuration."""
+        progress_data = config.get_user_eligibility_details(user_id=user.id)  # ty: ignore[unresolved-attribute]
+
+        existing_credential = (
+            Credential.objects.filter(
+                user_id=user.id,  # ty: ignore[unresolved-attribute]
+                learning_context_key=config.learning_context_key,
+                credential_type=config.credential_type.name,
+            )
+            .exclude(status=Credential.Status.ERROR)
+            .first()
+        )
+
+        return {
+            'credential_type_id': config.credential_type.pk,
+            'name': config.credential_type.name,
+            'is_eligible': progress_data.get('is_eligible', False),
+            'existing_credential': existing_credential.uuid if existing_credential else None,
+            'existing_credential_url': existing_credential.download_url if existing_credential else None,
+            **progress_data,
+        }
+
+    @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: 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.
+
+        Retrieve detailed eligibility information for all available credentials in a learning context.
+        This endpoint returns comprehensive progress data including:
+        - Current grades and requirements for grade-based credentials
+        - Completion percentages for completion-based credentials
+        - Step-by-step progress for learning paths
+        - Eligibility status for each credential type
+
+        **Example Request**
+
+            GET /api/learning_credentials/v1/eligibility/course-v1:OpenedX+DemoX+DemoCourse/
+
+        **Response Values**
+
+        If the request is successful, an HTTP 200 "OK" response is returned.
+
+        The response structure adapts based on credential types:
+        - Grade-based credentials include `current_grades` and `required_grades`
+        - Completion-based credentials include `current_completion` and `required_completion`
+        - Learning paths include detailed `steps` breakdown
+
+        **Example Response for Grade-based Credential**
+
+        ```json
+        {
+          "context_key": "course-v1:OpenedX+DemoX+DemoCourse",
+          "credentials": [
+            {
+              "credential_type_id": 1,
+              "name": "Certificate of Achievement",
+              "description": "",
+              "is_eligible": true,
+              "existing_credential": null,
+              "current_grades": {
+                "Final Exam": 86,
+                "Overall Grade": 82
+              },
+              "required_grades": {
+                "Final Exam": 65,
+                "Overall Grade": 80
+              }
+            }
+          ]
+        }
+        ```
+
+        **Example Response for Completion-based Credential**
+
+        ```json
+        {
+          "context_key": "course-v1:OpenedX+DemoX+DemoCourse",
+          "credentials": [
+            {
+              "credential_type_id": 2,
+              "name": "Certificate of Completion",
+              "description": "",
+              "is_eligible": false,
+              "existing_credential": null,
+              "current_completion": 74.0,
+              "required_completion": 100.0
+            }
+          ]
+        }
+        ```
+        """
+        configurations = CredentialConfiguration.objects.filter(
+            learning_context_key=learning_context_key
+        ).select_related('credential_type')
+
+        eligibility_data = [self._get_eligibility_data(request.user, config) 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)
+
+    @apidocs.schema(
+        parameters=[
+            apidocs.string_parameter(
+                "learning_context_key",
+                ParameterLocation.PATH,
+                description="Learning context identifier (e.g. course-v1:OpenedX+DemoX+DemoCourse)",
+            ),
+            apidocs.parameter(
+                "credential_type_id",
+                ParameterLocation.PATH,
+                int,
+                description="ID of the credential type to generate",
+            ),
+        ],
+        responses={
+            201: "Credential generation started.",
+            400: "User is not eligible for this credential or validation error.",
+            403: "User is not authenticated.",
+            404: "Learning context or credential type not found, or user does not have access.",
+            409: "User already has a valid credential of this type.",
+            500: "Internal server error during credential generation.",
+        },
+    )
+    def post(self, request: "Request", learning_context_key: str, credential_type_id: int) -> Response:
+        """
+        Trigger credential generation for an eligible user.
+
+        This endpoint initiates the credential generation process for a specific credential type.
+        The user must be eligible for the credential based on the configured requirements.
+
+        **Prerequisites:**
+        - User must be authenticated
+        - User must be enrolled in the course or have access to the learning path
+        - User must meet the eligibility criteria for the specific credential type
+        - User must not already have an existing valid credential of this type
+
+        **Process:**
+        1. Validates user eligibility using the configured processor function
+        2. Checks for existing credentials to prevent duplicates
+        3. Initiates asynchronous credential generation
+        4. Returns credential status and tracking information
+
+        **Notification:**
+        Users will receive an email notification when credential generation completes.
+
+        **Example Request**
+
+            POST /api/learning_credentials/v1/eligibility/course-v1:OpenedX+DemoX+DemoCourse/1/
+
+        **Response Values**
+
+        If the request is successful, an HTTP 201 "Created" response is returned.
+
+        **Example Response**
+
+        ```json
+        {
+          "status": "generating",
+          "credential_id": "123e4567-e89b-12d3-a456-426614174000",
+          "message": "Credential generation started. You will receive an email when ready."
+        }
+        ```
+        """
+        config = get_object_or_404(
+            CredentialConfiguration.objects.select_related('credential_type'),
+            learning_context_key=learning_context_key,
+            credential_type_id=credential_type_id,
+        )
+
+        existing_credential = (
+            Credential.objects.filter(
+                user_id=request.user.id,
+                learning_context_key=learning_context_key,
+                credential_type=config.credential_type.name,
+            )
+            .exclude(status=Credential.Status.ERROR)
+            .first()
+        )
+
+        if existing_credential:
+            return Response({"detail": "User already has a credential of this type."}, status=status.HTTP_409_CONFLICT)
+
+        if not config.get_eligible_user_ids(user_id=request.user.id):
+            return Response({"detail": "User is not eligible for this credential."}, status=status.HTTP_400_BAD_REQUEST)
+
+        generate_credential_for_user_task.delay(config.id, request.user.id)
+        return Response({"detail": "Credential generation started."}, status=status.HTTP_201_CREATED)
+
+
+class CredentialListView(APIView):
+    """
+    API view to list user credentials with staff override capability.
+
+    This endpoint provides access to user credential records with optional filtering
+    by learning context and staff oversight capabilities.
+
+    **Authentication Required**: Yes
+
+    **Staff Features**:
+    - Staff users can view credentials for any user by providing `username` parameter
+    - Non-staff users can only view their own credentials
+    """
+
+    def get_permissions(self) -> list:
+        """Instantiate and return the list of permissions required for this view."""
+        permission_classes = [IsAuthenticated, IsAdminOrSelf]
+
+        if self.request.query_params.get('learning_context_key'):
+            permission_classes.append(CanAccessLearningContext)
+
+        return [permission() for permission in permission_classes]
+
+    @apidocs.schema(
+        parameters=[
+            apidocs.string_parameter(
+                "learning_context_key",
+                ParameterLocation.QUERY,
+                description="Optional learning context to filter credentials (e.g. course-v1:OpenedX+DemoX+DemoCourse)",
+            ),
+            apidocs.string_parameter(
+                "username",
+                ParameterLocation.QUERY,
+                description="Username to view credentials for (staff only)",
+            ),
+        ],
+        responses={
+            200: CredentialListResponseSerializer,
+            403: "User is not authenticated or lacks permission to view specified user's credentials.",
+            404: "Specified user not found or learning context not found/accessible.",
+        },
+    )
+    def get(self, request: "Request") -> Response:
+        """
+        Retrieve a list of credentials for the authenticated user or a specified user.
+
+        This endpoint returns credential records with filtering options:
+        - Filter by learning context (course or learning path)
+        - Staff users can view credentials for any user
+        - Regular users can only view their own credentials
+
+        **Query Parameters:**
+        - `username` (staff only): View credentials for a specific user
+
+        **Path Parameters:**
+        - `learning_context_key` (optional): Filter credentials by learning context
+
+        **Response includes:**
+        - Credential ID and type
+        - Learning context information
+        - Creation date and status
+        - Download URL for completed credentials
+
+        **Example Request**
+
+            GET /api/learning_credentials/v1/credentials/
+            GET /api/learning_credentials/v1/credentials/course-v1:OpenedX+DemoX+DemoCourse/
+            GET /api/learning_credentials/v1/credentials/?username=student123  # staff only
+
+        **Response Values**
+
+        If the request is successful, an HTTP 200 "OK" response is returned.
+
+        **Example Response**
+
+        ```json
+        {
+          "credentials": [
+            {
+              "credential_id": "123e4567-e89b-12d3-a456-426614174000",
+              "credential_type": "Certificate of Achievement",
+              "context_key": "course-v1:OpenedX+DemoX+DemoCourse",
+              "status": "available",
+              "created_date": "2024-08-20T10:30:00Z",
+              "download_url": "https://example.com/credentials/123e4567.pdf"
+            }
+          ]
+        }
+        ```
+        """
+        learning_context_key = request.query_params.get('learning_context_key')
+        username = request.query_params.get('username')
+        user = get_object_or_404(User, username=username) if username else request.user
+
+        credentials_queryset = Credential.objects.filter(user_id=user.pk)
+
+        if learning_context_key:
+            credentials_queryset = credentials_queryset.filter(learning_context_key=learning_context_key)
+
+        credentials_data = CredentialModelSerializer(credentials_queryset, many=True).data
+        return Response({'credentials': credentials_data})

learning_credentials/apps.py

@@ -15,10 +15,20 @@ 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': {
+            'lms.djangoapp': {
+                'namespace': 'learning_credentials',
+                'app_name': 'learning_credentials',
+            }
+        },
         'settings_config': {
             'lms.djangoapp': {
                 'common': {'relative_path': 'settings.common'},
                 'production': {'relative_path': 'settings.production'},
             },
+            'cms.djangoapp': {
+                'common': {'relative_path': 'settings.common'},
+                'production': {'relative_path': 'settings.production'},
+            },
         },
     }

learning_credentials/compat.py

@@ -73,12 +73,21 @@ def get_learning_context_name(learning_context_key: LearningContextKey) -> str:
     return _get_learning_path_name(learning_context_key)
 
 
-def get_course_enrollments(course_id: CourseKey) -> list[User]:
-    """Get the course enrollments from Open edX."""
+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.
+    """
     # noinspection PyUnresolvedReferences,PyPackageRequirements
     from common.djangoapps.student.models import CourseEnrollment
 
     enrollments = CourseEnrollment.objects.filter(course_id=course_id, is_active=True).select_related('user')
+    if user_id:
+        enrollments = enrollments.filter(user__id=user_id)
+
     return [enrollment.user for enrollment in enrollments]
 
 

learning_credentials/core_api.py

@@ -0,0 +1,77 @@
+"""API functions for the Learning Credentials app."""
+
+import logging
+from typing import TYPE_CHECKING
+
+from .models import Credential, CredentialConfiguration
+from .tasks import generate_credential_for_user_task
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User
+    from opaque_keys.edx.keys import CourseKey
+
+logger = logging.getLogger(__name__)
+
+
+def get_eligible_users_by_credential_type(
+    course_id: 'CourseKey', user_id: int | None = None
+) -> dict[str, list['User']]:
+    """
+    Retrieve eligible users for each credential type in the given course.
+
+    :param course_id: The key of the course for which to check eligibility.
+    :param user_id: Optional. If provided, will check eligibility for the specific user.
+    :return: A dictionary with credential type as the key and eligible users as the value.
+    """
+    credential_configs = CredentialConfiguration.objects.filter(course_id=course_id)
+
+    if not credential_configs:
+        return {}
+
+    eligible_users_by_type = {}
+    for credential_config in credential_configs:
+        user_ids = credential_config.get_eligible_user_ids(user_id)
+        filtered_user_ids = credential_config.filter_out_user_ids_with_credentials(user_ids)
+
+        if user_id:
+            eligible_users_by_type[credential_config.credential_type.name] = list(set(filtered_user_ids) & {user_id})
+        else:
+            eligible_users_by_type[credential_config.credential_type.name] = filtered_user_ids
+
+    return eligible_users_by_type
+
+
+def get_user_credentials_by_type(course_id: 'CourseKey', user_id: int) -> dict[str, dict[str, str]]:
+    """
+    Retrieve the available credentials for a given user in a course.
+
+    :param course_id: The course ID for which to retrieve credentials.
+    :param user_id: The ID of the user for whom credentials are being retrieved.
+    :return: A dict where keys are credential types and values are dicts with the download link and status.
+    """
+    credentials = Credential.objects.filter(user_id=user_id, course_id=course_id)
+
+    return {cred.credential_type: {'download_url': cred.download_url, 'status': cred.status} for cred in credentials}
+
+
+def generate_credential_for_user(course_id: 'CourseKey', credential_type: str, user_id: int, force: bool = False):
+    """
+    Generate a credential for a user in a course.
+
+    :param course_id: The course ID for which to generate the credential.
+    :param credential_type: The type of credential to generate.
+    :param user_id: The ID of the user for whom the credential is being generated.
+    :param force: If True, will generate the credential even if the user is not eligible.
+    """
+    credential_config = CredentialConfiguration.objects.get(course_id=course_id, credential_type__name=credential_type)
+
+    if not credential_config:
+        logger.error('No course configuration found for course %s', course_id)
+        return
+
+    if not force and not credential_config.get_eligible_user_ids(user_id):
+        logger.error('User %s is not eligible for the credential in course %s', user_id, course_id)
+        msg = 'User is not eligible for the credential.'
+        raise ValueError(msg)
+
+    generate_credential_for_user_task.delay(credential_config.id, user_id)

learning_credentials/generators.py

@@ -89,7 +89,8 @@ def _write_text_on_template(template: any, font: str, username: str, context_nam
     pdf_canvas = canvas.Canvas(io.BytesIO(), pagesize=(template_width, template_height))
 
     # Write the learner name.
-    pdf_canvas.setFont(font, 32)
+    # TODO: Add tests.
+    pdf_canvas.setFont(font, options.get('name_size', 32))
     name_color = options.get('name_color', '#000')
     pdf_canvas.setFillColorRGB(*hex_to_rgb(name_color))
 
@@ -184,6 +185,7 @@ def generate_pdf_credential(
       - 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).
+      - 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.
       - 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).