feat!: ComponentVersionMedia.key -> ComponentVersionMedia.path

BREAKING CHANGE: Renamed ComponentVersionMedia.key -> ComponentVersionMedia.path
BREAKING CHANGE: In create_component_version_media(...) and
                 look_up_component_version_media(...), renamed param key -> path.

Part of: #322

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

Author: kdmccormick

olx_importer/management/commands/load_components.py

@@ -173,7 +173,7 @@ def import_block_type(self, block_type_name, now): # , publish_log_entry):
             content_api.create_component_version_media(
                 component_version,
                 text_content.pk,
-                key="block.xml",
+                path="block.xml",
             )
 
             # Cycle through static assets references and add those as well...

src/openedx_content/applets/backup_restore/zipper.py

@@ -381,9 +381,8 @@ def create_zip(self, path: str) -> None:
                         for component_version_media in prefetched_media:
                             media: Media = component_version_media.media
 
-                            # Important: The component_version_media.key contains implicitly
-                            # the file name and the file extension
-                            file_path = version_folder / component_version_media.key
+                            # component_version_media.path is the file name and extension
+                            file_path = version_folder / component_version_media.path
 
                             if media.has_file and media.path:
                                 # If has_file, we pull it from the file system

src/openedx_content/applets/components/admin.py

@@ -37,12 +37,12 @@ class ComponentAdmin(ReadOnlyModelAdmin):
     """
     Django admin configuration for Component
     """
-    list_display = ("key", "uuid", "component_type", "created")
+    list_display = ("entity_ref", "uuid", "component_type", "created")
     readonly_fields = [
         "learning_package",
         "uuid",
         "component_type",
-        "key",
+        "entity_ref",
         "created",
     ]
     list_filter = ("component_type", "learning_package")
@@ -69,13 +69,13 @@ def get_queryset(self, request):
         )
 
     fields = [
-        "key",
+        "path",
         "format_size",
         "rendered_data",
     ]
     readonly_fields = [
         "media",
-        "key",
+        "path",
         "format_size",
         "rendered_data",
     ]

src/openedx_content/applets/components/api.py

@@ -251,7 +251,7 @@ def create_next_component_version(
                 ComponentVersionMedia.objects.create(
                     media_id=media_pk,
                     component_version=component_version,
-                    key=key,
+                    path=key,
                 )
 
         if ignore_previous_media:
@@ -262,11 +262,11 @@ def create_next_component_version(
         last_version_media_mapping = ComponentVersionMedia.objects \
                                                           .filter(component_version=last_version)
         for cvrc in last_version_media_mapping:
-            if cvrc.key not in media_to_replace:
+            if cvrc.path not in media_to_replace:
                 ComponentVersionMedia.objects.create(
                     media_id=cvrc.media_id,
                     component_version=component_version,
-                    key=cvrc.key,
+                    path=cvrc.path,
                 )
 
         return component_version
@@ -441,7 +441,7 @@ def look_up_component_version_media(
     learning_package_ref: str,
     entity_ref: str,
     version_num: int,
-    key: Path,
+    path: Path,
 ) -> ComponentVersionMedia:
     """
     Look up ComponentVersionMedia by human readable identifiers.
@@ -456,7 +456,7 @@ def look_up_component_version_media(
         Q(component_version__component__learning_package__package_ref=learning_package_ref)
         & Q(component_version__component__publishable_entity__entity_ref=entity_ref)
         & Q(component_version__publishable_entity_version__version_num=version_num)
-        & Q(key=key)
+        & Q(path=path)
     )
     return ComponentVersionMedia.objects \
                                 .select_related(
@@ -472,29 +472,29 @@ def create_component_version_media(
     component_version_id: int,
     media_id: int,
     /,
-    key: str,
+    path: str,
 ) -> ComponentVersionMedia:
     """
     Add a Media to the given ComponentVersion
 
-    We don't allow keys that would be absolute paths, e.g. ones that start with
+    We don't allow paths that would be absolute, e.g. ones that start with
     '/'. Storing these causes headaches with building relative paths and because
     of mismatches with things that expect a leading slash and those that don't.
     So for safety and consistency, we strip off leading slashes and emit a
     warning when we do.
     """
-    if key.startswith('/'):
+    if path.startswith('/'):
         logger.warning(
             "Absolute paths are not supported: "
             f"removed leading '/' from ComponentVersion {component_version_id} "
-            f"media key: {repr(key)} (media_id: {media_id})"
+            f"media path: {repr(path)} (media_id: {media_id})"
         )
-        key = key.lstrip('/')
+        path = path.lstrip('/')
 
     cvrc, _created = ComponentVersionMedia.objects.get_or_create(
         component_version_id=component_version_id,
         media_id=media_id,
-        key=key,
+        path=path,
     )
     return cvrc
 
@@ -609,7 +609,7 @@ def _error_header(error: AssetError) -> dict[str, str]:
 
     # Check: Does the ComponentVersion have the requested asset (Media)?
     try:
-        cv_media = component_version.componentversionmedia_set.get(key=asset_path)
+        cv_media = component_version.componentversionmedia_set.get(path=asset_path)
     except ComponentVersionMedia.DoesNotExist:
         logger.error(f"ComponentVersion {component_version_uuid} has no asset {asset_path}")
         info_headers.update(

src/openedx_content/applets/components/models.py

@@ -232,31 +232,25 @@ class ComponentVersionMedia(models.Model):
     For instance, a Video ComponentVersion might be associated with multiple
     transcripts in different languages.
 
-    When Content is associated with an ComponentVersion, it has some local
-    key that is unique within the the context of that ComponentVersion. This
-    allows the ComponentVersion to do things like store an image file and
-    reference it by a "path" key.
+    When Content is associated with a ComponentVersion, it has a ``path``
+    that is unique within the context of that ComponentVersion. This is
+    used as a local file-path-like identifier, e.g. "static/image.png".
 
     Content is immutable and sharable across multiple ComponentVersions.
     """
 
     component_version = models.ForeignKey(ComponentVersion, on_delete=models.CASCADE)
     media = models.ForeignKey(Media, on_delete=models.RESTRICT)
 
-    # "key" is a reserved word for MySQL, so we're temporarily using the column
-    # name of "_key" to avoid breaking downstream tooling. A possible
-    # alternative name for this would be "path", since it's most often used as
-    # an internal file path. However, we might also want to put special
-    # identifiers that don't map as cleanly to file paths at some point.
-    key = ref_field(db_column="_key")
+    # path is a local file-path-like identifier for the media within a
+    # ComponentVersion.
+    path = ref_field()
 
     class Meta:
         constraints = [
-            # Uniqueness is only by ComponentVersion and key. If for some reason
-            # a ComponentVersion wants to associate the same piece of Media
-            # with two different identifiers, that is permitted.
+            # Uniqueness is only by ComponentVersion and path.
             models.UniqueConstraint(
-                fields=["component_version", "key"],
+                fields=["component_version", "path"],
                 name="oel_cvcontent_uniq_cv_key",
             ),
         ]

src/openedx_content/management/commands/add_assets_to_component.py

@@ -83,4 +83,4 @@ def handle(self, *args, **options):
             f"{next_version.component.entity_ref} ({next_version.uuid}):"
         )
         for cvm in next_version.componentversionmedia_set.all():
-            self.stdout.write(f"- {cvm.key} ({cvm.uuid})")
+            self.stdout.write(f"- {cvm.path} ({cvm.uuid})")

src/openedx_content/migrations/0016_rename_componentversionmedia_key_to_path.py

@@ -0,0 +1,29 @@
+from django.db import migrations, models
+
+import openedx_django_lib.fields
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('openedx_content', '0015_rename_learningpackage_db_column_key_to_package_ref'),
+    ]
+
+    operations = [
+        migrations.RemoveConstraint(
+            model_name='componentversionmedia',
+            name='oel_cvcontent_uniq_cv_key',
+        ),
+        migrations.RenameField(
+            model_name='componentversionmedia',
+            old_name='key',
+            new_name='path',
+        ),
+        migrations.AddConstraint(
+            model_name='componentversionmedia',
+            constraint=models.UniqueConstraint(
+                fields=['component_version', 'path'],
+                name='oel_cvcontent_uniq_cv_key',
+            ),
+        ),
+    ]

