feat: new REST API for units in content libraries

bradenmacdonald · bradenmacdonald · commit 40f89881162b · 2025-03-14T14:25:52.000-07:00
diff --git a/openedx/core/djangoapps/content_libraries/api/__init__.py b/openedx/core/djangoapps/content_libraries/api/__init__.py
@@ -1,5 +1,6 @@
 """
 Python API for working with content libraries
 """
+from .containers import *
 from .libraries import *
 from .blocks import *
diff --git a/openedx/core/djangoapps/content_libraries/api/containers.py b/openedx/core/djangoapps/content_libraries/api/containers.py
@@ -0,0 +1,113 @@
+"""
+API for containers (Sections, Subsections, Units) in Content Libraries
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+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 import authoring_models
+
+from ..models import ContentLibrary
+from .libraries import PublishableItem
+
+# The public API is only the following symbols:
+__all__ = [
+    "ContainerMetadata",
+    "create_container",
+]
+
+
+class ContainerType(Enum):
+    Unit = "unit"
+
+
+@dataclass(frozen=True, kw_only=True)
+class ContainerMetadata(PublishableItem):
+    """
+    Class that represents the metadata about an XBlock in a content library.
+    """
+    container_key: LibraryContainerLocator
+    container_type: ContainerType
+
+    @classmethod
+    def from_container(cls, library_key, container: authoring_models.Container, associated_collections=None):
+        """
+        Construct a LibraryXBlockMetadata from a Component object.
+        """
+        last_publish_log = container.versioning.last_publish_log
+
+        assert container.unit is not None
+        container_type = ContainerType.Unit
+
+        published_by = None
+        if last_publish_log and last_publish_log.published_by:
+            published_by = last_publish_log.published_by.username
+
+        draft = container.versioning.draft
+        published = container.versioning.published
+        last_draft_created = draft.created if draft else None
+        last_draft_created_by = draft.publishable_entity_version.created_by.username if draft else ""
+
+        return cls(
+            container_key=LibraryContainerLocator(
+                library_key,
+                container_type=container_type.value,
+                container_id=container.publishable_entity.key,
+            ),
+            container_type=container_type,
+            display_name=draft.title,
+            created=container.created,
+            modified=draft.created,
+            draft_version_num=draft.version_num,
+            published_version_num=published.version_num if published else None,
+            last_published=None if last_publish_log is None else last_publish_log.published_at,
+            published_by=published_by or "",
+            last_draft_created=last_draft_created,
+            last_draft_created_by=last_draft_created_by,
+            has_unpublished_changes=authoring_api.contains_unpublished_changes(container.pk),
+            collections=associated_collections or [],
+        )
+
+
+def create_container(
+    library_key: LibraryLocatorV2,
+    container_type: ContainerType,
+    slug: str | None,
+    title: str,
+    user_id: int | None,
+) -> ContainerMetadata:
+    """
+    Create a container (e.g. a Unit) in the specified content library.
+
+    It will initially be empty.
+    """
+    assert isinstance(library_key, LibraryLocatorV2)
+    content_library = ContentLibrary.objects.get_by_key(library_key)
+    assert content_library.learning_package_id  # Should never happen but we made this a nullable field so need to check
+    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:
+    LibraryContainerLocator(library_key=library_key, container_type=container_type.value, container_id=slug)
+    # Then try creating the actual container:
+    match container_type:
+        case ContainerType.Unit:
+            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,
+            )
+        case _:
+            raise ValueError(f"Invalid container type: {container_type}")
+    return ContainerMetadata.from_container(library_key, container)
diff --git a/openedx/core/djangoapps/content_libraries/api/libraries.py b/openedx/core/djangoapps/content_libraries/api/libraries.py
@@ -277,25 +277,40 @@ class CollectionMetadata:
 
 
 @dataclass(frozen=True)
-class LibraryXBlockMetadata:
+class LibraryItem:
     """
