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

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/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,
+)

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

@@ -0,0 +1,70 @@
+"""
+Container and ContainerVersion models
+"""
+from django.core.exceptions import ValidationError
+from django.db import models
+
+from .entity_list import EntityList
+from .publishable_entity import PublishableEntityMixin, PublishableEntityVersionMixin
+
+
+class Container(PublishableEntityMixin):
+    """
+    A Container is a type of PublishableEntity that holds other
+    PublishableEntities. For example, a "Unit" Container might hold several
+    Components.
+
+    For now, all containers have a static "entity list" that defines which
+    containers/components/enities they hold. As we complete the Containers API,
+    we will also add support for dynamic containers which may contain different
+    entities for different learners or at different times.
+
+    NOTE: We're going to want to eventually have some association between the
+    PublishLog and Containers that were affected in a publish because their
+    child elements were published.
+    """
+
+
+class ContainerVersion(PublishableEntityVersionMixin):
+    """
+    A version of a Container.
+
+    By convention, we would only want to create new versions when the Container
+    itself changes, and not when the Container's child elements change. For
+    example:
+
+    * Something was added to the Container.
+    * We re-ordered the rows in the container.
+    * Something was removed to the container.
+    * The Container's metadata changed, e.g. the title.
+    * We pin to different versions of the Container.
+
+    The last looks a bit odd, but it's because *how we've defined the Unit* has
+    changed if we decide to explicitly pin a set of versions for the children,
+    and then later change our minds and move to a different set. It also just
+    makes things easier to reason about if we say that entity_list never
+    changes for a given ContainerVersion.
+    """
+
+    container = models.ForeignKey(
+        Container,
+        on_delete=models.CASCADE,
+        related_name="versions",
+    )
+
+    # The list of entities (frozen and/or unfrozen) in this container
+    entity_list = models.ForeignKey(
+        EntityList,
+        on_delete=models.RESTRICT,
+        null=False,
+        related_name="container_versions",
+    )
+
+    def clean(self):
+        """
+        Validate this model before saving. Not called normally, but will be
+        called if anything is edited via a ModelForm like the Django admin.
+        """
+        super().clean()
+        if self.container_id != self.publishable_entity_version.entity.container.pk:  # pylint: disable=no-member
+            raise ValidationError("Inconsistent foreign keys to Container")

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

@@ -0,0 +1,95 @@
+"""
+Draft and Published models
+"""
+from django.db import models
+
+from .publish_log import PublishLogRecord
+from .publishable_entity import PublishableEntity, PublishableEntityVersion
+
+
+class Draft(models.Model):
+    """
+    Find the active draft version of an entity (usually most recently created).
+
+    This model mostly only exists to allow us to join against a bunch of
+    PublishableEntity objects at once and get all their latest drafts. You might
+    use this together with Published in order to see which Drafts haven't been
+    published yet.
+
+    A Draft entry should be created whenever a new PublishableEntityVersion is
+    created. This means there are three possible states:
+
+    1. No Draft entry for a PublishableEntity: This means a PublishableEntity
+       was created, but no PublishableEntityVersion was ever made for it, so
+       there was never a Draft version.
+    2. A Draft entry exists and points to a PublishableEntityVersion: This is
+       the most common state.
+    3. A Draft entry exists and points to a null version: This means a version
+       used to be the draft, but it's been functionally "deleted". The versions
+       still exist in our history, but we're done using it.
+
+    It would have saved a little space to add this data to the Published model
+    (and possibly call the combined model something else). Split Modulestore did
+    this with its active_versions table. I keep it separate here to get a better
+    separation of lifecycle events: i.e. this table *only* changes when drafts
+    are updated, not when publishing happens. The Published model only changes
+    when something is published.
+    """
+    # If we're removing a PublishableEntity entirely, also remove the Draft
+    # entry for it. This isn't a normal operation, but can happen if you're
+    # deleting an entire LearningPackage.
+    entity = models.OneToOneField(
+        PublishableEntity,
+        on_delete=models.CASCADE,
+        primary_key=True,
+    )
+    version = models.OneToOneField(
+        PublishableEntityVersion,
+        on_delete=models.RESTRICT,
+        null=True,
+        blank=True,
+    )
+
+
+class Published(models.Model):
+    """
+    Find the currently published version of an entity.
+
+    Notes:
+
+    * There is only ever one published PublishableEntityVersion per
+      PublishableEntity at any given time.
+    * It may be possible for a PublishableEntity to exist only as a Draft (and thus
+      not show up in this table).
+    * If a row exists for a PublishableEntity, but the ``version`` field is
+      None, it means that the entity was published at some point, but is no
+      longer published now–i.e. it's functionally "deleted", even though all
+      the version history is preserved behind the scenes.
+
+    TODO: Do we need to create a (redundant) title field in this model so that
+    we can more efficiently search across titles within a LearningPackage?
+    Probably not an immediate concern because the number of rows currently
+    shouldn't be > 10,000 in the more extreme cases.
+
+    TODO: Do we need to make a "most_recently" published version when an entry
+    is unpublished/deleted?
+    """
+
+    entity = models.OneToOneField(
+        PublishableEntity,
+        on_delete=models.CASCADE,
+        primary_key=True,
+    )
+    version = models.OneToOneField(
+        PublishableEntityVersion,
+        on_delete=models.RESTRICT,
+        null=True,
+    )
+    publish_log_record = models.ForeignKey(
+        PublishLogRecord,
+        on_delete=models.RESTRICT,
+    )
+
+    class Meta:
+        verbose_name = "Published Entity"
+        verbose_name_plural = "Published Entities"

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