src/openedx_content/migrations/0017_rename_componentversionmedia_db_column_key_to_path.py

@@ -0,0 +1,37 @@
+from django.db import migrations
+
+import openedx_django_lib.fields
+
+
+class Migration(migrations.Migration):
+    """
+    Rename the underlying DB column for ComponentVersionMedia.path from
+    '_key' to 'path'. Uses SeparateDatabaseAndState with RunSQL for
+    SQLite/MySQL compatibility. The table is named
+    'openedx_content_componentversionmedia' (Django default).
+    """
+
+    dependencies = [
+        ('openedx_content', '0016_rename_componentversionmedia_key_to_path'),
+    ]
+
+    operations = [
+        migrations.SeparateDatabaseAndState(
+            state_operations=[
+                migrations.AlterField(
+                    model_name='componentversionmedia',
+                    name='path',
+                    field=openedx_django_lib.fields.MultiCollationCharField(
+                        db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'},
+                        max_length=500,
+                    ),
+                ),
+            ],
+            database_operations=[
+                migrations.RunSQL(
+                    sql='ALTER TABLE openedx_content_componentversionmedia RENAME COLUMN _key TO path',
+                    reverse_sql='ALTER TABLE openedx_content_componentversionmedia RENAME COLUMN path TO _key',
+                ),
+            ],
+        ),
+    ]

tests/openedx_content/applets/backup_restore/test_backup.py

@@ -109,7 +109,7 @@ def setUpTestData(cls):
         api.create_component_version_media(
             new_problem_version.pk,
             new_txt_media.pk,
-            key="hello.txt",
+            path="hello.txt",
         )
 
         # Create a Draft component, one in each learning package
@@ -138,7 +138,7 @@ def setUpTestData(cls):
         api.create_component_version_media(
             new_html_version.pk,
             cls.html_asset_media.id,
-            key="static/other/subdirectory/hello.html",
+            path="static/other/subdirectory/hello.html",
         )
 
         components = api.get_publishable_entities(cls.learning_package)

tests/openedx_content/applets/backup_restore/test_restore.py

@@ -12,6 +12,7 @@
     CollectionSerializer,
     ComponentSerializer,
     ContainerSerializer,
+    EntitySerializer,
 )
 from openedx_content.applets.backup_restore.zipper import LearningPackageUnzipper, generate_staged_package_ref
 from openedx_content.applets.collections import api as collections_api
@@ -420,7 +421,7 @@ class EntitySerializerTest(TestCase):
     }
 
     def _serialize(self, extra):
-        from openedx_content.applets.backup_restore.serializers import EntitySerializer
+        """Serialize BASE_DATA merged with extra using EntitySerializer."""
         data = {**self.BASE_DATA, **extra}
         s = EntitySerializer(data=data)
         s.is_valid()