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

openedx_learning/__init__.py

@@ -2,4 +2,4 @@
 Open edX Learning ("Learning Core").
 """
 
-__version__ = "0.22.0"
+__version__ = "0.23.0"

openedx_learning/apps/authoring/publishing/admin.py

@@ -4,10 +4,19 @@ Django admin for publishing models
 from __future__ import annotations
 
 from django.contrib import admin
+from django.db.models import Count
 
 from openedx_learning.lib.admin_utils import ReadOnlyModelAdmin, one_to_one_related_model_html
 
-from .models import LearningPackage, PublishableEntity, Published, PublishLog, PublishLogRecord
+from .models import (
+    DraftChangeLog,
+    DraftChangeLogRecord,
+    LearningPackage,
+    PublishableEntity,
+    PublishLog,
+    PublishLogRecord,
+)
+from .models.publish_log import Published
 
 
 @admin.register(LearningPackage)
@@ -171,3 +180,69 @@ class PublishedAdmin(ReadOnlyModelAdmin):
 
     def message(self, published_obj):
         return published_obj.publish_log_record.publish_log.message
+
+
+class DraftChangeLogRecordTabularInline(admin.TabularInline):
+    """
+    Tabular inline for a single Draft change.
+    """
+    model = DraftChangeLogRecord
+
+    fields = (
+        "entity",
+        "title",
+        "old_version_num",
+        "new_version_num",
+    )
+    readonly_fields = fields
+
+    def get_queryset(self, request):
+        queryset = super().get_queryset(request)
+        return queryset.select_related("entity", "old_version", "new_version") \
+                       .order_by("entity__key")
+
+    def old_version_num(self, draft_change: DraftChangeLogRecord):
+        if draft_change.old_version is None:
+            return "-"
+        return draft_change.old_version.version_num
+
+    def new_version_num(self, draft_change: DraftChangeLogRecord):
+        if draft_change.new_version is None:
+            return "-"
+        return draft_change.new_version.version_num
+
+    def title(self, draft_change: DraftChangeLogRecord):
+        """
+        Get the title to display for the DraftChange
+        """
+        if draft_change.new_version:
+            return draft_change.new_version.title
+        if draft_change.old_version:
+            return draft_change.old_version.title
+        return ""
+
+
+@admin.register(DraftChangeLog)
+class DraftChangeSetAdmin(ReadOnlyModelAdmin):
+    """
+    Read-only admin to view Draft changes (via inline tables)
+    """
+    inlines = [DraftChangeLogRecordTabularInline]
+    fields = (
+        "uuid",
+        "learning_package",
+        "num_changes",
+        "changed_at",
+        "changed_by",
+    )
+    readonly_fields = fields
+    list_display = fields
+    list_filter = ["learning_package"]
+
+    def num_changes(self, draft_change_set):
+        return draft_change_set.num_changes
+
+    def get_queryset(self, request):
+        queryset = super().get_queryset(request)
+        return queryset.select_related("learning_package", "changed_by") \
+                       .annotate(num_changes=Count("records"))

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
@@ -82,6 +87,7 @@ __all__ = [
     "contains_unpublished_changes",
     "get_containers_with_entity",
     "get_container_children_count",
+    "bulk_draft_changes_for",
 ]
 
 
@@ -220,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
 
 
@@ -447,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.
+    """
+    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})"
+            )
+
+        # 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):
     """
-    draft = Draft.objects.get(entity_id=publishable_entity_id)
-    draft.version_id = publishable_entity_version_pk
-    draft.save()
+    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, /) -> None:
+def soft_delete_draft(publishable_entity_id: int, /, deleted_by: int | None = None) -> None:
     """
     Sets the Draft version to None.
 
@@ -475,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.
 
@@ -502,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(
@@ -1103,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
@@ -1145,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,
+        ]
+    )