feat: add deletion support to create_next_version and document it better

openedx_learning/core/components/api.py

@@ -88,6 +88,18 @@ def create_next_version(
     Before calling this, you should create any new contents via the contents
     API, since ``content_to_replace`` needs RawContent IDs for the values.
 
+    The ``content_to_replace`` dict is a mapping of strings representing the
+    local path/key for a file, to ``RawContent.id`` values. Using a `None` for
+    a value in this dict means to delete that key in the next version.
+
+    It is okay to mark entries for deletion that don't exist. For instance, if a
+    version has ``a.txt`` and ``b.txt``, sending a ``content_to_replace`` value
+    of ``{"a.txt": None, "c.txt": None}`` will remove ``a.txt`` from the next
+    version, leave ``b.txt`` alone, and will not error–even though there is no
+    ``c.txt`` in the previous version. This is to make it a little more
+    convenient to remove paths (e.g. due to deprecation) without having to
+    always check for its existence first.
+
     TODO: Have to add learning_downloadable info to this when it comes time to
           support static asset download.
     """

tests/openedx_learning/core/components/test_api.py

@@ -442,3 +442,26 @@ def test_multiple_versions(self):
                 .get(componentversionrawcontent__key="blank.txt")
                 .text_content
         )
+
+        # Now we're going to set "hello.txt" back to hello_content, but remove
+        # blank.txt, goodbye.txt, and an unknown "nothere.txt".
+        version_3 = components_api.create_next_version(
+            self.problem.pk,
+            title="Problem Version 3",
+            content_to_replace={
+                "hello.txt": hello_content.pk,
+                "blank.txt": None,
+                "goodbye.txt": None,
+                "nothere.txt": None,  # should not error
+            },
+            created=self.now,
+        )
+        assert version_3.version_num == 3
+        assert version_3.raw_contents.count() == 1
+        assert (
+            hello_content ==
+            version_3
+                .raw_contents
+                .get(componentversionrawcontent__key="hello.txt")
+                .text_content
+        )