openedx-learning 0.11.2__py2.py3-none-any.whl → 0.11.4__py2.py3-none-any.whl

openedx_learning/__init__.py

@@ -1,4 +1,4 @@
 """
 Open edX Learning ("Learning Core").
 """
-__version__ = "0.11.2"
+__version__ = "0.11.4"

openedx_learning/apps/authoring/collections/api.py

@@ -3,8 +3,13 @@ Collections API (warning: UNSTABLE, in progress API)
 """
 from __future__ import annotations
 
+from datetime import datetime, timezone
+
+from django.core.exceptions import ValidationError
 from django.db.models import QuerySet
 
+from ..publishing import api as publishing_api
+from ..publishing.models import PublishableEntity
 from .models import Collection
 
 # The public API that will be re-exported by openedx_learning.apps.authoring.api
@@ -13,48 +18,57 @@ from .models import Collection
 # start with an underscore AND it is not in __all__, that function is considered
 # to be callable only by other apps in the authoring package.
 __all__ = [
+    "add_to_collection",
     "create_collection",
     "get_collection",
     "get_collections",
-    "get_learning_package_collections",
+    "get_entity_collections",
+    "remove_from_collection",
     "update_collection",
 ]
 
 
 def create_collection(
     learning_package_id: int,
+    key: str,
+    *,
     title: str,
     created_by: int | None,
     description: str = "",
+    enabled: bool = True,
 ) -> Collection:
     """
     Create a new Collection
     """
     collection = Collection.objects.create(
         learning_package_id=learning_package_id,
+        key=key,
         title=title,
         created_by_id=created_by,
         description=description,
+        enabled=enabled,
     )
     return collection
 
 
-def get_collection(collection_id: int) -> Collection:
+def get_collection(learning_package_id: int, collection_key: str) -> Collection:
     """
     Get a Collection by ID
     """
-    return Collection.objects.get(id=collection_id)
+    return Collection.objects.get_by_key(learning_package_id, collection_key)
 
 
 def update_collection(
-    collection_id: int,
+    learning_package_id: int,
+    key: str,
+    *,
     title: str | None = None,
     description: str | None = None,
 ) -> Collection:
     """
-    Update a Collection
+    Update a Collection identified by the learning_package_id + key.
     """
-    collection = Collection.objects.get(id=collection_id)
+    collection = get_collection(learning_package_id, key)
 
     # If no changes were requested, there's nothing to update, so just return
     # the Collection as-is
@@ -70,23 +84,85 @@ def update_collection(
     return collection
 
 
-def get_learning_package_collections(learning_package_id: int) -> QuerySet[Collection]:
+def add_to_collection(
+    learning_package_id: int,
+    key: str,
+    entities_qset: QuerySet[PublishableEntity],
+    created_by: int | None = None,
+) -> Collection:
     """
-    Get all collections for a given learning package
+    Adds a QuerySet of PublishableEntities to a Collection.
 
-    Only enabled collections are returned
+    These Entities must belong to the same LearningPackage as the Collection, or a ValidationError will be raised.
+
+    PublishableEntities already in the Collection are silently ignored.
+
+    The Collection object's modified date is updated.
+
+    Returns the updated Collection object.
     """
-    return Collection.objects \
-                     .filter(learning_package_id=learning_package_id, enabled=True) \
-                     .select_related("learning_package") \
-                     .order_by('pk')
+    # Disallow adding entities outside the collection's learning package
+    invalid_entity = entities_qset.exclude(learning_package_id=learning_package_id).first()
+    if invalid_entity:
+        raise ValidationError(
+            f"Cannot add entity {invalid_entity.pk} in learning package {invalid_entity.learning_package_id} "
+            f"to collection {key} in learning package {learning_package_id}."
+        )
+
+    collection = get_collection(learning_package_id, key)
+    collection.entities.add(
+        *entities_qset.all(),
+        through_defaults={"created_by_id": created_by},
+    )
+    collection.modified = datetime.now(tz=timezone.utc)
+    collection.save()
+
+    return collection
 
 
-def get_collections(enabled: bool | None = None) -> QuerySet[Collection]:
+def remove_from_collection(
+    learning_package_id: int,
+    key: str,
+    entities_qset: QuerySet[PublishableEntity],
+) -> Collection:
     """