@@ -0,0 +1,69 @@
+"""
+Entity List models
+"""
+from django.db import models
+
+from .publishable_entity import PublishableEntity, PublishableEntityVersion
+
+
+class EntityList(models.Model):
+    """
+    EntityLists are a common structure to hold parent-child relations.
+
+    EntityLists are not PublishableEntities in and of themselves. That's because
+    sometimes we'll want the same kind of data structure for things that we
+    dynamically generate for individual students (e.g. Variants). EntityLists are
+    anonymous in a sense–they're pointed to by ContainerVersions and
+    other models, rather than being looked up by their own identifiers.
+    """
+
+
+class EntityListRow(models.Model):
+    """
+    Each EntityListRow points to a PublishableEntity, optionally at a specific
+    version.
+
+    There is a row in this table for each member of an EntityList. The order_num
+    field is used to determine the order of the members in the list.
+    """
+
+    entity_list = models.ForeignKey(EntityList, on_delete=models.CASCADE)
+
+    # This ordering should be treated as immutable–if the ordering needs to
+    # change, we create a new EntityList and copy things over.
+    order_num = models.PositiveIntegerField()
+
+    # Simple case would use these fields with our convention that null versions
+    # means "get the latest draft or published as appropriate". These entities
+    # could be Selectors, in which case we'd need to do more work to find the right
+    # variant. The publishing app itself doesn't know anything about Selectors
+    # however, and just treats it as another PublishableEntity.
+    entity = models.ForeignKey(PublishableEntity, on_delete=models.RESTRICT)
+
+    # The version references point to the specific PublishableEntityVersion that
+    # this EntityList has for this PublishableEntity for both the draft and
+    # published states. However, we don't want to have to create new EntityList
+    # every time that a member is updated, because that would waste a lot of
+    # space and make it difficult to figure out when the metadata of something
+    # like a Unit *actually* changed, vs. when its child members were being
+    # updated. Doing so could also potentially lead to race conditions when
+    # updating multiple layers of containers.
+    #
+    # So our approach to this is to use a value of None (null) to represent an
+    # unpinned reference to a PublishableEntity. It's shorthand for "just use
+    # the latest draft or published version of this, as appropriate".
+    entity_version = models.ForeignKey(
+        PublishableEntityVersion,
+        on_delete=models.RESTRICT,
+        null=True,
+        related_name="+",  # Do we need the reverse relation?
+    )
+
+    class Meta:
+        constraints = [
+            # If (entity_list, order_num) is not unique, it likely indicates a race condition - so force uniqueness.
+            models.UniqueConstraint(
+                fields=["entity_list", "order_num"],
+                name="oel_publishing_elist_row_order",
+            ),
+        ]

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

@@ -0,0 +1,75 @@
+"""
+LearningPackage model
+"""
+from django.db import models
+
+from openedx_learning.lib.fields import (
+    MultiCollationTextField,
+    case_insensitive_char_field,
+    immutable_uuid_field,
+    key_field,
+    manual_date_time_field,
+)
+
+
+class LearningPackage(models.Model):
+    """
+    Top level container for a grouping of authored content.
+
+    Each PublishableEntity belongs to exactly one LearningPackage.
+    """
+    # Explictly declare a 4-byte ID instead of using the app-default 8-byte ID.
+    # We do not expect to have more than 2 billion LearningPackages on a given
+    # site. Furthermore, many, many things have foreign keys to this model and
+    # uniqueness indexes on those foreign keys + their own fields, so the 4
+    # bytes saved will add up over time.
+    id = models.AutoField(primary_key=True)
+
+    uuid = immutable_uuid_field()
+
+    # "key" is a reserved word for MySQL, so we're temporarily using the column
+    # name of "_key" to avoid breaking downstream tooling. There's an open
+    # question as to whether this field needs to exist at all, or whether the
+    # top level library key it's currently used for should be entirely in the
+    # LibraryContent model.
+    key = key_field(db_column="_key")
+
+    title = case_insensitive_char_field(max_length=500, blank=False)
+
+    # TODO: We should probably defer this field, since many things pull back
+    # LearningPackage as select_related. Usually those relations only care about
+    # the UUID and key, so maybe it makes sense to separate the model at some
+    # point.
+    description = MultiCollationTextField(
+        blank=True,
+        null=False,
+        default="",
+        max_length=10_000,
+        # We don't really expect to ever sort by the text column, but we may
+        # want to do case-insensitive searches, so it's useful to have a case
+        # and accent insensitive collation.
+        db_collations={
+            "sqlite": "NOCASE",
+            "mysql": "utf8mb4_unicode_ci",
+        }
+    )
+
+    created = manual_date_time_field()
+    updated = manual_date_time_field()
+
+    def __str__(self):
+        return f"{self.key}"
+
+    class Meta:
+        constraints = [
+            # LearningPackage keys must be globally unique. This is something
+            # that might be relaxed in the future if this system were to be
+            # extensible to something like multi-tenancy, in which case we'd tie
+            # it to something like a Site or Org.
+            models.UniqueConstraint(
+                fields=["key"],
+                name="oel_publishing_lp_uniq_key",
+            )
+        ]
+        verbose_name = "Learning Package"
+        verbose_name_plural = "Learning Packages"

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

