openedx-learning 0.4.4__tar.gz → 0.5.1__tar.gz

{openedx-learning-0.4.4/openedx_learning.egg-info → openedx-learning-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.2
 Name: openedx-learning
-Version: 0.4.4
+Version: 0.5.1
 Summary: An experiment.
 Home-page: https://github.com/openedx/openedx-learning
 Author: David Ormsbee

{openedx-learning-0.4.4 → openedx-learning-0.5.1}/openedx_learning/__init__.py

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

{openedx-learning-0.4.4 → openedx-learning-0.5.1}/openedx_learning/core/components/admin.py

@@ -35,16 +35,15 @@ class ComponentAdmin(ReadOnlyModelAdmin):
     """
     Django admin configuration for Component
     """
-    list_display = ("key", "uuid", "namespace", "type", "created")
+    list_display = ("key", "uuid", "component_type", "created")
     readonly_fields = [
         "learning_package",
         "uuid",
-        "namespace",
-        "type",
+        "component_type",
         "key",
         "created",
     ]
-    list_filter = ("type", "learning_package")
+    list_filter = ("component_type", "learning_package")
     search_fields = ["publishable_entity__uuid", "publishable_entity__key"]
     inlines = [ComponentVersionInline]
 

openedx-learning-0.5.1/openedx_learning/core/components/api.py

@@ -0,0 +1,340 @@
+"""
+Components API (warning: UNSTABLE, in progress API)
+
+These functions are often going to be simple-looking write operations, but there
+is bookkeeping logic needed across multiple models to keep state consistent. You
+can read from the models directly for various queries if necessary–we do this in
+the Django Admin for instance. But you should NEVER mutate this app's models
+directly, since there might be other related models that you may not know about.
+
+Please look at the models.py file for more information about the kinds of data
+are stored in this app.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from django.db.models import Q, QuerySet
+from django.db.transaction import atomic
+
+from ...lib.cache import lru_cache
+from ..publishing import api as publishing_api
+from .models import Component, ComponentType, ComponentVersion, ComponentVersionRawContent
+
+
+@lru_cache(maxsize=128)
+def get_or_create_component_type_id(namespace: str, name: str) -> int:
+    """
+    Get the ID of a ComponentType, and create if missing.
+    """
+    component_type, _created = ComponentType.objects.get_or_create(
+        namespace=namespace,
+        name=name,
+    )
+    return component_type.id
+
+
+def create_component(
+    learning_package_id: int,
+    /,
+    namespace: str,
+    type_name: str,
+    local_key: str,
+    created: datetime,
+    created_by: int | None,
+) -> Component:
+    """
+    Create a new Component (an entity like a Problem or Video)
+    """
+    key = f"{namespace}:{type_name}@{local_key}"
+    with atomic():
+        publishable_entity = publishing_api.create_publishable_entity(
+            learning_package_id, key, created, created_by
+        )
+        component = Component.objects.create(
+            publishable_entity=publishable_entity,
+            learning_package_id=learning_package_id,
+            component_type_id=get_or_create_component_type_id(namespace, type_name),
+            local_key=local_key,
+        )
+    return component
+
+
+def create_component_version(
+    component_pk: int,
+    /,
+    version_num: int,
+    title: str,
+    created: datetime,
+    created_by: int | None,
+) -> ComponentVersion:
+    """
+    Create a new ComponentVersion
+    """
+    with atomic():
+        publishable_entity_version = publishing_api.create_publishable_entity_version(
+            component_pk,
+            version_num=version_num,
+            title=title,
+            created=created,
+            created_by=created_by,
+        )
+        component_version = ComponentVersion.objects.create(
+            publishable_entity_version=publishable_entity_version,
+            component_id=component_pk,
+        )
+    return component_version
+
+
+def create_next_version(
+    component_pk: int,
+    /,
+    title: str,
+    content_to_replace: dict[str, int | None],
+    created: datetime,
+    created_by: int | None = None,
+) -> ComponentVersion:
+    """
+    Create a new ComponentVersion based on the most recent version.
+
+    A very common pattern for making a new ComponentVersion is going to be "make
+    it just like the last version, except changing these one or two things".
+    Before calling this, you should create any new contents via the contents
+    API, since ``content_to_replace`` needs RawContent IDs for the values.
+
+    The ``content_to_replace`` dict is a mapping of strings representing the
+    local path/key for a file, to ``RawContent.id`` values. Using a `None` for
+    a value in this dict means to delete that key in the next version.
+
+    It is okay to mark entries for deletion that don't exist. For instance, if a
+    version has ``a.txt`` and ``b.txt``, sending a ``content_to_replace`` value
+    of ``{"a.txt": None, "c.txt": None}`` will remove ``a.txt`` from the next
+    version, leave ``b.txt`` alone, and will not error–even though there is no
+    ``c.txt`` in the previous version. This is to make it a little more
+    convenient to remove paths (e.g. due to deprecation) without having to
+    always check for its existence first.
+
+    TODO: Have to add learning_downloadable info to this when it comes time to
+          support static asset download.
+    """
+    # This needs to grab the highest version_num for this Publishable Entity.
+    # This will often be the Draft version, but not always. For instance, if
+    # an entity was soft-deleted, the draft would be None, but the version_num
+    # should pick up from the last edited version. Likewise, a Draft might get
+    # reverted to an earlier version, but we want the latest version_num when
+    # creating the next version.
+    component = Component.objects.get(pk=component_pk)
+    last_version = component.versioning.latest
+    if last_version is None:
+        next_version_num = 1
+    else:
+        next_version_num = last_version.version_num + 1
+
+    with atomic():
+        publishable_entity_version = publishing_api.create_publishable_entity_version(
+            component_pk,
+            version_num=next_version_num,
+            title=title,
+            created=created,
+            created_by=created_by,
+        )
+        component_version = ComponentVersion.objects.create(
+            publishable_entity_version=publishable_entity_version,
+            component_id=component_pk,
+        )
+        # First copy the new stuff over...
+        for key, raw_content_pk in content_to_replace.items():
+            # If the raw_content_pk is None, it means we want to remove the
+            # content represented by our key from the next version. Otherwise,
+            # we add our key->raw_content_pk mapping to the next version.
+            if raw_content_pk is not None:
+                ComponentVersionRawContent.objects.create(
+                    raw_content_id=raw_content_pk,
+                    component_version=component_version,
+                    key=key,
+                    learner_downloadable=False,
+                )
+        # Now copy any old associations that existed, as long as they aren't
+        # in conflict with the new stuff or marked for deletion.
+        last_version_content_mapping = ComponentVersionRawContent.objects \
+                                                                 .filter(component_version=last_version)
+        for cvrc in last_version_content_mapping:
+            if cvrc.key not in content_to_replace:
+                ComponentVersionRawContent.objects.create(
+                    raw_content_id=cvrc.raw_content_id,
+                    component_version=component_version,
+                    key=cvrc.key,
+                    learner_downloadable=cvrc.learner_downloadable,
+                )
+
+        return component_version
+
+
+def create_component_and_version(
+    learning_package_id: int,
+    /,
+    namespace: str,
+    type_name: str,
+    local_key: str,
+    title: str,
+    created: datetime,
+    created_by: int | None = None,
+) -> tuple[Component, ComponentVersion]:
+    """
+    Create a Component and associated ComponentVersion atomically
+    """
+    with atomic():
+        component = create_component(
+            learning_package_id, namespace, type_name, local_key, created, created_by
+        )
+        component_version = create_component_version(
+            component.pk,
+            version_num=1,
+            title=title,
+            created=created,
+            created_by=created_by,
+        )
+        return (component, component_version)
+
+
+def get_component(component_pk: int, /) -> Component:
+    """
+    Get Component by its primary key.
+
+    This is the same as the PublishableEntity's ID primary key.
+    """
+    return Component.with_publishing_relations.get(pk=component_pk)
+
+
+def get_component_by_key(
+    learning_package_id: int,
+    /,
+    namespace: str,
+    type_name: str,
+    local_key: str,
+) -> Component:
+    """
+    Get a Component by its unique (namespace, type, local_key) tuple.
+    """
+    return Component.with_publishing_relations \
+                    .get(
+                        learning_package_id=learning_package_id,
+                        component_type__namespace=namespace,
+                        component_type__name=type_name,
+                        local_key=local_key,
+                    )
+
+
+def component_exists_by_key(
+    learning_package_id: int,
+    /,
+    namespace: str,
+    type_name: str,
+    local_key: str
+) -> bool:
+    """
+    Return True/False for whether a Component exists.
+
+    Note that a Component still exists even if it's been soft-deleted (there's
+    no current Draft version for it), or if it's been unpublished.
+    """
+    try:
+        _component = Component.objects.only('pk', 'component_type').get(
+            learning_package_id=learning_package_id,
+            component_type__namespace=namespace,
+            component_type__name=type_name,
+            local_key=local_key,
+        )
+        return True
+    except Component.DoesNotExist:
+        return False
+
+
+def get_components(
+    learning_package_id: int,
+    /,
+    draft: bool | None = None,
+    published: bool | None = None,
+    namespace: str | None = None,
+    type_names: list[str] | None = None,
+    draft_title: str | None = None,
+    published_title: str | None = None,
+) -> QuerySet[Component]:
+    """
+    Fetch a QuerySet of Components for a LearningPackage using various filters.
+
+    This method will pre-load all the relations that we need in order to get
+    info from the Component's draft and published versions, since we'll be
+    referencing these a lot.
+    """
+    qset = Component.with_publishing_relations \
+                    .filter(learning_package_id=learning_package_id) \
+                    .order_by('pk')
+
+    if draft is not None:
+        qset = qset.filter(publishable_entity__draft__version__isnull=not draft)
+    if published is not None:
+        qset = qset.filter(publishable_entity__published__version__isnull=not published)
+    if namespace is not None:
+        qset = qset.filter(component_type__namespace=namespace)
+    if type_names is not None:
+        qset = qset.filter(component_type__name__in=type_names)
+    if draft_title is not None:
+        qset = qset.filter(
+            publishable_entity__draft__version__title__icontains=draft_title
+        )
+    if published_title is not None:
+        qset = qset.filter(
+            publishable_entity__published__version__title__icontains=published_title
+        )
+
+    return qset
+
+
+def get_component_version_content(
+    learning_package_key: str,
+    component_key: str,
+    version_num: int,
+    key: Path,
+) -> ComponentVersionRawContent:
+    """
+    Look up ComponentVersionRawContent by human readable keys.
+
+    Can raise a django.core.exceptions.ObjectDoesNotExist error if there is no
+    matching ComponentVersionRawContent.
+    """
+    queries = (
+        Q(component_version__component__learning_package__key=learning_package_key)
+        & Q(component_version__component__publishable_entity__key=component_key)
+        & Q(component_version__publishable_entity_version__version_num=version_num)
+        & Q(key=key)
+    )
+    return ComponentVersionRawContent.objects \
+                                     .select_related(
+                                         "raw_content",
+                                         "raw_content__media_type",
+                                         "raw_content__textcontent",
+                                         "component_version",
+                                         "component_version__component",
+                                         "component_version__component__learning_package",
+                                     ).get(queries)
+
+
+def add_content_to_component_version(
+    component_version_id: int,
+    /,
+    raw_content_id: int,
+    key: str,
+    learner_downloadable=False,
+) -> ComponentVersionRawContent:
+    """
+    Add a RawContent to the given ComponentVersion
+    """
+    cvrc, _created = ComponentVersionRawContent.objects.get_or_create(
+        component_version_id=component_version_id,
+        raw_content_id=raw_content_id,
+        key=key,
+        learner_downloadable=learner_downloadable,
+    )
+    return cvrc

{openedx-learning-0.4.4 → openedx-learning-0.5.1}/openedx_learning/core/components/migrations/0001_initial.py

@@ -1,4 +1,4 @@
-# Generated by Django 3.2.23 on 2023-12-04 00:41
+# Generated by Django 3.2.23 on 2024-01-31 05:34
 
 import uuid
 
@@ -13,7 +13,7 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
-        ('oel_publishing', '0002_alter_fk_on_delete'),
+        ('oel_publishing', '0001_initial'),
         ('oel_contents', '0001_initial'),
     ]
 
@@ -22,16 +22,21 @@ class Migration(migrations.Migration):
             name='Component',
             fields=[
                 ('publishable_entity', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, primary_key=True, serialize=False, to='oel_publishing.publishableentity')),
-                ('namespace', openedx_learning.lib.fields.MultiCollationCharField(db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'}, max_length=100)),
-                ('type', openedx_learning.lib.fields.MultiCollationCharField(blank=True, db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'}, max_length=100)),
                 ('local_key', openedx_learning.lib.fields.MultiCollationCharField(db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'}, max_length=500)),
-                ('learning_package', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='oel_publishing.learningpackage')),
             ],
             options={
                 'verbose_name': 'Component',
                 'verbose_name_plural': 'Components',
             },
         ),
+        migrations.CreateModel(
+            name='ComponentType',
+            fields=[
+                ('id', models.AutoField(primary_key=True, serialize=False)),
+                ('namespace', openedx_learning.lib.fields.MultiCollationCharField(db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'}, max_length=100)),
+                ('name', openedx_learning.lib.fields.MultiCollationCharField(blank=True, db_collations={'mysql': 'utf8mb4_bin', 'sqlite': 'BINARY'}, max_length=100)),
+            ],
+        ),
         migrations.CreateModel(
             name='ComponentVersion',
             fields=[
@@ -59,6 +64,16 @@ class Migration(migrations.Migration):
             name='raw_contents',
             field=models.ManyToManyField(related_name='component_versions', through='oel_components.ComponentVersionRawContent', to='oel_contents.RawContent'),
         ),
+        migrations.AddField(
+            model_name='component',
+            name='component_type',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, to='oel_components.componenttype'),
+        ),
+        migrations.AddField(
+            model_name='component',
+            name='learning_package',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='oel_publishing.learningpackage'),
+        ),
         migrations.AddIndex(
             model_name='componentversionrawcontent',
             index=models.Index(fields=['raw_content', 'component_version'], name='oel_cvrawcontent_c_cv'),
@@ -73,10 +88,10 @@ class Migration(migrations.Migration):
         ),
         migrations.AddIndex(
             model_name='component',
-            index=models.Index(fields=['learning_package', 'namespace', 'type', 'local_key'], name='oel_component_idx_lc_ns_t_lk'),
+            index=models.Index(fields=['component_type', 'local_key'], name='oel_component_idx_ct_lk'),
         ),
         migrations.AddConstraint(
             model_name='component',
-            constraint=models.UniqueConstraint(fields=('learning_package', 'namespace', 'type', 'local_key'), name='oel_component_uniq_lc_ns_t_lk'),
+            constraint=models.UniqueConstraint(fields=('learning_package', 'component_type', 'local_key'), name='oel_component_uniq_lc_ct_lk'),
         ),
     ]

{openedx-learning-0.4.4 → openedx-learning-0.5.1}/openedx_learning/core/components/models.py

@@ -21,12 +21,52 @@ from __future__ import annotations
 from django.db import models
 
 from openedx_learning.lib.fields import case_sensitive_char_field, immutable_uuid_field, key_field
+from openedx_learning.lib.managers import WithRelationsManager
 
 from ..contents.models import RawContent
 from ..publishing.model_mixins import PublishableEntityMixin, PublishableEntityVersionMixin
 from ..publishing.models import LearningPackage
 
 
+class ComponentType(models.Model):
+    """
+    Normalized representation of a type of Component.
+
+    The only namespace being used initially will be 'xblock.v1', but we will
+    probably add a few others over time, such as a component type to represent
+    packages of files for things like Files and Uploads or python_lib.zip files.
+
+    Make a ForeignKey against this table if you have to set policy based on the
+    type of Components–e.g. marking certain types of XBlocks as approved vs.
+    experimental for use in libraries.
+    """
+    id = models.AutoField(primary_key=True)
+
+    # namespace and name work together to help figure out what Component needs
+    # to handle this data. A namespace is *required*. The namespace for XBlocks
+    # is "xblock.v1" (to match the setup.py entrypoint naming scheme).
+    namespace = case_sensitive_char_field(max_length=100, blank=False)
+
+    # name is a way to help sub-divide namespace if that's convenient. This
+    # field cannot be null, but it can be blank if it's not necessary. For an
+    # XBlock, this corresponds to tag, e.g. "video". It's also the block_type in
+    # the UsageKey.
+    name = case_sensitive_char_field(max_length=100, blank=True)
+
+    constraints = [
+        models.UniqueConstraint(
+            fields=[
+                "namespace",
+                "name",
+            ],
+            name="oel_component_type_uniq_ns_n",
+        ),
+    ]
+
+    def __str__(self):
+        return f"{self.namespace}:{self.name}"
+
+
 class Component(PublishableEntityMixin):  # type: ignore[django-manager-missing]
     """
     This represents any Component that has ever existed in a LearningPackage.
