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

openedx_tagging/core/tagging/models/system_defined.py

@@ -0,0 +1,269 @@
+""" Tagging app system-defined taxonomies data models """
+import logging
+from typing import Any, List, Type, Union
+
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.db import models
+
+from openedx_tagging.core.tagging.models.base import ObjectTag
+
+from .base import Tag, Taxonomy, ObjectTag
+
+log = logging.getLogger(__name__)
+
+
+class SystemDefinedTaxonomy(Taxonomy):
+    """
+    Simple subclass of Taxonomy which requires the system_defined flag to be set.
+    """
+
+    class Meta:
+        proxy = True
+
+    @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 True
+
+
+class ModelObjectTag(ObjectTag):
+    """
+    Model-based ObjectTag, abstract class.
+
+    Used by ModelSystemDefinedTaxonomy to maintain dynamic Tags which are associated with a configured Model instance.
+    """
+
+    class Meta:
+        proxy = True
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Checks if the `tag_class_model` is correct
+        """
+        assert issubclass(self.tag_class_model, models.Model)
+        super().__init__(*args, **kwargs)
+
+    @property
+    def tag_class_model(self) -> Type:
+        """
+        Subclasses must implement this method to return the Django.model
+        class referenced by these object tags.
+        """
+        raise NotImplementedError
+
+    @property
+    def tag_class_value(self) -> str:
+        """
+        Returns the name of the tag_class_model field to use as the Tag.value when creating Tags for this taxonomy.
+
+        Subclasses may override this method to use different fields.
+        """
+        return "pk"
+
+    def get_instance(self) -> Union[models.Model, None]:
+        """
+        Returns the instance of tag_class_model associated with this object tag, or None if not found.
+        """
+        instance_id = self.tag.external_id if self.tag else None
+        if instance_id:
+            try:
+                return self.tag_class_model.objects.get(pk=instance_id)
+            except ValueError as e:
+                log.exception(f"{self}: {str(e)}")
+            except self.tag_class_model.DoesNotExist:
+                log.exception(
+                    f"{self}: {self.tag_class_model.__name__} pk={instance_id} does not exist."
+                )
+
+        return None
+
+    def _resync_tag(self) -> bool:
+        """
+        Resync our tag's value with the value from the instance.
+
+        If the instance associated with the tag no longer exists, we unset our tag, because it's no longer valid.
+
+        Returns True if the given tag was changed, False otherwise.
+        """
+        instance = self.get_instance()
+        if instance:
+            value = getattr(instance, self.tag_class_value)
+            self.value = value
+            if self.tag and self.tag.value != value:
+                self.tag.value = value
+                self.tag.save()
+                return True
+        else:
+            self.tag = None
+
+        return False
+
+    @property
+    def tag_ref(self) -> str:
+        return (self.tag.external_id or 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, or can be created.
+
+        Creates a Tag for the given tag_ref value, if one containing that external_id not already exist.
+        """
+        self.value = tag_ref
+
+        if self.taxonomy_id:
+            try:
+                self.tag = self.taxonomy.tag_set.get(
+                    external_id=tag_ref,
+                )
+            except (ValueError, Tag.DoesNotExist):
+                # Creates a new Tag for this instance
+                self.tag = Tag(
+                    taxonomy=self.taxonomy,
+                    external_id=tag_ref,
+                )
+
+            self._resync_tag()
+
+
+class ModelSystemDefinedTaxonomy(SystemDefinedTaxonomy):
+    """
+    Model based system taxonomy abstract class.
+
+    This type of taxonomy has an associated Django model in ModelObjectTag.tag_class_model().
+    They are designed to create Tags when required for new ObjectTags, to maintain
+    their status as "closed" taxonomies.
+    The Tags are representations of the instances of the associated model.
+
+    Tag.external_id stores an identifier from the instance (`pk` as default)
+    and Tag.value stores a human readable representation of the instance
+    (e.g. `username`).
+    The subclasses can override this behavior, to choose the right field.
+
+    When an ObjectTag is created with an existing Tag,
+    the Tag is re-synchronized with its instance.
+    """
+
+    class Meta:
+        proxy = True
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Checks if the `object_tag_class` is a subclass of ModelObjectTag.
+        """
+        assert issubclass(self.object_tag_class, ModelObjectTag)
+        super().__init__(*args, **kwargs)
+
+    @property
+    def object_tag_class(self) -> Type:
+        """
+        Returns the ObjectTag subclass associated with this taxonomy.
+
+        Model Taxonomy subclasses must implement this to provide a ModelObjectTag subclass.
+        """
+        raise NotImplementedError
+
+    def _check_instance(self, object_tag: ObjectTag) -> bool:
+        """
+        Returns True if the instance exists
+
+        Subclasses can override this method to perform their own instance validation checks.
+        """
+        object_tag = self.object_tag_class.cast(object_tag)
+        return bool(object_tag.get_instance())
+
+    def _check_tag(self, object_tag: ObjectTag) -> bool:
+        """
+        Returns True if the instance is valid
+        """
+        return super()._check_tag(object_tag) and self._check_instance(object_tag)
+
+
+class UserModelObjectTag(ModelObjectTag):
+    """
+    ObjectTags for the UserSystemDefinedTaxonomy.
+    """
+
+    class Meta:
+        proxy = True
+
+    @property
+    def tag_class_model(self) -> Type:
+        """
+        Associate the user model
+        """
+        return get_user_model()
+
+    @property
+    def tag_class_value(self) -> str:
+        """
+        Returns the name of the tag_class_model field to use as the Tag.value when creating Tags for this taxonomy.
+
+        Subclasses may override this method to use different fields.
+        """
+        return "username"
+
+
+class UserSystemDefinedTaxonomy(ModelSystemDefinedTaxonomy):
+    """
+    User based system taxonomy class.
+    """
+
+    class Meta:
+        proxy = True
+
+    @property
+    def object_tag_class(self) -> Type:
+        """
+        Returns the ObjectTag subclass associated with this taxonomy, which is ModelObjectTag by default.
+
+        Model Taxonomy subclasses must implement this to provide a ModelObjectTag subclass.
+        """
+        return UserModelObjectTag
+
+
+class LanguageTaxonomy(SystemDefinedTaxonomy):
+    """
+    Language System-defined taxonomy
+
+    The tags are filtered and validated taking into account the
+    languages available in Django LANGUAGES settings var
+    """
+
+    class Meta:
+        proxy = True
+
+    def get_tags(self, tag_set: models.QuerySet = None) -> List[Tag]:
+        """
+        Returns a list of all the available Language Tags, annotated with ``depth`` = 0.
+        """
+        available_langs = self._get_available_languages()
+        tag_set = self.tag_set.filter(external_id__in=available_langs)
+        return super().get_tags(tag_set=tag_set)
+
+    def _get_available_languages(cls) -> List[str]:
+        """
+        Get available languages from Django LANGUAGE.
+        """
+        langs = set()
+        for django_lang in settings.LANGUAGES:
+            # Split to get the language part
+            langs.add(django_lang[0].split("-")[0])
+        return langs
+
+    def _check_valid_language(self, object_tag: ObjectTag) -> bool:
+        """
+        Returns True if the tag is on the available languages
+        """
+        available_langs = self._get_available_languages()
+        return object_tag.tag.external_id in available_langs
+
+    def _check_tag(self, object_tag: ObjectTag) -> bool:
+        """
+        Returns True if the tag is on the available languages
+        """
+        return super()._check_tag(object_tag) and self._check_valid_language(object_tag)

openedx_tagging/core/tagging/rest_api/urls.py

@@ -0,0 +1,9 @@
+"""
+Taxonomies API URLs.
+"""
+
+from django.urls import path, include
+
+from .v1 import urls as v1_urls
+
+urlpatterns = [path("v1/", include(v1_urls))]

openedx_tagging/core/tagging/rest_api/v1/permissions.py

@@ -0,0 +1,17 @@
+"""
+Taxonomy permissions
+"""
+
+from rest_framework.permissions import DjangoObjectPermissions
+
+
+class TaxonomyObjectPermissions(DjangoObjectPermissions):
+    perms_map = {
+        "GET": ["%(app_label)s.view_%(model_name)s"],
+        "OPTIONS": [],
+        "HEAD": ["%(app_label)s.view_%(model_name)s"],
+        "POST": ["%(app_label)s.add_%(model_name)s"],
+        "PUT": ["%(app_label)s.change_%(model_name)s"],
+        "PATCH": ["%(app_label)s.change_%(model_name)s"],
+        "DELETE": ["%(app_label)s.delete_%(model_name)s"],
+    }

openedx_tagging/core/tagging/rest_api/v1/serializers.py

@@ -0,0 +1,31 @@
+"""
+API Serializers for taxonomies
+"""
+
+from rest_framework import serializers
+
+from openedx_tagging.core.tagging.models import Taxonomy
+
+
+class TaxonomyListQueryParamsSerializer(serializers.Serializer):
+    """
+    Serializer for the query params for the GET view
+    """
+
+    enabled = serializers.BooleanField(required=False)
+
+
+class TaxonomySerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Taxonomy
+        fields = [
+            "id",
+            "name",
+            "description",
+            "enabled",
+            "required",
+            "allow_multiple",
+            "allow_free_text",
+            "system_defined",
+            "visible_to_authors",
+        ]

openedx_tagging/core/tagging/rest_api/v1/urls.py

@@ -0,0 +1,14 @@
+"""
+Taxonomies API v1 URLs.
+"""
+
+from rest_framework.routers import DefaultRouter
+
+from django.urls.conf import path, include
+
+from . import views
+
+router = DefaultRouter()
+router.register("taxonomies", views.TaxonomyView, basename="taxonomy")
+
+urlpatterns = [path("", include(router.urls))]

openedx_tagging/core/tagging/rest_api/v1/views.py

@@ -0,0 +1,147 @@
+"""
+Tagging API Views
+"""
+from django.http import Http404
+from rest_framework.viewsets import ModelViewSet
+
+from ...api import (
+    create_taxonomy,
+    get_taxonomy,
+    get_taxonomies,
+)
+from .permissions import TaxonomyObjectPermissions
+from .serializers import TaxonomyListQueryParamsSerializer, TaxonomySerializer
+
+
+class TaxonomyView(ModelViewSet):
+    """
+    View to list, create, retrieve, update, or delete Taxonomies.
+
+    **List Query Parameters**
+        * enabled (optional) - Filter by enabled status. Valid values: true, false, 1, 0, "true", "false", "1"
+        * page (optional) - Page number (default: 1)
+        * page_size (optional) - Number of items per page (default: 10)
+
+    **List Example Requests**
+        GET api/tagging/v1/taxonomy                                                 - Get all taxonomies
+        GET api/tagging/v1/taxonomy?enabled=true                                    - Get all enabled taxonomies
+        GET api/tagging/v1/taxonomy?enabled=false                                   - Get all disabled taxonomies
+
+    **List Query Returns**
+        * 200 - Success
+        * 400 - Invalid query parameter
+        * 403 - Permission denied
+
+    **Retrieve Parameters**
+        * pk (required): - The pk of the taxonomy to retrieve
+
+    **Retrieve Example Requests**
+        GET api/tagging/v1/taxonomy/:pk                                             - Get a specific taxonomy
+
+    **Retrieve Query Returns**
+        * 200 - Success
+        * 404 - Taxonomy not found or User does not have permission to access the taxonomy
+
+    **Create Parameters**
+        * name (required): User-facing label used when applying tags from this taxonomy to Open edX objects.
+        * description (optional): Provides extra information for the user when applying tags from this taxonomy to an object.
+        * enabled (optional): Only enabled taxonomies will be shown to authors (default: true).
+        * required (optional): Indicates that one or more tags from this taxonomy must be added to an object (default: False).
+        * allow_multiple (optional): Indicates that multiple tags from this taxonomy may be added to an object (default: False).
+        * allow_free_text (optional): Indicates that tags in this taxonomy need not be predefined; authors may enter their own tag values (default: False).
+
+    **Create Example Requests**
+        POST api/tagging/v1/taxonomy                                                - Create a taxonomy
+        {
+            "name": "Taxonomy Name",                    - User-facing label used when applying tags from this taxonomy to Open edX objects."
+            "description": "This is a description",
+            "enabled": True,
+            "required": True,
+            "allow_multiple": True,
+            "allow_free_text": True,
+        }
+
+    **Create Query Returns**
+        * 201 - Success
+        * 403 - Permission denied
+
+    **Update Parameters**
+        * pk (required): - The pk of the taxonomy to update
+
+    **Update Request Body**
+        * name (optional): User-facing label used when applying tags from this taxonomy to Open edX objects.
+        * description (optional): Provides extra information for the user when applying tags from this taxonomy to an object.
+        * enabled (optional): Only enabled taxonomies will be shown to authors.
+        * required (optional): Indicates that one or more tags from this taxonomy must be added to an object.
+        * allow_multiple (optional): Indicates that multiple tags from this taxonomy may be added to an object.
+        * allow_free_text (optional): Indicates that tags in this taxonomy need not be predefined; authors may enter their own tag values.
+
+    **Update Example Requests**
+        PUT api/tagging/v1/taxonomy/:pk                                            - Update a taxonomy
+        {
+            "name": "Taxonomy New Name",
+            "description": "This is a new description",
+            "enabled": False,
+            "required": False,
+            "allow_multiple": False,
+            "allow_free_text": True,
+        }
+        PATCH api/tagging/v1/taxonomy/:pk                                          - Partially update a taxonomy
+        {
+            "name": "Taxonomy New Name",
+        }
+
+    **Update Query Returns**
+        * 200 - Success
+        * 403 - Permission denied
+
+    **Delete Parameters**
+        * pk (required): - The pk of the taxonomy to delete
+
+    **Delete Example Requests**
+        DELETE api/tagging/v1/taxonomy/:pk                                         - Delete a taxonomy
+
+    **Delete Query Returns**
+        * 200 - Success
+        * 404 - Taxonomy not found
+        * 403 - Permission denied
+
+    """
+
+    serializer_class = TaxonomySerializer
+    permission_classes = [TaxonomyObjectPermissions]
+
+    def get_object(self):
+        """
+        Return the requested taxonomy object, if the user has appropriate
+        permissions.
+        """
+        pk = self.kwargs.get("pk")
+        taxonomy = get_taxonomy(pk)
+        if not taxonomy:
+            raise Http404("Taxonomy not found")
+        self.check_object_permissions(self.request, taxonomy)
+
+        return taxonomy
+
+    def get_queryset(self):
+        """
+        Return a list of taxonomies.
+
+        Returns all taxonomies by default.
+        If you want the disabled taxonomies, pass enabled=False.
+        If you want the enabled taxonomies, pass enabled=True.
+        """
+        query_params = TaxonomyListQueryParamsSerializer(
+            data=self.request.query_params.dict()
+        )
+        query_params.is_valid(raise_exception=True)
+        enabled = query_params.data.get("enabled", None)
+
+        return get_taxonomies(enabled)
+
+    def perform_create(self, serializer):
+        """
+        Create a new taxonomy.
+        """
+        serializer.instance = create_taxonomy(**serializer.validated_data)

openedx_tagging/core/tagging/rules.py

@@ -16,10 +16,10 @@ is_taxonomy_admin = rules.is_staff
 @rules.predicate
 def can_view_taxonomy(user: User, taxonomy: Taxonomy = None) -> bool:
     """
