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.
The underlying database field is still named _key.

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
enforce it at the db level.

Part of: #322

TODO: Fix backup/restore, with backcompat for `key`

TODO: Should migrations be updated or left alone?

TODO: Should the column stay as _key or change?

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)
+    collection_code = serializers.CharField(required=True, source="key")
     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,
@@ -45,7 +45,7 @@ def create_collection(
     """
     collection = Collection.objects.create(
         learning_package_id=learning_package_id,
-        key=key,
+        collection_code=collection_code,
         title=title,
         created_by_id=created_by,
         description=description,
@@ -54,24 +54,24 @@ def create_collection(
     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 +89,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 +111,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 +125,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 +145,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 +161,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 +173,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,12 @@ 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.
+    # Formerly known as the "key", hence the column name.
+    collection_code = code_field(db_column='_key')
 
     title = case_insensitive_char_field(
         null=False,
@@ -170,11 +174,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 +200,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/backcompat/collections/migrations/0004_collection_key.py

@@ -6,19 +6,19 @@
 import openedx_django_lib.fields
 
 
-def generate_keys(apps, schema_editor):
+def generate_codes(apps, schema_editor):
     """
-    Generates a random strings to initialize the key field where NULL.
+    Generates a random strings to initialize the collection_code field where NULL.
     """
     length = 50
     Collection = apps.get_model("oel_collections", "Collection")
-    for collection in Collection.objects.filter(key=None):
+    for collection in Collection.objects.filter(collection_code=None):
         # Keep generating keys until we get a unique one
-        key = get_random_string(length)
-        while Collection.objects.filter(key=key).exists():
-            key = get_random_string(length)
+        collection_code = get_random_string(length)
+        while Collection.objects.filter(collection_code=collection_code).exists():
+            collection_code = get_random_string(length)
 
-        collection.key = key
+        collection.collection_code = collection_code
         collection.save()
 
 
@@ -32,18 +32,18 @@ class Migration(migrations.Migration):
         # 1. Temporarily add this field with null=True, blank=True
         migrations.AddField(
             model_name='collection',
-            name='key',
+            name='collection_code',
             field=openedx_django_lib.fields.MultiCollationCharField(
                 db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'},
                 db_column='_key', max_length=500, null=True, blank=True),
             preserve_default=False,
         ),
         # 2. Populate the null keys
-        migrations.RunPython(generate_keys),
+        migrations.RunPython(generate_codes),
         # 3. Add null=False, blank=False to disallow NULL values
         migrations.AlterField(
             model_name='collection',
-            name='key',
+            name='collection_code',
             field=openedx_django_lib.fields.MultiCollationCharField(
                 db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'},
                 db_column='_key', max_length=500, null=False, blank=False),
@@ -52,6 +52,6 @@ class Migration(migrations.Migration):
         # 4. Enforce unique constraint
         migrations.AddConstraint(
             model_name='collection',
-            constraint=models.UniqueConstraint(fields=('learning_package', 'key'), name='oel_coll_uniq_lp_key'),
+            constraint=models.UniqueConstraint(fields=('learning_package', 'collection_code'), name='oel_coll_uniq_lp_key'),
         ),
     ]