feat: emit a bulk publish event when entities are published

Author: bradenmacdonald

src/openedx_content/applets/publishing/api.py

@@ -502,6 +502,7 @@ def publish_from_drafts(
                 published_draft_ids.add(draft.pk)
 
         _create_side_effects_for_change_log(publish_log)
+        _emit_event_for_change_log(publish_log, time_stamp=published_at, user_id=published_by)
 
     return publish_log
 
@@ -928,9 +929,10 @@ def _emit_event_for_change_log(
     change_log: PublishLog | DraftChangeLog, time_stamp: datetime, user_id: int | None
 ) -> None:
     """
-    Construct and emit the _CHANGED event when a set of entities is changed or published.
+    Construct and emit the _CHANGED / _PUBLISHED event when a set of entities is
+    changed or published.
 
-    Works with either `DraftChangeLog` or `PublishLog`.
+    Works with either ``DraftChangeLog`` or ``PublishLog``.
     """
 
     learning_package_id = change_log.learning_package.id
@@ -944,11 +946,14 @@ def _emit_event_for_change_log(
         for record in change_log.records.select_related("old_version", "new_version").all()
     ]
 
+    change_log_data: signals.DraftChangeLogEventData | signals.PublishLogEventData
     if isinstance(change_log, DraftChangeLog):
         signal = signals.LEARNING_PACKAGE_ENTITIES_CHANGED
         change_log_data = signals.DraftChangeLogEventData(draft_change_log_id=change_log.id, changes=changes)
     else:
-        raise NotImplementedError
+        assert isinstance(change_log, PublishLog)
+        signal = signals.LEARNING_PACKAGE_ENTITIES_PUBLISHED
+        change_log_data = signals.PublishLogEventData(publish_log_id=change_log.id, changes=changes)
 
     # Send out an event immediately after this database transaction commits.
     def send_change_event():

src/openedx_content/applets/publishing/signals.py

@@ -14,7 +14,9 @@
     "UserAttributionEventData",
     "ChangeLogRecordData",
     "DraftChangeLogEventData",
+    "PublishLogEventData",
     "LEARNING_PACKAGE_ENTITIES_CHANGED",
+    "LEARNING_PACKAGE_ENTITIES_PUBLISHED",
 ]
 
 
@@ -56,12 +58,20 @@ class ChangeLogRecordData:
 
 @define
 class DraftChangeLogEventData:
-    """Summary of a `DraftChangeLog`"""
+    """Summary of a `DraftChangeLog` for event purposes"""
 
     draft_change_log_id: int
     changes: list[ChangeLogRecordData]
 
 
