feat!: Make openedx_content and openedx_tagging flat, top-level APIs

Author: kdmccormick

.coveragerc

@@ -2,8 +2,7 @@
 branch = True
 data_file = .coverage
 source =
-	openedx_learning
-	openedx_tagging
+    src
 omit =
     test_settings
     **/migrations/*

.github/workflows/lint-imports.yml

@@ -17,13 +17,13 @@ jobs:
       - name: setup python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install pip
         run: pip install -r requirements/pip.txt
 
       - name: Install Dependencies
-        run: pip install -r requirements/ci.txt
+        run: pip install -e . -r requirements/quality.txt
 
       - name: Analyze imports
         run: lint-imports

.gitignore

@@ -54,8 +54,8 @@ output/*/index.html
 # Sphinx
 docs/_build
 docs/modules.rst
-docs/openedx_learning.rst
-docs/openedx_learning.*.rst
+docs/openedx_content.rst
+docs/openedx_content.*.rst
 
 # Private requirements
 requirements/private.in
@@ -66,6 +66,7 @@ dev.db*
 
 # virtualenv
 venv/
+.venv/
 
 ### Visual Studio Code ###
 # Generally ignore VS Code configuration, except... 

.importlinter

@@ -1,59 +1,64 @@
-# openedx_learning is intended to be a library of apps used across multiple
+# This repo is intended to be a library of apps used across multiple
 # projects, and we want to ensure certain dependency relationships. Please
 # think through any changes you make to this file carefully, and don't just
 # casually modify these linting rules to "fix the build".
+
 [importlinter]
-root_package = openedx_learning
-
-# This is the most basic layering for openedx_learning.
-#
-# The "lib" package is meant for low level utilities, field definitions, and the
-# like, so it's at the bottom layer.
-#
-# The "core" apps are meant to be the heart of our system, with foundational
-# data models and plugin interfaces. It can rely on "lib" utilities.
-#
-# The "contrib" apps are meant to be apps that could easily be created outside
-# of openedx_learning in a separate repository, but are bundled here because
-# we think they'll be generally useful. These apps may call into "core" or "lib"
-# apps, but not the other way around. The "core" apps should *never* import from
-# "contrib".
-[importlinter:contract:openedx_learning_layering]
-name = Lib / Core / Contrib Layering
+root_packages =
+    openedx_content
+    openedx_tagging
+    openedx_django_lib
+    openedx_core
+
+# This is layering within our top-level src folders (mostly Django apps).
+# This should be updated as new Django apps are added.
+# It's possible this might need to grow into multiple rules.
+[importlinter:contract:src_layering]
+name = "top-level source folders are layered correctly"
 type = layers
-layers=
-    openedx_learning.contrib
-    openedx_learning.apps
-    openedx_learning.lib
+layers =
+    # Content is currently the highest-level thing in this repo.
+    # Over time, we may add apps "above" or "below" this.
+    openedx_content
+
+    # Tagging is very simple & fundamental. Should probably not depend on any other Django apps.
+    openedx_tagging
+
+    # Django utilities. Should not dependend on any of the real apps (above).
+    openedx_django_lib
+
+    # This just a empty packages to expose the __version__ number.
+    # Should not depend on anything.
+    openedx_core
 
-# This is layering within our Authoring apps. Every new app should be added to
+# This is layering within our Content applets. Every new applet should be added to
 # this list when it it created.
-[importlinter:contract:core_apps_layering]
-name = Authoring App Dependency Layering
+[importlinter:contract:content_applet_layering]
+name = "openedx_content's internal applets are layered correctly"
 type = layers
 layers=
-    # The public authoring API is at the top–none of the apps should call to it.
-    openedx_learning.api.authoring
+    # The public API is at the top. None of the apps should call to it.
+    openedx_content.api
 
     # The "backup_restore" app handle the new export and import mechanism.
-    openedx_learning.apps.openedx_content.applets.backup_restore
+    openedx_content.applets.backup_restore
 
     # The "components" app is responsible for storing versioned Components,
     # which is Open edX Studio terminology maps to things like individual
     # Problems, Videos, and blocks of HTML text. This is also the type we would
     # associate with a single "leaf" XBlock–one that is not a container type and
     # has no child elements.
-    openedx_learning.apps.openedx_content.applets.components
+    openedx_content.applets.components
 
     # The "contents" app stores the simplest pieces of binary and text data,
     # without versioning information. These belong to a single Learning Package.
-    openedx_learning.apps.openedx_content.applets.contents
+    openedx_content.applets.contents
 
     # The "collections" app stores arbitrary groupings of PublishableEntities.
     # Its only dependency should be the publishing app.
-    openedx_learning.apps.openedx_content.applets.collections
+    openedx_content.applets.collections
 
     # The lowest layer is "publishing", which holds the basic primitives needed
     # to create Learning Packages and manage the draft and publish states for
     # various types of content.
-    openedx_learning.apps.openedx_content.applets.publishing
+    openedx_content.applets.publishing

MANIFEST.in

@@ -2,5 +2,4 @@ include CHANGELOG.rst
 include LICENSE.txt
 include README.rst
 include requirements/base.in
