openedx-learning 0.20.0__py2.py3-none-any.whl → 0.23.0__py2.py3-none-any.whl

openedx_learning/apps/authoring/publishing/api.py

@@ -6,19 +6,24 @@ are stored in this app.
 """
 from __future__ import annotations
 
+from contextlib import nullcontext
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from enum import Enum
-from typing import TypeVar
+from typing import ContextManager, TypeVar
 
 from django.core.exceptions import ObjectDoesNotExist, ValidationError
 from django.db.models import F, Q, QuerySet
 from django.db.transaction import atomic
 
+from .contextmanagers import DraftChangeLogContext
 from .models import (
     Container,
     ContainerVersion,
     Draft,
+    DraftChangeLog,
+    DraftChangeLogRecord,
+    DraftSideEffect,
     EntityList,
     EntityListRow,
     LearningPackage,
@@ -27,10 +32,10 @@ from .models import (
     PublishableEntityMixin,
     PublishableEntityVersion,
     PublishableEntityVersionMixin,
-    Published,
     PublishLog,
     PublishLogRecord,
 )
+from .models.publish_log import Published
 
 # A few of the APIs in this file are generic and can be used for Containers in
 # general, or e.g. Units (subclass of Container) in particular. These type
@@ -74,12 +79,15 @@ __all__ = [
     "get_container",
     "get_container_by_key",
     "get_containers",
+    "get_collection_containers",
     "ChildrenEntitiesAction",
     "ContainerEntityListEntry",
+    "ContainerEntityRow",
     "get_entities_in_container",
     "contains_unpublished_changes",
     "get_containers_with_entity",
     "get_container_children_count",
+    "bulk_draft_changes_for",
 ]
 
 
@@ -218,10 +226,13 @@ def create_publishable_entity_version(
             created=created,
             created_by_id=created_by,
         )
-        Draft.objects.update_or_create(
-            entity_id=entity_id,
-            defaults={"version": version},
+        set_draft_version(
+            entity_id,
+            version.id,
+            set_at=created,
+            set_by=created_by,
         )
+
     return version
 
 
@@ -445,25 +456,247 @@ def get_published_version(publishable_entity_id: int, /) -> PublishableEntityVer
 
 
 def set_draft_version(
-    publishable_entity_id: int,
+    draft_or_id: Draft | int,
     publishable_entity_version_pk: int | None,
     /,
+    set_at: datetime | None = None,
+    set_by: int | None = None,  # User.id
 ) -> None:
     """
     Modify the Draft of a PublishableEntity to be a PublishableEntityVersion.
 
+    The ``draft`` argument can be either a Draft model object, or the primary
+    key of a Draft/PublishableEntity (Draft is defined so these will be the same
+    value).
+
     This would most commonly be used to set the Draft to point to a newly
     created PublishableEntityVersion that was created in Studio (because someone
     edited some content). Setting a Draft's version to None is like deleting it
     from Studio's editing point of view (see ``soft_delete_draft`` for more
     details).