-    Get all collections, optionally caller can filter by enabled flag
+    Removes a QuerySet of PublishableEntities from a Collection.
+
+    PublishableEntities are deleted (in bulk).
+
+    The Collection's modified date is updated (even if nothing was removed).
+
+    Returns the updated Collection.
+    """
+    collection = get_collection(learning_package_id, key)
+
+    collection.entities.remove(*entities_qset.all())
+    collection.modified = datetime.now(tz=timezone.utc)
+    collection.save()
+
+    return collection
+
+
+def get_entity_collections(learning_package_id: int, entity_key: str) -> QuerySet[Collection]:
+    """
+    Get all collections in the given learning package which contain this entity.
+
+    Only enabled collections are returned.
+    """
+    entity = publishing_api.get_publishable_entity_by_key(
+        learning_package_id,
+        key=entity_key,
+    )
+    return entity.collections.filter(enabled=True).order_by("pk")
+
+
+def get_collections(learning_package_id: int, enabled: bool | None = True) -> QuerySet[Collection]:
+    """
+    Get all collections for a given learning package
+
+    Enabled collections are returned by default.
     """
-    qs = Collection.objects.all()
+    qs = Collection.objects.filter(learning_package_id=learning_package_id)
     if enabled is not None:
         qs = qs.filter(enabled=enabled)
     return qs.select_related("learning_package").order_by('pk')

openedx_learning/apps/authoring/collections/migrations/0003_collection_entities.py

@@ -0,0 +1,38 @@
+# Generated by Django 4.2.15 on 2024-08-29 00:05
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+import openedx_learning.lib.validators
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('oel_publishing', '0002_alter_learningpackage_key_and_more'),
+        ('oel_collections', '0002_remove_collection_name_collection_created_by_and_more'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='CollectionPublishableEntity',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(auto_now_add=True, validators=[openedx_learning.lib.validators.validate_utc_datetime])),
+                ('collection', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='oel_collections.collection')),
+                ('created_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL)),
+                ('entity', models.ForeignKey(on_delete=django.db.models.deletion.RESTRICT, to='oel_publishing.publishableentity')),
+            ],
+        ),
+        migrations.AddField(
+            model_name='collection',
+            name='entities',
+            field=models.ManyToManyField(related_name='collections', through='oel_collections.CollectionPublishableEntity', to='oel_publishing.publishableentity'),
+        ),
+        migrations.AddConstraint(
+            model_name='collectionpublishableentity',
+            constraint=models.UniqueConstraint(fields=('collection', 'entity'), name='oel_collections_cpe_uniq_col_ent'),
+        ),
+    ]

openedx_learning/apps/authoring/collections/migrations/0004_collection_key.py

@@ -0,0 +1,57 @@
+# Generated by Django 4.2.15 on 2024-09-04 23:15
+
+from django.db import migrations, models
+from django.utils.crypto import get_random_string
+
+import openedx_learning.lib.fields
+
+
+def generate_keys(apps, schema_editor):
+    """
+    Generates a random strings to initialize the key field where NULL.
+    """
+    length = 50
+    Collection = apps.get_model("oel_collections", "Collection")
+    for collection in Collection.objects.filter(key=None):
+        # Keep generating keys until we get a unique one
+        key = get_random_string(length)
+        while Collection.objects.filter(key=key).exists():
+            key = get_random_string(length)
+
+        collection.key = key
+        collection.save()
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('oel_collections', '0003_collection_entities'),
+    ]
+
+    operations = [
+        # 1. Temporarily add this field with null=True, blank=True
+        migrations.AddField(
+            model_name='collection',
+            name='key',
+            field=openedx_learning.lib.fields.MultiCollationCharField(
+                db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'},
+                db_column='_key', max_length=500, null=True, blank=True),
+            preserve_default=False,
+        ),
+        # 2. Populate the null keys
+        migrations.RunPython(generate_keys),
+        # 3. Add null=False, blank=False to disallow NULL values
+        migrations.AlterField(
+            model_name='collection',
+            name='key',
+            field=openedx_learning.lib.fields.MultiCollationCharField(
+                db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'},
+                db_column='_key', max_length=500, null=False, blank=False),
+            preserve_default=False,
+        ),
+        # 4. Enforce unique constraint
+        migrations.AddConstraint(
+            model_name='collection',
+            constraint=models.UniqueConstraint(fields=('learning_package', 'key'), name='oel_coll_uniq_lp_key'),
+        ),
+    ]

openedx_learning/apps/authoring/collections/models.py

@@ -1,5 +1,68 @@
 """
 Core models for Collections
