openedx-core 1.4.1__py3-none-any.whl

openedx_catalog/ARCHITECTURE.md

@@ -0,0 +1,36 @@
+# Catalog App Architecture Diagram
+
+Here's a visual overview of how this app relates to other apps.
+
+(_Note: to see the diagram below, view this on GitHub or view in VS Code with [a Markdown-Mermaid extension](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) enabled._)
+
+```mermaid
+---
+config:
+  theme: 'forest'
+---
+flowchart TB
+    Catalog["**openedx_catalog** (CourseRun, CatalogCourse plus core metadata models, e.g. CourseSchedule. Other metadata models live in other apps but are 1:1 with CourseRun.)"]
+    Content["**openedx_content**<br>The content of the course. (publishing, containers, components, media)"]
+    Organizations["**edx-organizations** (Organization)"]
+    Enrollments["**platform: enrollments** (CourseEnrollment, CourseEnrollmentAllowed)"]
+    Modes["**platform: course_modes** (CourseMode)"]
+    Content -- "References (see ADR 0001)" --> Catalog
+    Catalog -- References --> Organizations
+    Enrollments -- References --> Modes
+    Enrollments -- References --> Catalog
+
+    style Enrollments fill:#ccc
+    style Modes fill:#ccc
+    style Organizations fill:#ccc
+
+    Pathways["<a href='https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5148147732/Brief+Modular+Content+Delivery+-+Platform+Strategy'>**openedx_learning: pathways**</a> (Pathway definition, PathwayItem, PathwayCertificate, etc. The unversioned CatalogPathway lives in openedx_catalog.)"]
+    Pathways -- References --> Catalog
+    Pathways -- References --> Content
+
+    style Pathways fill:#c0ffee,stroke-dasharray: 5 5
+
+    FutureCatalog["Future discovery service - learner-oriented, pluggable, browse/search courses and programs"] -- References --> Catalog
+    FutureCatalog <-- Plugin API --> Pathways
+    style FutureCatalog fill:#ffc0ee,stroke-dasharray: 5 5
+```

openedx_catalog/README.rst

@@ -0,0 +1,22 @@
+Learning Core: Catalog App
+==========================
+
+Overview
+--------
+
+The ``openedx_catalog`` Django apps provides core models to represent all courses in the Open edX platform. Higher-level apps can build on these models to implement features like enrollment, grading, scheduling, exams, and much more.
+
+Motivation
+----------
+
+The existing ``CourseOverview`` model in ``openedx-platform`` is derived from various places, but mostly from the metadata fields of the root ``Course`` object stored in modulestore (MongoDB) for each course. As we slowly transition toward storing course content fully in Open edX Core (in ``openedx_content``), we want to move to storing all course data and metadata in these sort of MySQL models. We're creating this new ``CourseRun`` model in ``openedx_catalog`` to support these goals:
+
+1. Provide a core model to represent each course, for foreign key purposes.
+2. To allow provisioning placeholder courses before any content even exists.
+3. To be much simpler and more performant than ``CourseOverview`` was (far fewer fields generally, fewer legacy fields, integer primary key).
+4. To be independent of how and where content is stored: the catalog is not aware of content, and the mapping from a course run to its content (in modulestore or in ``openedx_content``) is maintained outside this app. See `ADR 0001 <../../docs/openedx_catalog/decisions/0001-catalog-models-usage.rst>`__.
+
+Architecture
+------------
+
+See `the architecture diagram <./ARCHITECTURE.md>`__. (Because we use RST for all Python READMEs, it cannot be embedded here directly.)

openedx_catalog/admin.py