@@ -0,0 +1,106 @@
+"""
+PublishLog and PublishLogRecord models
+"""
+from django.conf import settings
+from django.db import models
+
+from openedx_learning.lib.fields import case_insensitive_char_field, immutable_uuid_field, manual_date_time_field
+
+from .learning_package import LearningPackage
+from .publishable_entity import PublishableEntity, PublishableEntityVersion
+
+
+class PublishLog(models.Model):
+    """
+    There is one row in this table for every time content is published.
+
+    Each PublishLog has 0 or more PublishLogRecords describing exactly which
+    PublishableEntites were published and what the version changes are. A
+    PublishLog is like a git commit in that sense, with individual
+    PublishLogRecords representing the files changed.
+
+    Open question: Empty publishes are allowed at this time, and might be useful
+    for "fake" publishes that are necessary to invoke other post-publish
+    actions. It's not clear at this point how useful this will actually be.
+
+    The absence of a ``version_num`` field in this model is intentional, because
+    having one would potentially cause write contention/locking issues when
+    there are many people working on different entities in a very large library.
+    We already see some contention issues occuring in ModuleStore for courses,
+    and we want to support Libraries that are far larger.
+
+    If you need a LearningPackage-wide indicator for version and the only thing
+    you care about is "has *something* changed?", you can make a foreign key to
+    the most recent PublishLog, or use the most recent PublishLog's primary key.
+    This should be monotonically increasing, though there will be large gaps in
+    values, e.g. (5, 190, 1291, etc.). Be warned that this value will not port
+    across sites. If you need site-portability, the UUIDs for this model are a
+    safer bet, though there's a lot about import/export that we haven't fully
+    mapped out yet.
+    """
+
+    uuid = immutable_uuid_field()
+    learning_package = models.ForeignKey(LearningPackage, on_delete=models.CASCADE)
+    message = case_insensitive_char_field(max_length=500, blank=True, default="")
+    published_at = manual_date_time_field()
+    published_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+    )
+
+    class Meta:
+        verbose_name = "Publish Log"
+        verbose_name_plural = "Publish Logs"
+
+
+class PublishLogRecord(models.Model):
+    """
+    A record for each publishable entity version changed, for each publish.
+
+    To revert a publish, we would make a new publish that swaps ``old_version``
+    and ``new_version`` field values.
+    """
+
+    publish_log = models.ForeignKey(
+        PublishLog,
+        on_delete=models.CASCADE,
+        related_name="records",
+    )
+    entity = models.ForeignKey(PublishableEntity, on_delete=models.RESTRICT)
+    old_version = models.ForeignKey(
+        PublishableEntityVersion,
+        on_delete=models.RESTRICT,
+        null=True,
+        blank=True,
+        related_name="+",
+    )
+    new_version = models.ForeignKey(
+        PublishableEntityVersion, on_delete=models.RESTRICT, null=True, blank=True
+    )
+
+    class Meta:
+        constraints = [
+            # A Publishable can have only one PublishLogRecord per PublishLog.
+            # You can't simultaneously publish two different versions of the
+            # same publishable.
+            models.UniqueConstraint(
+                fields=[
+                    "publish_log",
+                    "entity",
+                ],
+                name="oel_plr_uniq_pl_publishable",
+            )
+        ]
+        indexes = [
+            # Publishable (reverse) Publish Log Index:
+            #   * Find the history of publishes for a given Publishable,
+            #     starting with the most recent (since IDs are ascending ints).
+            models.Index(
+                fields=["entity", "-publish_log"],
+                name="oel_plr_idx_entity_rplr",
+            ),
+        ]
+        verbose_name = "Publish Log Record"
+        verbose_name_plural = "Publish Log Records"