openedx-learning 0.1.0__py2.py3-none-any.whl → 0.1.2__py2.py3-none-any.whl

openedx_tagging/core/tagging/management/commands/build_language_fixture.py

@@ -0,0 +1,48 @@
+"""
+Script that downloads all the ISO 639-1 languages and processes them
+to write the fixture for the Language system-defined taxonomy.
+
+This function is intended to be used only once,
+but can be edited in the future if more data needs to be added to the fixture.
+"""
+import json
+import urllib.request
+
+from django.core.management.base import BaseCommand
+
+endpoint = "https://pkgstore.datahub.io/core/language-codes/language-codes_json/data/97607046542b532c395cf83df5185246/language-codes_json.json"
+output = "./openedx_tagging/core/tagging/fixtures/language_taxonomy.yaml"
+
+
+class Command(BaseCommand):
+    def handle(self, **options):
+        json_data = self.download_json()
+        self.build_fixture(json_data)
+
+    def download_json(self):
+        with urllib.request.urlopen(endpoint) as response:
+            json_data = response.read()
+            return json.loads(json_data)
+
+    def build_fixture(self, json_data):
+        tag_pk = -1
+        with open(output, "w") as output_file:
+            for lang_data in json_data:
+                lang_value = self.get_lang_value(lang_data)
+                lang_code = lang_data["alpha2"]
+                output_file.write("- model: oel_tagging.tag\n")
+                output_file.write(f"  pk: {tag_pk}\n")
+                output_file.write("  fields:\n")
+                output_file.write("    taxonomy: -1\n")
+                output_file.write("    parent: null\n")
+                output_file.write(f"    value: {lang_value}\n")
+                output_file.write(f"    external_id: {lang_code}\n")
+                # System tags are identified with negative numbers to avoid clashing with user-created tags.
+                tag_pk -= 1
+
+    def get_lang_value(self, lang_data):
+        """
+        Gets the lang value. Some languages has many values.
+        """
+        lang_list = lang_data["English"].split(";")
+        return lang_list[0]

openedx_tagging/core/tagging/migrations/0003_auto_20230721_1238.py

@@ -0,0 +1,76 @@
+# Generated by Django 3.2.19 on 2023-07-21 17:38
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("oel_tagging", "0002_auto_20230718_2026"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="ModelObjectTag",
+            fields=[],
+            options={
+                "proxy": True,
+                "indexes": [],
+                "constraints": [],
+            },
+            bases=("oel_tagging.objecttag",),
+        ),
+        migrations.CreateModel(
+            name="SystemDefinedTaxonomy",
+            fields=[],
+            options={
+                "proxy": True,
+                "indexes": [],
+                "constraints": [],
+            },
+            bases=("oel_tagging.taxonomy",),
+        ),
+        migrations.RemoveField(
+            model_name="taxonomy",
+            name="system_defined",
+        ),
+        migrations.CreateModel(
+            name="LanguageTaxonomy",
+            fields=[],
+            options={
+                "proxy": True,
+                "indexes": [],
+                "constraints": [],
+            },
+            bases=("oel_tagging.systemdefinedtaxonomy",),
+        ),
+        migrations.CreateModel(
+            name="ModelSystemDefinedTaxonomy",
+            fields=[],
+            options={
+                "proxy": True,
+                "indexes": [],
+                "constraints": [],
+            },
+            bases=("oel_tagging.systemdefinedtaxonomy",),
+        ),
+        migrations.CreateModel(
+            name="UserModelObjectTag",
+            fields=[],
+            options={
+                "proxy": True,
+                "indexes": [],
+                "constraints": [],
+            },
+            bases=("oel_tagging.modelobjecttag",),
+        ),
+        migrations.CreateModel(
+            name="UserSystemDefinedTaxonomy",
+            fields=[],
+            options={
+                "proxy": True,
+                "indexes": [],
+                "constraints": [],
+            },
+            bases=("oel_tagging.modelsystemdefinedtaxonomy",),
+        ),
+    ]

openedx_tagging/core/tagging/migrations/0004_auto_20230723_2001.py

@@ -0,0 +1,34 @@
+# Generated by Django 3.2.19 on 2023-07-24 06:25
+
+from django.db import migrations, models
+import openedx_learning.lib.fields
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("oel_tagging", "0003_auto_20230721_1238"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="objecttag",
+            name="object_id",
+            field=openedx_learning.lib.fields.MultiCollationCharField(
+                db_collations={"mysql": "utf8mb4_unicode_ci", "sqlite": "NOCASE"},
+                db_index=True,
+                editable=False,
+                help_text="Identifier for the object being tagged",
+                max_length=255,
+            ),
+        ),
+        migrations.AlterUniqueTogether(
+            name="tag",
+            unique_together={("taxonomy", "external_id"), ("taxonomy", "value")},
+        ),
+        migrations.AddIndex(
+            model_name="objecttag",
+            index=models.Index(
+                fields=["taxonomy", "object_id"], name="oel_tagging_taxonom_aa24e6_idx"
+            ),
+        ),
+    ]

