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

openedx_learning/apps/authoring/publishing/{model_mixins.py → models/publishable_entity.py}

@@ -1,21 +1,260 @@
 """
-Helper mixin classes for content apps that want to use the publishing app.
+PublishableEntity model and PublishableEntityVersion + mixins
 """
-from __future__ import annotations
-
+from datetime import datetime
 from functools import cached_property
+from typing import ClassVar, Self
 
+from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
+from django.core.validators import MinValueValidator
 from django.db import models
-from django.db.models.query import QuerySet
 
-from .models import PublishableEntity, PublishableEntityVersion
+from openedx_learning.lib.fields import (
+    case_insensitive_char_field,
+    immutable_uuid_field,
+    key_field,
+    manual_date_time_field,
+)
+from openedx_learning.lib.managers import WithRelationsManager
+
+from .learning_package import LearningPackage
+
+
+class PublishableEntity(models.Model):
+    """
+    This represents any publishable thing that has ever existed in a
+    LearningPackage. It serves as a stable model that will not go away even if
+    these things are later unpublished or deleted.
+
+    A PublishableEntity belongs to exactly one LearningPackage.
+
+    Examples of Publishable Entities
+    --------------------------------
+
+    Components (e.g. VideoBlock, ProblemBlock), Units, and Sections/Subsections
+    would all be considered Publishable Entites. But anything that can be
+    imported, exported, published, and reverted in a course or library could be
+    modeled as a PublishableEntity, including things like Grading Policy or
+    possibly Taxonomies (?).
+
+    How to use this model
+    ---------------------
+
+    The publishing app understands that publishable entities exist, along with
+    their drafts and published versions. It has some basic metadata, such as
+    identifiers, who created it, and when it was created. It's meant to
+    encapsulate the draft and publishing related aspects of your content, but
+    the ``publishing`` app doesn't know anything about the actual content being
+    referenced.
+
+    You have to provide actual meaning to PublishableEntity by creating your own
+    models that will represent your particular content and associating them to
+    PublishableEntity via a OneToOneField with primary_key=True. The easiest way
+    to do this is to have your model inherit from PublishableEntityMixin.
+
+    Identifiers
+    -----------
+    The UUID is globally unique and should be treated as immutable.
+
+    The key field *is* mutable, but changing it will affect all
+    PublishedEntityVersions. They are locally unique within the LearningPackage.
+
+    If you are referencing this model from within the same process, use a
+    foreign key to the id. If you are referencing this PublishedEntity from an
+    external system/service, use the UUID. The key is the part that is most
+    likely to be human-readable, and may be exported/copied, but try not to rely
+    on it, since this value may change.
+
+    Note: When we actually implement the ability to change identifiers, we
+    should make a history table and a modified attribute on this model.
+
+    Why are Identifiers in this Model?
+    ----------------------------------
+
+    A PublishableEntity never stands alone–it's always intended to be used with
+    a 1:1 model like Component or Unit. So why have all the identifiers in this
+    model instead of storing them in those other models? Two reasons:
+
+    * Published things need to have the right identifiers so they can be used
+    throughout the system, and the UUID is serving the role of ISBN in physical
+    book publishing.
+    * We want to be able to enforce the idea that "key" is locally unique across
+    all PublishableEntities within a given LearningPackage. Component and Unit
+    can't do that without a shared model.
+
+    That being said, models that build on PublishableEntity are free to add
+    their own identifiers if it's useful to do so.
+
+    Why not Inherit from this Model?
+    --------------------------------
+
+    Django supports multi-table inheritance:
+
+      https://docs.djangoproject.com/en/4.2/topics/db/models/#multi-table-inheritance
+
+    We don't use that, primarily because we want to more clearly decouple
+    publishing concerns from the rest of the logic around Components, Units,
+    etc. If you made a Component and ComponentVersion models that subclassed
+    PublishableEntity and PublishableEntityVersion, and then accessed
+    ``component.versions``, you might expect ComponentVersions to come back and
+    be surprised when you get EntityVersions instead.
+
+    In general, we want freedom to add new Publishing models, fields, and
+    methods without having to worry about the downstream name collisions with
+    other apps (many of which might live in other repositories). The helper
+    mixins will provide a little syntactic sugar to make common access patterns
+    more convenient, like file access.
+    """
+
+    uuid = immutable_uuid_field()
+    learning_package = models.ForeignKey(
+        LearningPackage,
+        on_delete=models.CASCADE,
+        related_name="publishable_entities",
+    )
+
+    # "key" is a reserved word for MySQL, so we're temporarily using the column
+    # name of "_key" to avoid breaking downstream tooling. Consider renaming
+    # this later.
+    key = key_field(db_column="_key")
+
+    created = manual_date_time_field()
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+    )
+
+    class Meta:
+        constraints = [
+            # Keys are unique within a given LearningPackage.
+            models.UniqueConstraint(
+                fields=[
+                    "learning_package",
+                    "key",
+                ],
+                name="oel_pub_ent_uniq_lp_key",
+            )
+        ]
+        indexes = [
+            # Global Key Index:
+            #   * Search by key across all PublishableEntities on the site. This
+            #     would be a support-oriented tool from Django Admin.
+            models.Index(
+                fields=["key"],
+                name="oel_pub_ent_idx_key",
+            ),
+            # LearningPackage (reverse) Created Index:
+            #  * Search for most recently *created* PublishableEntities for a
+            #    given LearningPackage, since they're the most likely to be
+            #    actively worked on.
+            models.Index(
+                fields=["learning_package", "-created"],
+                name="oel_pub_ent_idx_lp_rcreated",
+            ),
+        ]
+        # These are for the Django Admin UI.
+        verbose_name = "Publishable Entity"
+        verbose_name_plural = "Publishable Entities"
+
+    def __str__(self):
+        return f"{self.key}"
+
+
+class PublishableEntityVersion(models.Model):
+    """
+    A particular version of a PublishableEntity.
+
+    This model has its own ``uuid`` so that it can be referenced directly. The
+    ``uuid`` should be treated as immutable.
+
+    PublishableEntityVersions are created once and never updated. So for
+    instance, the ``title`` should never be modified.
+
+    Like PublishableEntity, the data in this model is only enough to cover the
+    parts that are most important for the actual process of managing drafts and
+    publishes. You will want to create your own models to represent the actual
+    content data that's associated with this PublishableEntityVersion, and
+    connect them using a OneToOneField with primary_key=True. The easiest way to
+    do this is to inherit from PublishableEntityVersionMixin. Be sure to treat
+    these versioned models in your app as immutable as well.
+    """
+
+    uuid = immutable_uuid_field()
+    entity = models.ForeignKey(
+        PublishableEntity, on_delete=models.CASCADE, related_name="versions"
+    )
+
+    # Most publishable things will have some sort of title, but blanks are
+    # allowed for those that don't require one.
+    title = case_insensitive_char_field(max_length=500, blank=True, default="")
+
+    # The version_num starts at 1 and increments by 1 with each new version for
+    # a given PublishableEntity. Doing it this way makes it more convenient for
+    # users to refer to than a hash or UUID value. It also helps us catch race
+    # conditions on save, by setting a unique constraint on the entity and
+    # version_num.
+    version_num = models.PositiveIntegerField(
+        null=False,
+        validators=[MinValueValidator(1)],
+    )
 