+
+    Calling this function attaches a new DraftChangeLogRecordand attaches it to a
+    DraftChangeLog.
+
+    This function will create DraftSideEffect entries and properly add any
+    containers that may have been affected by this draft update, UNLESS it is
+    called from within a bulk_draft_changes_for block. If it is called from
+    inside a bulk_draft_changes_for block, it will not add side-effects for
+    containers, as bulk_draft_changes_for will automatically do that when the
+    block exits.
     """
-    draft = Draft.objects.get(entity_id=publishable_entity_id)
-    draft.version_id = publishable_entity_version_pk
-    draft.save()
+    if set_at is None:
+        set_at = datetime.now(tz=timezone.utc)
 
+    with atomic(savepoint=False):
+        if isinstance(draft_or_id, Draft):
+            draft = draft_or_id
+        elif isinstance(draft_or_id, int):
+            draft, _created = Draft.objects.select_related("entity") \
+                                           .get_or_create(entity_id=draft_or_id)
+        else:
+            class_name = draft_or_id.__class__.__name__
+            raise TypeError(
+                f"draft_or_id must be a Draft or int, not ({class_name})"
+            )
 
-def soft_delete_draft(publishable_entity_id: int, /) -> None:
+        # If the Draft is already pointing at this version, there's nothing to do.
+        old_version_id = draft.version_id
+        if old_version_id == publishable_entity_version_pk:
+            return
+
+        # The actual update of the Draft model is here. Everything after this
+        # block is bookkeeping in our DraftChangeLog.
+        draft.version_id = publishable_entity_version_pk
+        draft.save()
+
+        # Check to see if we're inside a context manager for an active
+        # DraftChangeLog (i.e. what happens if the caller is using the public
+        # bulk_draft_changes_for() API call), or if we have to make our own.
+        learning_package_id = draft.entity.learning_package_id
+        active_change_log = DraftChangeLogContext.get_active_draft_change_log(
+            learning_package_id
+        )
+        if active_change_log:
+            change = _add_to_existing_draft_change_log(
+                active_change_log,
+                draft.entity_id,
+                old_version_id=old_version_id,
+                new_version_id=publishable_entity_version_pk,
+            )
+            # We explicitly *don't* create container side effects here because
+            # there may be many changes in this DraftChangeLog, some of which
+            # haven't been made yet. It wouldn't make sense to create a side
+            # effect that says, "this Unit changed because this Component in it
+            # changed" if we were changing that same Unit later on in the same
+            # DraftChangeLog, because that new Unit version might not even
+            # include the child Component. So we'll let DraftChangeLogContext
+            # do that work when it exits its context.
+        else:
+            # This means there is no active DraftChangeLog, so we create our own
+            # and add our DraftChangeLogRecord to it. This has the minor
+            # optimization that we don't have to check for an existing
+            # DraftChangeLogRecord, because we know it can't exist yet.
+            change_log = DraftChangeLog.objects.create(
+                learning_package_id=learning_package_id,
+                changed_at=set_at,
+                changed_by_id=set_by,
+            )
+            change = DraftChangeLogRecord.objects.create(
+                draft_change_log=change_log,
+                entity_id=draft.entity_id,
+                old_version_id=old_version_id,
+                new_version_id=publishable_entity_version_pk,
+            )
+            _create_container_side_effects_for_draft_change(change)
+
+
+def _add_to_existing_draft_change_log(
+    active_change_log: DraftChangeLog,
+    entity_id: int,
+    old_version_id: int | None,
+    new_version_id: int | None,
+) -> DraftChangeLogRecord:
+    """
+    Create or update a DraftChangeLogRecord for the active_change_log passed in.
+
+    The an active_change_log may have many DraftChangeLogRecords already
+    associated with it. A DraftChangeLog can only have one DraftChangeLogRecord
+    per PublishableEntity, e.g. the same Component can't go from v1 to v2 and v2
+    to v3 in the same DraftChangeLog. The DraftChangeLogRecord is meant to
+    capture the before and after states of the Draft version for that entity,
+    so we always keep the first value for old_version, while updating to the
+    most recent value for new_version.
+
+    So for example, if we called this function with the same active_change_log
+    and the same entity_id but with versions: (None, v1), (v1, v2), (v2, v3);
+    we would collapse them into one DraftChangeLogrecord with old_version = None
+    and new_version = v3.
+    """
+    try:
+        # Check to see if this PublishableEntity has already been changed in
+        # this DraftChangeLog. If so, we update that record instead of creating
+        # a new one.
+        change = DraftChangeLogRecord.objects.get(
+            draft_change_log=active_change_log,
+            entity_id=entity_id,
+        )
+        if change.old_version_id == new_version_id:
+            # Special case: This change undoes the previous change(s). The value
+            # in change.old_version_id represents the Draft version before the
+            # DraftChangeLog was started, regardless of how many times we've
+            # changed it since we entered the bulk_draft_changes_for() context.
+            # If we get here in the code, it means that we're now setting the
+            # Draft version of this entity to be exactly what it was at the
+            # start, and we should remove it entirely from the DraftChangeLog.
+            #
+            # It's important that we remove these cases, because we use the
+            # old_version == new_version convention to record entities that have
+            # changed purely due to side-effects.
+            change.delete()
+        else:
+            # Normal case: We update the new_version, but leave the old_version
+            # as is. The old_version represents what the Draft was pointing to
+            # when the bulk_draft_changes_for() context started, so it persists
+            # if we change the same entity multiple times in the DraftChangeLog.
+            change.new_version_id = new_version_id
+            change.save()
+    except DraftChangeLogRecord.DoesNotExist:
+        # If we're here, this is the first DraftChangeLogRecord we're making for
+        # this PublishableEntity in the active DraftChangeLog.
+        change = DraftChangeLogRecord.objects.create(
+            draft_change_log=active_change_log,
+            entity_id=entity_id,
+            old_version_id=old_version_id,
+            new_version_id=new_version_id,
+        )
+
+    return change
+
+
+def _create_container_side_effects_for_draft_change_log(change_log: DraftChangeLog):
+    """
+    Iterate through the whole DraftChangeLog and process side-effects.
+    """
+    processed_entity_ids: set[int] = set()
+    for change in change_log.records.all():
+        _create_container_side_effects_for_draft_change(
+            change,
+            processed_entity_ids=processed_entity_ids,
+        )
+
+
+def _create_container_side_effects_for_draft_change(
+    original_change: DraftChangeLogRecord,
+    processed_entity_ids: set | None = None
+):
+    """
+    Given a draft change, add side effects for all affected containers.
+
+    This should only be run after the DraftChangeLogRecord has been otherwise
+    fully written out. We want to avoid the scenario where we create a
+    side-effect that a Component change affects a Unit if the Unit version is
+    also changed (maybe even deleted) in the same DraftChangeLog.
+
+    The `processed_entity_ids` set holds the entity IDs that we've already
+    calculated side-effects for. This is to save us from recalculating side-
+    effects for the same ancestor relationships over and over again. So if we're
+    calling this function in a loop for all the Components in a Unit, we won't
+    be recalculating the Unit's side-effect on its Subsection, and its
+    Subsection's side-effect on its Section.
+
+    TODO: This could get very expensive with the get_containers_with_entity
+    calls. We should measure the impact of this.
+    """
+    if processed_entity_ids is None:
+        # An optimization, but also a guard against infinite side-effect loops.
+        processed_entity_ids = set()
+
+    changes_and_containers = [
+        (original_change, container)
+        for container
+        in get_containers_with_entity(original_change.entity_id, ignore_pinned=True)
+    ]
+    while changes_and_containers:
+        change, container = changes_and_containers.pop()
+
+        # If the container is not already in the DraftChangeLog, we need to
+        # add it. Since it's being caused as a DraftSideEffect, we're going
+        # add it with the old_version == new_version convention.
+        container_draft_version_pk = container.versioning.draft.pk
+        container_change, _created = DraftChangeLogRecord.objects.get_or_create(
+            draft_change_log=change.draft_change_log,
+            entity_id=container.pk,
+            defaults={
+                'old_version_id': container_draft_version_pk,
+                'new_version_id': container_draft_version_pk
+            }
+        )
+
+        # Mark that change in the current loop has the side effect of changing
+        # the parent container. We'll do this regardless of whether the
+        # container version itself also changed. If a Unit has a Component and
+        # both the Unit and Component have their versions incremented, then the
+        # Unit has changed in both ways (the Unit's internal metadata as well as
+        # the new version of the child component).
+        DraftSideEffect.objects.get_or_create(cause=change, effect=container_change)
+        processed_entity_ids.add(change.entity_id)
+
+        # Now we find the next layer up of containers. So if the originally
+        # passed in publishable_entity_id was for a Component, then the
+        # ``container`` we've been creating the side effect for in this loop
+        # is the Unit, and ``parents_of_container`` would be any Sequences
+        # that contain the Unit.
+        parents_of_container = get_containers_with_entity(container.pk, ignore_pinned=True)
+
+        changes_and_containers.extend(
+            (container_change, container_parent)
+            for container_parent in parents_of_container
+            if container_parent.pk not in processed_entity_ids
+        )
+
+
+def soft_delete_draft(publishable_entity_id: int, /, deleted_by: int | None = None) -> None:
     """
     Sets the Draft version to None.
 