-    Anyone can view an enabled taxonomy,
+    Anyone can view an enabled taxonomy or list all taxonomies,
     but only taxonomy admins can view a disabled taxonomy.
     """
-    return (taxonomy and taxonomy.enabled) or is_taxonomy_admin(user)
+    return not taxonomy or taxonomy.cast().enabled or is_taxonomy_admin(user)
 
 
 @rules.predicate
@@ -28,24 +28,21 @@ def can_change_taxonomy(user: User, taxonomy: Taxonomy = None) -> bool:
     Even taxonomy admins cannot change system taxonomies.
     """
     return is_taxonomy_admin(user) and (
-        not taxonomy or not taxonomy or (taxonomy and not taxonomy.system_defined)
+        not taxonomy or (taxonomy and not taxonomy.cast().system_defined)
     )
 
 
 @rules.predicate
-def can_change_taxonomy_tag(user: User, tag: Tag = None) -> bool:
+def can_change_tag(user: User, tag: Tag = None) -> bool:
     """
     Even taxonomy admins cannot add tags to system taxonomies (their tags are system-defined), or free-text taxonomies
     (these don't have predefined tags).
     """
+    taxonomy = tag.taxonomy.cast() if (tag and tag.taxonomy_id) else None
     return is_taxonomy_admin(user) and (
         not tag
-        or not tag.taxonomy
-        or (
-            tag.taxonomy
-            and not tag.taxonomy.allow_free_text
-            and not tag.taxonomy.system_defined
-        )
+        or not taxonomy
+        or (taxonomy and not taxonomy.allow_free_text and not taxonomy.system_defined)
     )
 
 
