openedx-core 1.4.1__py3-none-any.whl

openedx_tagging/models/import_export.py

@@ -0,0 +1,150 @@
+"""
+Models used by the Taxonomy import/export tasks.
+"""
+
+from datetime import datetime
+
+from django.db import models
+from django.utils.translation import gettext as _
+from django.utils.translation import gettext_lazy
+
+from .base import Taxonomy
+
+
+class TagImportTaskState(models.TextChoices):
+    """
+    Enumerates the states that a TagImportTask can be in.
+    """
+    LOADING_DATA = "loading_data", gettext_lazy("Loading Data")
+    PLANNING = "planning", gettext_lazy("Planning")
+    EXECUTING = "executing", gettext_lazy("Executing")
+    SUCCESS = "success", gettext_lazy("Success")
+    ERROR = "error", gettext_lazy("Error")
+
+
+class TagImportTask(models.Model):
+    """
+    Stores the state, plan and logs of a tag import task
+    """
+
+    id = models.BigAutoField(primary_key=True)
+
+    taxonomy = models.ForeignKey(
+        "Taxonomy",
+        on_delete=models.CASCADE,
+        help_text=_("Taxonomy associated with this import"),
+    )
+
+    log = models.TextField(
+        blank=True, default=None, help_text=gettext_lazy("Action execution logs")
+    )
+
+    status = models.CharField(
+        max_length=20,
+        choices=TagImportTaskState.choices,
+        help_text=gettext_lazy("Task status"),
+    )
+
+    creation_date = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        indexes = [
+            models.Index(fields=["taxonomy", "-creation_date"]),
+        ]
+
+    @classmethod
+    def create(cls, taxonomy: Taxonomy):
+        """
+        Creates and logs a new TagImportTask.
+        """
+        task = cls(
+            taxonomy=taxonomy,
+            status=TagImportTaskState.LOADING_DATA.value,
+            log="",
+        )
+        task.add_log(_("Import task created"), save=False)
+        task.save()
+        return task
+
+    def add_log(self, message: str, save=True):
+        """
+        Appends a log message to the task.
+        """
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        log_message = f"[{timestamp}] {message}\n"
+        self.log += log_message
+        if save:
+            self.save()
+
+    def log_exception(self, exception: Exception):
+        """
+        Logs an exception and moves the task status to ERROR.
+        """
+        self.add_log(repr(exception), save=False)
+        self.status = TagImportTaskState.ERROR.value
+        self.save()
+
+    def log_parser_start(self):
+        """
+        Logs the parser start event.
+        """
+        self.add_log(_("Starting to load data from file"))
+
+    def log_parser_end(self, elapsed_time):
+        """
+        Logs the parser finished event.
+        """
+        self.add_log(_("Load data finished. Time elapsed: ") + str(elapsed_time) + _(" seconds"))
+
+    def handle_parser_errors(self, errors):
+        """
+        Handles parser errors by logging them and moving the task status to ERROR.
+        """
+        for error in errors:
+            self.add_log(f"{str(error)}", save=False)
+        self.status = TagImportTaskState.ERROR.value
+        self.save()
+
+    def log_start_planning(self):
+        """
+        Starts task planning with a log message, and moves the task status to PLANNING.
+        """
+        self.add_log(_("Starting plan actions"), save=False)
+        self.status = TagImportTaskState.PLANNING.value
+        self.save()
+
+    def log_plan(self, plan, elapsed_time):
+        """
+        Logs the task plan.
+        """
+        self.add_log(_("Plan finished. Time elapsed: ") + str(elapsed_time) + _(" seconds"))
+        plan_str = plan.plan()
+        self.log += f"\n{plan_str}\n"
+        self.save()
+
+    def handle_plan_errors(self):
+        """
+        Handles plan errors by moving the task status to ERROR.
+        """
+        # Error are logged with plan
+        self.status = TagImportTaskState.ERROR.value
+        self.save()
+
+    def log_start_execute(self):
+        """
+        Starts task execution with a log message, and moves the task status to EXECUTING.
+        """
+        self.add_log(_("Starting execute actions"), save=False)
+        self.status = TagImportTaskState.EXECUTING.value
+        self.save()
+
+    def log_end_execute(self, elapsed_time):
+        self.add_log(_("Execute actions finished. Time elapsed: ") + str(elapsed_time) + _(" seconds"))
+
+    def end_success(self, elapsed_time):
+        """
+        Completes task execution with a log message, and moves the task status to SUCCESS.
+        """
+        self.add_log(_("Execution finished. Total time elapsed: ") + str(elapsed_time) + _("seconds"), save=False)
+        self.status = TagImportTaskState.SUCCESS.value
+        self.save()