-    Class that represents the metadata about an XBlock in a content library.
+    Common fields for anything that can be found in a content library.
     """
-    usage_key: LibraryUsageLocatorV2
     created: datetime
     modified: datetime
+    display_name: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class PublishableItem(LibraryItem):
+    """
+    Common fields for anything that can be found in a content library that has
+    draft/publish support.
+    """
     draft_version_num: int
     published_version_num: int | None = None
-    display_name: str = ""
     last_published: datetime | None = None
-    # THe username of the user who last published this.
+    # The username of the user who last published this.
     published_by: str = ""
     last_draft_created: datetime | None = None
     # The username of the user who created the last draft.
     last_draft_created_by: str = ""
     has_unpublished_changes: bool = False
     collections: list[CollectionMetadata] = field(default_factory=list)
 
+
+@dataclass(frozen=True, kw_only=True)
+class LibraryXBlockMetadata(PublishableItem):
+    """
+    Class that represents the metadata about an XBlock in a content library.
+    """
+    usage_key: LibraryUsageLocatorV2
+
     @classmethod
     def from_component(cls, library_key, component, associated_collections=None):
         """
diff --git a/openedx/core/djangoapps/content_libraries/rest_api/containers.py b/openedx/core/djangoapps/content_libraries/rest_api/containers.py
@@ -0,0 +1,58 @@
+"""
+REST API views for containers (sections, subsections, units) in content libraries
+"""
+from __future__ import annotations
+
+import logging
+
+from django.contrib.auth import get_user_model
+from django.db.transaction import non_atomic_requests
+from django.utils.decorators import method_decorator
+from django.utils.translation import gettext as _
+from drf_yasg.utils import swagger_auto_schema
+
+from opaque_keys.edx.locator import LibraryLocatorV2
+from rest_framework.generics import GenericAPIView
+from rest_framework.response import Response
+
+from openedx.core.djangoapps.content_libraries import api, permissions
+from openedx.core.lib.api.view_utils import view_auth_classes
+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)
+
+        container_type = serializer.validated_data['container_type']
+        container = api.create_container(
+            library_key,
+            container_type,
+            title=serializer.validated_data['display_name'],
+            slug=serializer.validated_data.get('slug'),
+            user_id=request.user.id,
+        )
+
+        return Response(serializers.LibraryContainerMetadataSerializer(container).data)
diff --git a/openedx/core/djangoapps/content_libraries/rest_api/serializers.py b/openedx/core/djangoapps/content_libraries/rest_api/serializers.py
@@ -10,6 +10,7 @@
 from opaque_keys import InvalidKeyError
 
 from openedx_learning.api.authoring_models import Collection
