openedx-learning 0.18.3__py2.py3-none-any.whl → 0.19.1__py2.py3-none-any.whl

openedx_learning/apps/authoring/publishing/api.py

@@ -6,23 +6,37 @@ are stored in this app.
 """
 from __future__ import annotations
 
+from dataclasses import dataclass
 from datetime import datetime, timezone
+from typing import TypeVar
 
-from django.core.exceptions import ObjectDoesNotExist
+from django.core.exceptions import ObjectDoesNotExist, ValidationError
 from django.db.models import F, Q, QuerySet
 from django.db.transaction import atomic
 
-from .model_mixins import PublishableContentModelRegistry, PublishableEntityMixin, PublishableEntityVersionMixin
 from .models import (
+    Container,
+    ContainerVersion,
     Draft,
+    EntityList,
+    EntityListRow,
     LearningPackage,
+    PublishableContentModelRegistry,
     PublishableEntity,
+    PublishableEntityMixin,
     PublishableEntityVersion,
+    PublishableEntityVersionMixin,
     Published,
     PublishLog,
     PublishLogRecord,
 )
 
+# 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
+# variables are used to provide correct typing for those generic API methods.
+ContainerModel = TypeVar('ContainerModel', bound=Container)
+ContainerVersionModel = TypeVar('ContainerVersionModel', bound=ContainerVersion)
+
 # The public API that will be re-exported by openedx_learning.apps.authoring.api
 # is listed in the __all__ entries below. Internal helper functions that are
 # private to this module should start with an underscore. If a function does not
@@ -51,6 +65,18 @@ __all__ = [
     "reset_drafts_to_published",
     "register_content_models",
     "filter_publishable_entities",
+    # 🛑 UNSTABLE: All APIs related to containers are unstable until we've figured
+    #              out our approach to dynamic content (randomized, A/B tests, etc.)
+    "create_container",
+    "create_container_version",
+    "create_next_container_version",
+    "get_container",
+    "get_container_by_key",
+    "get_containers",
+    "ContainerEntityListEntry",
+    "get_entities_in_container",
+    "contains_unpublished_changes",
+    "get_containers_with_entity",
 ]
 
 
@@ -149,6 +175,8 @@ def create_publishable_entity(
     created: datetime,
     # User ID who created this
     created_by: int | None,
+    *,
+    can_stand_alone: bool = True,
 ) -> PublishableEntity:
     """
     Create a PublishableEntity.
@@ -161,6 +189,7 @@ def create_publishable_entity(
         key=key,
         created=created,
         created_by_id=created_by,
+        can_stand_alone=can_stand_alone,
     )
 
 
