An openedx_catalog app with a representation for CourseRuns [FC-0117] by bradenmacdonald · Pull Request #479 · openedx/openedx-core

bradenmacdonald · 2026-02-10T03:11:23Z

An implementation of #469.

Related platform PR: openedx/openedx-platform#38023

Notes

This adds a new dependency on edx-organizations (which also requires Pillow for the logo field)
This uses opaque-keys, which was already an indirect dependency but not used directly
Before this PR, only course runs have a display_name, and catalog courses do not have names nor exist in the core platform at all. I'm proposing we add a display_name field to the new core CatalogCourse model to support various use cases, including the proposed new studio home page. See the code for how this can be backfilled and how runs can always override the name for each run.
This PR does not really include a CRUD API (neither python nor REST) for manipulating CatalogCourse/CourseRun objects; just a minimal API that platform code can use to keep them in sync with CourseOverview.
However, this PR does include complete Django admin views that admins and developers can use for provisioning course runs, deleting course runs, testing data migrations, etc.
This current does NOT allow course runs to have a different course code or org code from other runs of the same catalog course. (This restriction could be loosened in the future.) However, the org code capitalization may vary among runs.
Currently, it is the course_overviews app that syncs data from modulestore -> CourseOverview -> openedx_catalog. It would be more robust and future-friendly to instead sync data directly from SplitModulestoreCourseIndex -> openedx_catalog , but it's harder to get information like display_name and language in the latter case as that's not available in the SplitModulestoreCourseIndex table. It could be retrieved from Mongo though.
This PR bakes into the data model the assumption that all runs of the same catalog course are in the same language. Discussion on Slack
Because these models are updated by CourseOverview based on the course_published signal, any test cases in platform that want to use these models have to be sure to enable that signal, which is disabled for test by default.

Architecture Diagram

See ARCHITECTURE.md.

Questions

Are org_code and course_code good terms to use? Should I call the latter number instead, like other parts of the code do? Should I call the org part org_short_name ?
Is the new url_code for each CatalogCourse useful? Do we want to make it editable now, or in the future?
Should we mark [parts of] this new catalog API as unstable?

Can be addressed later:

Should we make the new CourseRun a SoftDeletableModel to support course deletion without data loss? (Maybe we can't now, because soft-deleting it in that one table wouldn't affect the other tables that the system actually references. But in the future we could add this.)
Is "Course Schedule" a core concept that should live in this catalog app? I think yes, but it could also have a draft/publish workflow and ultimately live in openedx_content
Is "Course Visibility" a core concept that should be in this catalog app? (We actually have it defined as catalog_visibility, visible_to_staff_only, and course_visibility which all have different effects and different enum values, and also need to support "use system default")
Integrate authz ?
Check if we should deprecate edx-organization's OrganizationCourse
test what happens to enrollments if course is deleted then re-created with different capitalization (not even using this PR)

openedx-webhooks · 2026-02-10T03:11:28Z

Thanks for the pull request, @bradenmacdonald!

This repository is currently maintained by @axim-engineering.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

ormsbee · 2026-02-11T22:48:45Z

There is no stable/portable identifier for CatalogCourse objects, only their internal integer database ID. Do we need this? (An opaque key or something else?)

I don't know if we'll force it to be stable, but we'll probably want a SlugField(allow_unicode=True) so that we can address it in URLs in a descriptive looking way.

bradenmacdonald · 2026-02-24T18:00:28Z

There is no stable/portable identifier for CatalogCourse objects, only their internal integer database ID. Do we need this? (An opaque key or something else?)

I don't know if we'll force it to be stable, but we'll probably want a SlugField(allow_unicode=True) so that we can address it in URLs in a descriptive looking way.

Historical note: Apparently there was an old PR to add an opaque key for catalog courses, but it never merged: openedx/opaque-keys#87 Seems like they were called "aggregate courses" then.

…ng changed

…n that

kdmccormick

Partial review as I'm signing off for tonight, but overall really solid. I appreciate the comments and validation a lot. My only concerns so far are some superficial naming stuff.

kdmccormick · 2026-02-24T17:45:58Z

src/openedx_catalog/models/course_run.py

+    ("course-v1:...") and never expose the integer primary key of this model.
+
+    Note: throughout the system, we often abbreviate "course run" as just
+    "course", so the two concepts are usually interchangeable. The _set_ of runs


Suggested change

"course", so the two concepts are usually interchangeable. The _set_ of runs