-__all__ = [
-    "PublishableEntityMixin",
-    "PublishableEntityVersionMixin",
-    "PublishableContentModelRegistry",
-]
+    # All PublishableEntityVersions created as part of the same publish should
+    # have the exact same created datetime (not off by a handful of
+    # microseconds).
+    created = manual_date_time_field()
+
+    # User who created the PublishableEntityVersion. This can be null if the
+    # user is later removed. Open edX in general doesn't let you remove users,
+    # but we should try to model it so that this is possible eventually.
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+    )
+
+    class Meta:
+        constraints = [
+            # Prevent the situation where we have multiple
+            # PublishableEntityVersions claiming to be the same version_num for
+            # a given PublishableEntity. This can happen if there's a race
+            # condition between concurrent editors in different browsers,
+            # working on the same Publishable. With this constraint, one of
+            # those processes will raise an IntegrityError.
+            models.UniqueConstraint(
+                fields=[
+                    "entity",
+                    "version_num",
+                ],
+                name="oel_pv_uniq_entity_version_num",
+            )
+        ]
+        indexes = [
+            # LearningPackage (reverse) Created Index:
+            #   * Make it cheap to find the most recently created
+            #     PublishableEntityVersions for a given LearningPackage. This
+            #     represents the most recently saved work for a LearningPackage
+            #     and would be the most likely areas to get worked on next.
+            models.Index(
+                fields=["entity", "-created"],
+                name="oel_pv_idx_entity_rcreated",
+            ),
+            # Title Index:
+            #   * Search by title.
+            models.Index(
+                fields=[
+                    "title",
+                ],
+                name="oel_pv_idx_title",
+            ),
+        ]
+
+        # These are for the Django Admin UI.
+        verbose_name = "Publishable Entity Version"
+        verbose_name_plural = "Publishable Entity Versions"
 
 
 class PublishableEntityMixin(models.Model):