@@ -473,10 +706,15 @@ def soft_delete_draft(publishable_entity_id: int, /) -> None:
     of pointing the Draft back to the most recent ``PublishableEntityVersion``
     for a given ``PublishableEntity``.
     """
-    return set_draft_version(publishable_entity_id, None)
+    return set_draft_version(publishable_entity_id, None, set_by=deleted_by)
 
 
-def reset_drafts_to_published(learning_package_id: int, /) -> None:
+def reset_drafts_to_published(
+    learning_package_id: int,
+    /,
+    reset_at: datetime | None = None,
+    reset_by: int | None = None,  # User.id
+) -> None:
     """
     Reset all Drafts to point to the most recently Published versions.
 
@@ -500,27 +738,55 @@ def reset_drafts_to_published(learning_package_id: int, /) -> None:
     it's important that the code creating the "next" version_num looks at the
     latest version created for a PublishableEntity (its ``latest`` attribute),
     rather than basing it off of the version that Draft points to.
-
-    Also, there is no current immutable record for when a reset happens. It's
-    not like a publish that leaves an entry in the ``PublishLog``.
     """
+    if reset_at is None:
+        reset_at = datetime.now(tz=timezone.utc)
+
     # These are all the drafts that are different from the published versions.
     draft_qset = Draft.objects \
                       .select_related("entity__published") \
                       .filter(entity__learning_package_id=learning_package_id) \
-                      .exclude(entity__published__version_id=F("version_id"))
+                      .exclude(entity__published__version_id=F("version_id")) \
+                      .exclude(
+                          # NULL != NULL in SQL, so we want to exclude entries
+                          # where both the published version and draft version
+                          # are None. This edge case happens when we create
+                          # something and then delete it without publishing, and
+                          # then reset Drafts to their published state.
+                          Q(entity__published__version__isnull=True) &
+                          Q(version__isnull=True)
+                      )
+    # If there's nothing to reset because there are no changes from the
+    # published version, just return early rather than making an empty
+    # DraftChangeLog.
+    if not draft_qset:
+        return
+
+    active_change_log = DraftChangeLogContext.get_active_draft_change_log(learning_package_id)
+
+    # If there's an active DraftChangeLog, we're already in a transaction, so
+    # there's no need to open a new one.
+    tx_context: ContextManager
+    if active_change_log:
+        tx_context = nullcontext()
+    else:
+        tx_context = bulk_draft_changes_for(
+            learning_package_id, changed_at=reset_at, changed_by=reset_by
+        )
 
-    # Note: We can't do an .update with a F() on a joined field in the ORM, so
-    # we have to loop through the drafts individually to reset them. We can
-    # rework this into a bulk update or custom SQL if it becomes a performance
-    # issue.
-    with atomic():
+    with tx_context:
+        # Note: We can't do an .update with a F() on a joined field in the ORM,
+        # so we have to loop through the drafts individually to reset them
+        # anyhow. We can rework this into a bulk update or custom SQL if it
+        # becomes a performance issue, as long as we also port over the
+        # bookkeeping code in set_draft_version.
         for draft in draft_qset:
             if hasattr(draft.entity, 'published'):
-                draft.version_id = draft.entity.published.version_id
+                published_version_id = draft.entity.published.version_id
             else:
-                draft.version = None
-            draft.save()
+                published_version_id = None
+
+            set_draft_version(draft, published_version_id)
 
 
 def register_content_models(
@@ -639,8 +905,7 @@ def create_entity_list() -> EntityList:
 
 
 def create_entity_list_with_rows(
-    entity_pks: list[int],
-    entity_version_pks: list[int | None],
+    entity_rows: list[ContainerEntityRow],
     *,
     learning_package_id: int | None,
 ) -> EntityList:
@@ -649,10 +914,7 @@ def create_entity_list_with_rows(
     Create new entity list rows for an entity list.
 
     Args:
-        entity_pks: The IDs of the publishable entities that the entity list rows reference.
-        entity_version_pks: The IDs of the versions of the entities
-            (PublishableEntityVersion) that the entity list rows reference, or
-            Nones for "unpinned" (default).
+        entity_rows: List of ContainerEntityRows specifying the publishable entity ID and version ID (if pinned).
         learning_package_id: Optional. Verify that all the entities are from
             the specified learning package.
 
@@ -662,13 +924,25 @@ def create_entity_list_with_rows(
     # Do a quick check that the given entities are in the right learning package:
     if learning_package_id:
         if PublishableEntity.objects.filter(
-            pk__in=entity_pks,
+            pk__in=[entity.entity_pk for entity in entity_rows],
         ).exclude(
             learning_package_id=learning_package_id,
         ).exists():
             raise ValidationError("Container entities must be from the same learning package.")
 
-    order_nums = range(len(entity_pks))
+    # Ensure that any pinned entity versions are linked to the correct entity
+    pinned_entities = {
+        entity.version_pk: entity.entity_pk
+        for entity in entity_rows if entity.pinned
+    }
+    if pinned_entities:
+        entity_versions = PublishableEntityVersion.objects.filter(
+            pk__in=pinned_entities.keys(),
+        ).only('pk', 'entity_id')
+        for entity_version in entity_versions:
+            if pinned_entities[entity_version.pk] != entity_version.entity_id:
+                raise ValidationError("Container entity versions must belong to the specified entity.")
+
     with atomic(savepoint=False):
 
         entity_list = create_entity_list()
@@ -676,13 +950,11 @@ def create_entity_list_with_rows(
             [
                 EntityListRow(
                     entity_list=entity_list,
-                    entity_id=entity_pk,
+                    entity_id=entity.entity_pk,
                     order_num=order_num,
-                    entity_version_id=entity_version_pk,
-                )
-                for order_num, entity_pk, entity_version_pk in zip(
-                    order_nums, entity_pks, entity_version_pks
+                    entity_version_id=entity.version_pk,
                 )
+                for order_num, entity in enumerate(entity_rows)
             ]
         )
     return entity_list
@@ -725,8 +997,7 @@ def create_container_version(
     version_num: int,
     *,
     title: str,
-    publishable_entities_pks: list[int],
-    entity_version_pks: list[int | None] | None,
+    entity_rows: list[ContainerEntityRow],
     created: datetime,
     created_by: int | None,
     container_version_cls: type[ContainerVersionModel] = ContainerVersion,  # type: ignore[assignment]
@@ -739,8 +1010,7 @@ def create_container_version(
         container_id: The ID of the container that the version belongs to.
         version_num: The version number of the container.
         title: The title of the container.
-        publishable_entities_pks: The IDs of the members of the container.
-        entity_version_pks: The IDs of the versions to pin to, if pinning is desired.
+        entity_rows: List of ContainerEntityRows specifying the publishable entity ID and version ID (if pinned).
         created: The date and time the container version was created.
         created_by: The ID of the user who created the container version.
         container_version_cls: The subclass of ContainerVersion to use, if applicable.
@@ -749,16 +1019,13 @@ def create_container_version(
         The newly created container version.
     """
     assert title is not None