+@define
+class PublishLogEventData:
+    """Summary of a `PublishLog` for event purposes"""
+
+    publish_log_id: int
+    changes: list[ChangeLogRecordData]
+
+
 LEARNING_PACKAGE_ENTITIES_CHANGED = OpenEdxPublicSignal(
     event_type="org.openedx.content.publishing.lp_entities_changed.v1",
     data={
@@ -73,11 +83,45 @@ class DraftChangeLogEventData:
 """
 The draft version of one or more entities in a `LearningPackage` has changed.
 
-This is emitted for when the first version of an entity is **created**, when a
-new version of an entity is created (i.e. an entity is **modified**), when an
-entity is **reverted** to an old version, or when an entity is **deleted**.
-(All referring to the draft version of the entity.) The ``old_version`` and
-``new_version`` fields can be used to distinguish among these cases.
+This is emitted when the first version of an entity is **created**, when a new
+version of an entity is created (i.e. an entity is **modified**), when an entity
+is **reverted** to an old version, or when an entity is **deleted**. (All
+referring to the draft version of the entity.)
+
+The ``old_version`` and ``new_version`` fields can be used to distinguish among
+these cases (e.g. ``old_version`` is ``None`` for newly-created entities).
+
+This is a low-level batch event. It does not have any course or library context
+information available. It does not distinguish between Containers, Components,
+or other entity types.
+
+Collections and tags are not `PublishableEntity`-based, so do not participate in
+this event.
+
+⏳ This **batch** event is emitted **synchronously**. Handlers that do anything
+per-entity or that is possibly slow should dispatch an asynchronous task for
+processing the event.
+"""
+
+
+LEARNING_PACKAGE_ENTITIES_PUBLISHED = OpenEdxPublicSignal(
+    event_type="org.openedx.content.publishing.lp_entities_published.v1",
+    data={
+        "learning_package": LearningPackageEventData,
+        "changed_by": UserAttributionEventData,
+        "change_log": PublishLogEventData,
+    },
+)
+"""
+The published version of one or more entities in a `LearningPackage` has
+changed.
+
+This is emitted when **a newly-created entity is first published**, when
+**changes to an existing entity** are published, when a published entity is
+**reverted** to a previous version, or when **a "delete" is published**.
+
+The ``old_version`` and ``new_version`` fields can be used to distinguish among
+these cases (e.g. ``old_version`` is ``None`` for newly-created entities).
 
 This is a low-level batch event. It does not have any course or library context
 information available. It does not distinguish between Containers, Components,

tests/openedx_content/applets/containers/test_api.py

@@ -925,7 +925,7 @@ def test_contains_unpublished_changes_queries(
         assert containers_api.contains_unpublished_changes(grandparent.id)
 
     # Publish grandparent and all its descendants:
-    with django_assert_num_queries(135):  # TODO: investigate as this seems high!
+    with django_assert_num_queries(137):  # TODO: investigate as this seems high!
         publish_entity(grandparent)
 
     # Tests:
@@ -1244,7 +1244,7 @@ def test_uninstalled_publish(
     """Simple test of publishing a container of uninstalled type, plus its child, and reviewing the publish log"""
     # Publish container_of_uninstalled_type (and child_entity1). Should not affect anything else,
     # but we should see "child_entity1" omitted from the subsequent publish.
-    with django_assert_num_queries(49):
+    with django_assert_num_queries(51):
         publish_log = publish_entity(container_of_uninstalled_type)
         # Nothing else should have been affected by the publish:
         assert list(publish_log.records.order_by("entity__pk").values_list("entity__key", flat=True)) == [
@@ -1282,7 +1282,7 @@ def test_deep_publish_log(
     )
     # Publish container_of_uninstalled_type (and child_entity1). Should not affect anything else,
     # but we should see "child_entity1" omitted from the subsequent publish.
-    with django_assert_num_queries(49):
+    with django_assert_num_queries(51):
         publish_log = publish_entity(container_of_uninstalled_type)
         # Nothing else should have been affected by the publish:
         assert list(publish_log.records.order_by("entity__pk").values_list("entity__key", flat=True)) == [
@@ -1291,7 +1291,7 @@ def test_deep_publish_log(
         ]
 
     # Publish great_grandparent. Should publish the whole tree.
-    with django_assert_num_queries(126):
+    with django_assert_num_queries(128):
         publish_log = publish_entity(great_grandparent)
         assert list(publish_log.records.order_by("entity__pk").values_list("entity__key", flat=True)) == [
             "child_entity2",

tests/openedx_content/applets/publishing/test_signals.py

@@ -13,9 +13,7 @@
 pytestmark = pytest.mark.django_db(transaction=True)
 now_time = datetime.now(tz=timezone.utc)
 
-
-class DeliberateRollbackException(Exception):
-    """Exception used to deliberately cancel and roll back a DB transaction"""
+# LEARNING_PACKAGE_ENTITIES_CHANGED
 
 
 def test_single_entity_changed() -> None:
@@ -147,3 +145,104 @@ def test_multiple_entites_change_aborted() -> None:
                 api.create_publishable_entity_version(entity2.id, version_num=2, title="Entity 2 V2", **created_args)
                 # Delete entity 3:
                 api.set_draft_version(entity3.id, None, set_at=now_time, set_by=None)
+
+
+# LEARNING_PACKAGE_ENTITIES_PUBLISHED
+
+
+def test_publish_events(admin_user) -> None:
+    """
+    Test that LEARNING_PACKAGE_ENTITIES_PUBLISHED is emitted when we publish
+    changes to entities in a learning package.
+    """
+    learning_package = api.create_learning_package(key="lp1", title="Test LP 📦")
+    created_args = {"created": now_time, "created_by": admin_user.id}
+
+    # Entity 1 will have no initial version:
+    entity1 = api.create_publishable_entity(learning_package.id, key="entity1", **created_args)
+    # Entity 2 will have an initial version with some changes:
+    entity2 = api.create_publishable_entity(learning_package.id, key="entity2", **created_args)
+    api.create_publishable_entity_version(entity2.id, version_num=1, title="Entity 2 V1", **created_args)
+    api.create_publishable_entity_version(entity2.id, version_num=2, title="Entity 2 V2", **created_args)
+    # Entity 3 will have an initial version that later gets deleted:
+    entity3 = api.create_publishable_entity(learning_package.id, key="entity3", **created_args)
+    api.create_publishable_entity_version(entity3.id, version_num=1, title="Entity 3 V1", **created_args)
+
+    # Publish these initial changes:
+    first_publish_time = datetime.now(tz=timezone.utc)
+    with capture_events(expected_count=1) as captured:
+        first_log = api.publish_all_drafts(
+            learning_package.id, published_at=first_publish_time, published_by=admin_user.id
+        )
+
+    event = captured[0]
+    assert event.signal is api.signals.LEARNING_PACKAGE_ENTITIES_PUBLISHED
+    assert event.kwargs["learning_package"].id == learning_package.id
+    assert event.kwargs["learning_package"].title == "Test LP 📦"
+    assert event.kwargs["changed_by"].user_id is admin_user.id
+    assert event.kwargs["change_log"].publish_log_id == first_log.id
+    assert event.kwargs["change_log"].changes == [
+        # Entity 1 is not yet published, since it has no draft version.
+        # Entity 2 is newly published, and now at v2:
+        api.signals.ChangeLogRecordData(entity_id=entity2.id, old_version=None, new_version=2),
+        # Entity 3 is newly published, and now at v1:
+        api.signals.ChangeLogRecordData(entity_id=entity3.id, old_version=None, new_version=1),
+    ]
+    assert event.kwargs["metadata"].time == first_publish_time
+
+    # Now modify the entities again:
+    # Create a version of entity1:
+    api.create_publishable_entity_version(entity1.id, version_num=1, title="Entity 1 V1", **created_args)
+    # Create a version 3 of entity2:
+    api.create_publishable_entity_version(entity2.id, version_num=3, title="Entity 2 V3", **created_args)
+    # Delete entity 3:
+    api.set_draft_version(entity3.id, None, set_at=now_time, set_by=admin_user.id)
+
+    # Publish these new changes:
+    second_publish_time = datetime.now(tz=timezone.utc)
+    with capture_events(expected_count=1) as captured:
+        second_log = api.publish_all_drafts(
+            learning_package.id, published_at=second_publish_time, published_by=admin_user.id
+        )
+
+    event = captured[0]
+    assert event.signal is api.signals.LEARNING_PACKAGE_ENTITIES_PUBLISHED
+    assert event.kwargs["learning_package"].id == learning_package.id
+    assert event.kwargs["learning_package"].title == "Test LP 📦"
+    assert event.kwargs["changed_by"].user_id is admin_user.id
+    assert event.kwargs["change_log"].publish_log_id == second_log.id
+    assert event.kwargs["change_log"].changes == [
+        # Entity 1 is newly published at v1:
+        api.signals.ChangeLogRecordData(entity_id=entity1.id, old_version=None, new_version=1),
+        # Entity 2 jumps v2 -> v3:
+        api.signals.ChangeLogRecordData(entity_id=entity2.id, old_version=2, new_version=3),
+        # Entity 3 gets deleted:
+        api.signals.ChangeLogRecordData(entity_id=entity3.id, old_version=1, new_version=None),
+    ]
+    assert event.kwargs["metadata"].time == second_publish_time
+
+
+def test_publish_events_aborted(admin_user) -> None:
+    """
+    Test that LEARNING_PACKAGE_ENTITIES_PUBLISHED is NOT emitted when we roll
+    back a transaction that would have published some entities.
+    """
+    learning_package = api.create_learning_package(key="lp1", title="Test LP 📦")
+    created_args = {"created": now_time, "created_by": admin_user.id}
+
+    # Create an entity with some initial version:
+    entity1 = api.create_publishable_entity(learning_package.id, key="entity1", **created_args)
+    api.create_publishable_entity_version(entity1.id, version_num=1, title="Entity 1 V1", **created_args)
+
+    def do_publish():
+        draft_qset = api.get_all_drafts(learning_package.id).filter(entity=entity1)
+        api.publish_from_drafts(
+            learning_package.id, draft_qset=draft_qset, published_at=now_time, published_by=admin_user.id
+        )
+
+    with capture_events(expected_count=0):
+        with abort_transaction():
+            do_publish()
+
+    with capture_events(expected_count=1):
+        do_publish()

tests/openedx_content/applets/sections/test_api.py

@@ -155,7 +155,7 @@ def test_section_queries(self) -> None:
         """
         with self.assertNumQueries(39):
             section = self.create_section_with_subsections([self.subsection_1, self.subsection_2_v1])
-        with self.assertNumQueries(160):
+        with self.assertNumQueries(162):
             content_api.publish_from_drafts(
                 self.learning_package.id,
                 draft_qset=content_api.get_all_drafts(self.learning_package.id).filter(entity=section.id),

tests/openedx_content/applets/subsections/test_api.py

@@ -133,7 +133,7 @@ def test_subsection_queries(self) -> None:
         """
         with self.assertNumQueries(39):
             subsection = self.create_subsection_with_units([self.unit_1, self.unit_1_v1])
-        with self.assertNumQueries(102):  # TODO: this seems high?
+        with self.assertNumQueries(104):  # TODO: this seems high?
             content_api.publish_from_drafts(
                 self.learning_package.id,
                 draft_qset=content_api.get_all_drafts(self.learning_package.id).filter(entity=subsection.id),

tests/openedx_content/applets/units/test_api.py

@@ -134,7 +134,7 @@ def test_unit_queries(self) -> None:
         """
         with self.assertNumQueries(37):
             unit = self.create_unit_with_components([self.component_1, self.component_2_v1])
-        with self.assertNumQueries(48):  # TODO: this seems high?
+        with self.assertNumQueries(50):  # TODO: this seems high?
             content_api.publish_from_drafts(
                 self.learning_package.id,
                 draft_qset=content_api.get_all_drafts(self.learning_package.id).filter(entity=unit.id),