@@ -28,17 +267,12 @@ class PublishableEntityMixin(models.Model):
     the publishing app's api.register_content_models (see its docstring for
     details).
     """
-
-    class PublishableEntityMixinManager(models.Manager):
-        def get_queryset(self) -> QuerySet:
-            return super().get_queryset() \
-                          .select_related(
-                              "publishable_entity",
-                              "publishable_entity__published",
-                              "publishable_entity__draft",
-                          )
-
-    objects: models.Manager[PublishableEntityMixin] = PublishableEntityMixinManager()
+    # select these related entities by default for all queries
+    objects: ClassVar[WithRelationsManager[Self]] = WithRelationsManager(
+        "publishable_entity",
+        "publishable_entity__published",
+        "publishable_entity__draft",
+    )
 
     publishable_entity = models.OneToOneField(
         PublishableEntity, on_delete=models.CASCADE, primary_key=True
@@ -49,15 +283,15 @@ class PublishableEntityMixin(models.Model):
         return self.VersioningHelper(self)
 
     @property
-    def uuid(self):
+    def uuid(self) -> str:
         return self.publishable_entity.uuid
 
     @property
-    def key(self):
+    def key(self) -> str:
         return self.publishable_entity.key
 
     @property
-    def created(self):
+    def created(self) -> datetime:
         return self.publishable_entity.created
 
     @property
@@ -137,11 +371,24 @@ class PublishableEntityMixin(models.Model):
             field_to_pev = self.content_version_model_cls._meta.get_field(
                 "publishable_entity_version"
             )
-
             # Now that we know the field that leads to PublishableEntityVersion,
             # get the reverse related field name so that we can use that later.
             self.related_name = field_to_pev.related_query_name()
 
+            if field_to_pev.model != self.content_version_model_cls:
+                # In the case of multi-table inheritance and mixins, this can get tricky.
+                # Example:
+                #   content_version_model_cls is UnitVersion, which is a subclass of ContainerVersion
+                # This versioning helper can be accessed via unit_version.versioning (should return UnitVersion) or
+                # via container_version.versioning (should return ContainerVersion)
+                intermediate_model = field_to_pev.model  # example: ContainerVersion
+                # This is the field on the subclass (e.g. UnitVersion) that gets
+                # the intermediate (e.g. ContainerVersion). Example: "UnitVersion.container_version" (1:1 foreign key)
+                field_to_intermediate = self.content_version_model_cls._meta.get_ancestor_link(intermediate_model)
+                if field_to_intermediate:
+                    # Example: self.related_name = "containerversion.unitversion"
+                    self.related_name = self.related_name + "." + field_to_intermediate.related_query_name()
+
         def _content_obj_version(self, pub_ent_version: PublishableEntityVersion | None):
             """
             PublishableEntityVersion -> Content object version
@@ -151,7 +398,10 @@ class PublishableEntityMixin(models.Model):
             """
             if pub_ent_version is None:
                 return None
-            return getattr(pub_ent_version, self.related_name)
+            obj = pub_ent_version
+            for field_name in self.related_name.split("."):
+                obj = getattr(obj, field_name)
+            return obj
 
         @property
         def draft(self):
@@ -294,36 +544,29 @@ class PublishableEntityVersionMixin(models.Model):
     details).
     """
 
-    class PublishableEntityVersionMixinManager(models.Manager):
-        def get_queryset(self) -> QuerySet:
-            return (
-                super()
-                .get_queryset()
-                .select_related(
-                    "publishable_entity_version",
-                )
-            )
-
-    objects: models.Manager[PublishableEntityVersionMixin] = PublishableEntityVersionMixinManager()
+    # select these related entities by default for all queries
+    objects: ClassVar[WithRelationsManager[Self]] = WithRelationsManager(
+        "publishable_entity_version",
+    )
 
     publishable_entity_version = models.OneToOneField(
         PublishableEntityVersion, on_delete=models.CASCADE, primary_key=True
     )
 
     @property
-    def uuid(self):
+    def uuid(self) -> str:
         return self.publishable_entity_version.uuid
 
     @property
-    def title(self):
+    def title(self) -> str:
         return self.publishable_entity_version.title
 
     @property
-    def created(self):
+    def created(self) -> datetime:
         return self.publishable_entity_version.created
 
     @property
-    def version_num(self):
+    def version_num(self) -> int:
         return self.publishable_entity_version.version_num
 
     class Meta:

openedx_learning/apps/authoring/units/api.py