-    assert publishable_entities_pks is not None
+    assert entity_rows is not None
 
     with atomic(savepoint=False):
         container = Container.objects.select_related("publishable_entity").get(pk=container_id)
         entity = container.publishable_entity
-        if entity_version_pks is None:
-            entity_version_pks = [None] * len(publishable_entities_pks)
         entity_list = create_entity_list_with_rows(
-            entity_pks=publishable_entities_pks,
-            entity_version_pks=entity_version_pks,
+            entity_rows=entity_rows,
             learning_package_id=entity.learning_package_id,
         )
         container_version = _create_container_version(
@@ -785,8 +1052,7 @@ class ChildrenEntitiesAction(Enum):
 def create_next_entity_list(
     learning_package_id: int,
     last_version: ContainerVersion,
-    publishable_entities_pks: list[int],
-    entity_version_pks: list[int | None] | None,
+    entity_rows: list[ContainerEntityRow],
     entities_action: ChildrenEntitiesAction = ChildrenEntitiesAction.REPLACE,
 ) -> EntityList:
     """
@@ -795,55 +1061,53 @@ def create_next_entity_list(
     Args:
         learning_package_id: Learning package ID
         last_version: Last version of container.
-        publishable_entities_pks: The IDs of the members current members of the container.
-        entity_version_pks: The IDs of the versions to pin to, if pinning is desired.
+        entity_rows: List of ContainerEntityRows specifying the publishable entity ID and version ID (if pinned).
         entities_action: APPEND, REMOVE or REPLACE given entities from/to the container
 
     Returns:
         The newly created entity list.
     """
-    if entity_version_pks is None:
-        entity_version_pks: list[int | None] = [None] * len(publishable_entities_pks)  # type: ignore[no-redef]
     if entities_action == ChildrenEntitiesAction.APPEND:
         # get previous entity list rows
         last_entities = last_version.entity_list.entitylistrow_set.only(
             "entity_id",
             "entity_version_id"
         ).order_by("order_num")
-        # append given publishable_entities_pks and entity_version_pks
-        publishable_entities_pks = [entity.entity_id for entity in last_entities] + publishable_entities_pks
-        entity_version_pks = [  # type: ignore[operator, assignment]
-            entity.entity_version_id
+        # append given entity_rows to the existing children
+        entity_rows = [
+            ContainerEntityRow(
+                entity_pk=entity.entity_id,
+                version_pk=entity.entity_version_id,
+            )
             for entity in last_entities
-        ] + entity_version_pks
+        ] + entity_rows
     elif entities_action == ChildrenEntitiesAction.REMOVE:
-        # get previous entity list rows
+        # get previous entity list, excluding the entities in entity_rows
         last_entities = last_version.entity_list.entitylistrow_set.only(
             "entity_id",
             "entity_version_id"
+        ).exclude(
+            entity_id__in=[entity.entity_pk for entity in entity_rows]
         ).order_by("order_num")
-        # Remove entities that are in publishable_entities_pks
-        new_entities = [
-            entity
-            for entity in last_entities
-            if entity.entity_id not in publishable_entities_pks
+        entity_rows = [
+            ContainerEntityRow(
+                entity_pk=entity.entity_id,
+                version_pk=entity.entity_version_id,
+            )
+            for entity in last_entities.all()
         ]
-        publishable_entities_pks = [entity.entity_id for entity in new_entities]
-        entity_version_pks = [entity.entity_version_id for entity in new_entities]
-    next_entity_list = create_entity_list_with_rows(
-        entity_pks=publishable_entities_pks,
-        entity_version_pks=entity_version_pks,  # type: ignore[arg-type]
+
+    return create_entity_list_with_rows(
+        entity_rows=entity_rows,
         learning_package_id=learning_package_id,
     )
-    return next_entity_list
 
 
 def create_next_container_version(
     container_pk: int,
     *,
     title: str | None,
-    publishable_entities_pks: list[int] | None,
-    entity_version_pks: list[int | None] | None,
+    entity_rows: list[ContainerEntityRow] | None,
     created: datetime,
     created_by: int | None,
     container_version_cls: type[ContainerVersionModel] = ContainerVersion,  # type: ignore[assignment]
@@ -863,8 +1127,8 @@ def create_next_container_version(
     Args:
         container_pk: The ID of the container to create the next version of.
         title: The title of the container. None to keep the current title.
-        publishable_entities_pks: The IDs of the members current members of the container. Or None for no change.
-        entity_version_pks: The IDs of the versions to pin to, if pinning is desired.
+        entity_rows: List of ContainerEntityRows specifying the publishable entity ID and version ID (if pinned).
+        Or None for no change.
         created: The date and time the container version was created.
         created_by: The ID of the user who created the container version.
         container_version_cls: The subclass of ContainerVersion to use, if applicable.
@@ -879,15 +1143,15 @@ def create_next_container_version(
         last_version = container.versioning.latest
         assert last_version is not None
         next_version_num = last_version.version_num + 1
-        if publishable_entities_pks is None:
+
+        if entity_rows is None:
             # We're only changing metadata. Keep the same entity list.
             next_entity_list = last_version.entity_list
         else:
             next_entity_list = create_next_entity_list(
                 entity.learning_package_id,
                 last_version,
-                publishable_entities_pks,
-                entity_version_pks,
+                entity_rows,
                 entities_action
             )
 
@@ -955,6 +1219,21 @@ def get_containers(
     return container_cls.objects.filter(publishable_entity__learning_package=learning_package_id)
 
 
+def get_collection_containers(
+    learning_package_id: int,
+    collection_key: str,
+) -> QuerySet[Container]:
+    """
+    Returns a QuerySet of Containers relating to the PublishableEntities in a Collection.
+
+    Containers have a one-to-one relationship with PublishableEntity, but the reverse may not always be true.
+    """
+    return Container.objects.filter(
+        publishable_entity__learning_package_id=learning_package_id,
+        publishable_entity__collections__key=collection_key,
+    ).order_by('pk')
+
+
 @dataclass(frozen=True)
 class ContainerEntityListEntry:
     """
@@ -969,6 +1248,23 @@ class ContainerEntityListEntry:
         return self.entity_version.entity
 
 
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ContainerEntityRow:
+    """
+    [ 🛑 UNSTABLE ]
+    Used to specify the primary key of PublishableEntity and optional PublishableEntityVersion.
+
+    If version_pk is None (default), then the entity is considered "unpinned",
+    meaning that the latest version of the entity will be used.
+    """
+    entity_pk: int
+    version_pk: int | None = None
+
+    @property
+    def pinned(self):
+        return self.entity_pk and self.version_pk is not None
+
+
 def get_entities_in_container(
     container: Container,
     *,
@@ -1071,6 +1367,7 @@ def get_containers_with_entity(
         ignore_pinned: if true, ignore any pinned references to the entity.
     """
     if ignore_pinned:
+        # TODO: Do we need to run distinct() on this? Will fix in https://github.com/openedx/openedx-learning/issues/303
         qs = Container.objects.filter(
             # Note: these two conditions must be in the same filter() call, or the query won't be correct.
             publishable_entity__draft__version__containerversion__entity_list__entitylistrow__entity_id=publishable_entity_pk,  # pylint: disable=line-too-long # noqa: E501
@@ -1113,3 +1410,47 @@ def get_container_children_count(
     else:
         filter_deleted = {"entity__draft__version__isnull": False}
     return container_version.entity_list.entitylistrow_set.filter(**filter_deleted).count()
+
+
+def bulk_draft_changes_for(
+    learning_package_id: int,
+    changed_by: int | None = None,
+    changed_at: datetime | None = None
+) -> DraftChangeLogContext:
+    """
+    Context manager to do a single batch of Draft changes in.
+
+    Each publishable entity that is edited in this context will be tied to a
+    single DraftChangeLogRecord, representing the cumulative changes made to
+    that entity. Upon closing of the context, side effects of these changes will
+    be calcuated, which may result in more DraftChangeLogRecords being created
+    or updated. The resulting DraftChangeLogRecords and DraftChangeSideEffects
+    will be tied together into a single DraftChangeLog, representing the
+    collective changes to the learning package that happened in this context.
+    All changes will be committed in a single atomic transaction.
+
+    Example::
+
+        with bulk_draft_changes_for(learning_package.id):
+            for section in course:
+                update_section_drafts(learning_package.id, section)
+
+    If you make a change to an entity *without* using this context manager, then
+    the individual change (and its side effects) will be automatically wrapped
+    in a one-off change context. For example, this::
+
+        update_one_component(component.learning_package, component)
+
+    is identical to this::
+
+        with bulk_draft_changes_for(component.learning_package.id):
+            update_one_component(component.learning_package.id, component)
+    """
+    return DraftChangeLogContext(
+        learning_package_id,
+        changed_at=changed_at,
+        changed_by=changed_by,
+        exit_callbacks=[
+            _create_container_side_effects_for_draft_change_log,
+        ]
+    )