-recursive-include openedx_learning *.html *.png *.gif *.js *.css *.jpg *.jpeg *.svg *.py
-recursive-include openedx_tagging *.html *.png *.gif *.js *.css *.jpg *.jpeg *.svg *.py *.yaml *.json *.csv
+recursive-include src *.html *.png *.gif *.js *.css *.jpg *.jpeg *.svg *.py *.yaml *.json *.csv

Makefile

@@ -83,18 +83,14 @@ selfcheck: ## check that the Makefile is well-formed
 
 extract_translations: ## extract strings to be translated, outputting .mo files
 	rm -rf docs/_build
-	cd openedx_learning && ../manage.py makemessages -l en -v1 -d django
-	cd openedx_learning && ../manage.py makemessages -l en -v1 -d djangojs
-	cd openedx_tagging && ../manage.py makemessages -l en -v1 -d django
-	cd openedx_tagging && ../manage.py makemessages -l en -v1 -d djangojs
+	./manage.py makemessages -l en -v1 -d django
+	./manage.py makemessages -l en -v1 -d djangojs
 
 compile_translations: ## compile translation files, outputting .po files for each supported language
-	cd openedx_learning && ../manage.py compilemessages
-	cd openedx_tagging && ../manage.py compilemessages
+	./manage.py compilemessages
 
 detect_changed_source_translations:
-	cd openedx_learning && i18n_tool changed
-	cd openedx_tagging && i18n_tool changed
+	cd src && i18n_tool changed
 
 pull_translations: ## pull translations from Transifex
 	tx pull -a -f -t --mode reviewed
@@ -103,8 +99,7 @@ push_translations: ## push source translation files (.po) from Transifex
 	tx push -s
 
 dummy_translations: ## generate dummy translation (.po) files
-	cd openedx_learning && i18n_tool dummy
-	cd openedx_tagging && i18n_tool dummy
+	cd src && i18n_tool dummy
 
 build_dummy_translations: extract_translations dummy_translations compile_translations ## generate and compile dummy translation files
 

README.rst

@@ -7,29 +7,22 @@ Open edX Learning Core (and Tagging)
 Overview
 --------
 
-The ``openedx_learning`` package holds Django apps that represent core learning concepts and data models that have been extracted from edx-platform. At the moment, this repo also contains the ``openedx_tagging`` package, but this will likely be moved out in the future.
+The ``openedx-learning`` project holds Django apps that represent core learning platform concepts.
 
 Motivation
 ----------
 
-The short term goal of this project is to create a small, extensible core that is easier to reason about and write extensions for than edx-platform. The longer term goal is to create a more nimble core learning platform, enabling rapid experimentation and drastic changes to the learner experience that are difficult to implement with Open edX today.
+The short term goal of this project is to create a small, extensible core that is easier to reason about and write extensions for than openedx-platform. The longer term goal is to create a more nimble core learning platform, enabling rapid experimentation and drastic changes to the learner experience that are difficult to implement with Open edX today.
 
-Replacing edx-platform is explicitly *not* a goal of this project, as only a small fraction of the concepts in edx-platform make sense to carry over here. When these core concepts are extracted and the data migrated, edx-platform will import apps from this repo and make use of their public in-process APIs.
+Replacing openedx-platform is explicitly *not* a goal of this project, as only a small fraction of the concepts in openedx-platform make sense to carry over here. When these core concepts are extracted and the data migrated, openedx-platform will import apps from this repo and make use of their public in-process APIs.
 
 Architecture
 ------------
 
-Parts
-~~~~~
-
-* ``openedx_learning.lib`` is for shared utilities, and may include things like custom field types, plugin registration code, etc.
-* ``openedx_learning.apps`` contains our Learning Core Django apps, where foundational data structures and APIs will live. The first of these is ``authoring``, which holds apps related to the editing and publishing of learning content.
-* ``openedx_tagging.core`` contains the core Tagging app, which provides data structures and apis for tagging Open edX objects.
-
 Learning Core Package Dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Learning Core code should never import from ``edx-platform``.
+Learning Core code should never import from ``openedx-platform``.
 
 We want to be very strict about dependency management internally as well. Please read the `.importlinter config file <.importlinter>`_ file and the `Python API Conventions ADR <docs/decisions/0016-python-public-api-conventions>`_ for more details.
 
@@ -56,7 +49,7 @@ The structure of this repo follows [OEP-0049](https://open-edx-proposals.readthe
 Code Overview
 -------------
 
-The ``openedx_learning.apps`` package contains all our Django applications.
+The ``src`` folder contains all our Django applications.
 
 Development Workflow
 --------------------

docs/conf.py

@@ -35,7 +35,7 @@ def get_version(*file_paths):
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 sys.path.append(REPO_ROOT)
 
-VERSION = get_version('../openedx_learning', '__init__.py')
+VERSION = get_version('src/openedx_core', '__init__.py')
 
 # Configure Django for autodoc usage
 os.environ['DJANGO_SETTINGS_MODULE'] = 'test_settings'

mypy.ini

@@ -6,8 +6,7 @@ plugins =
     mypy_django_plugin.main,
     mypy_drf_plugin.main
 files =
-    openedx_learning,
-    openedx_tagging,
+    src,
     tests
 
 [mypy.plugins.django-stubs]

mysql_test_settings.py

@@ -17,7 +17,7 @@
     -p 3306:3306 mysql:8
 """
 
-from test_settings import *
+from test_settings import *  # pylint: disable=wildcard-import
 
 DATABASES = {
     "default": {