feat!: Add Container.container_code field

Adds a container_code field (code_field) and a learning_package FK to the
Container model. Also adds a UniqueConstraint on (learning_package,
container_code), which is stricter than Component's constraint
(no type scoping -- container codes must be unique across all container
types within a given LearningPackage).

For existing containers, container_code is backfilled from the entity key
via a data migration. Future containers will have container_code set
explicitly by the caller.

Backup/restore now writes container_code into the [entity.container]
section (Verawood and later). Archives created in Ulmo (which have no
container_code) fall back to using the entity key as the container_code
on restore.

BREAKING CHANGE: create_container() and create_container_and_version()
now require a container_code keyword argument. The same applies to
create_unit_and_version(), create_subsection_and_version(), and
create_section_and_version().

Part of: #322

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kdmccormick

src/openedx_content/applets/backup_restore/serializers.py

@@ -118,35 +118,45 @@ class ComponentVersionSerializer(EntityVersionSerializer):  # pylint: disable=ab
 class ContainerSerializer(EntitySerializer):  # pylint: disable=abstract-method
     """
     Serializer for containers.
+
+    Extracts container_code from the [entity.container] section.
+    Archives created in Verawood or later include an explicit
+    ``container_code`` field. Archives created in Ulmo do not, so we
+    fall back to using the entity key as the container_code.
     """
+
     container = serializers.DictField(required=True)
 
     def validate_container(self, value):
         """
         Custom validation logic for the container field.
-        Ensures that the container dict has exactly one key which is one of
-        "section", "subsection", or "unit" values.
+        Ensures that the container dict has exactly one type key ("section",
+        "subsection", or "unit"), optionally alongside "container_code".
         """
         errors = []
-        if not isinstance(value, dict) or len(value) != 1:
-            errors.append("Container must be a dict with exactly one key.")
-        if len(value) == 1:  # Only check the key if there is exactly one
-            container_type = list(value.keys())[0]
-            if container_type not in ("section", "subsection", "unit"):
-                errors.append(f"Invalid container value: {container_type}")
+        type_keys = [k for k in value if k in ("section", "subsection", "unit")]
+        if len(type_keys) != 1:
+            errors.append(
+                "Container must have exactly one type key: 'section', 'subsection', or 'unit'."
+            )
         if errors:
             raise serializers.ValidationError(errors)
         return value
 
     def validate(self, attrs):
         """
-        Custom validation logic:
-        parse the container dict to extract the container type.
+        Custom validation logic: extract container_type and container_code.
+
+        Archives created in Verawood or later supply an explicit
+        ``container_code`` field inside [entity.container]. Archives created
+        in Ulmo do not, so we fall back to using the entity key.
         """
-        container = attrs["container"]
-        container_type = list(container.keys())[0]  # It is safe to do this after validate_container
+        container = attrs.pop("container")
+        # It is safe to do this after validate_container
+        container_type = next(k for k in container if k in ("section", "subsection", "unit"))
         attrs["container_type"] = container_type
-        attrs.pop("container")  # Remove the container field after processing
+        # Verawood+: container_code is explicit. Ulmo: fall back to entity key.
+        attrs["container_code"] = container.get("container_code") or attrs["key"]
         return attrs
 
 

src/openedx_content/applets/backup_restore/toml.py

