feat!: Collection.key -> Collection.collection_code (#542)

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.

Backup-restore still write and reads the collection_code to/from TOML files as
`key` for backwards compatibility. This may change in a future "v2" restore
format.

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

Part of:
* #322

Author: kdmccormick

.gitignore

@@ -1,3 +1,4 @@
+.claude
 *.py[cod]
 __pycache__
 .pytest_cache

src/openedx_content/applets/backup_restore/serializers.py

@@ -156,7 +156,9 @@ class CollectionSerializer(serializers.Serializer):  # pylint: disable=abstract-
     Serializer for collections.
     """
     title = serializers.CharField(required=True)
-    key = serializers.CharField(required=True)
+    # The model field is now Collection.collection_code, but the archive format
+    # still uses "key".  A future v2 format may align the name.
+    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,9 @@ 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)
+    # Note: the model field is now Collection.collection_code, but the archive
+    # format still uses "key".  A future v2 format may align the name.
+    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

@@ -401,7 +401,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(
@@ -779,7 +779,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

@@ -34,7 +34,7 @@
 
 def create_collection(
     learning_package_id: LearningPackage.ID,
-    key: str,
+    collection_code: str,
     *,
     title: str,
     created_by: int | None,
@@ -44,35 +44,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: LearningPackage.ID, collection_key: str) -> Collection:
+def get_collection(learning_package_id: LearningPackage.ID, 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: LearningPackage.ID,
-    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
@@ -90,17 +92,17 @@ def update_collection(
 
 def delete_collection(
     learning_package_id: LearningPackage.ID,
-    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()
@@ -112,12 +114,12 @@ def delete_collection(
 
 def restore_collection(
     learning_package_id: LearningPackage.ID,
-    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()
@@ -126,7 +128,7 @@ def restore_collection(
 
 def add_to_collection(
     learning_package_id: LearningPackage.ID,
-    key: str,
+    collection_code: str,
     entities_qset: QuerySet[PublishableEntity],
     created_by: int | None = None,
 ) -> Collection:
@@ -146,10 +148,10 @@ def add_to_collection(
     if invalid_entity:
         raise ValidationError(
             f"Cannot add entity {invalid_entity.id} 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},
@@ -162,7 +164,7 @@ def add_to_collection(
 
 def remove_from_collection(
     learning_package_id: LearningPackage.ID,
-    key: str,
+    collection_code: str,
     entities_qset: QuerySet[PublishableEntity],
 ) -> Collection:
     """
@@ -174,7 +176,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)
@@ -198,7 +200,7 @@ def get_entity_collections(learning_package_id: LearningPackage.ID, entity_key:
 
 def get_collection_entities(
     learning_package_id: LearningPackage.ID,
-    collection_key: str,
+    collection_code: str,
 ) -> QuerySet[PublishableEntity]:
     """
     Returns a QuerySet of PublishableEntities in a Collection.
@@ -207,7 +209,7 @@ def get_collection_entities(
     """
     return PublishableEntity.objects.filter(
         learning_package_id=learning_package_id,
-        collections__key=collection_key,
+        collections__collection_code=collection_code,
     ).order_by("pk")
 
 

src/openedx_content/applets/collections/models.py

@@ -70,7 +70,7 @@
 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, code_field_check
 from openedx_django_lib.validators import validate_utc_datetime
 
 from ..publishing.models import LearningPackage, PublishableEntity
@@ -85,12 +85,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 +105,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,14 +171,15 @@ 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",
             ),
+            code_field_check("collection_code", name="oel_coll_collection_code_regex"),
         ]
         indexes = [
             models.Index(
@@ -196,7 +198,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: LearningPackage.ID,
-    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/units/models.py

@@ -1,6 +1,7 @@
 """
 Models that implement units
 """
+from __future__ import annotations
 
 from typing import NewType, cast, override
 

src/openedx_content/migrations/0008_rename_collection_key_to_collection_code.py

@@ -0,0 +1,73 @@
+"""
+Rename Collection.key -> Collection.collection_code and change from key_field to code_field.
+"""
+import re
+
+import django.core.validators
+import django.db.models.lookups
+from django.conf import settings
+from django.db import migrations, models
+
+import openedx_django_lib.fields
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('openedx_content', '0007_publishlogrecord_direct'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        # Drop old constraint (references the old field name).
+        migrations.RemoveConstraint(
+            model_name='collection',
+            name='oel_coll_uniq_lp_key',
+        ),
+        # Rename the column.
+        migrations.RenameField(
+            model_name='collection',
+            old_name='key',
+            new_name='collection_code',
+        ),
+        # Change from key_field (max_length=500, no validator) to code_field
+        # (max_length=255, with regex validator).
+        migrations.AlterField(
+            model_name='collection',
+            name='collection_code',
+            field=openedx_django_lib.fields.MultiCollationCharField(
+                db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'},
+                max_length=255,
+                validators=[
+                    django.core.validators.RegexValidator(
+                        re.compile('^[a-zA-Z0-9_.-]+\\Z'),
+                        'Enter a valid "code name" consisting of letters, numbers, underscores, hyphens, or periods.',
+                        'invalid',
+                    ),
+                ],
+            ),
+        ),
+        # Re-add uniqueness constraint with the new field name.
+        migrations.AddConstraint(
+            model_name='collection',
+            constraint=models.UniqueConstraint(
+                fields=('learning_package', 'collection_code'),
+                name='oel_coll_uniq_lp_key',
+            ),
+        ),
+        # DB-level regex check constraint.
+        migrations.AddConstraint(
+            model_name='collection',
+            constraint=models.CheckConstraint(
+                condition=django.db.models.lookups.Regex(
+                    models.F('collection_code'),
+                    '^[a-zA-Z0-9_.-]+\\Z',
+                ),
+                name='oel_coll_collection_code_regex',
+                violation_error_message=(
+                    'Enter a valid "code name" consisting of letters, numbers,'
+                    ' underscores, hyphens, or periods.'
+                ),
+            ),
+        ),
+    ]