openedx_tagging/models/utils.py

@@ -0,0 +1,13 @@
+"""
+Utilities for tagging and taxonomy models
+"""
+
+RESERVED_TAG_CHARS = [
+    '\t',  # Used in the database to separate tag levels in the "lineage" field
+           # e.g. lineage="Earth\tNorth America\tMexico\tMexico City\t"
+    ' > ',  # Used in the search index and Instantsearch frontend to separate tag levels
+            # e.g. tags_level3="Earth > North America > Mexico > Mexico City"
+    ';',   # Used in CSV exports to separate multiple tags from the same taxonomy
+           # e.g. languages-v1: en;es;fr
+]
+TAGS_CSV_SEPARATOR = RESERVED_TAG_CHARS[2]

openedx_tagging/readme.rst

@@ -0,0 +1,15 @@
+Tagging App
+===========
+
+The ``openedx_tagging`` app will enable content authors to tag pieces of content and quickly
+filter for ease of re-use.
+
+Motivation
+----------
+
+Tagging content is central to enable content re-use, facilitate the implementation
+of flexible content structures different from the current implementation and
+allow adaptive learning in the Open edX platform.
+
+This service has been implemented as pluggable django app. Since it is necessary for
+it to work independently of the content to which it links to.

openedx_tagging/rest_api/paginators.py

@@ -0,0 +1,105 @@
+"""
+Paginators uses by the REST API
+"""
+
+from typing import Type
+
+from edx_rest_framework_extensions.paginators import DefaultPagination  # type: ignore[import]
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from openedx_tagging.models import Tag, Taxonomy
+
+from .utils import UserPermissionsHelper
+
+# From this point, the tags begin to be paginated
+MAX_FULL_DEPTH_THRESHOLD = 10_000
+
+
+class CanAddPermissionMixin(UserPermissionsHelper):  # pylint: disable=abstract-method
+    """
+    This mixin inserts a boolean "can_add_<model>" field at the top level of the paginated response.
+
+    The value of the field indicates whether request user may create new instances of the current model.
+    """
+
+    @property
+    def _request(self) -> Request:
+        """Returns the current request for UserPermissionsHelper"""
+        return self.request  # type: ignore[attr-defined]
+
+    def get_paginated_response(self, data) -> Response:
+        """
+        Injects the user's model-level permissions into the paginated response.
+        """
+        response_data = super().get_paginated_response(data).data  # type: ignore[misc]
+        field_name = f"can_add_{self.model_name}"
+        response_data[field_name] = self.get_can_add()
+        return Response(response_data)
+
+
+class TaxonomyPagination(CanAddPermissionMixin, DefaultPagination):
+    """
+    Inserts permissions data for Taxonomies into the top level of the paginated response.
+    """
+
+    page_size = 500
+    max_page_size = 500
+
+    @property
+    def _model(self) -> Type:
+        """
+        Returns the model that is being paginated.
+        """
+        return Taxonomy
+
+
+class TagPermissionsMixin(CanAddPermissionMixin):
+    """
+    Checks "add_tag" permission using a Tag bound to the current taxonomy, so that taxonomies with
+    read_only=True correctly report can_add_tag=False.
+    """
+
+    @property
+    def _model(self) -> Type:
+        """
+        Returns the model that is being paginated.
+        """
+        return Tag
+
+    def paginate_queryset(self, queryset, request, view=None):
+        self._taxonomy = view.get_taxonomy() if view else None
+        return super().paginate_queryset(queryset, request, view=view)
+
+    def get_can_add(self, instance: Tag | None = None) -> bool | None:
+        if instance is None and self._taxonomy:
+            instance = Tag(taxonomy=self._taxonomy)
+        # Check read-only here (as well as via get_can_add()), because the permissions check is skipped for superusers
+        # but even they shouldn't be able to modify tags in read-only taxonomies.
+        if instance and instance.taxonomy and instance.taxonomy.read_only:
+            return False
+        return super().get_can_add(instance)
+
+
+class TagsPagination(TagPermissionsMixin, DefaultPagination):
+    """
+    Custom pagination configuration for taxonomies
+    with a large number of tags. Used on the get tags API view.
+    """
+
+    page_size = 10
+    max_page_size = 300
+
+
+class DisabledTagsPagination(TagPermissionsMixin, DefaultPagination):
+    """
+    Custom pagination configuration for taxonomies
+    with a small number of tags. Used on the get tags API view
+
+    This class allows to bring all the tags of the taxonomy.
+    It should be used if the number of tags within
+    the taxonomy does not exceed `TAGS_THRESHOLD`.
+    """
+
+    page_size = MAX_FULL_DEPTH_THRESHOLD
+    max_page_size = MAX_FULL_DEPTH_THRESHOLD + 1