@@ -44,6 +84,12 @@ class Component(PublishableEntityMixin):  # type: ignore[django-manager-missing]
 
     A Component belongs to exactly one LearningPackage.
 
+    A Component is 1:1 with PublishableEntity and has matching primary key
+    values. More specifically, ``Component.pk`` maps to
+    ``Component.publishable_entity_id``, and any place where the Publishing API
+    module expects to get a ``PublishableEntity.id``, you can use a
+    ``Component.pk`` instead.
+
     Identifiers
     -----------
 
@@ -56,7 +102,7 @@ class Component(PublishableEntityMixin):  # type: ignore[django-manager-missing]
     -----------------
 
     The ``key`` field on Component's ``publishable_entity`` is dervied from the
-    ``(namespace, type, local_key)`` fields in this model. We don't support
+    ``component_type`` and ``local_key`` fields in this model. We don't support
     changing the keys yet, but if we do, those values need to be kept in sync.
 
     How build on this model
@@ -68,63 +114,64 @@ class Component(PublishableEntityMixin):  # type: ignore[django-manager-missing]
     # Tell mypy what type our objects manager has.
     # It's actually PublishableEntityMixinManager, but that has the exact same
     # interface as the base manager class.
-    objects: models.Manager[Component]
+    objects: models.Manager[Component] = WithRelationsManager(
+        'component_type'
+    )
+
+    with_publishing_relations: models.Manager[Component] = WithRelationsManager(
+        'component_type',
+        'publishable_entity',
+        'publishable_entity__draft__version',
+        'publishable_entity__draft__version__componentversion',
+        'publishable_entity__published__version',
+        'publishable_entity__published__version__componentversion',
+    )
 
     # This foreign key is technically redundant because we're already locked to