@@ -310,6 +339,30 @@ def publish_from_drafts(
         published_at = datetime.now(tz=timezone.utc)
 
     with atomic():
+        # If the drafts include any containers, we need to auto-publish their descendants:
+        # TODO: this only handles one level deep and would need to be updated to support sections > subsections > units
+
+        # Get the IDs of the ContainerVersion for any Containers whose drafts are slated to be published.
+        container_version_ids = (
+            Container.objects.filter(publishable_entity__draft__in=draft_qset)
+            .values_list("publishable_entity__draft__version__containerversion__pk", flat=True)
+        )
+        if container_version_ids:
+            # We are publishing at least one container. Check if it has any child components that aren't already slated
+            # to be published.
+            unpublished_draft_children = EntityListRow.objects.filter(
+                entity_list__container_versions__pk__in=container_version_ids,
+                entity_version=None,  # Unpinned entities only
+            ).exclude(
+                entity__draft__version=F("entity__published__version")  # Exclude already published things
+            ).values_list("entity__draft__pk", flat=True)
+            if unpublished_draft_children:
+                # Force these additional child components to be published at the same time by adding them to the qset:
+                draft_qset = Draft.objects.filter(
+                    Q(pk__in=draft_qset.values_list("pk", flat=True)) |
+                    Q(pk__in=unpublished_draft_children)
+                )
+
         # One PublishLog for this entire publish operation.
         publish_log = PublishLog(
             learning_package_id=learning_package_id,
@@ -477,7 +530,7 @@ def register_content_models(
     This is so that we can provide convenience links between content models and
     content version models *through* the publishing apps, so that you can do
     things like finding the draft version of a content model more easily. See
-    the model_mixins.py module for more details.
+    the publishable_entity.py module for more details.
 
     This should only be imported and run from the your app's AppConfig.ready()
     method. For example, in the components app, this looks like:
@@ -513,3 +566,455 @@ def filter_publishable_entities(
         entities = entities.filter(published__version__isnull=not has_published)
 
     return entities
+
+
+def get_published_version_as_of(entity_id: int, publish_log_id: int) -> PublishableEntityVersion | None:
+    """
+    Get the published version of the given entity, at a specific snapshot in the
+    history of this Learning Package, given by the PublishLog ID.
+
+    This is a semi-private function, only available to other apps in the
+    authoring package.
+    """
+    record = PublishLogRecord.objects.filter(
+        entity_id=entity_id,
+        publish_log_id__lte=publish_log_id,
+    ).order_by('-publish_log_id').first()
+    return record.new_version if record else None
+
+
+def create_container(
+    learning_package_id: int,
+    key: str,
+    created: datetime,
+    created_by: int | None,
+    *,
+    can_stand_alone: bool = True,
+    # The types on the following line are correct, but mypy will complain - https://github.com/python/mypy/issues/3737
+    container_cls: type[ContainerModel] = Container,  # type: ignore[assignment]
+) -> ContainerModel:
+    """
+    [ 🛑 UNSTABLE ]
+    Create a new container.
+
+    Args:
+        learning_package_id: The ID of the learning package that contains the container.
+        key: The key of the container.
+        created: The date and time the container was created.
+        created_by: The ID of the user who created the container
+        can_stand_alone: Set to False when created as part of containers
+        container_cls: The subclass of Container to use, if applicable
+
+    Returns:
+        The newly created container.
+    """
+    assert issubclass(container_cls, Container)
+    with atomic():
+        publishable_entity = create_publishable_entity(
+            learning_package_id,
+            key,
+            created,
+            created_by,
+            can_stand_alone=can_stand_alone,
+        )
+        container = container_cls.objects.create(
+            publishable_entity=publishable_entity,
+        )
+    return container
+
+
+def create_entity_list() -> EntityList:
+    """
+    [ 🛑 UNSTABLE ]
+    Create a new entity list. This is an structure that holds a list of entities
+    that will be referenced by the container.
+
+    Returns:
+        The newly created entity list.
+    """
+    return EntityList.objects.create()
+
+
+def create_entity_list_with_rows(
+    entity_pks: list[int],
+    entity_version_pks: list[int | None],
+    *,
+    learning_package_id: int | None,
+) -> EntityList:
+    """
+    [ 🛑 UNSTABLE ]
+    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).
+        learning_package_id: Optional. Verify that all the entities are from
+            the specified learning package.
+
+    Returns:
+        The newly created entity list.
+    """
+    # 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,
+        ).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))
+    with atomic(savepoint=False):
+
+        entity_list = create_entity_list()
+        EntityListRow.objects.bulk_create(
+            [
+                EntityListRow(
+                    entity_list=entity_list,
+                    entity_id=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
+                )
+            ]
+        )
+    return entity_list
+
+
+def _create_container_version(
+    container: Container,
+    version_num: int,
+    *,
+    title: str,
+    entity_list: EntityList,
+    created: datetime,
+    created_by: int | None,
+    container_version_cls: type[ContainerVersionModel] = ContainerVersion,  # type: ignore[assignment]
+) -> ContainerVersionModel:
+    """
+    Private internal method for logic shared by create_container_version() and
+    create_next_container_version().
+    """
+    assert issubclass(container_version_cls, ContainerVersion)
+    with atomic(savepoint=False):  # Make sure this will happen atomically but we don't need to create a new savepoint.
+        publishable_entity_version = create_publishable_entity_version(
+            container.publishable_entity_id,
+            version_num=version_num,
+            title=title,
+            created=created,
+            created_by=created_by,
+        )
+        container_version = container_version_cls.objects.create(
+            publishable_entity_version=publishable_entity_version,
+            container_id=container.pk,
+            entity_list=entity_list,
+        )
+
+    return container_version
+
+
+def create_container_version(
+    container_id: int,
+    version_num: int,
+    *,
+    title: str,
+    publishable_entities_pks: list[int],
+    entity_version_pks: list[int | None] | None,
+    created: datetime,
+    created_by: int | None,
+    container_version_cls: type[ContainerVersionModel] = ContainerVersion,  # type: ignore[assignment]
+) -> ContainerVersionModel:
+    """
+    [ 🛑 UNSTABLE ]
+    Create a new container version.
+
+    Args:
+        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.
+        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.
+
+    Returns:
+        The newly created container version.
+    """
+    assert title is not None
+    assert publishable_entities_pks 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,
+            learning_package_id=entity.learning_package_id,
+        )
+        container_version = _create_container_version(
+            container,
+            version_num,
+            title=title,
+            entity_list=entity_list,
+            created=created,
+            created_by=created_by,
+            container_version_cls=container_version_cls,
+        )
+
+    return container_version
+
+
+def create_next_container_version(
+    container_pk: int,
+    *,
+    title: str | None,
+    publishable_entities_pks: list[int] | None,
+    entity_version_pks: list[int | None] | None,
+    created: datetime,
+    created_by: int | None,
+    container_version_cls: type[ContainerVersionModel] = ContainerVersion,  # type: ignore[assignment]
+) -> ContainerVersionModel:
+    """
+    [ 🛑 UNSTABLE ]
+    Create the next version of a container. A new version of the container is created
+    only when its metadata changes:
+
+    * Something was added to the Container.
+    * We re-ordered the rows in the container.
+    * Something was removed from the container.
+    * The Container's metadata changed, e.g. the title.
+    * We pin to different versions of the Container.
+
+    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.
+        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.
+
+    Returns:
+        The newly created container version.
+    """
+    assert issubclass(container_version_cls, ContainerVersion)
+    with atomic():
+        container = Container.objects.select_related("publishable_entity").get(pk=container_pk)
+        entity = container.publishable_entity
+        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:
+            # We're only changing metadata. Keep the same entity list.
+            next_entity_list = last_version.entity_list
+        else:
+            if entity_version_pks is None:
+                entity_version_pks = [None] * len(publishable_entities_pks)
+            next_entity_list = create_entity_list_with_rows(
+                entity_pks=publishable_entities_pks,
+                entity_version_pks=entity_version_pks,
+                learning_package_id=entity.learning_package_id,
+            )
+        next_container_version = _create_container_version(
+            container,
+            next_version_num,
+            title=title if title is not None else last_version.title,
+            entity_list=next_entity_list,
+            created=created,
+            created_by=created_by,
+            container_version_cls=container_version_cls,
+        )
+
+    return next_container_version
+
+
+def get_container(pk: int) -> Container:
+    """
+    [ 🛑 UNSTABLE ]
+    Get a container by its primary key.
+
+    Args:
+        pk: The primary key of the container.
+
+    Returns:
+        The container with the given primary key.
+    """
+    return Container.objects.get(pk=pk)
+
+
+def get_container_by_key(learning_package_id: int, /, key: str) -> Container:
+    """
+    [ 🛑 UNSTABLE ]
+    Get a container by its learning package and primary key.
+
+    Args:
+        learning_package_id: The ID of the learning package that contains the container.
+        key: The primary key of the container.
+
+    Returns:
+        The container with the given primary key.
+    """
+    return Container.objects.get(
+        publishable_entity__learning_package_id=learning_package_id,
+        publishable_entity__key=key,
+    )
+
+
+def get_containers(
+    learning_package_id: int,
+    container_cls: type[ContainerModel] = Container,  # type: ignore[assignment]
+) -> QuerySet[ContainerModel]:
+    """
+    [ 🛑 UNSTABLE ]
+    Get all containers in the given learning package.
+
+    Args:
+        learning_package_id: The primary key of the learning package
+        container_cls: The subclass of Container to use, if applicable
+
+    Returns:
+        A queryset containing the container associated with the given learning package.
+    """
+    assert issubclass(container_cls, Container)
+    return container_cls.objects.filter(publishable_entity__learning_package=learning_package_id)
+
+
+@dataclass(frozen=True)
+class ContainerEntityListEntry:
+    """
+    [ 🛑 UNSTABLE ]
+    Data about a single entity in a container, e.g. a component in a unit.
+    """
+    entity_version: PublishableEntityVersion
+    pinned: bool
+
+    @property
+    def entity(self):
+        return self.entity_version.entity
+
+
+def get_entities_in_container(
+    container: Container,
+    *,
+    published: bool,
+) -> list[ContainerEntityListEntry]:
+    """
+    [ 🛑 UNSTABLE ]
+    Get the list of entities and their versions in the current draft or
+    published version of the given container.
+
+    Args:
+        container: The Container, e.g. returned by `get_container()`
+        published: `True` if we want the published version of the container, or
+            `False` for the draft version.
+    """
+    assert isinstance(container, Container)
+    container_version = container.versioning.published if published else container.versioning.draft
+    if container_version is None:
+        raise ContainerVersion.DoesNotExist  # This container has not been published yet, or has been deleted.
+    assert isinstance(container_version, ContainerVersion)
+    entity_list = []
+    for row in container_version.entity_list.entitylistrow_set.order_by("order_num"):
+        entity_version = row.entity_version  # This will be set if pinned
+        if not entity_version:  # If this entity is "unpinned", use the latest published/draft version:
+            entity_version = row.entity.published.version if published else row.entity.draft.version
+        if entity_version is not None:  # As long as this hasn't been soft-deleted:
+            entity_list.append(ContainerEntityListEntry(
+                entity_version=entity_version,
+                pinned=row.entity_version is not None,
+            ))
+        # else we could indicate somehow a deleted item was here, e.g. by returning a ContainerEntityListEntry with
+        # deleted=True, but we don't have a use case for that yet.
+    return entity_list
+
+
+def contains_unpublished_changes(container_id: int) -> bool:
+    """
+    [ 🛑 UNSTABLE ]
+    Check recursively if a container has any unpublished changes.
+
+    Note: unlike this method, the similar-sounding
+    `container.versioning.has_unpublished_changes` property only reports
+    if the container itself has unpublished changes, not
+    if its contents do. So if you change a title or add a new child component,
+    `has_unpublished_changes` will be `True`, but if you merely edit a component
+    that's in the container, it will be `False`. This method will return `True`
+    in either case.
+    """
+    # This is similar to 'get_container(container.container_id)' but pre-loads more data.
+    container = Container.objects.select_related(
+        "publishable_entity__draft__version__containerversion__entity_list",
+    ).get(pk=container_id)
+
+    if container.versioning.has_unpublished_changes:
+        return True
+
+    # We only care about children that are un-pinned, since published changes to pinned children don't matter
+    entity_list = container.versioning.draft.entity_list
+
+    # This is a naive and inefficient implementation but should be correct.
+    # TODO: Once we have expanded the containers system to support multiple levels (not just Units and Components but
+    # also subsections and sections) and we have an expanded test suite for correctness, then we can optimize.
+    # We will likely change to a tracking-based approach rather than a "scan for changes" based approach.
+    for row in entity_list.entitylistrow_set.filter(entity_version=None).select_related(
+        "entity__container",
+        "entity__draft__version",
+        "entity__published__version",
+    ):
+        try:
+            child_container = row.entity.container
+        except Container.DoesNotExist:
+            child_container = None
+        if child_container:
+            # This is itself a container - check recursively:
+            if contains_unpublished_changes(child_container.pk):
+                return True
+        else:
+            # This is not a container:
+            draft_pk = row.entity.draft.version_id if row.entity.draft else None
+            published_pk = row.entity.published.version_id if hasattr(row.entity, "published") else None
+            if draft_pk != published_pk:
+                return True
+    return False
+
+
+def get_containers_with_entity(
+    publishable_entity_pk: int,
+    *,
+    ignore_pinned=False,
+) -> QuerySet[Container]:
+    """
+    [ 🛑 UNSTABLE ]
+    Find all draft containers that directly contain the given entity.
+
+    They will always be from the same learning package; cross-package containers
+    are not allowed.
+
+    Args:
+        publishable_entity_pk: The ID of the PublishableEntity to search for.
+        ignore_pinned: if true, ignore any pinned references to the entity.
+    """
+    if ignore_pinned:
+        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
+            publishable_entity__draft__version__containerversion__entity_list__entitylistrow__entity_version_id=None,  # pylint: disable=line-too-long # noqa: E501
+        ).order_by("pk")  # Ordering is mostly for consistent test cases.
+    else:
+        qs = Container.objects.filter(
+            publishable_entity__draft__version__containerversion__entity_list__entitylistrow__entity_id=publishable_entity_pk,  # pylint: disable=line-too-long # noqa: E501
+        ).order_by("pk")  # Ordering is mostly for consistent test cases.
+    # Could alternately do this query in two steps. Not sure which is more efficient; depends on how the DB plans it.
+    # # Find all the EntityLists that contain the given entity:
+    # lists = EntityList.objects.filter(entitylistrow__entity_id=publishable_entity_pk).values_list('pk', flat=True)
+    # qs = Container.objects.filter(
+    #     publishable_entity__draft__version__containerversion__entity_list__in=lists
+    # )
+    return qs