"course", so the two terms are usually interchangeable. The _set_ of runs

kdmccormick · 2026-02-26T23:39:33Z

src/openedx_catalog/models/course_run.py

+        null=False,
+        related_name="runs",
+    )
+    run = case_sensitive_char_field(


since we have org_code and course_code, why not run_code?

as an aside, I like the word "code" for this short sluggy things that combine together to make opaquekeys. We've called it several other things in other places ("slug", "url_name", "id", "key") but I'd been keen to retcon them all into "code" -- library_code, collection_code, block_code, container_code, etc.

kdmccormick · 2026-02-26T23:41:41Z

src/openedx_catalog/models/course_run.py

+    # When this course run was first created. We don't track "modified" as this model should be basically immutable,
+    # and the only field that may ever change is "display_name"; we also don't want people to think that the "modified"
+    # time reflects when edits were last made to the course.


thanks for this note 👍🏻

kdmccormick · 2026-02-26T23:47:35Z

src/openedx_catalog/models/catalog_course.py

+        # '+' is a bad separator because it can mean " " in URLs.
+        # '-', '.', and '_' cannot be used since they're allowed in the org code
+        # So for now we use ':', and in the future we may make the whole slug customizable.
+        return f"{self.org_code}:{self.course_code}"


whether or not to make it an OpaqueKey key... great question 😛

My take on OpaqueKeys is that their implementation is away more complicated than it needs to be, buuuuut, they are still better than parsing everything by hand all over the place, which is what will naturally happen over time whenever we have a key-like thing floating around.

As a compromise, what about returning a string that we could retroactively turn into an opaquekey if we see the need? All it would need is a prefix, like:

Suggested change

return f"{self.org_code}:{self.course_code}"

return f"catalog-course:{self.org_code}:{self.course_code}"

kdmccormick · 2026-02-26T23:50:34Z

src/openedx_catalog/models/course_run.py

+        help_text=_("The internal database ID for this course. Should not be exposed to users nor in APIs."),
+        editable=False,
+    )
+    course_id = CourseKeyField(


Suggested change

course_id = CourseKeyField(

course_key = CourseKeyField(

Could we call this course_key? *_id in Django usually a foreign key, and I think it's unfortunate we've used course_id in so many places. I'd love to standardize on *_key for anything that's an OpaqueKey instance.

kdmccormick · 2026-02-26T23:54:31Z

src/openedx_catalog/models/course_run.py

+            # Enforce that the course ID must end with "+run" where "run" is an exact match for the "run" field.
+            # This check may be removed or changed in the future if our course ID format ever changes
+            models.CheckConstraint(
+                # Note: EndsWith() on SQLite is always case-insensitive, so we code the constraint like this:
+                condition=Exact(Right("course_id", Length("run") + 1), Concat(models.Value("+"), "run")),
+                name="oex_catalog_courserun_courseid_run_match_exactly",
+                violation_error_message=_("The CourseRun 'run' field should match the run in the course_id key."),
+            ),


I have a sense that we'll eventually want to relax this in order to allow sites more flexibility on how they market their course runs, but I agree with adding the constraint for now and seeing how it plays out.

Turns out that I already had to relax it a bit, because it was breaking on CCX keys like ccx-v1:org+code+run+ccx@1 which don't end with +run. In fact, I realized CCX keys break a few different assumptions here - they also violate the constraint that (org, code, run) is unique per course run, because all CCX variants of a run have the same base course ID.

openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Feb 10, 2026

openedx-webhooks added this to Contributions Feb 10, 2026

github-project-automation bot moved this to Needs Triage in Contributions Feb 10, 2026

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Feb 10, 2026

bradenmacdonald added the FC Relates to an Axim Funded Contribution project label Feb 10, 2026

bradenmacdonald changed the title ~~An openedx_catalog app with a representation for CourseRuns~~ An openedx_catalog app with a representation for CourseRuns [FC-0117] Feb 10, 2026

bradenmacdonald force-pushed the braden/catalog branch from 17b313f to 8177a58 Compare February 13, 2026 19:51

bradenmacdonald changed the base branch from main to kdmccormick/root-packages February 13, 2026 19:51

Base automatically changed from kdmccormick/root-packages to main February 13, 2026 20:00

bradenmacdonald force-pushed the braden/catalog branch 5 times, most recently from 87f845c to ccebc9d Compare February 19, 2026 01:27

bradenmacdonald mentioned this pull request Feb 19, 2026

feat: Use openedx_catalog app, backfill its CourseRuns [FC-0117] openedx/openedx-platform#38023

Open

bradenmacdonald force-pushed the braden/catalog branch 3 times, most recently from 88e2f82 to bf0fbd6 Compare February 22, 2026 03:28

bradenmacdonald marked this pull request as ready for review February 24, 2026 07:26

kdmccormick self-requested a review February 24, 2026 16:23

bradenmacdonald force-pushed the braden/catalog branch from 8d56dc0 to d67189d Compare February 25, 2026 00:43

bradenmacdonald mentioned this pull request Feb 25, 2026

(WIP) feat: implement Pathways #482

Draft

bradenmacdonald added 4 commits February 26, 2026 14:31

feat: depend on edx-organizations

d8b8885

feat: new catalog app to model course runs and catalog courses

1c225aa

feat: add a pre_save hook to prevent Organization.short_name from bei…

da80093

…ng changed

feat: admin improvements - display CourseRun warnings

caf8a21

bradenmacdonald added 17 commits February 26, 2026 14:31

chore: fix mypy warnings

cd1345b

fix: better normalization of language codes for catalog courses.

4497b69

feat: add an initial API for catalog courses / course runs

b13c465

feat: add a 'url_slug' property to CatalogCourse

22f1676

feat: expand API, add tests

47c916b

refactor: convert tests to pytest format

d2b5fbd

chore: mypy/pylint fixes

f6c5945

fix: make course code (on CatalogCourse) case sensitive

9f59c92

refactor: re-order API methods

735feda

test: expand API tests

54d1576

fix: bug found by the new tests

c5d43ae

refactor: update to use opaque-keys 3.1

162089b

test: expand tests, fix a bug with logging

3773103

docs: some parts of platform call the course_code "number", so mentio…

442eec1

…n that

chore: fix import order

edc943d

docs: clarify CatalogCourse.language is "primary language"

d804a4e

feat: API for deleting a course run and/or catalog course

b83e3f7

bradenmacdonald force-pushed the braden/catalog branch from ac60e0e to b83e3f7 Compare February 26, 2026 22:31

chore: fix lint issue

d8deaa2

kdmccormick requested changes Feb 26, 2026

View reviewed changes

kdmccormick self-requested a review February 26, 2026 23:57

fix: CourseRun database constraint wasn't working with CCX keys

43f7b7c

bradenmacdonald force-pushed the braden/catalog branch from 4dd8ad7 to 43f7b7c Compare February 27, 2026 00:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

An openedx_catalog app with a representation for CourseRuns [FC-0117]#479

An openedx_catalog app with a representation for CourseRuns [FC-0117]#479
bradenmacdonald wants to merge 23 commits intomainfrom
braden/catalog

bradenmacdonald commented Feb 10, 2026 •

edited

Loading

Uh oh!

openedx-webhooks commented Feb 10, 2026 •

edited

Loading

Uh oh!

ormsbee commented Feb 11, 2026

Uh oh!

bradenmacdonald commented Feb 24, 2026

Uh oh!

kdmccormick left a comment

Uh oh!

kdmccormick Feb 24, 2026

Uh oh!

kdmccormick Feb 26, 2026

Uh oh!

kdmccormick Feb 26, 2026

Uh oh!

kdmccormick Feb 26, 2026

Uh oh!

kdmccormick Feb 26, 2026

Uh oh!

kdmccormick Feb 26, 2026

Uh oh!

bradenmacdonald Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	"course", so the two concepts are usually interchangeable. The _set_ of runs
	"course", so the two terms are usually interchangeable. The _set_ of runs

	return f"{self.org_code}:{self.course_code}"
	return f"catalog-course:{self.org_code}:{self.course_code}"

Conversation

bradenmacdonald commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Architecture Diagram

Questions

Uh oh!

openedx-webhooks commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ormsbee commented Feb 11, 2026

Uh oh!

bradenmacdonald commented Feb 24, 2026

Uh oh!

kdmccormick left a comment

Choose a reason for hiding this comment

Uh oh!

kdmccormick Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

kdmccormick Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

kdmccormick Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

kdmccormick Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

kdmccormick Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

kdmccormick Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

bradenmacdonald Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bradenmacdonald commented Feb 10, 2026 •

edited

Loading

openedx-webhooks commented Feb 10, 2026 •

edited

Loading