-    # a single LearningPackage through our publishable_entity relation. However, having
-    # this foreign key directly allows us to make indexes that efficiently
+    # a single LearningPackage through our publishable_entity relation. However,
+    # having this foreign key directly allows us to make indexes that efficiently
     # query by other Component fields within a given LearningPackage, which is
     # going to be a common use case (and we can't make a compound index using
     # columns from different tables).
     learning_package = models.ForeignKey(LearningPackage, on_delete=models.CASCADE)
 
-    # namespace and type work together to help figure out what Component needs
-    # to handle this data. A namespace is *required*. The namespace for XBlocks
-    # is "xblock.v1" (to match the setup.py entrypoint naming scheme).
-    namespace = case_sensitive_char_field(max_length=100, blank=False)
-
-    # type is a way to help sub-divide namespace if that's convenient. This
-    # field cannot be null, but it can be blank if it's not necessary. For an
-    # XBlock, type corresponds to tag, e.g. "video". It's also the block_type in
-    # the UsageKey.
-    type = case_sensitive_char_field(max_length=100, blank=True)
+    # What kind of Component are we? This will usually represent a specific
+    # XBlock block_type, but we want it to be more flexible in the long term.
+    component_type = models.ForeignKey(ComponentType, on_delete=models.PROTECT)
 
