feat!: Collection.key -> Collection.collection_code (WIP)

Also, standardize internal usage of collection_key to collection_code.
This helps clarify that Collection.key is *not* an OpaqueKey, but is rather
a local slug, which can be combined with other identifiers to form a fully-
qualified LibraryCollectionKey instance.

BREAKING CHANGE: Collection.key has been renamed to Collection.collection_code.

BREAKING CHANGE: Collection.collection_code now validates that its contents
matches '[A-Za-z0-9\-\_\.]+'.  This was already effectively true, because
LibraryCollectionKey can only be built with slug-like parts, but we now
we explicitly raise ValiationError from create_collection.

Part of: #322

Author: kdmccormick

src/openedx_content/applets/backup_restore/serializers.py

@@ -156,7 +156,7 @@ class CollectionSerializer(serializers.Serializer):  # pylint: disable=abstract-
     Serializer for collections.
     """
     title = serializers.CharField(required=True)
-    key = serializers.CharField(required=True)
+    key = serializers.CharField(required=True, source="collection_code")
     description = serializers.CharField(required=True, allow_blank=True)
     entities = serializers.ListField(
         child=serializers.CharField(),

src/openedx_content/applets/backup_restore/toml.py

@@ -220,7 +220,7 @@ def toml_collection(collection: Collection, entity_keys: list[str]) -> str:
 
     collection_table = tomlkit.table()
     collection_table.add("title", collection.title)
-    collection_table.add("key", collection.key)
+    collection_table.add("key", collection.collection_code)
     collection_table.add("description", collection.description)
     collection_table.add("created", collection.created)
     collection_table.add("entities", entities_array)

src/openedx_content/applets/backup_restore/zipper.py

@@ -400,7 +400,7 @@ def create_zip(self, path: str) -> None:
             collections = self.get_collections()
 
             for collection in collections:
-                collection_hash_slug = self.get_entity_toml_filename(collection.key)
+                collection_hash_slug = self.get_entity_toml_filename(collection.collection_code)
                 collection_toml_file_path = collections_folder / f"{collection_hash_slug}.toml"
                 entity_keys_related = collection.entities.order_by("key").values_list("key", flat=True)
                 self.add_file_to_zip(
@@ -778,7 +778,7 @@ def _save_collections(self, learning_package, collections):
             )
             collection = collections_api.add_to_collection(
                 learning_package_id=learning_package.id,
-                key=collection.key,
+                collection_code=collection.collection_code,
                 entities_qset=publishing_api.get_publishable_entities(learning_package.id).filter(key__in=entities)
             )
 

src/openedx_content/applets/collections/admin.py

@@ -13,14 +13,14 @@ class CollectionAdmin(admin.ModelAdmin):
 
     Allows users to easily disable/enable (aka soft delete and restore) or bulk delete Collections.
     """
-    readonly_fields = ["key", "learning_package"]
+    readonly_fields = ["collection_code", "learning_package"]
     list_filter = ["enabled"]
