feat: new REST API for units in content libraries

Author: bradenmacdonald

cms/envs/common.py

@@ -1876,6 +1876,7 @@
     "openedx_learning.apps.authoring.components",
     "openedx_learning.apps.authoring.contents",
     "openedx_learning.apps.authoring.publishing",
+    "openedx_learning.apps.authoring.units",
 ]
 
 

lms/envs/common.py

@@ -3373,6 +3373,7 @@ def _make_locale_paths(settings):  # pylint: disable=missing-function-docstring
     "openedx_learning.apps.authoring.components",
     "openedx_learning.apps.authoring.contents",
     "openedx_learning.apps.authoring.publishing",
+    "openedx_learning.apps.authoring.units",
 ]
 
 

openedx/core/djangoapps/content_libraries/api/__init__.py

@@ -1,2 +1,3 @@
+from .containers import *
 from .libraries import *
 from .blocks import *

openedx/core/djangoapps/content_libraries/api/containers.py

@@ -0,0 +1,61 @@
+"""
+API for containers (Sections, Subsections, Units) in Content Libraries
+"""
+from __future__ import annotations
+from datetime import datetime
+from typing import Literal
+from uuid import uuid4
+
+from django.utils.text import slugify
+from opaque_keys.edx.locator import (
+    LibraryLocatorV2,
+    LibraryContainerLocator,
+)
+
+from openedx_learning.api import authoring as authoring_api
+from openedx_learning.api.authoring_models import (
+    Component,
+    ComponentVersion,
+    LearningPackage,
+    PublishableEntity,
+    Unit,
+)
+
+from ..constants import CONTAINER_UNIT_TYPE
+from ..models import ContentLibrary
+
+# The public API is only the following symbols:
+__all__ = [
+    "create_container",
+]
+
+
+def create_container(
+    library_key: LibraryLocatorV2,
+    container_type: Literal["unit"],  # Python won't let us define the type using CONTAINER_UNIT_TYPE unfortunately 
+    slug: str | None,
+    title: str,
+    user_id: int | None,
+) -> tuple[LibraryContainerLocator, Unit]:
+    """
+    Create a container (e.g. a Unit) in the specified content library.
+
+    It will initially be empty.
+    """
+    assert isinstance(library_key, LibraryLocatorV2)
+    assert container_type in [CONTAINER_UNIT_TYPE]
+    content_library = ContentLibrary.objects.get_by_key(library_key)
+    if slug is None:
+        # Automatically generate a slug. Append a random suffix so it should be unique.
+        slug = slugify(title, allow_unicode=True) + '-' + uuid4().hex[-6:]
+    # Make sure the slug is valid by first creating a key for the new container:
+    container_key = LibraryContainerLocator(lib_key=library_key, container_type=container_type, container_id=slug)
+    # Then try creating the actual container:
+    container, _initial_version = authoring_api.create_unit_and_version(
+        content_library.learning_package_id,
+        key=slug,
+        title=title,
+        created=datetime.now(),
+        created_by=user_id,
+    )
+    return container_key, container

openedx/core/djangoapps/content_libraries/constants.py

@@ -11,6 +11,9 @@
 CC_4_BY_ND = 'CC:4.0:BY:ND'
 CC_4_BY_SA = 'CC:4.0:BY:SA'
 