openedx_learning/apps/authoring/publishing/apps.py

@@ -14,3 +14,12 @@ class PublishingConfig(AppConfig):
     verbose_name = "Learning Core > Authoring > Publishing"
     default_auto_field = "django.db.models.BigAutoField"
     label = "oel_publishing"
+
+    def ready(self):
+        """
+        Register Container and ContainerVersion.
+        """
+        from .api import register_content_models  # pylint: disable=import-outside-toplevel
+        from .models import Container, ContainerVersion  # pylint: disable=import-outside-toplevel
+
+        register_content_models(Container, ContainerVersion)

openedx_learning/apps/authoring/publishing/migrations/0003_containers.py

@@ -0,0 +1,54 @@
+# Generated by Django 4.2.19 on 2025-03-11 04:10
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('oel_publishing', '0002_alter_learningpackage_key_and_more'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Container',
+            fields=[
+                ('publishable_entity', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, primary_key=True, serialize=False, to='oel_publishing.publishableentity')),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='EntityList',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='EntityListRow',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('order_num', models.PositiveIntegerField()),
+                ('entity', models.ForeignKey(on_delete=django.db.models.deletion.RESTRICT, to='oel_publishing.publishableentity')),
+                ('entity_list', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='oel_publishing.entitylist')),
+                ('entity_version', models.ForeignKey(null=True, on_delete=django.db.models.deletion.RESTRICT, related_name='+', to='oel_publishing.publishableentityversion')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='ContainerVersion',
+            fields=[
+                ('publishable_entity_version', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, primary_key=True, serialize=False, to='oel_publishing.publishableentityversion')),
+                ('container', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='versions', to='oel_publishing.container')),
+                ('entity_list', models.ForeignKey(on_delete=django.db.models.deletion.RESTRICT, related_name='container_versions', to='oel_publishing.entitylist')),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.AddConstraint(
+            model_name='entitylistrow',
+            constraint=models.UniqueConstraint(fields=('entity_list', 'order_num'), name='oel_publishing_elist_row_order'),
+        ),
+    ]

