openedx-learning 0.23.1__tar.gz → 0.26.0__tar.gz

{openedx_learning-0.23.1/openedx_learning.egg-info → openedx_learning-0.26.0}/PKG-INFO

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

{openedx_learning-0.23.1 → openedx_learning-0.26.0}/openedx_learning/__init__.py

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

{openedx_learning-0.23.1 → openedx_learning-0.26.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-0.23.1 → openedx_learning-0.26.0}/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-0.23.1 → openedx_learning-0.26.0}/openedx_learning/apps/authoring/publishing/api.py

@@ -1203,6 +1203,7 @@ def get_container_by_key(learning_package_id: int, /, key: str) -> Container:
 def get_containers(
     learning_package_id: int,
     container_cls: type[ContainerModel] = Container,  # type: ignore[assignment]
+    include_deleted: bool | None = False,
 ) -> QuerySet[ContainerModel]:
     """
     [ 🛑 UNSTABLE ]
@@ -1211,12 +1212,17 @@ def get_containers(
     Args:
         learning_package_id: The primary key of the learning package
         container_cls: The subclass of Container to use, if applicable
+        include_deleted: If True, include deleted containers (with no draft version) in the result.
 
     Returns:
         A queryset containing the container associated with the given learning package.
     """
     assert issubclass(container_cls, Container)
-    return container_cls.objects.filter(publishable_entity__learning_package=learning_package_id)
+    container_qset = container_cls.objects.filter(publishable_entity__learning_package=learning_package_id)
+    if not include_deleted:
+        container_qset = container_qset.filter(publishable_entity__draft__version__isnull=False)
+
+    return container_qset.order_by('pk')
 
 
 def get_collection_containers(
@@ -1322,7 +1328,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 +1376,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-0.23.1 → openedx_learning-0.26.0}/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-0.26.0/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-0.26.0/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-0.26.0/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-0.26.0/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'