-    # local_key is an identifier that is local to the (namespace, type).  The
-    # publishable.key should be calculated as a combination of (namespace, type,
-    # local_key).
+    # local_key is an identifier that is local to the learning_package and
+    # component_type.  The publishable.key should be calculated as a
+    # combination of component_type and local_key.
     local_key = key_field()
 
     class Meta:
         constraints = [
-            # The combination of (namespace, type, local_key) is unique within
+            # The combination of (component_type, local_key) is unique within
             # a given LearningPackage. Note that this means it is possible to
-            # have two Components that have the exact same local_key. An XBlock
-            # would be modeled as namespace="xblock.v1" with the type as the
-            # block_type, so the local_key would only be the block_id (the
-            # very last part of the UsageKey).
+            # have two Components in the same LearningPackage to have the same
+            # local_key if the component_types are different. So for example,
+            # you could have a ProblemBlock and VideoBlock that both have the
+            # local_key "week_1".
             models.UniqueConstraint(
                 fields=[
                     "learning_package",
-                    "namespace",
-                    "type",
+                    "component_type",
                     "local_key",
                 ],
-                name="oel_component_uniq_lc_ns_t_lk",
+                name="oel_component_uniq_lc_ct_lk",
             ),
         ]
         indexes = [
-            # Global Namespace/Type/Local-Key Index:
+            # Global Component-Type/Local-Key Index:
             #   * Search by the different Components fields across all Learning
             #     Packages on the site. This would be a support-oriented tool
             #     from Django Admin.
             models.Index(
                 fields=[
-                    "learning_package",
-                    "namespace",
-                    "type",
+                    "component_type",
                     "local_key",
                 ],
-                name="oel_component_idx_lc_ns_t_lk",
+                name="oel_component_idx_ct_lk",
             ),
         ]
 