openedx_tagging/core/tagging/migrations/0005_language_taxonomy.py

@@ -0,0 +1,29 @@
+# Generated by Django 3.2.19 on 2023-07-28 13:33
+
+from django.db import migrations
+from django.core.management import call_command
+
+
+def load_language_taxonomy(apps, schema_editor):
+    """
+    Load language taxonomy and tags
+    """
+    call_command("loaddata", "--app=oel_tagging", "language_taxonomy.yaml")
+
+
+def revert(apps, schema_editor):
+    """
+    Deletes language taxonomy an tags
+    """
+    Taxonomy = apps.get_model("oel_tagging", "Taxonomy")
+    Taxonomy.objects.filter(id=-1).delete()
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("oel_tagging", "0004_auto_20230723_2001"),
+    ]
+
+    operations = [
+        migrations.RunPython(load_language_taxonomy, revert),
+    ]

openedx_tagging/core/tagging/migrations/0006_alter_objecttag_unique_together.py

@@ -0,0 +1,16 @@
+# Generated by Django 3.2.19 on 2023-08-02 16:20
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("oel_tagging", "0005_language_taxonomy"),
+    ]
+
+    operations = [
+        migrations.AlterUniqueTogether(
+            name="objecttag",
+            unique_together={("taxonomy", "_value", "object_id")},
+        ),
+    ]

openedx_tagging/core/tagging/models/__init__.py

@@ -0,0 +1,11 @@
+from .base import (
+    Tag,
+    Taxonomy,
+    ObjectTag,
+)
+from .system_defined import (
+    ModelObjectTag,
+    ModelSystemDefinedTaxonomy,
+    UserSystemDefinedTaxonomy,
+    LanguageTaxonomy,
+)

openedx_tagging/core/tagging/{models.py → models/base.py}

@@ -1,4 +1,4 @@
-""" Tagging app data models """
+""" Tagging app base data models """
 import logging
 from typing import List, Type, Union
 
@@ -6,7 +6,10 @@ from django.db import models
 from django.utils.module_loading import import_string
 from django.utils.translation import gettext_lazy as _
 
-from openedx_learning.lib.fields import MultiCollationTextField, case_insensitive_char_field
+from openedx_learning.lib.fields import (
+    MultiCollationTextField,
+    case_insensitive_char_field,
+)
 
 log = logging.getLogger(__name__)
 
@@ -66,6 +69,10 @@ class Tag(models.Model):
             models.Index(fields=["taxonomy", "value"]),
             models.Index(fields=["taxonomy", "external_id"]),
         ]
+        unique_together = [
+            ["taxonomy", "external_id"],
+            ["taxonomy", "value"],
+        ]
 
     def __repr__(self):
         """
@@ -140,14 +147,6 @@ class Taxonomy(models.Model):
             "Indicates that tags in this taxonomy need not be predefined; authors may enter their own tag values."
         ),
     )
-    system_defined = models.BooleanField(
-        default=False,
-        editable=False,
-        help_text=_(
-            "Indicates that tags and metadata for this taxonomy are maintained by the system;"
-            " taxonomy admins will not be permitted to modify them.",
-        ),
-    )
     visible_to_authors = models.BooleanField(
         default=True,
         editable=False,
@@ -177,8 +176,25 @@ class Taxonomy(models.Model):
         """
         User-facing string representation of a Taxonomy.
         """
+        try:
+            if self._taxonomy_class:
+                return f"<{self.taxonomy_class.__name__}> ({self.id}) {self.name}"
+        except ImportError:
+            # Log error and continue
+            log.exception(
+                f"Unable to import taxonomy_class for {self.id}: {self._taxonomy_class}"
+            )
         return f"<{self.__class__.__name__}> ({self.id}) {self.name}"
 
+    @property
+    def object_tag_class(self) -> Type:
+        """
+        Returns the ObjectTag subclass associated with this taxonomy, which is ObjectTag by default.
+
+        Taxonomy subclasses may override this method to use different subclasses of ObjectTag.
+        """
+        return ObjectTag
+
     @property
     def taxonomy_class(self) -> Type:
         """
@@ -190,6 +206,14 @@ class Taxonomy(models.Model):
             return import_string(self._taxonomy_class)
         return None
 
+    @property
+    def system_defined(self) -> bool:
+        """
+        Indicates that tags and metadata for this taxonomy are maintained by the system;
+        taxonomy admins will not be permitted to modify them.
+        """
+        return False
+
     @taxonomy_class.setter
     def taxonomy_class(self, taxonomy_class: Union[Type, None]):
         """
@@ -239,15 +263,16 @@ class Taxonomy(models.Model):
         self.required = taxonomy.required
         self.allow_multiple = taxonomy.allow_multiple
         self.allow_free_text = taxonomy.allow_free_text
-        self.system_defined = taxonomy.system_defined
         self.visible_to_authors = taxonomy.visible_to_authors
         self._taxonomy_class = taxonomy._taxonomy_class
         return self
 
-    def get_tags(self) -> List[Tag]:
+    def get_tags(self, tag_set: models.QuerySet = None) -> List[Tag]:
         """
         Returns a list of all Tags in the current taxonomy, from the root(s) down to TAXONOMY_MAX_DEPTH tags, in tree order.
 