+from openedx.core.djangoapps.content_libraries.api.containers import ContainerMetadata, ContainerType
 from openedx.core.djangoapps.content_libraries.constants import (
     ALL_RIGHTS_RESERVED,
     LICENSE_OPTIONS,
@@ -230,6 +231,45 @@ class LibraryXBlockStaticFilesSerializer(serializers.Serializer):
     files = LibraryXBlockStaticFileSerializer(many=True)
 
 
+class LibraryContainerMetadataSerializer(serializers.Serializer):
+    """
+    Serializer for Containers like Sections, Subsections, Units
+
+    Converts from ContainerMetadata to JSON-compatible data
+    """
+    container_key = serializers.CharField(read_only=True)
+    container_type = serializers.CharField()
+    display_name = serializers.CharField()
+    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)
+
+    def to_representation(self, instance: ContainerMetadata):
+        """ Convert to JSON-serializable data types """
+        data = super().to_representation(instance)
+        data["container_type"] = instance.container_type.value  # Force to a string, not an enum value instance
+        return data
+
+    def to_internal_value(self, data):
+        """
+        Convert JSON-ish data back to native python types.
+        Returns a dictionary, not a ContainerMetadata instance.
+        """
+        result = super().to_internal_value(data)
+        result["container_type"] = ContainerType(data["container_type"])
+        return result
+
+
 class ContentLibraryBlockImportTaskSerializer(serializers.ModelSerializer):
     """
     Serializer for a Content Library block import task.
diff --git a/openedx/core/djangoapps/content_libraries/tests/base.py b/openedx/core/djangoapps/content_libraries/tests/base.py
@@ -22,6 +22,7 @@
 URL_LIB_LINKS = URL_LIB_DETAIL + 'links/'  # Get the list of links in this library, or add a new one
 URL_LIB_COMMIT = URL_LIB_DETAIL + 'commit/'  # Commit (POST) or revert (DELETE) all pending changes to this library
 URL_LIB_BLOCKS = URL_LIB_DETAIL + 'blocks/'  # Get the list of XBlocks in this library, or add a new one
+URL_LIB_CONTAINERS = URL_LIB_DETAIL + 'containers/'  # Create a new container in this library
 URL_LIB_TEAM = URL_LIB_DETAIL + 'team/'  # Get the list of users/groups authorized to use this library
 URL_LIB_TEAM_USER = URL_LIB_TEAM + 'user/{username}/'  # Add/edit/remove a user's permission to use this library
 URL_LIB_TEAM_GROUP = URL_LIB_TEAM + 'group/{group_name}/'  # Add/edit/remove a group's permission to use this library
@@ -350,3 +351,11 @@ def _get_library_block_fields(self, block_key, version=None, expect_response=200
     def _set_library_block_fields(self, block_key, new_fields, expect_response=200):
         """ Set the fields of a specific block in the library. This API is only used by the MFE editors. """
         return self._api('post', URL_BLOCK_FIELDS_URL.format(block_key=block_key), new_fields, expect_response)
+
+    def _create_container(self, lib_key, container_type, slug: str | None, display_name: str, expect_response=200):
+        """ Create a container (unit etc.) """
+        return self._api('post', URL_LIB_CONTAINERS.format(lib_key=lib_key), {
+            "container_type": container_type,
+            "slug": slug,
+            "display_name": display_name,
+        }, expect_response)
diff --git a/openedx/core/djangoapps/content_libraries/tests/test_containers.py b/openedx/core/djangoapps/content_libraries/tests/test_containers.py
@@ -0,0 +1,62 @@
+"""
+Tests for Learning-Core-based Content Libraries
+"""
+from datetime import datetime, timezone
+
+import ddt
+from freezegun import freeze_time
+
+from openedx.core.djangoapps.content_libraries.tests.base import ContentLibrariesRestApiTest
+from openedx.core.djangolib.testing.utils import skip_unless_cms
+
+
+@skip_unless_cms
+@ddt.ddt
+class ContainersTestCase(ContentLibrariesRestApiTest):
+    """
+    Tests for containers (Sections, Subsections, Units) in Content Libraries.
+
+    These tests use the REST API, which in turn relies on the Python API.
+    Some tests may use the python API directly if necessary to provide
+    coverage of any code paths not accessible via the REST API.
+
+    In general, these tests should
+    (1) Use public APIs only - don't directly create data using other methods,
+        which results in a less realistic test and ties the test suite too
+        closely to specific implementation details.
+        (Exception: users can be provisioned using a user factory)
+    (2) Assert that fields are present in responses, but don't assert that the
+        entire response has some specific shape. That way, things like adding
+        new fields to an API response, which are backwards compatible, won't
+        break any tests, but backwards-incompatible API changes will.
+    """
+    # Note: if we need events at some point, add OpenEdxEventsTestMixin and set the list here; see other test suites.
+    # ENABLED_OPENEDX_EVENTS = []
+
+    def test_unit_crud(self):
+        """
+        Test Create, Read, Update, and Delete of a Unit
+        """
+        lib = self._create_library(slug="containers", title="Container Test Library", description="Units and more")
+
+        # Create a unit:
+        create_date = datetime(2024, 9, 8, 7, 6, 5, tzinfo=timezone.utc)
+        with freeze_time(create_date):
+            container_data = self._create_container(lib["id"], "unit", slug="u1", display_name="Test Unit")
+        expected_data = {
+            "container_key": "lct:CL-TEST:containers:unit:u1",
+            "container_type": "unit",
+            "display_name": "Test Unit",
+            "last_published": None,
+            "published_by": None,
+            "last_draft_created": "2024-09-08T07:06:05Z",
+            "last_draft_created_by": 'Bob',
+            'has_unpublished_changes': True,
+            'created': '2024-09-08T07:06:05Z',
+            'modified': '2024-09-08T07:06:05Z',
+            'collections': [],
+        }
+
+        self.assertDictContainsEntries(container_data, expected_data)
+
+    # TODO: test that a regular user with read-only permissions on the library cannot create units
diff --git a/openedx/core/djangoapps/content_libraries/urls.py b/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'),
