openedx-learning 0.2.6__tar.gz → 0.3.3__tar.gz

{openedx-learning-0.2.6/openedx_learning.egg-info → openedx-learning-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.2
 Name: openedx-learning
-Version: 0.2.6
+Version: 0.3.3
 Summary: An experiment.
 Home-page: https://github.com/openedx/openedx-learning
 Author: David Ormsbee
@@ -136,7 +136,7 @@ Description: openedx-learning
         Reporting Security Issues
         -------------------------
         
-        Please do not report security issues in public. Please email security@edx.org.
+        Please do not report security issues in public. Please email security@openedx.org.
         
         Help
         ----

{openedx-learning-0.2.6 → openedx-learning-0.3.3}/README.rst

@@ -128,7 +128,7 @@ This repo is in a very experimental state. Discussion using GitHub Issues is wel
 Reporting Security Issues
 -------------------------
 
-Please do not report security issues in public. Please email security@edx.org.
+Please do not report security issues in public. Please email security@openedx.org.
 
 Help
 ----

{openedx-learning-0.2.6 → openedx-learning-0.3.3}/openedx_learning/__init__.py

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

{openedx-learning-0.2.6 → openedx-learning-0.3.3}/openedx_learning/core/components/models.py

@@ -157,7 +157,7 @@ class ComponentVersion(PublishableEntityVersionMixin):
 
     # The raw_contents hold the actual interesting data associated with this
     # ComponentVersion.
-    raw_contents = models.ManyToManyField(
+    raw_contents: models.ManyToManyField[RawContent, ComponentVersionRawContent] = models.ManyToManyField(
         RawContent,
         through="ComponentVersionRawContent",
         related_name="component_versions",

{openedx-learning-0.2.6 → openedx-learning-0.3.3}/openedx_learning/core/publishing/admin.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 
 from django.contrib import admin
 
-from openedx_learning.lib.admin_utils import ReadOnlyModelAdmin
+from openedx_learning.lib.admin_utils import ReadOnlyModelAdmin, one_to_one_related_model_html
 
 from .models import LearningPackage, PublishableEntity, Published, PublishLog, PublishLogRecord
 
@@ -77,7 +77,7 @@ class PublishableEntityAdmin(ReadOnlyModelAdmin):
     """
     Read-only admin view for Publishable Entities
     """
-    fields = (
+    list_display = [
         "key",
         "draft_version",
         "published_version",
@@ -85,23 +85,49 @@ class PublishableEntityAdmin(ReadOnlyModelAdmin):
         "learning_package",
         "created",
         "created_by",
-    )
-    readonly_fields = fields
-    list_display = fields
+    ]
     list_filter = ["learning_package"]
     search_fields = ["key", "uuid"]
 
+    fields = [
+        "key",
+        "draft_version",
+        "published_version",
+        "uuid",
+        "learning_package",
+        "created",
+        "created_by",
+        "see_also",
+    ]
+    readonly_fields = [
+        "key",
+        "draft_version",
+        "published_version",
+        "uuid",
+        "learning_package",
+        "created",
+        "created_by",
+        "see_also",
+    ]
+
     def get_queryset(self, request):
         queryset = super().get_queryset(request)
         return queryset.select_related(
-            "learning_package", "published__version", "draft__version"
+            "learning_package", "published__version",
         )
 
+    def see_also(self, entity):
+        return one_to_one_related_model_html(entity)
+
     def draft_version(self, entity):
-        return entity.draft.version.version_num
+        if entity.draft.version:
+            return entity.draft.version.version_num
+        return None
 
     def published_version(self, entity):
-        return entity.published.version.version_num
+        if entity.published.version:
+            return entity.published.version.version_num
+        return None
 
 
 @admin.register(Published)

{openedx-learning-0.2.6 → openedx-learning-0.3.3}/openedx_learning/core/publishing/api.py

@@ -93,9 +93,9 @@ def create_publishable_entity_version(
             created=created,
             created_by_id=created_by,
         )
-        Draft.objects.create(
+        Draft.objects.update_or_create(
             entity_id=entity_id,
-            version=version,
+            defaults={"version": version},
         )
     return version
 
@@ -180,6 +180,42 @@ def publish_from_drafts(
     return publish_log
 
 
+def get_draft_version(publishable_entity_id: int) -> PublishableEntityVersion | None:
+    """
+    Return current draft PublishableEntityVersion for this PublishableEntity.
+
+    This function will return None if there is no current draft.
+    """
+    try:
+        draft = Draft.objects.select_related("version").get(
+            entity_id=publishable_entity_id
+        )
+    except Draft.DoesNotExist:
+        # No draft was ever created.
+        return None
+
+    # draft.version could be None if it was set that way by set_draft_version.
+    # Setting the Draft.version to None is how we show that we've "deleted" the
+    # content in Studio.
+    return draft.version
+
+
+def set_draft_version(publishable_entity_id: int, publishable_entity_version_pk: int | None) -> None:
+    """
+    Modify the Draft of a PublishableEntity to be a PublishableEntityVersion.
+
+    This would most commonly be used to set the Draft to point to a newly
+    created PublishableEntityVersion that was created in Studio (because someone
+    edited some content). Setting a Draft's version to None is like deleting it
+    from Studio's editing point of view. We don't actually delete the Draft row
+    because we'll need that for publishing purposes (i.e. to delete content from
+    the published branch).
+    """
+    draft = Draft.objects.get(entity_id=publishable_entity_id)
+    draft.version_id = publishable_entity_version_pk
+    draft.save()
+
+
 def register_content_models(
     content_model_cls: type[PublishableEntityMixin],
     content_version_model_cls: type[PublishableEntityVersionMixin],

openedx-learning-0.3.3/openedx_learning/core/publishing/migrations/0002_alter_fk_on_delete.py

@@ -0,0 +1,30 @@
+# Generated by Django 3.2.21 on 2023-10-13 14:25
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    """
+    Make it so that Draft and Published cascade deletes from PublishableEntity.
+
+    This makes it so that deleting a LearningPackage properly cleans up these
+    models as well.
+    """
+
+    dependencies = [
+        ('oel_publishing', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='draft',
+            name='entity',
+            field=models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, primary_key=True, serialize=False, to='oel_publishing.publishableentity'),
+        ),
+        migrations.AlterField(
+            model_name='published',
+            name='entity',
+            field=models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, primary_key=True, serialize=False, to='oel_publishing.publishableentity'),
+        ),
+    ]

{openedx-learning-0.2.6 → openedx-learning-0.3.3}/openedx_learning/core/publishing/models.py

@@ -308,10 +308,12 @@ class Draft(models.Model):
     are updated, not when publishing happens. The Published model only changes
     when something is published.
     """
-
+    # If we're removing a PublishableEntity entirely, also remove the Draft
+    # entry for it. This isn't a normal operation, but can happen if you're
+    # deleting an entire LearningPackage.
     entity = models.OneToOneField(
         PublishableEntity,
-        on_delete=models.RESTRICT,
+        on_delete=models.CASCADE,
         primary_key=True,
     )
     version = models.OneToOneField(
@@ -425,7 +427,7 @@ class Published(models.Model):
 
     entity = models.OneToOneField(
         PublishableEntity,
-        on_delete=models.RESTRICT,
+        on_delete=models.CASCADE,
         primary_key=True,
     )
     version = models.OneToOneField(

openedx-learning-0.3.3/openedx_learning/lib/admin_utils.py

@@ -0,0 +1,100 @@
+"""
+Convenience utilities for the Django Admin.
+"""
+from django.contrib import admin
+from django.db.models.fields.reverse_related import OneToOneRel
+from django.urls import NoReverseMatch, reverse
+from django.utils.html import format_html, format_html_join
+
+
+class ReadOnlyModelAdmin(admin.ModelAdmin):
+    """
+    ModelAdmin subclass that removes any editing ability.
+
+    The Django Admin is really useful for quickly examining model data. At the
+    same time, model creation and updates follow specific rules that are meant
+    to be enforced above the model layer (in api.py files), so making edits in
+    the Django Admin is potentially dangerous.
+
+    In general, if you're providing Django Admin interfaces for your
+    openedx-learning related app data models, you should subclass this class
+    instead of subclassing admin.ModelAdmin directly.
+    """
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False
+
+
+def one_to_one_related_model_html(model_obj):
+    """
+    HTML for clickable list of a models that are 1:1-related to ``model_obj``.
+
+    Our design pattern encourages people to hang models off of our lower-level
+    core lib models. For example, Component has a OneToOneField that references
+    PublishableEntity. It would be really convenient to have PublishableEntity's
+    admin page display the link to Component, but the ``publishable`` app is
+    intended to be a lower-level app than ``components`` and isn't supposed to
+    be aware of it. The same situation occurs for third-party apps that might
+    want to extend Component.
+
+    So instead of creating a circular dependency by having ``publishing``
+    referencing ``components``, we use Django model introspection to iterate
+    over all models that have a OneToOneField to the passe din``model_obj``.
+    This allows us to preserve our dependency boundaries within openedx-learning
+    and accomodate any third party apps that might further extend these models.
+
+    This will output a list with one entry for each related field.
+
+    * If the field's value is None, we output f"{field_name}: -"
+    * If the field has a value but no "change" admin page, we output the string
+      representation of the model obj referenced by that field, i.e.
+      f{"field_name: {related_model_obj}"}.
+    * If the field has a value and an admin page, we output the same as above,
+      but we make the related model object's string representation a link to its
+      "change" admin page.
+    """
+    one_to_one_field_names = [
+        field.name
+        for field in model_obj._meta.related_objects
+        if isinstance(field, OneToOneRel)
+    ]
+    text = []
+    for field_name in one_to_one_field_names:
+        related_model_obj = getattr(model_obj, field_name, None)
+
+        # No instance of the related model was found, so just use "-"
+        if related_model_obj is None:
+            text.append(f"{field_name}: -")
+            continue
+
+        app_label = related_model_obj._meta.app_label
+        model_name = related_model_obj._meta.model_name
+        try:
+            details_url = reverse(
+                f"admin:{app_label}_{model_name}_change",
+                args=(related_model_obj.pk,)
+            )
+        except NoReverseMatch:
+            # No Admin URL available, so just put the str representation of the
+            # related model instance.
+            text.append(f"{field_name}: {related_model_obj}")
+            continue
+
+        # If we go this far, there is a related model instance and it has a
+        # "change" admin page (even though it's probably read-only via
+        # permissions).
+        html = format_html(
+            '{}: <a href="{}">{}</a>',
+            field_name,
+            details_url,
+            related_model_obj,
+        )
+        text.append(html)
+
+    return format_html_join("\n", "<li>{}</li>", ((t,) for t in text))

{openedx-learning-0.2.6 → openedx-learning-0.3.3/openedx_learning.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.2
 Name: openedx-learning
-Version: 0.2.6
+Version: 0.3.3
 Summary: An experiment.
 Home-page: https://github.com/openedx/openedx-learning
 Author: David Ormsbee
@@ -136,7 +136,7 @@ Description: openedx-learning
         Reporting Security Issues
         -------------------------
         
-        Please do not report security issues in public. Please email security@edx.org.
+        Please do not report security issues in public. Please email security@openedx.org.
         
         Help
         ----

{openedx-learning-0.2.6 → openedx-learning-0.3.3}/openedx_learning.egg-info/SOURCES.txt

@@ -38,6 +38,7 @@ openedx_learning/core/publishing/apps.py
 openedx_learning/core/publishing/model_mixins.py
 openedx_learning/core/publishing/models.py
 openedx_learning/core/publishing/migrations/0001_initial.py
+openedx_learning/core/publishing/migrations/0002_alter_fk_on_delete.py
 openedx_learning/core/publishing/migrations/__init__.py
 openedx_learning/lib/__init__.py
 openedx_learning/lib/admin_utils.py
@@ -56,6 +57,7 @@ openedx_tagging/core/tagging/__init__.py
 openedx_tagging/core/tagging/admin.py
 openedx_tagging/core/tagging/api.py
 openedx_tagging/core/tagging/apps.py
+openedx_tagging/core/tagging/data.py
 openedx_tagging/core/tagging/rules.py
 openedx_tagging/core/tagging/urls.py
 openedx_tagging/core/tagging/import_export/__init__.py
@@ -81,11 +83,14 @@ openedx_tagging/core/tagging/migrations/0009_alter_objecttag_object_id.py
 openedx_tagging/core/tagging/migrations/0010_cleanups.py
 openedx_tagging/core/tagging/migrations/0011_remove_required.py
 openedx_tagging/core/tagging/migrations/0012_language_taxonomy.py
+openedx_tagging/core/tagging/migrations/0013_tag_parent_blank.py
+openedx_tagging/core/tagging/migrations/0014_minor_fixes.py
 openedx_tagging/core/tagging/migrations/__init__.py
 openedx_tagging/core/tagging/models/__init__.py
 openedx_tagging/core/tagging/models/base.py
 openedx_tagging/core/tagging/models/import_export.py
 openedx_tagging/core/tagging/models/system_defined.py
+openedx_tagging/core/tagging/models/utils.py
 openedx_tagging/core/tagging/rest_api/__init__.py
 openedx_tagging/core/tagging/rest_api/paginators.py
 openedx_tagging/core/tagging/rest_api/urls.py

openedx-learning-0.3.3/openedx_tagging/core/tagging/admin.py

@@ -0,0 +1,44 @@
+"""
+Tagging app admin
+"""
+from __future__ import annotations
+
+from django.contrib import admin
+
+from .models import ObjectTag, Tag, Taxonomy
+
+admin.site.register(Taxonomy)
+
+
+@admin.register(Tag)
+class TagAdmin(admin.ModelAdmin):
+    """
+    Admin definition for Tag model
+    """
+    autocomplete_fields = ["parent"]
+    search_fields = ["value", "external_id"]
+    list_display = ["__str__", "taxonomy", "external_id"]
+    list_filter = ["taxonomy"]
+
+    def has_add_permission(self, request):
+        """
+        Don't create Tags using the django admin. Use the API or UI.
+        """
+        return False
+
+
+@admin.register(ObjectTag)
+class ObjectTagAdmin(admin.ModelAdmin):
+    """
+    Admin definition for ObjectTag model
+    """
+    fields = ["object_id", "taxonomy", "tag", "_value"]
+    autocomplete_fields = ["tag"]
+    list_display = ["object_id", "name", "value"]
+    readonly_fields = ["object_id"]
+
+    def has_add_permission(self, request):
+        """
+        Don't create ObjectTags using the django admin. Use the API or UI.
+        """
+        return False

{openedx-learning-0.2.6 → openedx-learning-0.3.3}/openedx_tagging/core/tagging/api.py

@@ -12,11 +12,14 @@ are stored in this app.
 """
 from __future__ import annotations
 
-from django.db import transaction
-from django.db.models import F, QuerySet
+from django.db import models, transaction
+from django.db.models import F, QuerySet, Value
+from django.db.models.functions import Coalesce, Concat, Lower
 from django.utils.translation import gettext as _
 
+from .data import TagDataQuerySet
 from .models import ObjectTag, Tag, Taxonomy
+from .models.utils import ConcatNull
 
 # Export this as part of the API
 TagDoesNotExist = Tag.DoesNotExist
@@ -70,54 +73,66 @@ def get_taxonomies(enabled=True) -> QuerySet[Taxonomy]:
     return queryset.filter(enabled=enabled)
 
 
-def get_tags(taxonomy: Taxonomy) -> list[Tag]:
+def get_tags(taxonomy: Taxonomy) -> TagDataQuerySet:
     """
-    Returns a list of predefined tags for the given taxonomy.
+    Returns a QuerySet of all the tags in the given taxonomy.
 
-    Note that if the taxonomy allows free-text tags, then the returned list will be empty.
+    Note that if the taxonomy is dynamic or free-text, only tags that have
+    already been applied to some object will be returned.
     """
-    return taxonomy.cast().get_tags()
+    return taxonomy.cast().get_filtered_tags()
 
 
-def get_root_tags(taxonomy: Taxonomy) -> list[Tag]:
+def get_root_tags(taxonomy: Taxonomy) -> TagDataQuerySet:
     """
     Returns a list of the root tags for the given taxonomy.
 
     Note that if the taxonomy allows free-text tags, then the returned list will be empty.
     """
-    return list(taxonomy.cast().get_filtered_tags())
+    return taxonomy.cast().get_filtered_tags(depth=1)
 
 
-def search_tags(taxonomy: Taxonomy, search_term: str) -> list[Tag]:
+def search_tags(
+    taxonomy: Taxonomy,
+    search_term: str,
+    exclude_object_id: str | None = None,
+    include_counts: bool = False,
+) -> TagDataQuerySet:
     """
-    Returns a list of all tags that contains `search_term` of the given taxonomy.
+    Returns a list of all tags that contains `search_term` of the given
+    taxonomy, as well as their ancestors (so they can be displayed in a tree).
 
-    Note that if the taxonomy allows free-text tags, then the returned list will be empty.
+    If exclude_object_id is set, any tags applied to that object will be
+    excluded from the results, e.g. to power an autocomplete search when adding
+    additional tags to an object.
     """
-    return list(
-        taxonomy.cast().get_filtered_tags(
-            search_term=search_term,
-            search_in_all=True,
+    excluded_values = None
+    if exclude_object_id:
+        # Fetch tags that the object already has to exclude them from the result.
+        # Note: this adds a fair bit of complexity. In the future, maybe we can just do this filtering on the frontend?
+        excluded_values = list(
+            taxonomy.objecttag_set.filter(object_id=exclude_object_id).values_list(
+                "_value", flat=True
+            )
         )
+    qs = taxonomy.cast().get_filtered_tags(
+        search_term=search_term,
+        excluded_values=excluded_values,
+        include_counts=include_counts,
     )
+    return qs
 
 
 def get_children_tags(
     taxonomy: Taxonomy,
-    parent_tag_id: int,
-    search_term: str | None = None,
-) -> list[Tag]:
+    parent_tag_value: str,
+) -> TagDataQuerySet:
     """
-    Returns a list of children tags for the given parent tag.
+    Returns a QuerySet of children tags for the given parent tag.
 
     Note that if the taxonomy allows free-text tags, then the returned list will be empty.
     """
-    return list(
-        taxonomy.cast().get_filtered_tags(
-            parent_tag_id=parent_tag_id,
-            search_term=search_term,
-        )
-    )
+    return taxonomy.cast().get_filtered_tags(parent_tag_value=parent_tag_value, depth=1)
 
 
 def resync_object_tags(object_tags: QuerySet | None = None) -> int:
@@ -152,8 +167,20 @@ def get_object_tags(
     filters = {"taxonomy_id": taxonomy_id} if taxonomy_id else {}
     tags = (
         object_tag_class.objects.filter(object_id=object_id, **filters)
-        .select_related("tag", "taxonomy")
-        .order_by("id")
+        # Preload related objects, including data for the "get_lineage" method on ObjectTag/Tag:
+        .select_related("taxonomy", "tag", "tag__parent", "tag__parent__parent")
+        # Sort the tags within each taxonomy in "tree order". See Taxonomy._get_filtered_tags_deep for details on this:
+        .annotate(sort_key=Lower(Concat(
+            ConcatNull(F("tag__parent__parent__parent__value"), Value("\t")),
+            ConcatNull(F("tag__parent__parent__value"), Value("\t")),
+            ConcatNull(F("tag__parent__value"), Value("\t")),
+            Coalesce(F("tag__value"), F("_value")),
+            Value("\t"),
+            output_field=models.CharField(),
+        )))
+        .annotate(taxonomy_name=Coalesce(F("taxonomy__name"), F("_name")))
+        # Sort first by taxonomy name, then by tag value in tree order:
+        .order_by("taxonomy_name", "sort_key")
     )
     return tags
 
@@ -253,71 +280,6 @@ def tag_object(
             object_tag.save()
 
 
-# TODO: return tags from closed taxonomies as well as the count of how many times each is used.
-def autocomplete_tags(
-    taxonomy: Taxonomy,
-    search: str,
-    object_id: str | None = None,
-    object_tags_only=True,
-) -> QuerySet:
-    """
-    Provides auto-complete suggestions by matching the `search` string against existing
-    ObjectTags linked to the given taxonomy. A case-insensitive search is used in order
-    to return the highest number of relevant tags.
-
-    If `object_id` is provided, then object tag values already linked to this object
-    are omitted from the returned suggestions. (ObjectTag values must be unique for a
-    given object + taxonomy, and so omitting these suggestions helps users avoid
-    duplication errors.).
-
-    Returns a QuerySet of dictionaries containing distinct `value` (string) and
-    `tag` (numeric ID) values, sorted alphabetically by `value`.
-    The `value` is what should be shown as a suggestion to users,
-    and if it's a free-text taxonomy, `tag` will be `None`:  we include the `tag` ID
-    in anticipation of the second use case listed below.
-
-    Use cases:
-    * This method is useful for reducing tag variation in free-text taxonomies by showing
-      users tags that are similar to what they're typing. E.g., if the `search` string "dn"
-      shows that other objects have been tagged with "DNA", "DNA electrophoresis", and "DNA fingerprinting",
-      this encourages users to use those existing tags if relevant, instead of creating new ones that
-      look similar (e.g. "dna finger-printing").
-    * It could also be used to assist tagging for closed taxonomies with a list of possible tags which is too
-      large to return all at once, e.g. a user model taxonomy that dynamically creates tags on request for any
-      registered user in the database. (Note that this is not implemented yet, but may be as part of a future change.)
-    """
-    if not object_tags_only:
-        raise NotImplementedError(
-            _(
-                "Using this would return a query set of tags instead of object tags."
-                "For now we recommend fetching all of the taxonomy's tags "
-                "using get_tags() and filtering them on the frontend."
-            )
-        )
-    # Fetch tags that the object already has to exclude them from the result
-    excluded_tags: list[str] = []
-    if object_id:
-        excluded_tags = list(
-            taxonomy.objecttag_set.filter(object_id=object_id).values_list(
-                "_value", flat=True
-            )
-        )
-    return (
-        # Fetch object tags from this taxonomy whose value contains the search
-        taxonomy.objecttag_set.filter(_value__icontains=search)
-        # omit any tags whose values match the tags on the given object
-        .exclude(_value__in=excluded_tags)
-        # alphabetical ordering
-        .order_by("_value")
-        # Alias the `_value` field to `value` to make it nicer for users
-        .annotate(value=F("_value"))
-        # obtain tag values
-        .values("value", "tag_id")
-        # remove repeats
-        .distinct()
-    )
-
-
 def add_tag_to_taxonomy(
     taxonomy: Taxonomy,
     tag: str,

openedx-learning-0.3.3/openedx_tagging/core/tagging/data.py

@@ -0,0 +1,39 @@
+"""
+Data models used by openedx-tagging
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypedDict
+
+from django.db.models import QuerySet
+from typing_extensions import NotRequired, TypeAlias
+
+
+class TagData(TypedDict):
+    """
+    Data about a single tag. Many of the tagging API methods return Django
+    QuerySets that resolve to these dictionaries.
+
+    Even though the data will be in this same format, it will not necessarily
+    be an instance of this class but rather a plain dictionary. This is more a
+    type than a class.
+    """
+    value: str
+    external_id: str | None
+    child_count: int
+    depth: int
+    parent_value: str | None
+    # Note: usage_count may or may not be present, depending on the request.
+    usage_count: NotRequired[int]
+    # Internal database ID, if any. Generally should not be used; prefer 'value' which is unique within each taxonomy.
+    _id: int | None
+
+
+if TYPE_CHECKING:
+    from django_stubs_ext import ValuesQuerySet
+    TagDataQuerySet: TypeAlias = ValuesQuerySet[Any, TagData]
+    # The following works better for pyright (provides proper VS Code autocompletions),
+    # but I can't find any way to specify different types for pyright vs mypy :/
+    # TagDataQuerySet: TypeAlias = QuerySet[TagData]
+else:
+    TagDataQuerySet = QuerySet[TagData]