@@ -109,11 +109,15 @@ def _get_toml_publishable_entity_table(
     entity_table.add("published", published_table)
 
     if hasattr(entity, "container"):
+        container = entity.container
         container_table = tomlkit.table()
+        # Write container_code explicitly so that restore (Verawood and later)
+        # does not need to parse the entity key.
+        container_table.add("container_code", container.container_code)
         container_types = ["section", "subsection", "unit"]
 
         for container_type in container_types:
-            if hasattr(entity.container, container_type):
+            if hasattr(container, container_type):
                 container_table.add(container_type, tomlkit.table())
                 break  # stop after the first match
 

src/openedx_content/applets/containers/admin.py

@@ -89,20 +89,23 @@ class ContainerAdmin(ReadOnlyModelAdmin):
     Django admin configuration for Container
     """
 
-    list_display = ("key", "container_type_display", "published", "draft", "created")
+    list_display = ("container_code", "container_type_display", "published", "draft", "created")
     fields = [
         "pk",
         "publishable_entity",
         "learning_package",
+        "container_code",
+        "container_type_display",
         "published",
         "draft",
         "created",
         "created_by",
         "see_also",
         "most_recent_parent_entity_list",
     ]
+    # container_code is a model field; container_type_display is a method
     readonly_fields = fields  # type: ignore[assignment]
-    search_fields = ["publishable_entity__uuid", "publishable_entity__key"]
+    search_fields = ["publishable_entity__uuid", "publishable_entity__key", "container_code"]
     inlines = [ContainerVersionInlineForContainer]
 
     def learning_package(self, obj: Container) -> SafeText:
@@ -184,7 +187,7 @@ class ContainerVersionInlineForEntityList(admin.TabularInline):
     fields = [
         "pk",
         "version_num",
-        "container_key",
+        "container_code",
         "title",
         "created",
         "created_by",
@@ -203,8 +206,8 @@ def get_queryset(self, request):
             )
         )
 
-    def container_key(self, obj: ContainerVersion) -> SafeText:
-        return model_detail_link(obj.container, obj.container.key)
+    def container_code(self, obj: ContainerVersion) -> SafeText:
+        return model_detail_link(obj.container, obj.container.container_code)
 
 
 class EntityListRowInline(admin.TabularInline):

src/openedx_content/applets/containers/api.py

@@ -140,6 +140,7 @@ def create_container(
     created: datetime,
     created_by: int | None,
     *,
+    container_code: str,
     container_cls: type[ContainerModel],
     can_stand_alone: bool = True,
 ) -> ContainerModel:
@@ -152,6 +153,8 @@ def create_container(
         key: The key of the container.
         created: The date and time the container was created.
         created_by: The ID of the user who created the container
+        container_code: A local slug identifier for the container, unique within
+            the learning package (regardless of container type).
         container_cls: The subclass of container to create (e.g. `Unit`)
         can_stand_alone: Set to False when created as part of containers
 
@@ -170,7 +173,9 @@ def create_container(
         )
         container = container_cls.objects.create(
             publishable_entity=publishable_entity,
+            learning_package_id=learning_package_id,
             container_type=container_cls.get_container_type(),
+            container_code=container_code,
         )
     return container
 
@@ -341,6 +346,7 @@ def create_container_and_version(
     learning_package_id: LearningPackage.ID,
     key: str,
     *,
+    container_code: str,
     title: str,
     container_cls: type[ContainerModel],
     entities: EntityListInput | None = None,
@@ -354,6 +360,8 @@ def create_container_and_version(
     Args:
         learning_package_id: The learning package ID.
         key: The key.
+        container_code: A local slug identifier for the container, unique within
+            the learning package (regardless of container type).
         title: The title of the new container.
         container_cls: The subclass of container to create (e.g. Unit)
         entities: List of the entities that will comprise the entity list, in
@@ -371,6 +379,7 @@ def create_container_and_version(
             key,
             created,
             created_by,
+            container_code=container_code,
             can_stand_alone=can_stand_alone,
             container_cls=container_cls,
         )

src/openedx_content/applets/containers/models.py

@@ -11,8 +11,9 @@
 from django.db import models
 from typing_extensions import deprecated
 
-from openedx_django_lib.fields import case_sensitive_char_field
+from openedx_django_lib.fields import case_sensitive_char_field, code_field
 
+from ..publishing.models.learning_package import LearningPackage
 from ..publishing.models.publishable_entity import (
     PublishableEntity,
     PublishableEntityMixin,
@@ -171,6 +172,12 @@ class Container(PublishableEntityMixin):
     olx_tag_name: str = ""
     _type_instance: ContainerType  # Cache used by get_container_type()
 
+    # This foreign key is technically redundant because we're already locked to
+    # a single LearningPackage through our publishable_entity relation. However,
+    # having this foreign key directly allows us to make indexes that efficiently
+    # query by other Container fields within a given LearningPackage.
+    learning_package = models.ForeignKey(LearningPackage, on_delete=models.CASCADE)
+
     # The type of the container. Cannot be changed once the container is created.
     container_type = models.ForeignKey(
         ContainerType,
@@ -179,6 +186,11 @@ class Container(PublishableEntityMixin):
         editable=False,
     )
 
+    # container_code is an identifier that is local to the learning_package.
+    # Unlike component_code, it is unique across all container types within
+    # the same LearningPackage.
+    container_code = code_field()
+
     @property
     def id(self) -> ID:
         return cast(Container.ID, self.publishable_entity_id)
@@ -194,6 +206,14 @@ def pk(self):
         # override this with a deprecated marker, so it shows a warning in developer's IDEs like VS Code.
         return self.id
 
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["learning_package", "container_code"],
+                name="oel_container_uniq_lp_cc",
+            ),
+        ]
+
     @classmethod
     def validate_entity(cls, entity: PublishableEntity) -> None:
         """

src/openedx_content/applets/sections/api.py

@@ -33,6 +33,7 @@ def create_section_and_version(
     learning_package_id: LearningPackage.ID,
     key: str,
     *,
+    container_code: str,
     title: str,
     subsections: Iterable[Subsection | SubsectionVersion] | None = None,
     created: datetime,
@@ -49,6 +50,7 @@ def create_section_and_version(
     section, sv = containers_api.create_container_and_version(
         learning_package_id,
         key=key,
+        container_code=container_code,
         title=title,
         entities=subsections,
         created=created,

src/openedx_content/applets/subsections/api.py

@@ -33,6 +33,7 @@ def create_subsection_and_version(
     learning_package_id: LearningPackage.ID,
     key: str,
     *,
+    container_code: str,
     title: str,
     units: Iterable[Unit | UnitVersion] | None = None,
     created: datetime,
@@ -49,6 +50,7 @@ def create_subsection_and_version(
     subsection, sv = containers_api.create_container_and_version(
         learning_package_id,
         key=key,
+        container_code=container_code,
         title=title,
         entities=units,
         created=created,

src/openedx_content/applets/units/api.py

@@ -33,6 +33,7 @@ def create_unit_and_version(
     learning_package_id: LearningPackage.ID,
     key: str,
     *,
+    container_code: str,
     title: str,
     components: Iterable[Component | ComponentVersion] | None = None,
     created: datetime,
@@ -49,6 +50,7 @@ def create_unit_and_version(
     unit, uv = containers_api.create_container_and_version(
         learning_package_id,
         key=key,
+        container_code=container_code,
         title=title,
         entities=components,
         created=created,

src/openedx_content/migrations/0010_add_container_code.py

@@ -0,0 +1,88 @@
+import re
+
+import django.core.validators
+import django.db.models.deletion
+from django.db import migrations, models
+
+import openedx_django_lib.fields
+
+
+def backfill_container_code(apps, schema_editor):
+    """
+    Backfill container_code and learning_package from publishable_entity.
+
+    For existing containers, container_code is set to the entity key (the
+    only identifier available at this point). Future containers will have
+    container_code set by the caller.
+    """
+    Container = apps.get_model("openedx_content", "Container")
+    for container in Container.objects.select_related("publishable_entity__learning_package").all():
+        container.learning_package = container.publishable_entity.learning_package
+        container.container_code = container.publishable_entity.key
+        container.save(update_fields=["learning_package", "container_code"])
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("openedx_content", "0009_rename_component_local_key_to_component_code"),
+    ]
+
+    operations = [
+        # 1. Add learning_package FK (nullable initially for backfill)
+        migrations.AddField(
+            model_name="container",
+            name="learning_package",
+            field=models.ForeignKey(
+                null=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                to="openedx_content.learningpackage",
+            ),
+        ),
+        # 2. Add container_code (nullable initially for backfill)
+        migrations.AddField(
+            model_name="container",
+            name="container_code",
+            field=openedx_django_lib.fields.MultiCollationCharField(
+                db_collations={"mysql": "utf8mb4_bin", "sqlite": "BINARY"},
+                max_length=255,
+                null=True,
+            ),
+        ),
+        # 3. Backfill both fields from publishable_entity
+        migrations.RunPython(backfill_container_code, migrations.RunPython.noop),
+        # 4. Make both fields non-nullable and add regex validation to container_code
+        migrations.AlterField(
+            model_name="container",
+            name="learning_package",
+            field=models.ForeignKey(
+                null=False,
+                on_delete=django.db.models.deletion.CASCADE,
+                to="openedx_content.learningpackage",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="container",
+            name="container_code",
+            field=openedx_django_lib.fields.MultiCollationCharField(
+                db_collations={"mysql": "utf8mb4_bin", "sqlite": "BINARY"},
+                max_length=255,
+                validators=[
+                    django.core.validators.RegexValidator(
+                        re.compile(r"^[a-zA-Z0-9_.-]+\Z"),
+                        "Enter a valid \"code name\" consisting of letters, numbers, "
+                        "underscores, hyphens, or periods.",
+                        "invalid",
+                    ),
+                ],
+            ),
+        ),
+        # 5. Add uniqueness constraint
+        migrations.AddConstraint(
+            model_name="container",
+            constraint=models.UniqueConstraint(
+                fields=["learning_package", "container_code"],
+                name="oel_container_uniq_lp_cc",
+            ),
+        ),
+    ]

tests/openedx_content/applets/backup_restore/test_backup.py

@@ -163,6 +163,7 @@ def setUpTestData(cls):
             key="unit-1",
             created=cls.now,
             created_by=cls.user.id,
+            container_code="unit-1",
             container_cls=Unit,
         )