@@ -0,0 +1,290 @@
+"""Units API.
+
+This module provides functions to manage units.
+"""
+from dataclasses import dataclass
+from datetime import datetime
+
+from django.db.transaction import atomic
+
+from openedx_learning.apps.authoring.components.models import Component, ComponentVersion
+
+from ..publishing import api as publishing_api
+from .models import Unit, UnitVersion
+
+# 🛑 UNSTABLE: All APIs related to containers are unstable until we've figured
+#              out our approach to dynamic content (randomized, A/B tests, etc.)
+__all__ = [
+    "create_unit",
+    "create_unit_version",
+    "create_next_unit_version",
+    "create_unit_and_version",
+    "get_unit",
+    "get_unit_version",
+    "get_latest_unit_version",
+    "UnitListEntry",
+    "get_components_in_unit",
+    "get_components_in_unit",
+    "get_components_in_published_unit_as_of",
+]
+
+
+def create_unit(
+    learning_package_id: int, key: str, created: datetime, created_by: int | None
+) -> Unit:
+    """
+    [ 🛑 UNSTABLE ] Create a new unit.
+
+    Args:
+        learning_package_id: The learning package ID.
+        key: The key.
+        created: The creation date.
+        created_by: The user who created the unit.
+    """
+    return publishing_api.create_container(
+        learning_package_id,
+        key,
+        created,
+        created_by,
+        container_cls=Unit,
+    )
+
+
+def create_unit_version(
+    unit: Unit,
+    version_num: int,
+    *,
+    title: str,
+    publishable_entities_pks: list[int],
+    entity_version_pks: list[int | None],
+    created: datetime,
+    created_by: int | None = None,
+) -> UnitVersion:
+    """
+    [ 🛑 UNSTABLE ] Create a new unit version.
+
+    This is a very low-level API, likely only needed for import/export. In
+    general, you will use `create_unit_and_version()` and
+    `create_next_unit_version()` instead.
+
+    Args:
+        unit_pk: The unit ID.
+        version_num: The version number.
+        title: The title.
+        publishable_entities_pk: The publishable entities.
+        entity: The entity.
+        created: The creation date.
+        created_by: The user who created the unit.
+    """
+    return publishing_api.create_container_version(
+        unit.pk,
+        version_num,
+        title=title,
+        publishable_entities_pks=publishable_entities_pks,
+        entity_version_pks=entity_version_pks,
+        created=created,
+        created_by=created_by,
+        container_version_cls=UnitVersion,
+    )
+
+
+def _pub_entities_for_components(
+    components: list[Component | ComponentVersion] | None,
+) -> tuple[list[int], list[int | None]] | tuple[None, None]:
+    """
+    Helper method: given a list of Component | ComponentVersion, return the
+    lists of publishable_entities_pks and entity_version_pks needed for the
+    base container APIs.
+
+    ComponentVersion is passed when we want to pin a specific version, otherwise
+    Component is used for unpinned.
+    """
+    if components is None:
+        # When these are None, that means don't change the entities in the list.
+        return None, None
+    for c in components:
+        if not isinstance(c, (Component, ComponentVersion)):
+            raise TypeError("Unit components must be either Component or ComponentVersion.")
+    publishable_entities_pks = [
+        (c.publishable_entity_id if isinstance(c, Component) else c.component.publishable_entity_id)
+        for c in components
+    ]
+    entity_version_pks = [
+        (cv.pk if isinstance(cv, ComponentVersion) else None)
+        for cv in components
+    ]
+    return publishable_entities_pks, entity_version_pks
+
+
+def create_next_unit_version(
+    unit: Unit,
+    *,
+    title: str | None = None,
+    components: list[Component | ComponentVersion] | None = None,
+    created: datetime,
+    created_by: int | None = None,
+) -> UnitVersion:
+    """
+    [ 🛑 UNSTABLE ] Create the next unit version.
+
+    Args:
+        unit_pk: The unit ID.
+        title: The title. Leave as None to keep the current title.
+        components: The components, as a list of Components (unpinned) and/or ComponentVersions (pinned). Passing None
+           will leave the existing components unchanged.
+        created: The creation date.
+        created_by: The user who created the unit.
+    """
+    publishable_entities_pks, entity_version_pks = _pub_entities_for_components(components)
+    unit_version = publishing_api.create_next_container_version(
+        unit.pk,
+        title=title,
+        publishable_entities_pks=publishable_entities_pks,
+        entity_version_pks=entity_version_pks,
+        created=created,
+        created_by=created_by,
+        container_version_cls=UnitVersion,
+    )
+    return unit_version
+
+
+def create_unit_and_version(
+    learning_package_id: int,
+    key: str,
+    *,
+    title: str,
+    components: list[Component | ComponentVersion] | None = None,
+    created: datetime,
+    created_by: int | None = None,
+) -> tuple[Unit, UnitVersion]:
+    """
+    [ 🛑 UNSTABLE ] Create a new unit and its version.
+
+    Args:
+        learning_package_id: The learning package ID.
+        key: The key.
+        created: The creation date.
+        created_by: The user who created the unit.
+    """
+    publishable_entities_pks, entity_version_pks = _pub_entities_for_components(components)
+    with atomic():
+        unit = create_unit(learning_package_id, key, created, created_by)
+        unit_version = create_unit_version(
+            unit,
+            1,
+            title=title,
+            publishable_entities_pks=publishable_entities_pks or [],
+            entity_version_pks=entity_version_pks or [],
+            created=created,
+            created_by=created_by,
+        )
+    return unit, unit_version
+
+
+def get_unit(unit_pk: int) -> Unit:
+    """
+    [ 🛑 UNSTABLE ] Get a unit.
+
+    Args:
+        unit_pk: The unit ID.
+    """
+    return Unit.objects.get(pk=unit_pk)
+
+
+def get_unit_version(unit_version_pk: int) -> UnitVersion:
+    """
+    [ 🛑 UNSTABLE ] Get a unit version.
+
+    Args:
+        unit_version_pk: The unit version ID.
+    """
+    return UnitVersion.objects.get(pk=unit_version_pk)
+
+
+def get_latest_unit_version(unit_pk: int) -> UnitVersion:
+    """
+    [ 🛑 UNSTABLE ] Get the latest unit version.
+
+    Args:
+        unit_pk: The unit ID.
+    """
+    return Unit.objects.get(pk=unit_pk).versioning.latest
+
+
+@dataclass(frozen=True)
+class UnitListEntry:
+    """
+    [ 🛑 UNSTABLE ]
+    Data about a single entity in a container, e.g. a component in a unit.
+    """
+    component_version: ComponentVersion
+    pinned: bool = False
+
+    @property
+    def component(self):
+        return self.component_version.component
+
+
+def get_components_in_unit(
+    unit: Unit,
+    *,
+    published: bool,
+) -> list[UnitListEntry]:
+    """
+    [ 🛑 UNSTABLE ]
+    Get the list of entities and their versions in the draft or published
+    version of the given Unit.
+
+    Args:
+        unit: The Unit, e.g. returned by `get_unit()`
+        published: `True` if we want the published version of the unit, or
+            `False` for the draft version.
+    """
+    assert isinstance(unit, Unit)
+    components = []
+    for entry in publishing_api.get_entities_in_container(unit, published=published):
+        # Convert from generic PublishableEntityVersion to ComponentVersion:
+        component_version = entry.entity_version.componentversion
+        assert isinstance(component_version, ComponentVersion)
+        components.append(UnitListEntry(component_version=component_version, pinned=entry.pinned))
+    return components
+
+
+def get_components_in_published_unit_as_of(
+    unit: Unit,
+    publish_log_id: int,
+) -> list[UnitListEntry] | None:
+    """
+    [ 🛑 UNSTABLE ]
+    Get the list of entities and their versions in the published version of the
+    given container as of the given PublishLog version (which is essentially a
+    version for the entire learning package).
+
+    TODO: This API should be updated to also return the UnitVersion so we can
+          see the unit title and any other metadata from that point in time.
+    TODO: accept a publish log UUID, not just int ID?
+    TODO: move the implementation to be a generic 'containers' implementation
+          that this units function merely wraps.
+    TODO: optimize, perhaps by having the publishlog store a record of all
+          ancestors of every modified PublishableEntity in the publish.
+    """
+    assert isinstance(unit, Unit)
+    unit_pub_entity_version = publishing_api.get_published_version_as_of(unit.publishable_entity_id, publish_log_id)
+    if unit_pub_entity_version is None:
+        return None  # This unit was not published as of the given PublishLog ID.
+    container_version = unit_pub_entity_version.containerversion
+
+    entity_list = []
+    rows = container_version.entity_list.entitylistrow_set.order_by("order_num")
+    for row in rows:
+        if row.entity_version is not None:
+            component_version = row.entity_version.componentversion
+            assert isinstance(component_version, ComponentVersion)
+            entity_list.append(UnitListEntry(component_version=component_version, pinned=True))
+        else:
+            # Unpinned component - figure out what its latest published version was.
+            # This is not optimized. It could be done in one query per unit rather than one query per component.
+            pub_entity_version = publishing_api.get_published_version_as_of(row.entity_id, publish_log_id)
+            if pub_entity_version:
+                entity_list.append(UnitListEntry(component_version=pub_entity_version.componentversion, pinned=False))
+    return entity_list