@@ -133,7 +180,7 @@ class Component(PublishableEntityMixin):  # type: ignore[django-manager-missing]
         verbose_name_plural = "Components"
 
     def __str__(self):
-        return f"{self.namespace}:{self.type}:{self.local_key}"
+        return f"{self.component_type.namespace}:{self.component_type.name}:{self.local_key}"
 
 
 class ComponentVersion(PublishableEntityVersionMixin):

{openedx-learning-0.4.4 → openedx-learning-0.5.1}/openedx_learning/core/contents/api.py

@@ -12,14 +12,14 @@ from datetime import datetime
 from django.core.files.base import ContentFile
 from django.db.transaction import atomic
 
-from openedx_learning.lib.cache import lru_cache
-from openedx_learning.lib.fields import create_hash_digest
-
+from ...lib.cache import lru_cache
+from ...lib.fields import create_hash_digest
 from .models import MediaType, RawContent, TextContent
 
 
 def create_raw_content(
     learning_package_id: int,
+    /,
     data_bytes: bytes,
     mime_type: str,
     created: datetime,
@@ -32,7 +32,7 @@ def create_raw_content(
 
     raw_content = RawContent.objects.create(
         learning_package_id=learning_package_id,
-        media_type_id=get_media_type_id(mime_type),
+        media_type_id=get_or_create_media_type_id(mime_type),
         hash_digest=hash_digest,
         size=len(data_bytes),
         created=created,
@@ -57,7 +57,7 @@ def create_text_from_raw_content(raw_content: RawContent, encoding="utf-8-sig")
 
 
 @lru_cache(maxsize=128)
-def get_media_type_id(mime_type: str) -> int:
+def get_or_create_media_type_id(mime_type: str) -> int:
     """
     Return the MediaType.id for the desired mime_type string.
 
@@ -91,6 +91,7 @@ def get_media_type_id(mime_type: str) -> int:
 
 def get_or_create_raw_content(
     learning_package_id: int,
+    /,
     data_bytes: bytes,
     mime_type: str,
     created: datetime,
@@ -117,6 +118,7 @@ def get_or_create_raw_content(
 
 def get_or_create_text_content_from_bytes(
     learning_package_id: int,
+    /,
     data_bytes: bytes,
     mime_type: str,
     created: datetime,