@@ -54,10 +51,12 @@ def can_change_object_tag(user: User, object_tag: ObjectTag = None) -> bool:
     """
     Taxonomy admins can create or modify object tags on enabled taxonomies.
     """
+    taxonomy = (
+        object_tag.taxonomy.cast() if (object_tag and object_tag.taxonomy_id) else None
+    )
+    object_tag = taxonomy.object_tag_class.cast(object_tag) if taxonomy else object_tag
     return is_taxonomy_admin(user) and (
-        not object_tag
-        or not object_tag.taxonomy
-        or (object_tag.taxonomy and object_tag.taxonomy.enabled)
+        not object_tag or not taxonomy or (taxonomy and taxonomy.enabled)
     )
 
 
@@ -68,8 +67,8 @@ rules.add_perm("oel_tagging.delete_taxonomy", can_change_taxonomy)
 rules.add_perm("oel_tagging.view_taxonomy", can_view_taxonomy)
 
 # Tag
-rules.add_perm("oel_tagging.add_tag", can_change_taxonomy_tag)
-rules.add_perm("oel_tagging.change_tag", can_change_taxonomy_tag)
+rules.add_perm("oel_tagging.add_tag", can_change_tag)
+rules.add_perm("oel_tagging.change_tag", can_change_tag)
 rules.add_perm("oel_tagging.delete_tag", is_taxonomy_admin)
 rules.add_perm("oel_tagging.view_tag", rules.always_allow)
 

openedx_tagging/core/tagging/urls.py

@@ -0,0 +1,10 @@
+"""
+Tagging API URLs.
+"""
+
+from django.urls import path, include
+
+from .rest_api import urls
+
+app_name = "oel_tagging"
+urlpatterns = [path("", include(urls))]