@@ -0,0 +1,112 @@
+"""
+Django Admin pages for openedx_catalog.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING
+
+from django.contrib import admin
+from django.db.models import Count, QuerySet
+from django.urls import reverse
+from django.utils.html import format_html
+from django.utils.translation import gettext_lazy as _
+
+from .models import CatalogCourse, CourseRun
+
+if TYPE_CHECKING:
+
+    class CatalogCourseWithRunCount(CatalogCourse):
+        run_count: int
+
+
+class CatalogCourseAdmin(admin.ModelAdmin):
+    """
+    The CatalogCourse model admin.
+    """
+
+    list_filter = ["org__short_name", "language"]
+    list_display = [
+        "title",
+        "org_display",
+        "course_code",
+        "runs_summary",
+        "key_str",
+        "created_date",
+        "language",
+    ]
+
+    def get_readonly_fields(self, request, obj: CatalogCourse | None = None) -> tuple[str, ...]:
+        if obj:  # editing an existing object
+            return ("org", "course_code")
+        return tuple()
+
+    def get_queryset(self, request) -> QuerySet[CatalogCourseWithRunCount]:
+        """Add the 'run_count' to the list_display queryset"""
+        qs = super().get_queryset(request)
+        qs = qs.annotate(run_count=Count("runs"))
+        return qs
+
+    @admin.display(description="Organization", ordering="org__short_name")
+    def org_display(self, obj: CatalogCourse) -> str:
+        """Display the organization, only showing the short_name if different from full name"""
+        if obj.org.name == obj.org.short_name:
+            return obj.org.short_name
+        return str(obj.org)
+
+    @admin.display(description=_("Created"), ordering="created")
+    def created_date(self, obj: CatalogCourse) -> datetime.date:
+        """Display the created date without the timestamp"""
+        return obj.created.date()
+
+    @admin.display(description=_("Runs"))
+    def runs_summary(self, obj: CatalogCourseWithRunCount) -> str:
+        """Summarize the runs"""
+        if obj.run_count == 0:
+            return "-"
+        url = reverse("admin:openedx_catalog_courserun_changelist") + f"?catalog_course={obj.pk}"
+        first_few_runs = obj.runs.order_by("-run_code")[:3]
+        runs_summary = ", ".join(run.run_code for run in first_few_runs)
+        if obj.run_count > 4:
+            runs_summary += f", ... ({obj.run_count})"
+        return format_html('<a href="{}">{}</a>', url, runs_summary)
+
+
+admin.site.register(CatalogCourse, CatalogCourseAdmin)
+
+
+class CourseRunAdmin(admin.ModelAdmin):
+    """
+    The CourseRun model admin.
+    """
+
+    list_display = ["title", "created_date", "catalog_course", "org_code", "course_code", "run_code", "warnings"]
+    readonly_fields = ("course_key",)
+    # There may be thousands of catalog courses, so don't use <select>
+    raw_id_fields = ["catalog_course"]
+
+    def get_readonly_fields(self, request, obj: CourseRun | None = None):
+        if obj:  # editing an existing object
+            return self.readonly_fields + ("run_code",)
+        return self.readonly_fields
+
+    @admin.display(description=_("Created"), ordering="created")
+    def created_date(self, obj: CourseRun) -> datetime.date:
+        """Display the created date without the timestamp"""
+        return obj.created.date()
+
+    def warnings(self, obj: CourseRun) -> str | None:
+        """Display warnings of any detected issues"""
+        if obj.course_code != obj.catalog_course.course_code:
+            return "🚨 Critical: mismatched course code"
+        if obj.org_code != obj.catalog_course.org.short_name:
+            if obj.org_code.lower() == obj.catalog_course.org.short_name.lower():
+                return "⚠️ Warning: Incorrect org code capitalization"
+            return "🚨 Critical: mismatched org code"
+        # It would be nice to indicate if there's associated course content or not, but openedx-core isn't aware of
+        # modulestore so we have no way to check that here.
+        return None
+
+
+admin.site.register(CourseRun, CourseRunAdmin)

openedx_catalog/api.py

@@ -0,0 +1,30 @@
+"""
+Open edX Core Catalog API
+
+Note: this is currently a very minimal API. At this point, the openedx_catalog
+app mainly exists to provide core models that represent "catalog courses" and
+"course runs" for use by foreign keys across the system.
+
+If a course "exists" in the system, you can trust that it will exist as a
+CatalogCourse and CourseRun row in this openedx_catalog app, and use those as
+needed when creating foreign keys in various apps. This should be much more
+efficient than storing the full course key as a string or creating a foreign key
+to the (large) CourseOverview table.
+
+Note that the opposite does not hold. Admins can now create CourseRuns and/or
+CatalogCourses that don't yet have any content attached. So you may find entries
+in this openedx_catalog app that don't correspond to courses in modulestore.
+
+In addition, we currently do not account for which courses should be visible to
+which users. So this API does not yet provide any "list courses" methods. In the
+future, the catalog API will be extended to implement course listing along with
+pluggable logic for managing multiple catalogs of courses that can account for
+instance-specific logic (e.g. enterprise, subscriptions, white labelling) when
+determining which courses are visible to which users.
+"""
+
+# Import only the public API methods denoted with __all__
+# pylint: disable=wildcard-import
+from .api_impl import *
+
+# You'll also want the models from .models_api

openedx_catalog/api_impl.py

@@ -0,0 +1,251 @@
+"""
+Implementation of the `openedx_catalog` API.
+"""
+
+import logging
+from typing import overload
+
+from opaque_keys.edx.keys import CourseKey
+from organizations.api import ensure_organization  # type: ignore[import]
+from organizations.api import exceptions as org_exceptions
+
+from .models import CatalogCourse, CourseRun
+
+log = logging.getLogger(__name__)
+
+# These are the public API methods that anyone can use
+__all__ = [
+    "get_catalog_course",
+    "update_catalog_course",
+    "delete_catalog_course",
+    "get_course_run",
+    "sync_course_run_details",
+    "create_course_run_for_modulestore_course_with",
+    "delete_course_run",
+]
+
+
+@overload
+def get_catalog_course(*, org_code: str, course_code: str) -> CatalogCourse: ...
+@overload
+def get_catalog_course(*, key_str: str) -> CatalogCourse: ...
+@overload
+def get_catalog_course(*, pk: CatalogCourse.ID) -> CatalogCourse: ...
+
+
+def get_catalog_course(
+    pk: CatalogCourse.ID | None = None,
+    key_str: str = "",
+    org_code: str = "",
+    course_code: str = "",
+) -> CatalogCourse:
+    """
+    Get a catalog course (set of runs).
+
+    ⚠️ Does not check permissions or visibility rules.
+
+    The CatalogCourse may not have any runs associated with it.
+    """
+    assert pk or key_str or (org_code and course_code)
+    if pk:
+        assert not org_code
+        assert not key_str
+        return CatalogCourse.objects.get(pk=pk)
+    if key_str:
+        assert key_str.startswith("catalog-course:")
+        assert not org_code
+        assert not course_code
+        _, org_code, course_code = key_str.split(":", 2)
+    # We might as well select_related org because we're joining to check the org__short_name field anyways.
+    return CatalogCourse.objects.select_related("org").get(org__short_name=org_code, course_code=course_code)
+
+
+def update_catalog_course(
+    catalog_course: CatalogCourse | CatalogCourse.ID,
+    *,
+    title: str | None = None,  # Specify a string to change the title (display name).
+    # The short language code (one of settings.ALL_LANGUAGES), e.g. "en", "es", "zh_HANS"
+    language_short: str | None = None,
+) -> None:
+    """
+    Update a `CatalogCourse`.
+
+    ⚠️ Does not check permissions.
+    """
+    if isinstance(catalog_course, CatalogCourse):
+        cc = catalog_course
+    else:
+        cc = CatalogCourse.objects.get(pk=catalog_course)
+
+    update_fields = []
+    if title:
+        cc.title = title
+        update_fields.append("title")
+    if language_short:
+        cc.language_short = language_short
+        update_fields.append("language")
+    if update_fields:
+        cc.save(update_fields=update_fields)
+
+
+def delete_catalog_course(catalog_course: CatalogCourse | CatalogCourse.ID) -> None:
+    """
+    Delete a `CatalogCourse`. This will fail with a `ProtectedError` if any runs exist.
+
+    ⚠️ Does not check permissions.
+    ⚠️ Does not emit any course lifecycle events.
+    """
+    if isinstance(catalog_course, CatalogCourse):
+        cc = catalog_course
+    else:
+        cc = CatalogCourse.objects.get(pk=catalog_course)
+    cc.delete()
+
+
+def get_course_run(course_key: CourseKey) -> CourseRun:
+    """
+    Get a single course run.
+
+    ⚠️ Does not check permissions or visibility rules.
+
+    The CourseRun may or may not have content associated with it.
+
+    Tip: to get all runs associated with a CatalogCourse, use
+    `get_catalog_course(...).runs`
+    """
+    return CourseRun.objects.get(course_key__exact=course_key)
+
+
+def sync_course_run_details(
+    course_key: CourseKey,
+    *,
+    title: str | None,  # Specify a string to change the title (display name).
+) -> None:
+    """
+    Update a `CourseRun` with details from a more authoritative model (e.g.
+    `CourseOverview`). Currently the only field that can be updated is
+    `title` (display name).
+
+    The name of this function reflects the fact that the `CourseRun` model is
+    not currently a source of truth. So it's not a "rename the course" API, but
+    rather a "some other part of the system already renamed the course" API,
+    during a transition period until `CourseRun` is the main source of truth.
+
+    Once `CourseRun` is the main source of truth, this will be replaced with a
+    `update_course_run` API that will become the main way to rename a course.
+
+    ⚠️ Does not check permissions.
+    ⚠️ Does not emit any course lifecycle events.
+    """
+    run = CourseRun.objects.get(course_key=course_key)
+    if title:
+        run.title = title
+        run.save(update_fields=["title"])
+
+
+def create_course_run_for_modulestore_course_with(
+    course_key: CourseKey,
+    *,
+    title: str,
+    # The short language code (in openedx-platform, this is one of settings.ALL_LANGUAGES), e.g. "en", "es", "zh_HANS"
+    language_short: str | None = None,
+) -> CourseRun:
+    """
+    Create a `CourseRun` (and, if necessary, its corresponding `CatalogCourse`).
+    This API is meant to be used for data synchonrization purposes (keeping the
+    new catalog models in sync with modulestore), and is not a generic "create a
+    course run" API.
+
+    If the `CourseRun` already exists, this will log a warning.
+
+    The `created` timestamp of the `CourseRun` will be set to now, so this is
+    not meant for historical data (use a data migration).
+
+    ⚠️ Does not check permissions.
+    ⚠️ Does not emit any course lifecycle events.
+    """
+    # Note: this code shares a lot with the code in
+    # openedx-platform/openedx/core/djangoapps/content/course_overviews/migrations/0030_backfill_...
+    # but migrations should generally represent a point-in-time transformation, not call an API method that may continue
+    # to be developed. So even though it's not DRY, the code is repeated here.
+
+    org_code = course_key.org
+    course_code = course_key.course
+    try:
+        cc = CatalogCourse.objects.get(org__short_name=org_code, course_code=course_code)
+    except CatalogCourse.DoesNotExist:
+        cc = None
+
+    if not cc:
+        # Create the catalog course.
+
+        # First, ensure that the Organization exists.
+        try:
+            org_data = ensure_organization(org_code)
+        except org_exceptions.InvalidOrganizationException as exc:
+            # Note: IFF the org exists among the modulestore courses but not in the Organizations database table,
+            # and if auto-create is disabled (it's enabled by default), this will raise InvalidOrganizationException. It
+            # would be up to the operator to decide how they want to resolve that.
+            raise ValueError(
+                f'The organization short code "{org_code}" exists in modulestore ({str(course_key)}) but '
+                "not the Organizations table, and auto-creating organizations is disabled. You can resolve this by "
+                "creating the Organization manually (e.g. from the Django admin) or turning on auto-creation. "
+                "You can set active=False to prevent this Organization from being used other than for historical data. "
+            ) from exc
+        if org_data["short_name"] != org_code:
+            # On most installations, the 'short_name' database column is case insensitive (unfortunately)
+            log.warning(
+                'The course with ID "%s" does not match its Organization.short_name "%s"',
+                str(course_key),
+                org_data["short_name"],
+            )
+
+        # Actually create the CatalogCourse. We use get_or_create just to be extra robust against race conditions, since
+        # we don't care if another worker/thread/etc has beaten us to creating this.
+        cc, _cc_created = CatalogCourse.objects.get_or_create(
+            org_id=org_data["id"],
+            course_code=course_code,
+            defaults={
+                "title": title,
+                **({"language_short": language_short} if language_short else {}),
+            },
+        )
+
+    new_run, created = CourseRun.objects.get_or_create(
+        catalog_course=cc,
+        run_code=course_key.run,
+        course_key=course_key,
+        defaults={"title": title},
+    )
+
+    if not created:
+        log.warning('Expected to create CourseRun for "%s" but it already existed.', str(course_key))
+
+    return new_run
+
+
+def delete_course_run(course_key: CourseKey) -> None:
+    """
+    Delete a `CourseRun`.
+
+    For now, this method is only useful for keeping the `CourseRun` data in sync
+    with other models like `CourseOverview` that are used as a source of truth.
+    Calling this method will not yet affect most parts of the system, so you
+    should only use this if the course run is a "placeholder" course that has no
+    content yet, or the course has already been deleted in the other parts of
+    the platform (e.g. modulestore). In the future, we will invert this
+    dependency, and calling this _would_ cascade to delete `CourseOverview`, and
+    perhaps other records as well.
+
+    (This method does not delete content, if any content is associated with the
+    run, and that is not expected to change. In the future, a separate API
+    method may implement "delete course + content + (optionally) enrollments +
+    student state + etc.".)
+
+    This may fail with a `ProtectedError` or other `IntegrityError` subclass if
+    there are still active references to the course run.
+
+    ⚠️ Does not check permissions.
+    ⚠️ Does not emit any course lifecycle events.
+    """
+    CourseRun.objects.get(course_key=course_key).delete()

openedx_catalog/apps.py

@@ -0,0 +1,21 @@
+"""
+App Config for the openedx_catalog app.
+"""
+
+from django.apps import AppConfig
+
+
+class CatalogAppConfig(AppConfig):
+    """
+    Initialize and configure the Catalog app
+    """
+
+    name = "openedx_catalog"
+    verbose_name = "Open edX Core > Catalog"
+    default_auto_field = "django.db.models.BigAutoField"
+    label = "openedx_catalog"
+
+    def ready(self) -> None:
+
+        # Connect signal handlers.
+        from . import signals  # pylint: disable=import-outside-toplevel,unused-import