openedx_tagging/rest_api/urls.py

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

openedx_tagging/rest_api/utils.py

@@ -0,0 +1,110 @@
+"""
+Utilities for the API
+"""
+from typing import Optional, Type
+
+from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication  # type: ignore[import]
+from edx_rest_framework_extensions.auth.session.authentication import (  # type: ignore[import]
+    SessionAuthenticationAllowInactiveUser,
+)
+from rest_framework.request import Request
+
+
+def view_auth_classes(func_or_class):
+    """
+    Function and class decorator that abstracts the authentication classes for api views.
+    """
+    def _decorator(func_or_class):
+        """
+        Requires either OAuth2 or Session-based authentication;
+        are the same authentication classes used on edx-platform
+        """
+        func_or_class.authentication_classes = (
+            JwtAuthentication,
+            SessionAuthenticationAllowInactiveUser,
+        )
+        return func_or_class
+    return _decorator(func_or_class)
+
+
+class UserPermissionsHelper:
+    """
+    Provides helper methods for serializing user permissions.
+    """
+    @property
+    def _request(self) -> Request:
+        """
+        Returns the current request.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    @property
+    def _model(self) -> Type:
+        """
+        Returns the model used when checking permissions.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    @property
+    def app_label(self) -> Type:
+        """
+        Returns the app_label for the model used when checking permissions.
+        """
+        return self._model._meta.app_label
+
+    @property
+    def model_name(self) -> Type:
+        """
+        Returns the name of the model used when checking permissions.
+        """
+        return self._model._meta.model_name
+
+    def _get_permission_name(self, action: str) -> str:
+        """
+        Returns the fully-qualified permission name corresponding to the current model and `action`.
+        """
+        assert action in ("add", "view", "change", "delete")
+        return f'{self.app_label}.{action}_{self.model_name}'
+
+    def _can(self, perm_name: str, instance=None) -> Optional[bool]:
+        """
+        Does the current `request.user` have the given `perm` on the `instance` object?
+
+        Returns None if no permissions were requested.
+        Returns True if they may.
+        Returns False if they may not.
+        """
+        request = self._request
+        assert request and request.user
+        return request.user.has_perm(perm_name, instance)
+
+    def get_can_add(self, instance=None) -> Optional[bool]:
+        """
+        Returns True if the current user is allowed to add new instances.
+
+        `instance` is optional: most tagging models don't need one to check "add" permissions, but some
+        (e.g. Tag, whose "add" permission depends on its taxonomy's read_only flag) do.
+        """
+        perm_name = self._get_permission_name('add')
+        return self._can(perm_name, instance)
+
+    def get_can_view(self, instance) -> Optional[bool]:
+        """
+        Returns True if the current user is allowed to view/see this instance.
+        """
+        perm_name = self._get_permission_name('view')
+        return self._can(perm_name, instance)
+
+    def get_can_change(self, instance) -> Optional[bool]:
+        """
+        Returns True if the current user is allowed to edit/change this instance.
+        """
+        perm_name = self._get_permission_name('change')
+        return self._can(perm_name, instance)
+
+    def get_can_delete(self, instance) -> Optional[bool]:
+        """
+        Returns True if the current user is allowed to delete this instance.
+        """
+        perm_name = self._get_permission_name('change')
+        return self._can(perm_name, instance)

