openedx-learning 0.11.1__tar.gz → 0.11.3__tar.gz

{openedx_learning-0.11.1/openedx_learning.egg-info → openedx_learning-0.11.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openedx-learning
-Version: 0.11.1
+Version: 0.11.3
 Summary: Open edX Learning Core and Tagging.
 Home-page: https://github.com/openedx/openedx-learning
 Author: David Ormsbee
@@ -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: rules<4.0
+Requires-Dist: Django<5.0
+Requires-Dist: djangorestframework<4.0
 Requires-Dist: edx-drf-extensions
-Requires-Dist: celery
 Requires-Dist: attrs
-Requires-Dist: djangorestframework<4.0
-Requires-Dist: Django<5.0
+Requires-Dist: rules<4.0
+Requires-Dist: celery
 
 Open edX Learning Core (and Tagging)
 ====================================

{openedx_learning-0.11.1 → openedx_learning-0.11.3}/openedx_learning/__init__.py

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

openedx_learning-0.11.3/openedx_learning/apps/authoring/collections/api.py

@@ -0,0 +1,163 @@
+"""
+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
+# is listed in the __all__ entries below. Internal helper functions that are
+# private to this module should start with an underscore. If a function does not
+# 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_entity_collections",
+    "remove_from_collection",
+    "update_collection",
+]
+
+
+def create_collection(
+    learning_package_id: int,
+    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,
+        title=title,
+        created_by_id=created_by,
+        description=description,
+        enabled=enabled,
+    )
+    return collection
+
+
+def get_collection(collection_id: int) -> Collection:
+    """
+    Get a Collection by ID
+    """
+    return Collection.objects.get(id=collection_id)
+
+
+def update_collection(
+    collection_id: int,
+    title: str | None = None,
+    description: str | None = None,
+) -> Collection:
+    """
+    Update a Collection
+    """
+    collection = Collection.objects.get(id=collection_id)
+
+    # If no changes were requested, there's nothing to update, so just return
+    # the Collection as-is
+    if all(field is None for field in [title, description]):
+        return collection
+
+    if title is not None:
+        collection.title = title
+    if description is not None:
+        collection.description = description
+
+    collection.save()
+    return collection
+
+
+def add_to_collection(
+    collection_id: int,
+    entities_qset: QuerySet[PublishableEntity],
+    created_by: int | None = None,
+) -> Collection:
+    """
+    Adds a QuerySet of PublishableEntities to a Collection.
+
+    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.
+    """
+    collection = get_collection(collection_id)
+    learning_package_id = collection.learning_package_id
+
+    # 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 {collection_id} in learning package {learning_package_id}."
+        )
+
+    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 remove_from_collection(
+    collection_id: int,
+    entities_qset: QuerySet[PublishableEntity],
+) -> Collection:
+    """
+    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(collection_id)
+
+    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.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-0.11.3/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-0.11.3/openedx_learning/apps/authoring/collections/models.py

@@ -0,0 +1,207 @@
+"""
+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
+
+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, PublishableEntity
+
+__all__ = [
+    "Collection",
+    "CollectionPublishableEntity",
+]
+
+
+class Collection(models.Model):
+    """
+    Represents a collection of library components
+    """
+
+    id = models.AutoField(primary_key=True)
+
+    # Each collection belongs to a learning package
+    learning_package = models.ForeignKey(LearningPackage, on_delete=models.CASCADE)
+
+    title = case_insensitive_char_field(
+        null=False,
+        blank=False,
+        max_length=500,
+        help_text=_(
+            "The title of the collection."
+        ),
+    )
+
+    description = MultiCollationTextField(
+        blank=True,
+        null=False,
+        default="",
+        max_length=10_000,
+        help_text=_(
+            "Provides extra information for the user about this collection."
+        ),
+        db_collations={
+            "sqlite": "NOCASE",
+            "mysql": "utf8mb4_unicode_ci",
+        }
+    )
+
+    # We don't have api functions to handle the enabled field. This is a placeholder for future use and
+    # a way to "soft delete" collections.
+    enabled = models.BooleanField(
+        default=True,
+        help_text=_(
+            "Whether the collection is enabled or not."
+        ),
+    )
+
+    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,
+        ],
+    )
+
+    modified = models.DateTimeField(
+        auto_now=True,
+        validators=[
+            validate_utc_datetime,
+        ],
+    )
+
+    entities: models.ManyToManyField[PublishableEntity, "CollectionPublishableEntity"] = models.ManyToManyField(
+        PublishableEntity,
+        through="CollectionPublishableEntity",
+        related_name="collections",
+    )
+
+    class Meta:
+        verbose_name_plural = "Collections"
+        indexes = [
+            models.Index(fields=["learning_package", "title"]),
+        ]
+
+    def __repr__(self) -> str:
+        """
+        Developer-facing representation of a Collection.
+        """
+        return str(self)
+
+    def __str__(self) -> str:
+        """
+        User-facing string representation of a Collection.
+        """
+        return f"<{self.__class__.__name__}> ({self.id}:{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.1 → openedx_learning-0.11.3/openedx_learning.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openedx-learning
-Version: 0.11.1
+Version: 0.11.3
 Summary: Open edX Learning Core and Tagging.
 Home-page: https://github.com/openedx/openedx-learning
 Author: David Ormsbee
@@ -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: rules<4.0
+Requires-Dist: Django<5.0
+Requires-Dist: djangorestframework<4.0
 Requires-Dist: edx-drf-extensions
-Requires-Dist: celery
 Requires-Dist: attrs
-Requires-Dist: djangorestframework<4.0
-Requires-Dist: Django<5.0
+Requires-Dist: rules<4.0
+Requires-Dist: celery
 
 Open edX Learning Core (and Tagging)
 ====================================

{openedx_learning-0.11.1 → openedx_learning-0.11.3}/openedx_learning.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ openedx_learning/apps/authoring/collections/apps.py
 openedx_learning/apps/authoring/collections/models.py
 openedx_learning/apps/authoring/collections/migrations/0001_initial.py
 openedx_learning/apps/authoring/collections/migrations/0002_remove_collection_name_collection_created_by_and_more.py
+openedx_learning/apps/authoring/collections/migrations/0003_collection_entities.py
 openedx_learning/apps/authoring/collections/migrations/__init__.py
 openedx_learning/apps/authoring/components/__init__.py
 openedx_learning/apps/authoring/components/admin.py

openedx_learning-0.11.1/openedx_learning/apps/authoring/collections/api.py

@@ -1,80 +0,0 @@
-"""
-Collections API (warning: UNSTABLE, in progress API)
-"""
-from __future__ import annotations
-
-from django.db.models import QuerySet
-
-from .models import Collection
-
-# The public API that will be re-exported by openedx_learning.apps.authoring.api
-# is listed in the __all__ entries below. Internal helper functions that are
-# private to this module should start with an underscore. If a function does not
-# 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__ = [
-    "create_collection",
-    "get_collection",
-    "get_learning_package_collections",
-    "update_collection",
-]
-
-
-def create_collection(
-    learning_package_id: int,
-    title: str,
-    created_by: int | None,
-    description: str = "",
-) -> Collection:
-    """
-    Create a new Collection
-    """
-    collection = Collection.objects.create(
-        learning_package_id=learning_package_id,
-        title=title,
-        created_by_id=created_by,
-        description=description,
-    )
-    return collection
-
-
-def get_collection(collection_id: int) -> Collection:
-    """
-    Get a Collection by ID
-    """
-    return Collection.objects.get(id=collection_id)
-
-
-def update_collection(
-    collection_id: int,
-    title: str | None = None,
-    description: str | None = None,
-) -> Collection:
-    """
-    Update a Collection
-    """
-    collection = Collection.objects.get(id=collection_id)
-
-    # If no changes were requested, there's nothing to update, so just return
-    # the Collection as-is
-    if all(field is None for field in [title, description]):
-        return collection
-
-    if title is not None:
-        collection.title = title
-    if description is not None:
-        collection.description = description
-
-    collection.save()
-    return collection
-
-
-def get_learning_package_collections(learning_package_id: int) -> QuerySet[Collection]:
-    """
-    Get all collections for a given learning package
-
-    Only enabled collections are returned
-    """
-    return Collection.objects \
-                     .filter(learning_package_id=learning_package_id, enabled=True) \
-                     .select_related("learning_package")

openedx_learning-0.11.1/openedx_learning/apps/authoring/collections/models.py

@@ -1,98 +0,0 @@
-"""
-Core models for Collections
-"""
-from __future__ import annotations
-
-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
-
-__all__ = [
-    "Collection",
-]
-
-
-class Collection(models.Model):
-    """
-    Represents a collection of library components
-    """
-
-    id = models.AutoField(primary_key=True)
-
-    # Each collection belongs to a learning package
-    learning_package = models.ForeignKey(LearningPackage, on_delete=models.CASCADE)
-
-    title = case_insensitive_char_field(
-        null=False,
-        blank=False,
-        max_length=500,
-        help_text=_(
-            "The title of the collection."
-        ),
-    )
-
-    description = MultiCollationTextField(
-        blank=True,
-        null=False,
-        default="",
-        max_length=10_000,
-        help_text=_(
-            "Provides extra information for the user about this collection."
-        ),
-        db_collations={
-            "sqlite": "NOCASE",
-            "mysql": "utf8mb4_unicode_ci",
-        }
-    )
-
-    # We don't have api functions to handle the enabled field. This is a placeholder for future use and
-    # a way to "soft delete" collections.
-    enabled = models.BooleanField(
-        default=True,
-        help_text=_(
-            "Whether the collection is enabled or not."
-        ),
-    )
-
-    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,
-        ],
-    )
-
-    modified = models.DateTimeField(
-        auto_now=True,
-        validators=[
-            validate_utc_datetime,
-        ],
-    )
-
-    class Meta:
-        verbose_name_plural = "Collections"
-        indexes = [
-            models.Index(fields=["learning_package", "title"]),
-        ]
-
-    def __repr__(self) -> str:
-        """
-        Developer-facing representation of a Collection.
-        """
-        return str(self)
-
-    def __str__(self) -> str:
-        """
-        User-facing string representation of a Collection.
-        """
-        return f"<{self.__class__.__name__}> ({self.id}:{self.title})"

{openedx_learning-0.11.1 → openedx_learning-0.11.3}/openedx_learning.egg-info/requires.txt

@@ -1,6 +1,6 @@
-rules<4.0
+Django<5.0
+djangorestframework<4.0
 edx-drf-extensions
-celery
 attrs
-djangorestframework<4.0
-Django<5.0
+rules<4.0
+celery