feat: new openedx_catalog app to model catalog courses + runs (v0.36.0) (#479)

* feat: depend on edx-organizations
* feat: new catalog app to model course runs and catalog courses
* feat: add a pre_save hook to prevent Organization.short_name from being changed
* docs: some parts of platform call the course_code "number", so mention that
* docs: clarify CatalogCourse.language is "primary language"
* refactor: course_id -> course_key, run -> run_code, display_name -> title

Author: bradenmacdonald

projects/dev.py

@@ -34,7 +34,11 @@
     "django.contrib.admin",
     "django.contrib.admindocs",
 
+    # Open edX Organizations (dependency for openedx_catalog)
+    "organizations",
+
     # Our Apps
+    "openedx_catalog",
     "openedx_tagging",
     "openedx_content",
     *openedx_content_backcompat_apps_to_install(),

requirements/base.in

@@ -13,3 +13,5 @@ edx-drf-extensions        # Extensions to the Django REST Framework used by Open
 rules<4.0                 # Django extension for rules-based authorization checks
 
 tomlkit                   # Parses and writes TOML configuration files
+
+edx-organizations         # Implemented the "Organization" model that CatalogCourse/CourseRun are keyed to

requirements/base.txt

@@ -42,13 +42,20 @@ django==5.2.12
     #   -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt
     #   -r requirements/base.in
     #   django-crum
+    #   django-model-utils
+    #   django-simple-history
     #   django-waffle
     #   djangorestframework
     #   drf-jwt
     #   edx-django-utils
     #   edx-drf-extensions
+    #   edx-organizations
 django-crum==0.7.9
     # via edx-django-utils
+django-model-utils==5.0.0
+    # via edx-organizations
+django-simple-history==3.11.0
+    # via edx-organizations
 django-waffle==5.0.0
     # via
     #   edx-django-utils
@@ -58,22 +65,31 @@ djangorestframework==3.16.1
     #   -r requirements/base.in
     #   drf-jwt
     #   edx-drf-extensions
+    #   edx-organizations
 dnspython==2.8.0
     # via pymongo
 drf-jwt==1.19.2
     # via edx-drf-extensions
 edx-django-utils==8.0.1
     # via edx-drf-extensions
 edx-drf-extensions==10.6.0
-    # via -r requirements/base.in
+    # via
+    #   -r requirements/base.in
+    #   edx-organizations
 edx-opaque-keys==3.1.0
-    # via edx-drf-extensions
+    # via
+    #   edx-drf-extensions
+    #   edx-organizations
+edx-organizations==7.3.0
+    # via -r requirements/base.in
 idna==3.11
     # via requests
 kombu==5.6.2
     # via celery
 packaging==26.0
     # via kombu
+pillow==12.1.0
+    # via edx-organizations
 prompt-toolkit==3.0.52
     # via click-repl
 psutil==7.2.2

requirements/dev.txt

@@ -117,6 +117,8 @@ django==5.2.12
     #   -r requirements/quality.txt
     #   django-crum
     #   django-debug-toolbar
+    #   django-model-utils
+    #   django-simple-history
     #   django-stubs
     #   django-stubs-ext
     #   django-waffle
@@ -125,6 +127,7 @@ django==5.2.12
     #   edx-django-utils
     #   edx-drf-extensions
     #   edx-i18n-tools
+    #   edx-organizations
 django-crum==0.7.9
     # via
     #   -r requirements/quality.txt
@@ -133,6 +136,14 @@ django-debug-toolbar==6.2.0
     # via
     #   -r requirements/dev.in
     #   -r requirements/quality.txt
+django-model-utils==5.0.0
+    # via
+    #   -r requirements/quality.txt
+    #   edx-organizations
+django-simple-history==3.11.0
+    # via
+    #   -r requirements/quality.txt
+    #   edx-organizations
 django-stubs==5.2.9
     # via
     #   -r requirements/quality.txt
@@ -151,6 +162,7 @@ djangorestframework==3.16.1
     #   -r requirements/quality.txt
     #   drf-jwt
     #   edx-drf-extensions
+    #   edx-organizations
 djangorestframework-stubs==3.16.8
     # via -r requirements/quality.txt
 dnspython==2.8.0
@@ -170,7 +182,9 @@ edx-django-utils==8.0.1
     #   -r requirements/quality.txt
     #   edx-drf-extensions
 edx-drf-extensions==10.6.0
-    # via -r requirements/quality.txt
+    # via
+    #   -r requirements/quality.txt
+    #   edx-organizations
 edx-i18n-tools==1.9.0
     # via -r requirements/dev.in
 edx-lint==5.6.0
@@ -179,6 +193,9 @@ edx-opaque-keys==3.1.0
     # via
     #   -r requirements/quality.txt
     #   edx-drf-extensions
+    #   edx-organizations
+edx-organizations==7.3.0
+    # via -r requirements/quality.txt
 filelock==3.25.0
     # via
     #   -r requirements/ci.txt
@@ -306,6 +323,10 @@ pathspec==1.0.4
     # via
     #   -r requirements/quality.txt
     #   mypy
+pillow==12.1.0
+    # via
+    #   -r requirements/quality.txt
+    #   edx-organizations
 pip-tools==7.5.3
     # via -r requirements/pip-tools.txt
 platformdirs==4.9.4

requirements/doc.txt

@@ -83,20 +83,31 @@ django==5.2.12
     #   -r requirements/test.txt
     #   django-crum
     #   django-debug-toolbar
+    #   django-model-utils
+    #   django-simple-history
     #   django-stubs
     #   django-stubs-ext
     #   django-waffle
     #   djangorestframework
     #   drf-jwt
     #   edx-django-utils
     #   edx-drf-extensions
+    #   edx-organizations
     #   sphinxcontrib-django
 django-crum==0.7.9
     # via
     #   -r requirements/test.txt
     #   edx-django-utils
 django-debug-toolbar==6.2.0
     # via -r requirements/test.txt
+django-model-utils==5.0.0
+    # via
+    #   -r requirements/test.txt
+    #   edx-organizations
+django-simple-history==3.11.0
+    # via
+    #   -r requirements/test.txt
+    #   edx-organizations
 django-stubs==5.2.9
     # via
     #   -r requirements/test.txt
@@ -115,6 +126,7 @@ djangorestframework==3.16.1
     #   -r requirements/test.txt
     #   drf-jwt
     #   edx-drf-extensions
+    #   edx-organizations
 djangorestframework-stubs==3.16.8
     # via -r requirements/test.txt
 dnspython==2.8.0
@@ -139,11 +151,16 @@ edx-django-utils==8.0.1
     #   -r requirements/test.txt
     #   edx-drf-extensions
 edx-drf-extensions==10.6.0
-    # via -r requirements/test.txt
+    # via
+    #   -r requirements/test.txt
+    #   edx-organizations
 edx-opaque-keys==3.1.0
     # via
     #   -r requirements/test.txt
     #   edx-drf-extensions
+    #   edx-organizations
+edx-organizations==7.3.0
+    # via -r requirements/test.txt
 freezegun==1.5.5
     # via -r requirements/test.txt
 grimp==3.14
@@ -210,6 +227,10 @@ pathspec==1.0.4
     # via
     #   -r requirements/test.txt
     #   mypy
+pillow==12.1.0
+    # via
+    #   -r requirements/test.txt
+    #   edx-organizations
 pluggy==1.6.0
     # via
     #   -r requirements/test.txt

requirements/quality.txt

@@ -88,19 +88,30 @@ django==5.2.12
     #   -r requirements/test.txt
     #   django-crum
     #   django-debug-toolbar
+    #   django-model-utils
+    #   django-simple-history
     #   django-stubs
     #   django-stubs-ext
     #   django-waffle
     #   djangorestframework
     #   drf-jwt
     #   edx-django-utils
     #   edx-drf-extensions
+    #   edx-organizations
 django-crum==0.7.9
     # via
     #   -r requirements/test.txt
     #   edx-django-utils
 django-debug-toolbar==6.2.0
     # via -r requirements/test.txt
+django-model-utils==5.0.0
+    # via
+    #   -r requirements/test.txt
+    #   edx-organizations
+django-simple-history==3.11.0
+    # via
+    #   -r requirements/test.txt
+    #   edx-organizations
 django-stubs==5.2.9
     # via
     #   -r requirements/test.txt
@@ -119,6 +130,7 @@ djangorestframework==3.16.1
     #   -r requirements/test.txt
     #   drf-jwt
     #   edx-drf-extensions
+    #   edx-organizations
 djangorestframework-stubs==3.16.8
     # via -r requirements/test.txt
 dnspython==2.8.0
@@ -136,13 +148,18 @@ edx-django-utils==8.0.1
     #   -r requirements/test.txt
     #   edx-drf-extensions
 edx-drf-extensions==10.6.0
-    # via -r requirements/test.txt
+    # via
+    #   -r requirements/test.txt
+    #   edx-organizations
 edx-lint==5.6.0
     # via -r requirements/quality.in
 edx-opaque-keys==3.1.0
     # via
     #   -r requirements/test.txt
     #   edx-drf-extensions
+    #   edx-organizations
+edx-organizations==7.3.0
+    # via -r requirements/test.txt
 freezegun==1.5.5
     # via -r requirements/test.txt
 grimp==3.14
@@ -231,6 +248,10 @@ pathspec==1.0.4
     # via
     #   -r requirements/test.txt
     #   mypy
+pillow==12.1.0
+    # via
+    #   -r requirements/test.txt
+    #   edx-organizations
 platformdirs==4.9.4
     # via pylint
 pluggy==1.6.0

requirements/test.txt

@@ -72,19 +72,30 @@ ddt==1.7.2
     #   -r requirements/base.txt
     #   django-crum
     #   django-debug-toolbar
+    #   django-model-utils
+    #   django-simple-history
     #   django-stubs
     #   django-stubs-ext
     #   django-waffle
     #   djangorestframework
     #   drf-jwt
     #   edx-django-utils
     #   edx-drf-extensions
+    #   edx-organizations
 django-crum==0.7.9
     # via
     #   -r requirements/base.txt
     #   edx-django-utils
 django-debug-toolbar==6.2.0
     # via -r requirements/test.in
+django-model-utils==5.0.0
+    # via
+    #   -r requirements/base.txt
+    #   edx-organizations
+django-simple-history==3.11.0
+    # via
+    #   -r requirements/base.txt
+    #   edx-organizations
 django-stubs==5.2.9
     # via
     #   -r requirements/test.in
@@ -101,6 +112,7 @@ djangorestframework==3.16.1
     #   -r requirements/base.txt
     #   drf-jwt
     #   edx-drf-extensions
+    #   edx-organizations
 djangorestframework-stubs==3.16.8
     # via -r requirements/test.in
 dnspython==2.8.0
@@ -116,11 +128,16 @@ edx-django-utils==8.0.1
     #   -r requirements/base.txt
     #   edx-drf-extensions
 edx-drf-extensions==10.6.0
-    # via -r requirements/base.txt
+    # via
+    #   -r requirements/base.txt
+    #   edx-organizations
 edx-opaque-keys==3.1.0
     # via
     #   -r requirements/base.txt
     #   edx-drf-extensions
+    #   edx-organizations
+edx-organizations==7.3.0
+    # via -r requirements/base.txt
 freezegun==1.5.5
     # via -r requirements/test.in
 grimp==3.14
@@ -162,6 +179,10 @@ packaging==26.0
     #   pytest
 pathspec==1.0.4
     # via mypy
+pillow==12.1.0
+    # via
+    #   -r requirements/base.txt
+    #   edx-organizations
 pluggy==1.6.0
     # via
     #   pytest

src/openedx_catalog/ARCHITECTURE.md

@@ -0,0 +1,35 @@
+# 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)"]
+    Catalog <-. "Direction of this relationship TBD." .-> Content
+    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_pathways**</a> (Pathway, PathwaySchedule, PathwayEnrollment, PathwayCertificate, etc.)"]
+    Pathways -- References --> Catalog
+
+    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
+```