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

openedx_learning/__init__.py

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

openedx_learning/api/authoring.py

@@ -13,6 +13,7 @@ from ..apps.authoring.collections.api import *
 from ..apps.authoring.components.api import *
 from ..apps.authoring.contents.api import *
 from ..apps.authoring.publishing.api import *
+from ..apps.authoring.units.api import *
 
 # This was renamed after the authoring API refactoring pushed this and other
 # app APIs into the openedx_learning.api.authoring module. Here I'm aliasing to

openedx_learning/api/authoring_models.py

@@ -10,5 +10,5 @@ consistent.
 from ..apps.authoring.collections.models import *
 from ..apps.authoring.components.models import *
 from ..apps.authoring.contents.models import *
-from ..apps.authoring.publishing.model_mixins import *
 from ..apps.authoring.publishing.models import *
+from ..apps.authoring.units.models import *

openedx_learning/apps/authoring/components/api.py

@@ -231,7 +231,7 @@ def create_next_component_version(
         return component_version
 
 
-def create_component_and_version(
+def create_component_and_version(  # pylint: disable=too-many-positional-arguments
     learning_package_id: int,
     /,
     component_type: ComponentType,
@@ -326,7 +326,7 @@ def component_exists_by_key(
         return False
 
 
-def get_components(
+def get_components(  # pylint: disable=too-many-positional-arguments
     learning_package_id: int,
     /,
     draft: bool | None = None,
@@ -468,7 +468,7 @@ def _get_component_version_info_headers(component_version: ComponentVersion) ->
         "X-Open-edX-Component-Uuid": component.uuid,
         # Component Version
         "X-Open-edX-Component-Version-Uuid": component_version.uuid,
-        "X-Open-edX-Component-Version-Num": component_version.version_num,
+        "X-Open-edX-Component-Version-Num": str(component_version.version_num),
         # Learning Package
         "X-Open-edX-Learning-Package-Key": learning_package.key,
         "X-Open-edX-Learning-Package-Uuid": learning_package.uuid,

openedx_learning/apps/authoring/components/apps.py

@@ -14,7 +14,7 @@ class ComponentsConfig(AppConfig):
     default_auto_field = "django.db.models.BigAutoField"
     label = "oel_components"
 
-    def ready(self):
+    def ready(self) -> None:
         """
         Register Component and ComponentVersion.
         """

openedx_learning/apps/authoring/components/models.py

@@ -17,13 +17,14 @@ convention, but it's possible we might want to have special identifiers later.
 """
 from __future__ import annotations
 
+from typing import ClassVar
+
 from django.db import models
 
 from ....lib.fields import case_sensitive_char_field, immutable_uuid_field, key_field
 from ....lib.managers import WithRelationsManager
 from ..contents.models import Content
-from ..publishing.model_mixins import PublishableEntityMixin, PublishableEntityVersionMixin
-from ..publishing.models import LearningPackage
+from ..publishing.models import LearningPackage, PublishableEntityMixin, PublishableEntityVersionMixin
 
 __all__ = [
     "ComponentType",
@@ -72,11 +73,11 @@ class ComponentType(models.Model):
         ),
     ]
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"{self.namespace}:{self.name}"
 
 
-class Component(PublishableEntityMixin):  # type: ignore[django-manager-missing]
+class Component(PublishableEntityMixin):
     """
     This represents any Component that has ever existed in a LearningPackage.
 
@@ -120,14 +121,12 @@ class Component(PublishableEntityMixin):  # type: ignore[django-manager-missing]
     Make a foreign key to the Component model when you need a stable reference
     that will exist for as long as the LearningPackage itself exists.
     """
-    # Tell mypy what type our objects manager has.
-    # It's actually PublishableEntityMixinManager, but that has the exact same
-    # interface as the base manager class.
-    objects: models.Manager[Component] = WithRelationsManager(
+    # Set up our custom manager. It has the same API as the default one, but selects related objects by default.
+    objects: ClassVar[WithRelationsManager[Component]] = WithRelationsManager(  # type: ignore[assignment]
         'component_type'
     )
 
-    with_publishing_relations: models.Manager[Component] = WithRelationsManager(
+    with_publishing_relations = WithRelationsManager(
         'component_type',
         'publishable_entity',
         'publishable_entity__draft__version',
@@ -190,7 +189,7 @@ class Component(PublishableEntityMixin):  # type: ignore[django-manager-missing]
         verbose_name = "Component"
         verbose_name_plural = "Components"
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"{self.component_type.namespace}:{self.component_type.name}:{self.local_key}"
 
 
@@ -201,10 +200,6 @@ class ComponentVersion(PublishableEntityVersionMixin):
     This holds the content using a M:M relationship with Content via
     ComponentVersionContent.
     """
-    # Tell mypy what type our objects manager has.
-    # It's actually PublishableEntityVersionMixinManager, but that has the exact
-    # same interface as the base manager class.
-    objects: models.Manager[ComponentVersion]
 
     # This is technically redundant, since we can get this through
     # publishable_entity_version.publishable.component, but this is more

openedx_learning/apps/authoring/contents/models.py

@@ -121,7 +121,7 @@ class MediaType(models.Model):
             ),
         ]
 
-    def __str__(self):
+    def __str__(self) -> str:
         base = f"{self.type}/{self.sub_type}"
         if self.suffix:
             return f"{base}+{self.suffix}"

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,16 @@ __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",
+    "ContainerEntityListEntry",
+    "get_entities_in_container",
+    "contains_unpublished_changes",
+    "get_containers_with_entity",
 ]
 
 
@@ -310,6 +334,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 +525,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 +561,411 @@ 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,
+    # 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
+        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
+        )
+        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)
+
+
+@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)