-    list_display = ["key", "title", "enabled", "modified"]
+    list_display = ["collection_code", "title", "enabled", "modified"]
     fieldsets = [
         (
             "",
             {
-                "fields": ["key", "learning_package"],
+                "fields": ["collection_code", "learning_package"],
             }
         ),
         (

src/openedx_content/applets/collections/api.py

@@ -33,7 +33,7 @@
 
 def create_collection(
     learning_package_id: int,
-    key: str,
+    collection_code: str,
     *,
     title: str,
     created_by: int | None,
@@ -43,35 +43,37 @@ def create_collection(
     """
     Create a new Collection
     """
-    collection = Collection.objects.create(
+    collection = Collection(
         learning_package_id=learning_package_id,
-        key=key,
+        collection_code=collection_code,
         title=title,
         created_by_id=created_by,
         description=description,
         enabled=enabled,
     )
+    collection.full_clean()
+    collection.save()
     return collection
 
 
-def get_collection(learning_package_id: int, collection_key: str) -> Collection:
+def get_collection(learning_package_id: int, collection_code: str) -> Collection:
     """
     Get a Collection by ID
     """
-    return Collection.objects.get_by_key(learning_package_id, collection_key)
+    return Collection.objects.get_by_code(learning_package_id, collection_code)
 
 
 def update_collection(
     learning_package_id: int,
-    key: str,
+    collection_code: str,
     *,
     title: str | None = None,
     description: str | None = None,
 ) -> Collection:
     """
-    Update a Collection identified by the learning_package_id + key.
+    Update a Collection identified by the learning_package_id + collection_code.
     """
-    collection = get_collection(learning_package_id, key)
+    collection = get_collection(learning_package_id, collection_code)
 
     # If no changes were requested, there's nothing to update, so just return
     # the Collection as-is
@@ -89,17 +91,17 @@ def update_collection(
 
 def delete_collection(
     learning_package_id: int,
-    key: str,
+    collection_code: str,
     *,
     hard_delete=False,
 ) -> Collection:
     """
-    Disables or deletes a collection identified by the given learning_package + key.
+    Disables or deletes a collection identified by the given learning_package + collection_code.
 
     By default (hard_delete=False), the collection is "soft deleted", i.e disabled.
     Soft-deleted collections can be re-enabled using restore_collection.
     """
-    collection = get_collection(learning_package_id, key)
+    collection = get_collection(learning_package_id, collection_code)
 
     if hard_delete:
         collection.delete()
@@ -111,12 +113,12 @@ def delete_collection(
 
 def restore_collection(
     learning_package_id: int,
-    key: str,
+    collection_code: str,
 ) -> Collection:
     """
     Undo a "soft delete" by re-enabling a Collection.
     """
-    collection = get_collection(learning_package_id, key)
+    collection = get_collection(learning_package_id, collection_code)
 
     collection.enabled = True
     collection.save()
@@ -125,7 +127,7 @@ def restore_collection(
 
 def add_to_collection(
     learning_package_id: int,
-    key: str,
+    collection_code: str,
     entities_qset: QuerySet[PublishableEntity],
     created_by: int | None = None,
 ) -> Collection:
@@ -145,10 +147,10 @@ def add_to_collection(
     if invalid_entity:
         raise ValidationError(
             f"Cannot add entity {invalid_entity.pk} in learning package {invalid_entity.learning_package_id} "
-            f"to collection {key} in learning package {learning_package_id}."
+            f"to collection {collection_code} in learning package {learning_package_id}."
         )
 
-    collection = get_collection(learning_package_id, key)
+    collection = get_collection(learning_package_id, collection_code)
     collection.entities.add(
         *entities_qset.all(),
         through_defaults={"created_by_id": created_by},
@@ -161,7 +163,7 @@ def add_to_collection(
 
 def remove_from_collection(
     learning_package_id: int,
-    key: str,
+    collection_code: str,
     entities_qset: QuerySet[PublishableEntity],
 ) -> Collection:
     """
@@ -173,7 +175,7 @@ def remove_from_collection(
 
     Returns the updated Collection.
     """
-    collection = get_collection(learning_package_id, key)
+    collection = get_collection(learning_package_id, collection_code)
 
     collection.entities.remove(*entities_qset.all())
     collection.modified = datetime.now(tz=timezone.utc)

src/openedx_content/applets/collections/models.py

@@ -70,7 +70,9 @@
 from django.db import models
 from django.utils.translation import gettext_lazy as _
 
-from openedx_django_lib.fields import MultiCollationTextField, case_insensitive_char_field, key_field
+from openedx_django_lib.fields import (
+    MultiCollationTextField, case_insensitive_char_field, code_field
+)
 from openedx_django_lib.validators import validate_utc_datetime
 
 from ..publishing.models import LearningPackage, PublishableEntity
@@ -85,12 +87,12 @@ class CollectionManager(models.Manager):
     """
     Custom manager for Collection class.
     """
-    def get_by_key(self, learning_package_id: int, key: str):
+    def get_by_code(self, learning_package_id: int, collection_code: str):
         """
-        Get the Collection for the given Learning Package + key.
+        Get the Collection for the given Learning Package + collection code.
         """
         return self.select_related('learning_package') \
-                   .get(learning_package_id=learning_package_id, key=key)
+                   .get(learning_package_id=learning_package_id, collection_code=collection_code)
 
 
 class Collection(models.Model):
@@ -105,10 +107,11 @@ class Collection(models.Model):
     learning_package = models.ForeignKey(LearningPackage, on_delete=models.CASCADE)
 
     # Every collection is uniquely and permanently identified within its learning package
-    # by a 'key' that is set during creation. Both will appear in the
+    # by a 'code' that is set during creation. Both will appear in the
     # collection's opaque key:
-    # e.g. "lib-collection:lib:key" is the opaque key for a library collection.
-    key = key_field(db_column='_key')
+    # e.g. "lib-collection:{org_code}:{library_code}:{collection_code}"
+    #       is the opaque key for a library collection.
+    collection_code = code_field()
 
     title = case_insensitive_char_field(
         null=False,
@@ -170,11 +173,11 @@ class Collection(models.Model):
     class Meta:
         verbose_name_plural = "Collections"
         constraints = [
-            # Keys are unique within a given LearningPackage.
+            # Collection codes are unique within a given LearningPackage.
             models.UniqueConstraint(
                 fields=[
                     "learning_package",
-                    "key",
+                    "collection_code",
                 ],
                 name="oel_coll_uniq_lp_key",
             ),
@@ -196,7 +199,7 @@ def __str__(self) -> str:
         """
         User-facing string representation of a Collection.
         """
-        return f"<{self.__class__.__name__}> (lp:{self.learning_package_id} {self.key}:{self.title})"
+        return f"<{self.__class__.__name__}> (lp:{self.learning_package_id} {self.collection_code}:{self.title})"
 
 
 class CollectionPublishableEntity(models.Model):

src/openedx_content/applets/components/api.py

@@ -436,7 +436,7 @@ def get_components(  # pylint: disable=too-many-positional-arguments
 
 def get_collection_components(
     learning_package_id: int,
-    collection_key: str,
+    collection_code: str,
 ) -> QuerySet[Component]:
     """
     Returns a QuerySet of Components relating to the PublishableEntities in a Collection.
@@ -445,7 +445,7 @@ def get_collection_components(
     """
     return Component.objects.filter(
         learning_package_id=learning_package_id,
-        publishable_entity__collections__key=collection_key,
+        publishable_entity__collections__collection_code=collection_code,
     ).order_by('pk')
 
 

src/openedx_content/applets/publishing/api.py

@@ -1745,7 +1745,7 @@ def get_containers(
 
 def get_collection_containers(
     learning_package_id: int,
-    collection_key: str,
+    collection_code: str,
 ) -> QuerySet[Container]:
     """
     Returns a QuerySet of Containers relating to the PublishableEntities in a Collection.
@@ -1754,7 +1754,7 @@ def get_collection_containers(
     """
     return Container.objects.filter(
         publishable_entity__learning_package_id=learning_package_id,
-        publishable_entity__collections__key=collection_key,
+        publishable_entity__collections__collection_code=collection_code,
     ).order_by('pk')
 
 

src/openedx_content/applets/units/models.py

@@ -1,6 +1,8 @@
 """
 Models that implement units
 """
+from __future__ import annotations
+
 from django.db import models
 
 from ..publishing.models import Container, ContainerVersion

src/openedx_content/migrations/0004_rename_collection_key_to_code_in_python.py

@@ -0,0 +1,28 @@
+# Generated by Django 5.2.12 on 2026-03-24 20:33
+
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('openedx_content', '0003_rename_content_to_media'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.RemoveConstraint(
+            model_name='collection',
+            name='oel_coll_uniq_lp_key',
+        ),
+        migrations.RenameField(
+            model_name='collection',
+            old_name='key',
+            new_name='collection_code',
+        ),
+        migrations.AddConstraint(
+            model_name='collection',
+            constraint=models.UniqueConstraint(fields=('learning_package', 'collection_code'), name='oel_coll_uniq_lp_key'),
+        ),
+    ]