+
+TLDR Guidelines:
+1. DO NOT modify these models to store full version snapshots.
+2. DO NOT use these models to try to reconstruct historical versions of
+   Collections for fast querying.
+
+If you're trying to do either of these things, you probably want a new model or
+app. For more details, read on.
+
+The goal of these models is to provide a lightweight method of organizing
+PublishableEntities. The first use case for this is modeling the structure of a
+v1 Content Library within a LearningPackage. This is what we'll use the
+Collection model for.
+
+An important thing to note here is that Collections are *NOT* publishable
+entities themselves. They have no "Draft" or "Published" versions. Collections
+are never "published", though the things inside of them are.
+
+When a LibraryContentBlock makes use of a Content Library, it copies all of
+the items it will use into the Course itself. It will also store a version
+on the LibraryContentBlock -- this is a MongoDB ObjectID in v1 and an integer in
+v2 Libraries. Later on, the LibraryContentBlock will want to check back to see
+if any updates have been made, using its version as a key. If a new version
+exists, the course team has the option of re-copying data from the Library.
+
+ModuleStore based v1 Libraries and Blockstore-based v2 libraries both version
+the entire library in a series of snapshots. This makes it difficult to have
+very large libraries, which is an explicit goal for Modular Learning. In
+Learning Core, we've moved to tracking the versions of individual Components to
+address this issue. But that means we no longer have a single version indicator
+for "has anything here changed"?
+
+We *could* have put that version in the ``publishing`` app's PublishLog, but
+that would make it too broad. We want the ability to eventually collapse many v1
+Libraries into a single Learning Core backed v2 Library. If we tracked the
+versioning in only a central location, then we'd have many false positives where
+the version was bumped because something else in the Learning Package changed.
+So instead, we're creating a new Collection model inside the LearningPackage to
+track that concept.
+
+A critical takeaway is that we don't have to store snapshots of every version of
+a Collection, because that data has been copied over by the LibraryContentBlock.
+We only need to store the current state of the Collection, and increment the
+version numbers when changes happen. This will allow the LibraryContentBlock to
+check in and re-copy over the latest version if the course team desires.
+
+That's why these models only store the current state of a Collection. Unlike the
+``components`` app,  ``collections`` does not store fully materialized snapshots
+of past versions. This is done intentionally in order to save space and reduce
+the cost of writes. Collections may grow to be very large, and we don't want to
+be writing N rows with every version, where N is the number of
+PublishableEntities in a Collection.
+
+MVP of these models does not store changesets, but we can add this when there's a
+use case for it. The number of rows in these changesets would grow in proportion
+to the number of things that are actually changing (instead of copying over
+everything on every version). This is could be used to make it easier to figure out
+what changed between two given versions of a Collection. A LibraryContentBlock
+in a course would have stored the version number of the last time it copied data
+from the Collection, and we can eventually surface this data to the user. Note that
+while it may be possible to reconstruct past versions of Collections based off of
+this changeset data, it's going to be a very slow process to do so, and it is
+strongly discouraged.
 """
 from __future__ import annotations
 
@@ -7,25 +70,46 @@ from django.conf import settings
 from django.db import models
 from django.utils.translation import gettext_lazy as _
 
-from ....lib.fields import MultiCollationTextField, case_insensitive_char_field
-from ....lib.validators import validate_utc_datetime
-from ..publishing.models import LearningPackage
+from openedx_learning.lib.fields import MultiCollationTextField, case_insensitive_char_field, key_field
+from openedx_learning.lib.validators import validate_utc_datetime
+
+from ..publishing.models import LearningPackage, PublishableEntity
 
 __all__ = [
     "Collection",
+    "CollectionPublishableEntity",
 ]
 
 
+class CollectionManager(models.Manager):
+    """
+    Custom manager for Collection class.
+    """
+    def get_by_key(self, learning_package_id: int, key: str):
+        """
+        Get the Collection for the given Learning Package + key.
+        """
+        return self.select_related('learning_package') \
+                   .get(learning_package_id=learning_package_id, key=key)
+
+
 class Collection(models.Model):
     """
     Represents a collection of library components
     """
+    objects: CollectionManager[Collection] = CollectionManager()
 
     id = models.AutoField(primary_key=True)
 
     # Each collection belongs to a learning package
     learning_package = models.ForeignKey(LearningPackage, on_delete=models.CASCADE)
 
+    # Every collection is uniquely and permanently identified within its learning package
+    # by a 'key' that is set during creation. Both will appear in the
+    # collection's opaque key:
+    # e.g. "lib-collection:lib:key" is the opaque key for a library collection.
+    key = key_field(db_column='_key')
+
     title = case_insensitive_char_field(
         null=False,
         blank=False,
@@ -79,8 +163,24 @@ class Collection(models.Model):
         ],
     )
 
+    entities: models.ManyToManyField[PublishableEntity, "CollectionPublishableEntity"] = models.ManyToManyField(
+        PublishableEntity,
+        through="CollectionPublishableEntity",
+        related_name="collections",
+    )
+
     class Meta:
         verbose_name_plural = "Collections"
+        constraints = [
+            # Keys are unique within a given LearningPackage.
+            models.UniqueConstraint(
+                fields=[
+                    "learning_package",
+                    "key",
+                ],
+                name="oel_coll_uniq_lp_key",
+            ),
+        ]
         indexes = [
             models.Index(fields=["learning_package", "title"]),
         ]
@@ -95,4 +195,43 @@ class Collection(models.Model):
         """
         User-facing string representation of a Collection.
         """
-        return f"<{self.__class__.__name__}> ({self.id}:{self.title})"
+        return f"<{self.__class__.__name__}> (lp:{self.learning_package_id} {self.key}:{self.title})"
+
+
+class CollectionPublishableEntity(models.Model):
+    """
+    Collection -> PublishableEntity association.
+    """
+    collection = models.ForeignKey(
+        Collection,
+        on_delete=models.CASCADE,
+    )
+    entity = models.ForeignKey(
+        PublishableEntity,
+        on_delete=models.RESTRICT,
+    )
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+    )
+    created = models.DateTimeField(
+        auto_now_add=True,
+        validators=[
+            validate_utc_datetime,
+        ],
+    )
+
+    class Meta:
+        constraints = [
+            # Prevent race conditions from making multiple rows associating the
+            # same Collection to the same Entity.
+            models.UniqueConstraint(
+                fields=[
+                    "collection",
+                    "entity",
+                ],
+                name="oel_collections_cpe_uniq_col_ent",
+            )
+        ]

{openedx_learning-0.11.2.dist-info → openedx_learning-0.11.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openedx-learning
-Version: 0.11.2
+Version: 0.11.4
 Summary: Open edX Learning Core and Tagging.
 Home-page: https://github.com/openedx/openedx-learning
 Author: David Ormsbee
@@ -9,7 +9,7 @@ License: AGPL 3.0
 Keywords: Python edx
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Django
-Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.2
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
 Classifier: Natural Language :: English
@@ -18,12 +18,12 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
 License-File: LICENSE.txt
-Requires-Dist: Django<5.0
-Requires-Dist: rules<4.0
 Requires-Dist: edx-drf-extensions
-Requires-Dist: djangorestframework<4.0
-Requires-Dist: attrs
 Requires-Dist: celery
+Requires-Dist: rules<4.0
+Requires-Dist: attrs
+Requires-Dist: Django<5.0
+Requires-Dist: djangorestframework<4.0
 
 Open edX Learning Core (and Tagging)
 ====================================

{openedx_learning-0.11.2.dist-info → openedx_learning-0.11.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-openedx_learning/__init__.py,sha256=jEycplMzOABlZc9NUIkiXm-xHQUhJI-kaHVtqQ-5hDI,68
+openedx_learning/__init__.py,sha256=FMXyR0DLIu3bZiyMThKBsLYaXQyU0ilJ_EpYc0ehnLw,68
 openedx_learning/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/api/authoring.py,sha256=vbRpiQ2wOfN3oR2bbN0-bI2ra0QRtha9tVixKW1ENis,929
@@ -6,11 +6,13 @@ openedx_learning/api/authoring_models.py,sha256=PrhEYozI7nzC7N1v_sP1QgjwjRvLX6it
 openedx_learning/apps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/collections/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-openedx_learning/apps/authoring/collections/api.py,sha256=lF6Wva4ySekwkJGy7z0Kv2pONW2Ho1YffnLYcJ1cyv4,2595
+openedx_learning/apps/authoring/collections/api.py,sha256=8jNn_S43JqWIGWyDvR7McxGJ-3TboibdHF3LWyQMFWE,4978
 openedx_learning/apps/authoring/collections/apps.py,sha256=67imy9vnyXml4cfLNGFJhuZr2yx1q92-xz4ih3yJgNU,416
-openedx_learning/apps/authoring/collections/models.py,sha256=K_hfFxMirAqntgL1yxoS8LjTJkVOHCszoR6PwMfJGQ8,2427
+openedx_learning/apps/authoring/collections/models.py,sha256=YAwDf8igFbs8Fox3QpbkzBOvYL39cBsRdelxlXx6IYs,8545
 openedx_learning/apps/authoring/collections/migrations/0001_initial.py,sha256=xcJoqMLROW9FTILYrz6UsyotVu9wBN5tRBwRoAWG6dg,1496
 openedx_learning/apps/authoring/collections/migrations/0002_remove_collection_name_collection_created_by_and_more.py,sha256=NRl-_-EkE-w4JLeJsZf6lHxYNV3TIAJVIWbv_-xytGo,2162
+openedx_learning/apps/authoring/collections/migrations/0003_collection_entities.py,sha256=-YddfCFS0HW3JsEcpatjakOyeGVklOmba9uRQ-0zIxQ,1805
+openedx_learning/apps/authoring/collections/migrations/0004_collection_key.py,sha256=G1STMrsCjU8Ykp0Zm_nIf5YqZCBy1TRTVX7q7zrly8c,2021
 openedx_learning/apps/authoring/collections/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openedx_learning/apps/authoring/components/admin.py,sha256=QE7e76C6X2V1AQPxQe6SayQPfCMmbs4RZPEPIGcvTWw,4672
@@ -103,8 +105,8 @@ openedx_tagging/core/tagging/rest_api/v1/serializers.py,sha256=gbvEBLvsmfPc3swWz
 openedx_tagging/core/tagging/rest_api/v1/urls.py,sha256=dNUKCtUCx_YzrwlbEbpDfjGVQbb2QdJ1VuJCkladj6E,752
 openedx_tagging/core/tagging/rest_api/v1/views.py,sha256=ZRkSILdb8g5k_BcuuVVfdffEdY9vFQ_YtMa3JrN0Xz8,35581
 openedx_tagging/core/tagging/rest_api/v1/views_import.py,sha256=kbHUPe5A6WaaJ3J1lFIcYCt876ecLNQfd19m7YYub6c,1470
-openedx_learning-0.11.2.dist-info/LICENSE.txt,sha256=QTW2QN7q3XszgUAXm9Dzgtu5LXYKbR1SGnqMa7ufEuY,35139
-openedx_learning-0.11.2.dist-info/METADATA,sha256=7xfFEtSUdToIKa-HQVfKknu6_m_BQ62APno2fQulC_4,8777
-openedx_learning-0.11.2.dist-info/WHEEL,sha256=GUeE9LxUgRABPG7YM0jCNs9cBsAIx0YAkzCB88PMLgc,109
-openedx_learning-0.11.2.dist-info/top_level.txt,sha256=IYFbr5mgiEHd-LOtZmXj3q3a0bkGK1M9LY7GXgnfi4M,33
-openedx_learning-0.11.2.dist-info/RECORD,,
+openedx_learning-0.11.4.dist-info/LICENSE.txt,sha256=QTW2QN7q3XszgUAXm9Dzgtu5LXYKbR1SGnqMa7ufEuY,35139
+openedx_learning-0.11.4.dist-info/METADATA,sha256=QxT-9RsbGVZmy8qBhYwsnwl8vwTMh3vXqJ6FfeRfx1g,8777
+openedx_learning-0.11.4.dist-info/WHEEL,sha256=qUzzGenXXuJTzyjFah76kDVqDvnk-YDzY00svnrl84w,109
+openedx_learning-0.11.4.dist-info/top_level.txt,sha256=IYFbr5mgiEHd-LOtZmXj3q3a0bkGK1M9LY7GXgnfi4M,33
+openedx_learning-0.11.4.dist-info/RECORD,,

{openedx_learning-0.11.2.dist-info → openedx_learning-0.11.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (73.0.1)
+Generator: setuptools (74.1.2)
 Root-Is-Purelib: true
 Tag: py2-none-any
 Tag: py3-none-any