feat: emit event signals when publishable entities are changed.

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

Author: bradenmacdonald

src/openedx_content/applets/publishing/api.py

@@ -35,6 +35,7 @@
     PublishSideEffect,
 )
 from .models.publish_log import Published
+from . import signals
 
 # The public API that will be re-exported by openedx_content.api
 # is listed in the __all__ entries below. Internal helper functions that are
@@ -685,6 +686,17 @@ def set_draft_version(
             )
             draft.save()
             _create_side_effects_for_change_log(change_log)
+            # Send out an event immediately, since this is an isolated change.
+            # TODO: use transaction.on_commit for this event.
+            signals.LEARNING_PACKAGE_ENTITIES_CHANGED.send_event(
+                time=set_at,
+                learning_package=signals.LearningPackageEventData(
+                    id=learning_package_id,
+                    title="TODO: set me",
+                ),
+                changed_by=signals.UserAttributionEventData(user_id=set_by),
+                change_log=signals.DraftChangeLogEventData(draft_change_log_id=change_log.id),
+            )
 
 
 def _add_to_existing_draft_change_log(

src/openedx_content/applets/publishing/signals.py

@@ -0,0 +1,45 @@
+"""
+Low-level events/signals emitted by openedx_content
+"""
+
+from attrs import define
+from openedx_events.tooling import OpenEdxPublicSignal  # type: ignore[import-untyped]
+
+from .models.learning_package import LearningPackage
+
+
+@define
+class LearningPackageEventData:
+    """Identifies which learning package an event is associated with."""
+    id: LearningPackage.ID
+    title: str  # Since 'id' is not easily human-understandable, we include the title too
+
+@define
+class UserAttributionEventData:
+    """Identifies which user triggered the event."""
+    user_id: int | None
+
+@define
+class DraftChangeLogEventData:
+    """Summary of a `DraftChangeLog`"""
+    draft_change_log_id: int
+
+
+LEARNING_PACKAGE_ENTITIES_CHANGED = OpenEdxPublicSignal(
+    event_type="org.openedx.content.publishing.lp_entities_changed.v1",
+    data={
+        "learning_package": LearningPackageEventData,
+        "changed_by": UserAttributionEventData,
+        "change_log": DraftChangeLogEventData,
+    },
+)
+"""
+The draft version of one or more entities in a `LearningPackage` has changed.
+
+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.
+"""

tests/openedx_content/applets/publishing/test_signals.py

@@ -0,0 +1,40 @@
+"""
+Tests related to the Catalog signal handlers
+"""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from openedx_content import api
+from openedx_content.applets.publishing.signals import LEARNING_PACKAGE_ENTITIES_CHANGED
+
+from tests.utils import capture_events
+
+pytestmark = pytest.mark.django_db
+now_time = datetime.now(tz=timezone.utc)
+
+
+def test_unbatched_events() -> None:
+    """
+    Test that LEARNING_PACKAGE_ENTITIES_CHANGED is emitted when we change a
+    publishable entity.
+    """
+    learning_package = api.create_learning_package(key="lp1", title="Test LP")
+
+    entity = api.create_publishable_entity(learning_package.id, key="entity1", created=now_time, created_by=None)
+    # create_publishable_entity_version also calls set_draft_version internally, so
+    with capture_events(expected_count=1) as captured:
+        v1 = api.create_publishable_entity_version(
+            entity.id, version_num=1, title="Entity 1 V1", created=now_time, created_by=None
+        )
+
+    entity.refresh_from_db()
+    assert api.get_draft_version(entity.id) == v1
+
+    event = captured[0]
+    assert event.signal is LEARNING_PACKAGE_ENTITIES_CHANGED
+    assert event.kwargs["learning_package"].id == learning_package.id
+    assert event.kwargs["changed_by"].user_id is None
+    assert event.kwargs["change_log"].draft_change_log_id > 0
+    assert event.kwargs["metadata"].time == now_time

tests/utils.py

@@ -0,0 +1,79 @@
+"""
+Shared testing utilities for openedx-core tests.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Generator
+
+from openedx_events.tooling import OpenEdxPublicSignal  # type: ignore[import-untyped]
+
+
+@dataclass
+class CapturedEvent:
+    """A single captured event emission."""
+
+    signal: OpenEdxPublicSignal
+    kwargs: dict
+
+
+@contextmanager
+def capture_events(
+    signals: list[OpenEdxPublicSignal] | None = None,
+    expected_count: int | None = None,
+) -> Generator[list[CapturedEvent], None, None]:
+    """
+    Context manager that captures Open edX events emitted during the block.
+
+    Args:
+        signals: Optional list of ``OpenEdxPublicSignal`` instances to monitor.
+                 Defaults to all registered signals (OpenEdxPublicSignal.all_events()).
+        expected_count: How many events are expected (optional). If specified,
+                        will assert that the resulting list has this length.
+
+    Yields:
+        list[CapturedEvent]: A list that is populated as each event fires.
+                             Each entry has a ``signal`` attribute and a ``kwargs``
+                             dict containing the event data (learning_package,
+                             changed_by, etc.) plus ``metadata`` and
+                             ``from_event_bus``.
+
+    Example usage::
+
+        with capture_events(expected_count=1) as captured:
+            api.do_something(entity.id, ...)
+
+        assert captured[0].signal is LEARNING_PACKAGE_ENTITIES_CHANGED
+        assert captured[0].kwargs['learning_package'].id == learning_package.id
+    """
+    if signals is None:
+        signals = list(OpenEdxPublicSignal.all_events())
+
+    captured: list[CapturedEvent] = []
+    receivers: dict[OpenEdxPublicSignal, object] = {}
+
+    for signal in signals:
+
+        def make_receiver(sig: OpenEdxPublicSignal):
+            def receiver(sender, **kwargs):
+                kwargs.pop("signal", None)
+                captured.append(CapturedEvent(signal=sig, kwargs=kwargs))
+
+            return receiver
+
+        receiver = make_receiver(signal)
+        signal.connect(receiver)
+        receivers[signal] = receiver
+
+    try:
+        yield captured
+    finally:
+        for signal, receiver in receivers.items():
+            signal.disconnect(receiver)
+
+    if expected_count is not None:
+        assert len(captured) == expected_count, (
+            f"Expected {expected_count} event(s), got {len(captured)}: {[e.signal for e in captured]}"
+        )