+        Use `tag_set` to do an initial filtering of the tags.
+
         Annotates each returned Tag with its ``depth`` in the tree (starting at 0).
 
         Performance note: may perform as many as TAXONOMY_MAX_DEPTH select queries.
@@ -256,9 +281,12 @@ class Taxonomy(models.Model):
         if self.allow_free_text:
             return tags
 
+        if tag_set is None:
+            tag_set = self.tag_set
+
         parents = None
         for depth in range(TAXONOMY_MAX_DEPTH):
-            filtered_tags = self.tag_set.prefetch_related("parent")
+            filtered_tags = tag_set.prefetch_related("parent")
             if parents is None:
                 filtered_tags = filtered_tags.filter(parent=None)
             else:
@@ -366,9 +394,10 @@ class Taxonomy(models.Model):
                 _(f"Taxonomy ({self.id}) requires at least one tag per object.")
             )
 
+        ObjectTagClass = self.object_tag_class
         current_tags = {
             tag.tag_ref: tag
-            for tag in ObjectTag.objects.filter(
+            for tag in ObjectTagClass.objects.filter(
                 taxonomy=self,
                 object_id=object_id,
             )
@@ -378,20 +407,12 @@ class Taxonomy(models.Model):
             if tag_ref in current_tags:
                 object_tag = current_tags.pop(tag_ref)
             else:
-                object_tag = ObjectTag(
+                object_tag = ObjectTagClass(
                     taxonomy=self,
                     object_id=object_id,
                 )
 
-            try:
-                object_tag.tag = self.tag_set.get(
-                    id=tag_ref,
-                )
-            except (ValueError, Tag.DoesNotExist):
-                # This might be ok, e.g. if self.allow_free_text.
-                # We'll validate below before saving.
-                object_tag.value = tag_ref
-
+            object_tag.tag_ref = tag_ref
             object_tag.resync()
             if not self.validate_object_tag(object_tag):
                 raise ValueError(
@@ -409,6 +430,52 @@ class Taxonomy(models.Model):
 
         return updated_tags
 
+    def autocomplete_tags(
+        self,
+        search: str,
+        object_id: str = None,
+    ) -> models.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`.
+
+        Subclasses can override this method to perform their own autocomplete process.
+        Subclass use cases:
+        * Large taxonomy associated with a model. It can be overridden to get
+          the suggestions directly from the model by doing own filtering.
+        * Taxonomy with a list of available tags: It can be overridden to only
+          search the suggestions on a list of available tags.
+        """
+        # Fetch tags that the object already has to exclude them from the result
+        excluded_tags = []
+        if object_id:
+            excluded_tags = self.objecttag_set.filter(object_id=object_id).values_list(
+                "_value", flat=True
+            )
+        return (
+            # Fetch object tags from this taxonomy whose value contains the search
+            self.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=models.F("_value"))
+            # obtain tag values
+            .values("value", "tag_id")
+            # remove repeats
+            .distinct()
+        )
+
 
 class ObjectTag(models.Model):
     """
@@ -431,6 +498,7 @@ class ObjectTag(models.Model):
     id = models.BigAutoField(primary_key=True)
     object_id = case_insensitive_char_field(
         max_length=255,
+        db_index=True,
         editable=False,
         help_text=_("Identifier for the object being tagged"),
     )
@@ -472,8 +540,10 @@ class ObjectTag(models.Model):
 
     class Meta:
         indexes = [
+            models.Index(fields=["taxonomy", "object_id"]),
             models.Index(fields=["taxonomy", "_value"]),
         ]
+        unique_together = ("taxonomy", "_value", "object_id")
 
     def __repr__(self):
         """
@@ -531,6 +601,24 @@ class ObjectTag(models.Model):
         """
         return self.tag.id if self.tag_id else self._value
 
+    @tag_ref.setter
+    def tag_ref(self, tag_ref: str):
+        """
+        Sets the ObjectTag's Tag and/or value, depending on whether a valid Tag is found.
+
+        Subclasses may override this method to dynamically create Tags.
+        """
+        self.value = tag_ref
+
+        if self.taxonomy_id:
+            try:
+                self.tag = self.taxonomy.tag_set.get(pk=tag_ref)
+                self.value = self.tag.value
+            except (ValueError, Tag.DoesNotExist):
+                # This might be ok, e.g. if our taxonomy.allow_free_text, so we just pass through here.
+                # We rely on the caller to validate before saving.
+                pass
+
     def is_valid(self) -> bool:
         """
         Returns True if this ObjectTag represents a valid taxonomy tag.