openedx_tagging/rest_api/v1/exception_handlers.py

@@ -0,0 +1,58 @@
+"""
+Tagging REST API exception handling utilities.
+"""
+
+import logging
+import traceback
+
+from django.conf import settings
+from django.http import Http404
+from rest_framework import status
+from rest_framework.exceptions import APIException, PermissionDenied
+from rest_framework.response import Response
+from rest_framework.views import exception_handler
+
+log = logging.getLogger(__name__)
+
+
+def _custom_exception_handler(exc: Exception, context: dict) -> Response | None:
+    """
+    Return standard DRF errors for APIException and a generic 500 otherwise.
+    This exception handler should eventually be replaced by a more top-level
+    exception handler in the openedx-platform repo after the ADR for it is accepted:
+    https://github.com/openedx/openedx-platform/pull/38246
+    """
+    # For exceptions expected by DRF return the standard DRF error response:
+    # Instances of APIException, subclasses of APIException, Django's Http404 exception,
+    # and Django's PermissionDenied exception.
+    is_expected_exception = isinstance(
+        exc, (APIException, Http404, PermissionDenied)
+    )
+    if is_expected_exception:
+        return exception_handler(exc, context)
+
+    # DRF always calls exception handlers from within an `except:` block, so we can assume
+    # that `log.exception` will automatically insert those exception details and a stack trace.
+    log.exception("Unexpected exception while handling API request")
+
+    if settings.DEBUG:
+        description_with_traceback = f"{exc.__class__.__name__}: {str(exc)}\n\nTraceback:\n{traceback.format_exc()}"
+
+        return Response(
+            {"detail": description_with_traceback},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+    return Response(
+        {"detail": "An unexpected error occurred while processing the request."},
+        status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+    )
+
+
+class TaggingExceptionHandlerMixin:
+    """
+    Scope custom exception handling to tagging API views only.
+    """
+
+    def get_exception_handler(self):
+        return _custom_exception_handler

openedx_tagging/rest_api/v1/permissions.py

@@ -0,0 +1,68 @@
+"""
+Tagging permissions
+"""
+import rules
+from rest_framework.permissions import DjangoObjectPermissions
+
+from ...models import Tag, Taxonomy
+
+
+class TaxonomyObjectPermissions(DjangoObjectPermissions):
+    """
+    Maps each REST API methods to its corresponding Taxonomy permission.
+    """
+    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"],
+    }
+
+
+class ObjectTagObjectPermissions(DjangoObjectPermissions):
+    """
+    Maps each REST API methods to its corresponding ObjectTag permission.
+    """
+    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"],
+    }
+
+
+class TaxonomyTagsObjectPermissions(DjangoObjectPermissions):
+    """
+    Maps each REST API methods to its corresponding Taxonomy permission.
+    """
+    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"],
+    }
+
+    # This is to handle the special case for GET list of Taxonomy Tags
+    def has_object_permission(self, request, view, obj):
+        """
+        Returns True if the user on the given request is allowed the given view for the given object.
+        """
+        obj = obj.taxonomy if isinstance(obj, Tag) else obj
+        return rules.has_perm("oel_tagging.list_tag", request.user, obj)
+
+    def _queryset(self, view):
+        """
+        Returns the queryset to use when checking model and object permissions.
+
+        The base class method calls view.get_queryset(), but that method performs database queries, so we override it.
+        """
+        return Taxonomy.objects