openedx-learning 0.23.1__py2.py3-none-any.whl → 0.25.0__py2.py3-none-any.whl

openedx_learning/__init__.py

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

openedx_learning/api/authoring.py

@@ -13,6 +13,8 @@ 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.sections.api import *
+from ..apps.authoring.subsections.api import *
 from ..apps.authoring.units.api import *
 
 # This was renamed after the authoring API refactoring pushed this and other

openedx_learning/api/authoring_models.py

@@ -11,4 +11,6 @@ from ..apps.authoring.collections.models import *
 from ..apps.authoring.components.models import *
 from ..apps.authoring.contents.models import *
 from ..apps.authoring.publishing.models import *
+from ..apps.authoring.sections.models import *
+from ..apps.authoring.subsections.models import *
 from ..apps.authoring.units.models import *

openedx_learning/apps/authoring/publishing/api.py

@@ -1322,7 +1322,10 @@ def contains_unpublished_changes(container_id: int) -> bool:
         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
+    entity_list = getattr(container.versioning.draft, "entity_list", None)
+    if entity_list is None:
+        # This container has been soft-deleted, so it has no children.
+        return False
 
     # 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
@@ -1367,23 +1370,16 @@ def get_containers_with_entity(
         ignore_pinned: if true, ignore any pinned references to the entity.
     """
     if ignore_pinned:
-        # TODO: Do we need to run distinct() on this? Will fix in https://github.com/openedx/openedx-learning/issues/303
         qs = Container.objects.filter(
             # Note: these two conditions must be in the same filter() call, or the query won't be correct.
             publishable_entity__draft__version__containerversion__entity_list__entitylistrow__entity_id=publishable_entity_pk,  # pylint: disable=line-too-long # noqa: E501
             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
+        )
+    return qs.order_by("pk").distinct()  # Ordering is mostly for consistent test cases.
 
 
 def get_container_children_count(

openedx_learning/apps/authoring/publishing/migrations/0008_alter_draftchangelogrecord_options_and_more.py

@@ -1,7 +1,6 @@
 # Generated by Django 4.2.20 on 2025-04-17 18:22
-
-from django.db import migrations, models
 import django.db.models.deletion
+from django.db import migrations, models
 
 
 class Migration(migrations.Migration):

openedx_learning/apps/authoring/sections/api.py

@@ -0,0 +1,310 @@
+"""Sections API.
+
+This module provides functions to manage sections.
+"""
+from dataclasses import dataclass
+from datetime import datetime
+
+from django.db.transaction import atomic
+
+from openedx_learning.apps.authoring.subsections.models import Subsection, SubsectionVersion
+
+from ..publishing import api as publishing_api
+from .models import Section, SectionVersion
+
+# 🛑 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_section",
+    "create_section_version",
+    "create_next_section_version",
+    "create_section_and_version",
+    "get_section",
+    "get_section_version",
+    "get_latest_section_version",
+    "SectionListEntry",
+    "get_subsections_in_section",
+    "get_subsections_in_section",
+    "get_subsections_in_published_section_as_of",
+]
+
+
+def create_section(
+    learning_package_id: int,
+    key: str,
+    created: datetime,
+    created_by: int | None,
+    *,
+    can_stand_alone: bool = True,
+) -> Section:
+    """
+    [ 🛑 UNSTABLE ] Create a new section.
+
+    Args:
+        learning_package_id: The learning package ID.
+        key: The key.
+        created: The creation date.
+        created_by: The user who created the section.
+        can_stand_alone: Set to False when created as part of containers
+    """
+    return publishing_api.create_container(
+        learning_package_id,
+        key,
+        created,
+        created_by,
+        can_stand_alone=can_stand_alone,
+        container_cls=Section,
+    )
+
+
+def create_section_version(
+    section: Section,
+    version_num: int,
+    *,
+    title: str,
+    entity_rows: list[publishing_api.ContainerEntityRow],
+    created: datetime,
+    created_by: int | None = None,
+) -> SectionVersion:
+    """
+    [ 🛑 UNSTABLE ] Create a new section version.
+
+    This is a very low-level API, likely only needed for import/export. In
+    general, you will use `create_section_and_version()` and
+    `create_next_section_version()` instead.
+
+    Args:
+        section_pk: The section ID.
+        version_num: The version number.
+        title: The title.
+        entity_rows: child entities/versions
+        created: The creation date.
+        created_by: The user who created the section.
+    """
+    return publishing_api.create_container_version(
+        section.pk,
+        version_num,
+        title=title,
+        entity_rows=entity_rows,
+        created=created,
+        created_by=created_by,
+        container_version_cls=SectionVersion,
+    )
+
+
+def _pub_entities_for_subsections(
+    subsections: list[Subsection | SubsectionVersion] | None,
+) -> list[publishing_api.ContainerEntityRow] | None:
+    """
+    Helper method: given a list of Subsection | SubsectionVersion, return the
+    lists of publishable_entities_pks and entity_version_pks needed for the
+    base container APIs.
+
+    SubsectionVersion is passed when we want to pin a specific version, otherwise
+    Subsection is used for unpinned.
+    """
+    if subsections is None:
+        # When these are None, that means don't change the entities in the list.
+        return None
+    for u in subsections:
+        if not isinstance(u, (Subsection, SubsectionVersion)):
+            raise TypeError("Section subsections must be either Subsection or SubsectionVersion.")
+    return [
+        (
+            publishing_api.ContainerEntityRow(
+                entity_pk=s.container.publishable_entity_id,
+                version_pk=None,
+            ) if isinstance(s, Subsection)
+            else publishing_api.ContainerEntityRow(
+                entity_pk=s.subsection.container.publishable_entity_id,
+                version_pk=s.container_version.publishable_entity_version_id,
+            )
+        )
+        for s in subsections
+    ]
+
+
+def create_next_section_version(
+    section: Section,
+    *,
+    title: str | None = None,
+    subsections: list[Subsection | SubsectionVersion] | None = None,
+    created: datetime,
+    created_by: int | None = None,
+    entities_action: publishing_api.ChildrenEntitiesAction = publishing_api.ChildrenEntitiesAction.REPLACE,
+) -> SectionVersion:
+    """
+    [ 🛑 UNSTABLE ] Create the next section version.
+
+    Args:
+        section_pk: The section ID.
+        title: The title. Leave as None to keep the current title.
+        subsections: The subsections, as a list of Subsections (unpinned) and/or SubsectionVersions (pinned).
+            Passing None will leave the existing subsections unchanged.
+        created: The creation date.
+        created_by: The user who created the section.
+    """
+    entity_rows = _pub_entities_for_subsections(subsections)
+    section_version = publishing_api.create_next_container_version(
+        section.pk,
+        title=title,
+        entity_rows=entity_rows,
+        created=created,
+        created_by=created_by,
+        container_version_cls=SectionVersion,
+        entities_action=entities_action,
+    )
+    return section_version
+
+
+def create_section_and_version(
+    learning_package_id: int,
+    key: str,
+    *,
+    title: str,
+    subsections: list[Subsection | SubsectionVersion] | None = None,
+    created: datetime,
+    created_by: int | None = None,
+    can_stand_alone: bool = True,
+) -> tuple[Section, SectionVersion]:
+    """
+    [ 🛑 UNSTABLE ] Create a new section 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 section.
+        can_stand_alone: Set to False when created as part of containers
+    """
+    entity_rows = _pub_entities_for_subsections(subsections)
+    with atomic():
+        section = create_section(
+            learning_package_id,
+            key,
+            created,
+            created_by,
+            can_stand_alone=can_stand_alone,
+        )
+        section_version = create_section_version(
+            section,
+            1,
+            title=title,
+            entity_rows=entity_rows or [],
+            created=created,
+            created_by=created_by,
+        )
+    return section, section_version
+
+
+def get_section(section_pk: int) -> Section:
+    """
+    [ 🛑 UNSTABLE ] Get a section.
+
+    Args:
+        section_pk: The section ID.
+    """
+    return Section.objects.get(pk=section_pk)
+
+
+def get_section_version(section_version_pk: int) -> SectionVersion:
+    """
+    [ 🛑 UNSTABLE ] Get a section version.
+
+    Args:
+        section_version_pk: The section version ID.
+    """
+    return SectionVersion.objects.get(pk=section_version_pk)
+
+
+def get_latest_section_version(section_pk: int) -> SectionVersion:
+    """
+    [ 🛑 UNSTABLE ] Get the latest section version.
+
+    Args:
+        section_pk: The section ID.
+    """
+    return Section.objects.get(pk=section_pk).versioning.latest
+
+
+@dataclass(frozen=True)
+class SectionListEntry:
+    """
+    [ 🛑 UNSTABLE ]
+    Data about a single entity in a container, e.g. a subsection in a section.
+    """
+    subsection_version: SubsectionVersion
+    pinned: bool = False
+
+    @property
+    def subsection(self):
+        return self.subsection_version.subsection
+
+
+def get_subsections_in_section(
+    section: Section,
+    *,
+    published: bool,
+) -> list[SectionListEntry]:
+    """
+    [ 🛑 UNSTABLE ]
+    Get the list of entities and their versions in the draft or published
+    version of the given Section.
+
+    Args:
+        section: The Section, e.g. returned by `get_section()`
+        published: `True` if we want the published version of the section, or
+            `False` for the draft version.
+    """
+    assert isinstance(section, Section)
+    subsections = []
+    for entry in publishing_api.get_entities_in_container(section, published=published):
+        # Convert from generic PublishableEntityVersion to SubsectionVersion:
+        subsection_version = entry.entity_version.containerversion.subsectionversion
+        assert isinstance(subsection_version, SubsectionVersion)
+        subsections.append(SectionListEntry(subsection_version=subsection_version, pinned=entry.pinned))
+    return subsections
+
+
+def get_subsections_in_published_section_as_of(
+    section: Section,
+    publish_log_id: int,
+) -> list[SectionListEntry] | 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 SectionVersion so we can
+          see the section 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 sections 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(section, Section)
+    section_pub_entity_version = publishing_api.get_published_version_as_of(
+        section.publishable_entity_id, publish_log_id
+    )
+    if section_pub_entity_version is None:
+        return None  # This section was not published as of the given PublishLog ID.
+    container_version = section_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:
+            subsection_version = row.entity_version.containerversion.subsectionversion
+            assert isinstance(subsection_version, SubsectionVersion)
+            entity_list.append(SectionListEntry(subsection_version=subsection_version, pinned=True))
+        else:
+            # Unpinned subsection - figure out what its latest published version was.
+            # This is not optimized. It could be done in one query per section rather than one query per subsection.
+            pub_entity_version = publishing_api.get_published_version_as_of(row.entity_id, publish_log_id)
+            if pub_entity_version:
+                entity_list.append(SectionListEntry(
+                    subsection_version=pub_entity_version.containerversion.subsectionversion, pinned=False
+                ))
+    return entity_list

openedx_learning/apps/authoring/sections/apps.py

@@ -0,0 +1,25 @@
+"""
+Subsection Django application initialization.
+"""
+
+from django.apps import AppConfig
+
+
+class SectionsConfig(AppConfig):
+    """
+    Configuration for the subsections Django application.
+    """
+
+    name = "openedx_learning.apps.authoring.sections"
+    verbose_name = "Learning Core > Authoring > Sections"
+    default_auto_field = "django.db.models.BigAutoField"
+    label = "oel_sections"
+
+    def ready(self):
+        """
+        Register Section and SectionVersion.
+        """
+        from ..publishing.api import register_content_models  # pylint: disable=import-outside-toplevel
+        from .models import Section, SectionVersion  # pylint: disable=import-outside-toplevel
+
+        register_content_models(Section, SectionVersion)

openedx_learning/apps/authoring/sections/migrations/0001_initial.py

@@ -0,0 +1,36 @@
+# Generated by Django 4.2.20 on 2025-04-11 12:53
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('oel_publishing', '0005_alter_entitylistrow_options'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Section',
+            fields=[
+                ('container', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='oel_publishing.container')),
+            ],
+            options={
+                'abstract': False,
+            },
+            bases=('oel_publishing.container',),
+        ),
+        migrations.CreateModel(
+            name='SectionVersion',
+            fields=[
+                ('container_version', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='oel_publishing.containerversion')),
+            ],
+            options={
+                'abstract': False,
+            },
+            bases=('oel_publishing.containerversion',),
+        ),
+    ]

openedx_learning/apps/authoring/sections/models.py

@@ -0,0 +1,50 @@
+"""
+Models that implement sections
+"""
+from django.db import models
+
+from ..publishing.models import Container, ContainerVersion
+
+__all__ = [
+    "Section",
+    "SectionVersion",
+]
+
+
+class Section(Container):
+    """
+    A Section is type of Container that holds Units.
+
+    Via Container and its PublishableEntityMixin, Sections are also publishable
+    entities and can be added to other containers.
+    """
+    container = models.OneToOneField(
+        Container,
+        on_delete=models.CASCADE,
+        parent_link=True,
+        primary_key=True,
+    )
+
+
+class SectionVersion(ContainerVersion):
+    """
+    A SectionVersion is a specific version of a Section.
+
+    Via ContainerVersion and its EntityList, it defines the list of Units
+    in this version of the Section.
+    """
+    container_version = models.OneToOneField(
+        ContainerVersion,
+        on_delete=models.CASCADE,
+        parent_link=True,
+        primary_key=True,
+    )
+
+    @property
+    def section(self):
+        """ Convenience accessor to the Section this version is associated with """
+        return self.container_version.container.section  # pylint: disable=no-member
+
+    # Note: the 'publishable_entity_version' field is inherited and will appear on this model, but does not exist
+    # in the underlying database table. It only exists in the ContainerVersion table.
+    # You can verify this by running 'python manage.py sqlmigrate oel_sections 0001_initial'

openedx_learning/apps/authoring/subsections/api.py

@@ -0,0 +1,309 @@
+"""Subsections API.
+
+This module provides functions to manage subsections.
+"""
+from dataclasses import dataclass
+from datetime import datetime
+
+from django.db.transaction import atomic
+
+from openedx_learning.apps.authoring.units.models import Unit, UnitVersion
+
+from ..publishing import api as publishing_api
+from .models import Subsection, SubsectionVersion
+
+# 🛑 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_subsection",
+    "create_subsection_version",
+    "create_next_subsection_version",
+    "create_subsection_and_version",
+    "get_subsection",
+    "get_subsection_version",
+    "get_latest_subsection_version",
+    "SubsectionListEntry",
+    "get_units_in_subsection",
+    "get_units_in_subsection",
+    "get_units_in_published_subsection_as_of",
+]
+
+
+def create_subsection(
+    learning_package_id: int,
+    key: str,
+    created: datetime,
+    created_by: int | None,
+    *,
+    can_stand_alone: bool = True,
+) -> Subsection:
+    """
+    [ 🛑 UNSTABLE ] Create a new subsection.
+
+    Args:
+        learning_package_id: The learning package ID.
+        key: The key.
+        created: The creation date.
+        created_by: The user who created the subsection.
+        can_stand_alone: Set to False when created as part of containers
+    """
+    return publishing_api.create_container(
+        learning_package_id,
+        key,
+        created,
+        created_by,
+        can_stand_alone=can_stand_alone,
+        container_cls=Subsection,
+    )
+
+
+def create_subsection_version(
+    subsection: Subsection,
+    version_num: int,
+    *,
+    title: str,
+    entity_rows: list[publishing_api.ContainerEntityRow],
+    created: datetime,
+    created_by: int | None = None,
+) -> SubsectionVersion:
+    """
+    [ 🛑 UNSTABLE ] Create a new subsection version.
+
+    This is a very low-level API, likely only needed for import/export. In
+    general, you will use `create_subsection_and_version()` and
+    `create_next_subsection_version()` instead.
+
+    Args:
+        subsection_pk: The subsection ID.
+        version_num: The version number.
+        title: The title.
+        entity_rows: child entities/versions
+        created: The creation date.
+        created_by: The user who created the subsection.
+    """
+    return publishing_api.create_container_version(
+        subsection.pk,
+        version_num,
+        title=title,
+        entity_rows=entity_rows,
+        created=created,
+        created_by=created_by,
+        container_version_cls=SubsectionVersion,
+    )
+
+
+def _pub_entities_for_units(
+    units: list[Unit | UnitVersion] | None,
+) -> list[publishing_api.ContainerEntityRow] | None:
+    """
+    Helper method: given a list of Unit | UnitVersion, return the
+    list of ContainerEntityRows needed for the base container APIs.
+
+    UnitVersion is passed when we want to pin a specific version, otherwise
+    Unit is used for unpinned.
+    """
+    if units is None:
+        # When these are None, that means don't change the entities in the list.
+        return None
+    for u in units:
+        if not isinstance(u, (Unit, UnitVersion)):
+            raise TypeError("Subsection units must be either Unit or UnitVersion.")
+    return [
+        (
+            publishing_api.ContainerEntityRow(
+                entity_pk=u.container.publishable_entity_id,
+                version_pk=None,
+            ) if isinstance(u, Unit)
+            else publishing_api.ContainerEntityRow(
+                entity_pk=u.unit.container.publishable_entity_id,
+                version_pk=u.container_version.publishable_entity_version_id,
+            )
+        )
+        for u in units
+    ]
+
+
+def create_next_subsection_version(
+    subsection: Subsection,
+    *,
+    title: str | None = None,
+    units: list[Unit | UnitVersion] | None = None,
+    created: datetime,
+    created_by: int | None = None,
+    entities_action: publishing_api.ChildrenEntitiesAction = publishing_api.ChildrenEntitiesAction.REPLACE,
+) -> SubsectionVersion:
+    """
+    [ 🛑 UNSTABLE ] Create the next subsection version.
+
+    Args:
+        subsection_pk: The subsection ID.
+        title: The title. Leave as None to keep the current title.
+        units: The units, as a list of Units (unpinned) and/or UnitVersions (pinned). Passing None
+           will leave the existing units unchanged.
+        created: The creation date.
+        created_by: The user who created the subsection.
+    """
+    entity_rows = _pub_entities_for_units(units)
+    subsection_version = publishing_api.create_next_container_version(
+        subsection.pk,
+        title=title,
+        entity_rows=entity_rows,
+        created=created,
+        created_by=created_by,
+        container_version_cls=SubsectionVersion,
+        entities_action=entities_action,
+    )
+    return subsection_version
+
+
+def create_subsection_and_version(
+    learning_package_id: int,
+    key: str,
+    *,
+    title: str,
+    units: list[Unit | UnitVersion] | None = None,
+    created: datetime,
+    created_by: int | None = None,
+    can_stand_alone: bool = True,
+) -> tuple[Subsection, SubsectionVersion]:
+    """
+    [ 🛑 UNSTABLE ] Create a new subsection 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 subsection.
+        can_stand_alone: Set to False when created as part of containers
+    """
+    entity_rows = _pub_entities_for_units(units)
+    with atomic():
+        subsection = create_subsection(
+            learning_package_id,
+            key,
+            created,
+            created_by,
+            can_stand_alone=can_stand_alone,
+        )
+        subsection_version = create_subsection_version(
+            subsection,
+            1,
+            title=title,
+            entity_rows=entity_rows or [],
+            created=created,
+            created_by=created_by,
+        )
+    return subsection, subsection_version
+
+
+def get_subsection(subsection_pk: int) -> Subsection:
+    """
+    [ 🛑 UNSTABLE ] Get a subsection.
+
+    Args:
+        subsection_pk: The subsection ID.
+    """
+    return Subsection.objects.get(pk=subsection_pk)
+
+
+def get_subsection_version(subsection_version_pk: int) -> SubsectionVersion:
+    """
+    [ 🛑 UNSTABLE ] Get a subsection version.
+
+    Args:
+        subsection_version_pk: The subsection version ID.
+    """
+    return SubsectionVersion.objects.get(pk=subsection_version_pk)
+
+
+def get_latest_subsection_version(subsection_pk: int) -> SubsectionVersion:
+    """
+    [ 🛑 UNSTABLE ] Get the latest subsection version.
+
+    Args:
+        subsection_pk: The subsection ID.
+    """
+    return Subsection.objects.get(pk=subsection_pk).versioning.latest
+
+
+@dataclass(frozen=True)
+class SubsectionListEntry:
+    """
+    [ 🛑 UNSTABLE ]
+    Data about a single entity in a container, e.g. a unit in a subsection.
+    """
+    unit_version: UnitVersion
+    pinned: bool = False
+
+    @property
+    def unit(self):
+        return self.unit_version.unit
+
+
+def get_units_in_subsection(
+    subsection: Subsection,
+    *,
+    published: bool,
+) -> list[SubsectionListEntry]:
+    """
+    [ 🛑 UNSTABLE ]
+    Get the list of entities and their versions in the draft or published
+    version of the given Subsection.
+
+    Args:
+        subsection: The Subsection, e.g. returned by `get_subsection()`
+        published: `True` if we want the published version of the subsection, or
+            `False` for the draft version.
+    """
+    assert isinstance(subsection, Subsection)
+    units = []
+    for entry in publishing_api.get_entities_in_container(subsection, published=published):
+        # Convert from generic PublishableEntityVersion to UnitVersion:
+        unit_version = entry.entity_version.containerversion.unitversion
+        assert isinstance(unit_version, UnitVersion)
+        units.append(SubsectionListEntry(unit_version=unit_version, pinned=entry.pinned))
+    return units
+
+
+def get_units_in_published_subsection_as_of(
+    subsection: Subsection,
+    publish_log_id: int,
+) -> list[SubsectionListEntry] | 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 SubsectionVersion so we can
+          see the subsection 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 subsections 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(subsection, Subsection)
+    subsection_pub_entity_version = publishing_api.get_published_version_as_of(
+        subsection.publishable_entity_id, publish_log_id
+    )
+    if subsection_pub_entity_version is None:
+        return None  # This subsection was not published as of the given PublishLog ID.
+    container_version = subsection_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:
+            unit_version = row.entity_version.containerversion.unitversion
+            assert isinstance(unit_version, UnitVersion)
+            entity_list.append(SubsectionListEntry(unit_version=unit_version, pinned=True))
+        else:
+            # Unpinned unit - figure out what its latest published version was.
+            # This is not optimized. It could be done in one query per subsection rather than one query per unit.
+            pub_entity_version = publishing_api.get_published_version_as_of(row.entity_id, publish_log_id)
+            if pub_entity_version:
+                entity_list.append(
+                    SubsectionListEntry(unit_version=pub_entity_version.containerversion.unitversion, pinned=False)
+                )
+    return entity_list

openedx_learning/apps/authoring/subsections/apps.py

@@ -0,0 +1,25 @@
+"""
+Subsection Django application initialization.
+"""
+
+from django.apps import AppConfig
+
+
+class SubsectionsConfig(AppConfig):
+    """
+    Configuration for the subsections Django application.
+    """
+
+    name = "openedx_learning.apps.authoring.subsections"
+    verbose_name = "Learning Core > Authoring > Subsections"
+    default_auto_field = "django.db.models.BigAutoField"
+    label = "oel_subsections"
+
+    def ready(self):
+        """
+        Register Subsection and SubsectionVersion.
+        """
+        from ..publishing.api import register_content_models  # pylint: disable=import-outside-toplevel
+        from .models import Subsection, SubsectionVersion  # pylint: disable=import-outside-toplevel
+
+        register_content_models(Subsection, SubsectionVersion)

openedx_learning/apps/authoring/subsections/migrations/0001_initial.py

@@ -0,0 +1,36 @@
+# Generated by Django 4.2.19 on 2025-04-09 12:59
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('oel_publishing', '0005_alter_entitylistrow_options'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Subsection',
+            fields=[
+                ('container', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='oel_publishing.container')),
+            ],
+            options={
+                'abstract': False,
+            },
+            bases=('oel_publishing.container',),
+        ),
+        migrations.CreateModel(
+            name='SubsectionVersion',
+            fields=[
+                ('container_version', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='oel_publishing.containerversion')),
+            ],
+            options={
+                'abstract': False,
+            },
+            bases=('oel_publishing.containerversion',),
+        ),
+    ]

openedx_learning/apps/authoring/subsections/models.py

@@ -0,0 +1,50 @@
+"""
+Models that implement subsections
+"""
+from django.db import models
+
+from ..publishing.models import Container, ContainerVersion
+
+__all__ = [
+    "Subsection",
+    "SubsectionVersion",
+]
+
+
+class Subsection(Container):
+    """
+    A Subsection is type of Container that holds Units.
+
+    Via Container and its PublishableEntityMixin, Subsections are also publishable
+    entities and can be added to other containers.
+    """
+    container = models.OneToOneField(
+        Container,
+        on_delete=models.CASCADE,
+        parent_link=True,
+        primary_key=True,
+    )
+
+
+class SubsectionVersion(ContainerVersion):
+    """
+    A SubsectionVersion is a specific version of a Subsection.
+
+    Via ContainerVersion and its EntityList, it defines the list of Units
+    in this version of the Subsection.
+    """
+    container_version = models.OneToOneField(
+        ContainerVersion,
+        on_delete=models.CASCADE,
+        parent_link=True,
+        primary_key=True,
+    )
+
+    @property
+    def subsection(self):
+        """ Convenience accessor to the Subsection this version is associated with """
+        return self.container_version.container.subsection  # pylint: disable=no-member
+
+    # Note: the 'publishable_entity_version' field is inherited and will appear on this model, but does not exist
+    # in the underlying database table. It only exists in the ContainerVersion table.
+    # You can verify this by running 'python manage.py sqlmigrate oel_subsections 0001_initial'

{openedx_learning-0.23.1.dist-info → openedx_learning-0.25.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openedx-learning
-Version: 0.23.1
+Version: 0.25.0
 Summary: Open edX Learning Core and Tagging.
 Home-page: https://github.com/openedx/openedx-learning
 Author: David Ormsbee
@@ -20,11 +20,11 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
 License-File: LICENSE.txt
 Requires-Dist: attrs
-Requires-Dist: Django
 Requires-Dist: edx-drf-extensions
+Requires-Dist: djangorestframework<4.0
 Requires-Dist: celery
+Requires-Dist: Django
 Requires-Dist: rules<4.0
-Requires-Dist: djangorestframework<4.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

{openedx_learning-0.23.1.dist-info → openedx_learning-0.25.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
-openedx_learning/__init__.py,sha256=U0-MtvTb7-MpDx0zi9AhepGePH3oI3FKWsiFGVLf9j8,69
+openedx_learning/__init__.py,sha256=lNlJOtMWHuLa4KYYQnRoBVXd6zGNsGJtRfTQzq3XeD8,69
 openedx_learning/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-openedx_learning/api/authoring.py,sha256=AuEegFTT3tAer_3zSxcxqLq3Yd_eilk-Hxt4ESYearA,970
-openedx_learning/api/authoring_models.py,sha256=oXwqeMAnXBWgVIUcJa0he5QjHvG296AJE-1hDpjd8JM,681
+openedx_learning/api/authoring.py,sha256=1sh-hUH3pJLVIQHzzjlqWb_9uxf9y3-hanLpU4mRvXc,1061
+openedx_learning/api/authoring_models.py,sha256=lA500-C7LBlVzeaEVqmCiQMAPPmeoDMi8wS0TbzgdGw,778
 openedx_learning/apps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/collections/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -37,7 +37,7 @@ openedx_learning/apps/authoring/contents/migrations/0001_initial.py,sha256=FtOTm
 openedx_learning/apps/authoring/contents/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/publishing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/publishing/admin.py,sha256=sLmtttaYIQi8XWw_wOdDD9xbF34g1giMEj5yIN-b-4M,7012
-openedx_learning/apps/authoring/publishing/api.py,sha256=14JojKz57Vl_16JwWcDSOM9JzZm6h0sxAmldmb3SVeE,55712
+openedx_learning/apps/authoring/publishing/api.py,sha256=tGFZGI6cod2ymabjLXn3RqfjzUwb95ioSOm77LD8vcA,55246
 openedx_learning/apps/authoring/publishing/apps.py,sha256=v9PTe3YoICaYT9wfu268ZkVAlnZFvxi-DqYdbRi25bY,750
 openedx_learning/apps/authoring/publishing/contextmanagers.py,sha256=AH5zhr0Tz_gUG9--dfr_oZAu8DMy94n6mnOJuPbWkeU,6723
 openedx_learning/apps/authoring/publishing/migrations/0001_initial.py,sha256=wvekNV19YRSdxRmQaFnLSn_nCsQlHIucPDVMmgKf_OE,9272
@@ -47,7 +47,7 @@ openedx_learning/apps/authoring/publishing/migrations/0004_publishableentity_can
 openedx_learning/apps/authoring/publishing/migrations/0005_alter_entitylistrow_options.py,sha256=Pp4O-VSI75n3UTZZW6CU4TOVIVc5lZvUg5YfMvZyrYM,377
 openedx_learning/apps/authoring/publishing/migrations/0006_draftchangelog.py,sha256=TdioE59_fXCf4ykWhXJfEjyxdDmqbbbLCwLeT1C9irA,3497
 openedx_learning/apps/authoring/publishing/migrations/0007_bootstrap_draftchangelog.py,sha256=EoFFSv52CeiuMGf3KmBvr34sx9N-tv8afdXWVR8wPFA,4154
-openedx_learning/apps/authoring/publishing/migrations/0008_alter_draftchangelogrecord_options_and_more.py,sha256=5Xm5EV3HvnguLC2UbMTyt_I3q9iI4ZBH0YoNEpNipFI,1207
+openedx_learning/apps/authoring/publishing/migrations/0008_alter_draftchangelogrecord_options_and_more.py,sha256=m_UjGSYcdYBRIMAlxwXEdO4kVgQOQyr1VjufbssldhI,1206
 openedx_learning/apps/authoring/publishing/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/publishing/models/__init__.py,sha256=ZhpKo4F30VJatp1F-jQSJnKw8AeHFig9E9SlGnxxBCc,1108
 openedx_learning/apps/authoring/publishing/models/container.py,sha256=GCUD3WTlgvgZSQOKcoOsfhNAfc5pz3Wbs9ClE9mhtB0,2594
@@ -56,6 +56,18 @@ openedx_learning/apps/authoring/publishing/models/entity_list.py,sha256=8MyJqDdC
 openedx_learning/apps/authoring/publishing/models/learning_package.py,sha256=1fuNLHD6k0qGuL0jXYGf4-TA5WczgxJrXUdAIM_JNBI,2688
 openedx_learning/apps/authoring/publishing/models/publish_log.py,sha256=QD7Fb00yUMWM4HHae_m60JW-TDX8upbQdWCEIdhB0yE,5615
 openedx_learning/apps/authoring/publishing/models/publishable_entity.py,sha256=-6Fde_sYqaq1AUC4sw4Rf1X9Hh4jun2Py7Xhsl4VWuY,25419
+openedx_learning/apps/authoring/sections/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openedx_learning/apps/authoring/sections/api.py,sha256=cwsxfHZa6fY_GyC4gSvSRAjayNQWKGY9DWLAyJ_u8Oc,10357
+openedx_learning/apps/authoring/sections/apps.py,sha256=iamzAiVlAWXGlZExP_bKSn38u4mUF8H0-Pa7eFtAkro,743
+openedx_learning/apps/authoring/sections/models.py,sha256=2GK-dDMJwNRw_9gNFho8iKcDV-iYz_zBzqGMDmQ_jbc,1450
+openedx_learning/apps/authoring/sections/migrations/0001_initial.py,sha256=iW5AFhC26mfZNWEVNu8cTsr32Ca4htL4CUanHoXfaeY,1152
+openedx_learning/apps/authoring/sections/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openedx_learning/apps/authoring/subsections/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openedx_learning/apps/authoring/subsections/api.py,sha256=Cgjq3Y6ZZTzIQXMX6p7Y4jhFwIBFwKhSY_HCTeziMGc,10260
+openedx_learning/apps/authoring/subsections/apps.py,sha256=WueCaPOE-7x3cu-6rA9FdeKzipCZSNIhvqpAbxTysOg,773
+openedx_learning/apps/authoring/subsections/models.py,sha256=1uhdpS9Eg6keSqkzQaE8-XSVLAQlmi0llIIU2V7Nl44,1492
+openedx_learning/apps/authoring/subsections/migrations/0001_initial.py,sha256=7kEHIC-EwG2KvlW4hg5tnl45--dW4Yv5gqV5SDqNYNo,1158
+openedx_learning/apps/authoring/subsections/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/units/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/units/api.py,sha256=KJA7Bh7IBE22E6cMSZNp6pamjjA1Vf8EhHw0rvQtlPM,9797
 openedx_learning/apps/authoring/units/apps.py,sha256=cIzphjDw5sjIZ3NLE911N7IMUa8JQSXMReNl03uI7jg,701
@@ -75,7 +87,7 @@ openedx_learning/lib/fields.py,sha256=eiGoXMPhRuq25EH2qf6BAODshAQE3DBVdIYAMIUAXW
 openedx_learning/lib/managers.py,sha256=-Q3gxalSqyPZ9Im4DTROW5tF8wVTZLlmfTe62_xmowY,1643
 openedx_learning/lib/test_utils.py,sha256=g3KLuepIZbaDBCsaj9711YuqyUx7LD4gXDcfNC-mWdc,527
 openedx_learning/lib/validators.py,sha256=iqEdEAvFV2tC7Ecssx69kjecpdU8nE87AlDJYrqrsnc,404
-openedx_learning-0.23.1.dist-info/licenses/LICENSE.txt,sha256=QTW2QN7q3XszgUAXm9Dzgtu5LXYKbR1SGnqMa7ufEuY,35139
+openedx_learning-0.25.0.dist-info/licenses/LICENSE.txt,sha256=QTW2QN7q3XszgUAXm9Dzgtu5LXYKbR1SGnqMa7ufEuY,35139
 openedx_tagging/__init__.py,sha256=V9N8M7f9LYlAbA_DdPUsHzTnWjYRXKGa5qHw9P1JnNI,30
 openedx_tagging/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_tagging/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -131,7 +143,7 @@ openedx_tagging/core/tagging/rest_api/v1/serializers.py,sha256=0HQD_Jrf6-YpocYfz
 openedx_tagging/core/tagging/rest_api/v1/urls.py,sha256=dNUKCtUCx_YzrwlbEbpDfjGVQbb2QdJ1VuJCkladj6E,752
 openedx_tagging/core/tagging/rest_api/v1/views.py,sha256=Hf92cy-tE767DE9FgsZcPKiCYrf5ihfETz8qGKBnuiU,36278
 openedx_tagging/core/tagging/rest_api/v1/views_import.py,sha256=kbHUPe5A6WaaJ3J1lFIcYCt876ecLNQfd19m7YYub6c,1470
-openedx_learning-0.23.1.dist-info/METADATA,sha256=4BwlvkX7Uk-Nxt1yBCzarwd79d6GeATiexL4SOjyfG0,9032
-openedx_learning-0.23.1.dist-info/WHEEL,sha256=MAQBAzGbXNI3bUmkDsiV_duv8i-gcdnLzw7cfUFwqhU,109
-openedx_learning-0.23.1.dist-info/top_level.txt,sha256=IYFbr5mgiEHd-LOtZmXj3q3a0bkGK1M9LY7GXgnfi4M,33
-openedx_learning-0.23.1.dist-info/RECORD,,
+openedx_learning-0.25.0.dist-info/METADATA,sha256=rmB371B58VVRJ5nrps1VFxqAdI8uMm0oMvpaAi5Uj2g,9032
+openedx_learning-0.25.0.dist-info/WHEEL,sha256=Td9E1opt19FSuwsk_gcDwtsGPmyXw7uz9xQf-y2gvl8,109
+openedx_learning-0.25.0.dist-info/top_level.txt,sha256=IYFbr5mgiEHd-LOtZmXj3q3a0bkGK1M9LY7GXgnfi4M,33
+openedx_learning-0.25.0.dist-info/RECORD,,

{openedx_learning-0.23.1.dist-info → openedx_learning-0.25.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.0)
+Generator: setuptools (79.0.0)
 Root-Is-Purelib: true
 Tag: py2-none-any
 Tag: py3-none-any