+# Container types
+CONTAINER_UNIT_TYPE = 'unit'
+
 LICENSE_OPTIONS = (
     (ALL_RIGHTS_RESERVED, _('All Rights Reserved.')),
     (CC_4_BY, _('Creative Commons Attribution 4.0')),

openedx/core/djangoapps/content_libraries/rest_api/containers.py

@@ -0,0 +1,74 @@
+"""
+REST API views for containers (sections, subsections, units) in content libraries
+"""
+from __future__ import annotations
+
+from functools import wraps
+import logging
+
+from django.conf import settings
+from django.contrib.auth import authenticate, get_user_model, login
+from django.contrib.auth.models import Group
+from django.core.exceptions import ObjectDoesNotExist
+from django.db.transaction import atomic, non_atomic_requests
+from django.http import Http404, HttpResponse, HttpResponseBadRequest, JsonResponse, StreamingHttpResponse
+from django.shortcuts import get_object_or_404
+from django.urls import reverse
+from django.utils.decorators import method_decorator
+from django.utils.translation import gettext as _
+from django.views.decorators.clickjacking import xframe_options_exempt
+from django.views.decorators.csrf import csrf_exempt
+from django.views.generic.base import TemplateResponseMixin, View
+from drf_yasg.utils import swagger_auto_schema
+from pylti1p3.contrib.django import DjangoCacheDataStorage, DjangoDbToolConf, DjangoMessageLaunch, DjangoOIDCLogin
+from pylti1p3.exception import LtiException, OIDCException
+
+import edx_api_doc_tools as apidocs
+from opaque_keys import InvalidKeyError
+from opaque_keys.edx.locator import LibraryLocatorV2, LibraryContainerLocator
+from rest_framework import status
+from rest_framework.exceptions import NotFound, PermissionDenied, ValidationError
+from rest_framework.generics import GenericAPIView
+from rest_framework.parsers import MultiPartParser
+from rest_framework.response import Response
+from rest_framework.views import APIView
+from rest_framework.viewsets import GenericViewSet
+
+from openedx.core.djangoapps.content_libraries import api, permissions
+from openedx.core.lib.api.view_utils import view_auth_classes
+from openedx.core.djangoapps.xblock import api as xblock_api
+from openedx.core.types.http import RestRequest
+from . import serializers
+from .utils import convert_exceptions
+
+User = get_user_model()
+log = logging.getLogger(__name__)
+
+
+@method_decorator(non_atomic_requests, name="dispatch")
+@view_auth_classes()
+class LibraryContainersView(GenericAPIView):
+    """
+    Views to work with Containers in a specific content library.
+    """
+    serializer_class = serializers.LibraryContainerMetadataSerializer
+
+    @convert_exceptions
+    @swagger_auto_schema(
+        request_body=serializers.LibraryContainerMetadataSerializer,
+        responses={200: serializers.LibraryContainerMetadataSerializer}
+    )
+    def post(self, request, lib_key_str):
+        """
+        Create a new Container in this content library
+        """
+        library_key = LibraryLocatorV2.from_string(lib_key_str)
+        api.require_permission_for_library_key(library_key, request.user, permissions.CAN_EDIT_THIS_CONTENT_LIBRARY)
+        serializer = serializers.LibraryContainerMetadataSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+
+        # Create a new regular top-level block:
+        container_type = serializer.validated_data['container_type']
+        _key, container = api.create_container(container_type)
+
+        return Response(serializers.LibraryContainerMetadataSerializer(container).data)

openedx/core/djangoapps/content_libraries/rest_api/serializers.py

@@ -230,6 +230,28 @@ class LibraryXBlockStaticFilesSerializer(serializers.Serializer):
     files = LibraryXBlockStaticFileSerializer(many=True)
 
 
+class LibraryContainerMetadataSerializer(serializers.Serializer):
+    """
+    Serializer for Containers like Sections, Subsections, Units
+    """
+    id = serializers.CharField(source="container_key", read_only=True)
+    container_type = serializers.CharField(source="container_key.container_type")
+    title = serializers.CharField(read_only=True)
+    last_published = serializers.DateTimeField(format=DATETIME_FORMAT, read_only=True)
+    published_by = serializers.CharField(read_only=True)
+    last_draft_created = serializers.DateTimeField(format=DATETIME_FORMAT, read_only=True)
+    last_draft_created_by = serializers.CharField(read_only=True)
+    has_unpublished_changes = serializers.BooleanField(read_only=True)
+    created = serializers.DateTimeField(format=DATETIME_FORMAT, read_only=True)
+    modified = serializers.DateTimeField(format=DATETIME_FORMAT, read_only=True)
+    tags_count = serializers.IntegerField(read_only=True)
+    collections = CollectionMetadataSerializer(many=True, required=False, read_only=True)
+
+    # When creating a new container in a library, the slug becomes the ID part of
+    # the definition key and usage key:
+    slug = serializers.CharField(write_only=True)
+
+
 class ContentLibraryBlockImportTaskSerializer(serializers.ModelSerializer):
     """
     Serializer for a Content Library block import task.

openedx/core/djangoapps/content_libraries/urls.py

@@ -6,7 +6,7 @@
 
 from rest_framework import routers
 
-from .rest_api import blocks, collections, libraries
+from .rest_api import blocks, collections, containers, libraries
 
 
 # Django application name.
@@ -38,6 +38,8 @@
             path('block_types/', libraries.LibraryBlockTypesView.as_view()),
             # Get the list of XBlocks in this library, or add a new one:
             path('blocks/', blocks.LibraryBlocksView.as_view()),
+            # Add a new container (unit etc.) to this library:
+            path('containers/', containers.LibraryContainersView.as_view()),
             # Publish (POST) or revert (DELETE) all pending changes to this library:
             path('commit/', libraries.LibraryCommitView.as_view()),
             # Get the list of users/groups who have permission to view/edit/administer this library:
@@ -70,6 +72,14 @@
             path('publish/', blocks.LibraryBlockPublishView.as_view()),
             # Future: discard changes for just this one block
         ])),
+        # Containers are Sections, Subsections, and Units
+        path('containers/<usage_v2:container_key>/', include([
+            # Get metadata about a specific container in this library, or delete the container:
+            # path('', views.LibraryContainerView.as_view()),
+            # Update collections for a given container
+            # path('collections/', views.LibraryContainerCollectionsView.as_view(), name='update-collections-ct'),
+            # path('publish/', views.LibraryContainerPublishView.as_view()),
+        ])),
         re_path(r'^lti/1.3/', include([
             path('login/', libraries.LtiToolLoginView.as_view(), name='lti-login'),
             path('launch/', libraries.LtiToolLaunchView.as_view(), name='lti-launch'),