openedx_learning/apps/authoring/publishing/migrations/0004_publishableentity_can_stand_alone.py

@@ -0,0 +1,21 @@
+# Generated by Django 4.2.19 on 2025-03-17 11:07
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('oel_publishing', '0003_containers'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='publishableentity',
+            name='can_stand_alone',
+            field=models.BooleanField(
+                default=True,
+                help_text="Set to True when created independently, False when created as part of a container.",
+            ),
+        ),
+    ]

openedx_learning/apps/authoring/publishing/models/__init__.py

@@ -0,0 +1,27 @@
+"""
+The data models here are intended to be used by other apps to publish different
+types of content, such as Components, Units, Sections, etc. These models should
+support the logic for the management of the publishing process:
+
+* The relationship between publishable entities and their many versions.
+* Hierarchical relationships between "container" entities and their children
+* The management of drafts.
+* Publishing specific versions of publishable entities.
+* Finding the currently published versions.
+* The act of publishing, and doing so atomically.
+* Managing reverts.
+* Storing and querying publish history.
+"""
+
+from .container import Container, ContainerVersion
+from .draft_published import Draft, Published
+from .entity_list import EntityList, EntityListRow
+from .learning_package import LearningPackage
+from .publish_log import PublishLog, PublishLogRecord
+from .publishable_entity import (
+    PublishableContentModelRegistry,
+    PublishableEntity,
+    PublishableEntityMixin,
+    PublishableEntityVersion,
+    PublishableEntityVersionMixin,
+)