openedx-learning 0.28.0__tar.gz → 0.29.0__tar.gz

{openedx_learning-0.28.0/openedx_learning.egg-info → openedx_learning-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openedx-learning
-Version: 0.28.0
+Version: 0.29.0
 Summary: Open edX Learning Core and Tagging.
 Home-page: https://github.com/openedx/openedx-learning
 Author: David Ormsbee
@@ -19,13 +19,13 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
 License-File: LICENSE.txt
+Requires-Dist: djangorestframework<4.0
+Requires-Dist: edx-drf-extensions
+Requires-Dist: attrs
 Requires-Dist: celery
+Requires-Dist: tomlkit
 Requires-Dist: rules<4.0
 Requires-Dist: Django
-Requires-Dist: edx-drf-extensions
-Requires-Dist: tomlkit
-Requires-Dist: attrs
-Requires-Dist: djangorestframework<4.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -148,6 +148,15 @@ Every time you develop something in this repo
 
   # Open a PR and ask for review.
 
+Configuring Visual Studio Code
+------------------------------
+
+If you are using VS Code as your editor, you can enable the Testing bar by copying from the example configuration provided in the ``.vscode`` directory::
+
+    cd .vscode/
+    cp launch.json.example launch.json
+    cp settings.json.example settings.json
+
 License
 -------
 

{openedx_learning-0.28.0 → openedx_learning-0.29.0}/README.rst

@@ -108,6 +108,15 @@ Every time you develop something in this repo
 
   # Open a PR and ask for review.
 
+Configuring Visual Studio Code
+------------------------------
+
+If you are using VS Code as your editor, you can enable the Testing bar by copying from the example configuration provided in the ``.vscode`` directory::
+
+    cd .vscode/
+    cp launch.json.example launch.json
+    cp settings.json.example settings.json
+
 License
 -------
 

{openedx_learning-0.28.0 → openedx_learning-0.29.0}/openedx_learning/__init__.py

@@ -2,4 +2,4 @@
 Open edX Learning ("Learning Core").
 """
 
-__version__ = "0.28.0"
+__version__ = "0.29.0"

openedx_learning-0.29.0/openedx_learning/apps/authoring/backup_restore/api.py

@@ -0,0 +1,30 @@
+"""
+Backup Restore API
+"""
+import zipfile
+
+from django.contrib.auth.models import User as UserType  # pylint: disable=imported-auth-user
+
+from openedx_learning.apps.authoring.backup_restore.zipper import LearningPackageUnzipper, LearningPackageZipper
+from openedx_learning.apps.authoring.publishing.api import get_learning_package_by_key
+
+
+def create_zip_file(lp_key: str, path: str, user: UserType | None = None) -> None:
+    """
+    Creates a dump zip file for the given learning package key at the given path.
+    The zip file contains a TOML representation of the learning package and its contents.
+
+    Can throw a NotFoundError at get_learning_package_by_key
+    """
+    learning_package = get_learning_package_by_key(lp_key)
+    LearningPackageZipper(learning_package, user).create_zip(path)
+
+
+def load_learning_package(path: str, key: str | None = None, user: UserType | None = None) -> dict:
+    """
+    Loads a learning package from a zip file at the given path.
+    Restores the learning package and its contents to the database.
+    Returns a dictionary with the status of the operation and any errors encountered.
+    """
+    with zipfile.ZipFile(path, "r") as zipf:
+        return LearningPackageUnzipper(zipf, key, user).load()

{openedx_learning-0.28.0 → openedx_learning-0.29.0}/openedx_learning/apps/authoring/backup_restore/management/commands/lp_dump.py

@@ -1,8 +1,10 @@
 """
-Django management commands to handle backup and restore learning packages (WIP)
+Django management commands to handle backup learning packages (WIP)
 """
 import logging
+import time
 
+from django.contrib.auth import get_user_model
 from django.core.management import CommandError
 from django.core.management.base import BaseCommand
 
@@ -12,6 +14,9 @@ from openedx_learning.apps.authoring.publishing.api import LearningPackage
 logger = logging.getLogger(__name__)
 
 
+User = get_user_model()
+
+
 class Command(BaseCommand):
     """
     Django management command to export a learning package to a zip file.
@@ -21,15 +26,28 @@ class Command(BaseCommand):
     def add_arguments(self, parser):
         parser.add_argument('lp_key', type=str, help='The key of the LearningPackage to dump')
         parser.add_argument('file_name', type=str, help='The name of the output zip file')
+        parser.add_argument(
+            '--username',
+            type=str,
+            help='The username of the user performing the backup operation.',
+            default=None
+        )
 
     def handle(self, *args, **options):
         lp_key = options['lp_key']
         file_name = options['file_name']
-        if not file_name.endswith(".zip"):
+        username = options['username']
+        if not file_name.lower().endswith(".zip"):
             raise CommandError("Output file name must end with .zip")
         try:
-            create_zip_file(lp_key, file_name)
-            message = f'{lp_key} written to {file_name}'
+            # Get the user performing the operation
+            user = None
+            if username:
+                user = User.objects.get(username=username)
+            start_time = time.time()
+            create_zip_file(lp_key, file_name, user=user)
+            elapsed = time.time() - start_time
+            message = f'{lp_key} written to {file_name} (create_zip_file: {elapsed:.2f} seconds)'
             self.stdout.write(self.style.SUCCESS(message))
         except LearningPackage.DoesNotExist as exc:
             message = f"Learning package with key {lp_key} not found"

openedx_learning-0.29.0/openedx_learning/apps/authoring/backup_restore/management/commands/lp_load.py

@@ -0,0 +1,57 @@
+"""
+Django management commands to handle restore learning packages (WIP)
+"""
+import logging
+import time
+
+from django.contrib.auth import get_user_model
+from django.core.management import CommandError
+from django.core.management.base import BaseCommand
+
+from openedx_learning.apps.authoring.backup_restore.api import load_learning_package
+
+logger = logging.getLogger(__name__)
+
+User = get_user_model()
+
+
+class Command(BaseCommand):
+    """
+    Django management command to load a learning package from a zip file.
+    """
+    help = 'Load a learning package from a zip file.'
+
+    def add_arguments(self, parser):
+        parser.add_argument('file_name', type=str, help='The path of the input zip file to load.')
+        parser.add_argument('username', type=str, help='The username of the user performing the load operation.')
+
+    def handle(self, *args, **options):
+        file_name = options['file_name']
+        username = options['username']
+        if not file_name.lower().endswith(".zip"):
+            raise CommandError("Input file name must end with .zip")
+        try:
+            start_time = time.time()
+            # Get the user performing the operation
+            user = User.objects.get(username=username)
+
+            result = load_learning_package(file_name, user=user)
+            duration = time.time() - start_time
+            if result["status"] == "error":
+                message = "Errors encountered during restore:\n"
+                log_buffer = result.get("log_file_error")
+                if log_buffer:
+                    message += log_buffer.getvalue()
+                raise CommandError(message)
+            message = f'{file_name} loaded successfully (duration: {duration:.2f} seconds)'
+            self.stdout.write(self.style.SUCCESS(message))
+        except FileNotFoundError as exc:
+            message = f"Learning package file {file_name} not found: {exc}"
+            raise CommandError(message) from exc
+        except Exception as e:
+            message = f"Failed to load '{file_name}': {e}"
+            logger.exception(
+                "Failed to load zip file %s ",
+                file_name,
+            )
+            raise CommandError(message) from e

openedx_learning-0.29.0/openedx_learning/apps/authoring/backup_restore/serializers.py

@@ -0,0 +1,168 @@
+"""
+The serializers module for restoration of authoring data.
+"""
+from datetime import timezone
+
+from rest_framework import serializers
+
+from openedx_learning.apps.authoring.components import api as components_api
+
+
+class LearningPackageSerializer(serializers.Serializer):  # pylint: disable=abstract-method
+    """
+    Serializer for learning packages.
+
+    Note:
+        The `key` field is serialized, but it is generally not trustworthy for restoration.
+        During restore, a new key may be generated or overridden.
+    """
+    title = serializers.CharField(required=True)
+    key = serializers.CharField(required=True)
+    description = serializers.CharField(required=True, allow_blank=True)
+    created = serializers.DateTimeField(required=True, default_timezone=timezone.utc)
+
+
+class LearningPackageMetadataSerializer(serializers.Serializer):  # pylint: disable=abstract-method
+    """
+    Serializer for learning package metadata.
+
+    Note:
+        This serializer handles data exported to an archive (e.g., during backup),
+        but the metadata is not restored to the database and is meant solely for inspection.
+    """
+    format_version = serializers.IntegerField(required=True)
+    created_by = serializers.CharField(required=False, allow_null=True)
+    created_by_email = serializers.EmailField(required=False, allow_null=True)
+    created_at = serializers.DateTimeField(required=True, default_timezone=timezone.utc)
+    origin_server = serializers.CharField(required=False, allow_null=True)
+
+
+class EntitySerializer(serializers.Serializer):  # pylint: disable=abstract-method
+    """
+    Serializer for publishable entities.
+    """
+    can_stand_alone = serializers.BooleanField(required=True)
+    key = serializers.CharField(required=True)
+    created = serializers.DateTimeField(required=True, default_timezone=timezone.utc)
+    created_by = serializers.CharField(required=True, allow_null=True)
+
+
+class EntityVersionSerializer(serializers.Serializer):  # pylint: disable=abstract-method
+    """
+    Serializer for publishable entity versions.
+    """
+    title = serializers.CharField(required=True)
+    entity_key = serializers.CharField(required=True)
+    created = serializers.DateTimeField(required=True, default_timezone=timezone.utc)
+    created_by = serializers.CharField(required=True, allow_null=True)
+    version_num = serializers.IntegerField(required=True)
+
+
+class ComponentSerializer(EntitySerializer):  # pylint: disable=abstract-method
+    """
+    Serializer for components.
+    Contains logic to convert entity_key to component_type and local_key.
+    """
+
+    def validate(self, attrs):
+        """
+        Custom validation logic:
+        parse the entity_key into (component_type, local_key).
+        """
+        entity_key = attrs["key"]
+        try:
+            component_type_obj, local_key = components_api.get_or_create_component_type_by_entity_key(entity_key)
+            attrs["component_type"] = component_type_obj
+            attrs["local_key"] = local_key
+        except ValueError as exc:
+            raise serializers.ValidationError({"key": str(exc)})
+        return attrs
+
+
+class ComponentVersionSerializer(EntityVersionSerializer):  # pylint: disable=abstract-method
+    """
+    Serializer for component versions.
+    """
+
+
+class ContainerSerializer(EntitySerializer):  # pylint: disable=abstract-method
+    """
+    Serializer for containers.
+    """
+    container = serializers.DictField(required=True)
+
+    def validate_container(self, value):
+        """
+        Custom validation logic for the container field.
+        Ensures that the container dict has exactly one key which is one of
+        "section", "subsection", or "unit" values.
+        """
+        errors = []
+        if not isinstance(value, dict) or len(value) != 1:
+            errors.append("Container must be a dict with exactly one key.")
+        if len(value) == 1:  # Only check the key if there is exactly one
+            container_type = list(value.keys())[0]
+            if container_type not in ("section", "subsection", "unit"):
+                errors.append(f"Invalid container value: {container_type}")
+        if errors:
+            raise serializers.ValidationError(errors)
+        return value
+
+    def validate(self, attrs):
+        """
+        Custom validation logic:
+        parse the container dict to extract the container type.
+        """
+        container = attrs["container"]
+        container_type = list(container.keys())[0]  # It is safe to do this after validate_container
+        attrs["container_type"] = container_type
+        attrs.pop("container")  # Remove the container field after processing
+        return attrs
+
+
+class ContainerVersionSerializer(EntityVersionSerializer):  # pylint: disable=abstract-method
+    """
+    Serializer for container versions.
+    """
+    container = serializers.DictField(required=True)
+
+    def validate_container(self, value):
+        """
+        Custom validation logic for the container field.
+        Ensures that the container dict has exactly one key "children" which is a list of strings.
+        """
+        errors = []
+        if not isinstance(value, dict) or len(value) != 1:
+            errors.append("Container must be a dict with exactly one key.")
+        if "children" not in value:
+            errors.append("Container must have a 'children' key.")
+        if "children" in value and not isinstance(value["children"], list):
+            errors.append("'children' must be a list.")
+        if errors:
+            raise serializers.ValidationError(errors)
+        return value
+
+    def validate(self, attrs):
+        """
+        Custom validation logic:
+        parse the container dict to extract the children list.
+        """
+        children = attrs["container"]["children"]  # It is safe to do this after validate_container
+        attrs["children"] = children
+        attrs.pop("container")  # Remove the container field after processing
+        return attrs
+
+
+class CollectionSerializer(serializers.Serializer):  # pylint: disable=abstract-method
+    """
+    Serializer for collections.
+    """
+    title = serializers.CharField(required=True)
+    key = serializers.CharField(required=True)
+    description = serializers.CharField(required=True, allow_blank=True)
+    created_by = serializers.IntegerField(required=True, allow_null=True)
+    entities = serializers.ListField(
+        child=serializers.CharField(),
+        required=True,
+        allow_empty=True,
+    )

openedx_learning-0.29.0/openedx_learning/apps/authoring/backup_restore/toml.py

@@ -0,0 +1,254 @@
+"""
+TOML serialization for learning packages and publishable entities.
+"""
+
+from datetime import datetime
+from typing import Any, Dict
+
+import tomlkit
+from django.contrib.auth.models import User as UserType  # pylint: disable=imported-auth-user
+
+from openedx_learning.apps.authoring.collections.models import Collection
+from openedx_learning.apps.authoring.publishing import api as publishing_api
+from openedx_learning.apps.authoring.publishing.models import PublishableEntity, PublishableEntityVersion
+from openedx_learning.apps.authoring.publishing.models.learning_package import LearningPackage
+
+
+def toml_learning_package(
+        learning_package: LearningPackage,
+        timestamp: datetime,
+        format_version: int = 1,
+        user: UserType | None = None,
+        origin_server: str | None = None
+        ) -> str:
+    """
+    Create a TOML representation of the learning package.
+
+    The resulting content looks like:
+        [meta]
+        format_version = 1
+        created_by = "dormsbee"
+        created_at = 2025-09-03T17:50:59.536190Z
+        origin_server = "cms.test"
+
+        [learning_package]
+        title = "Components Test Case Learning Package"
+        key = "ComponentTestCase-test-key"
+        description = "This is a test learning package for components."
+        created = 2025-09-03T17:50:59.536190Z
+        updated = 2025-09-03T17:50:59.536190Z
+    """
+    doc = tomlkit.document()
+
+    # Learning package main info
+    section = tomlkit.table()
+    section.add("title", learning_package.title)
+    section.add("key", learning_package.key)
+    section.add("description", learning_package.description)
+    section.add("created", learning_package.created)
+    section.add("updated", learning_package.updated)
+
+    # Learning package metadata
+    metadata = tomlkit.table()
+    metadata.add("format_version", format_version)
+    if user:
+        metadata.add("created_by", user.username)
+        metadata.add("created_by_email", user.email)
+    metadata.add("created_at", timestamp)
+    if origin_server:
+        metadata.add("origin_server", origin_server)
+
+    doc.add("meta", metadata)
+    doc.add("learning_package", section)
+    return tomlkit.dumps(doc)
+
+
+def _get_toml_publishable_entity_table(
+        entity: PublishableEntity,
+        draft_version: PublishableEntityVersion | None,
+        published_version: PublishableEntityVersion | None,
+        include_versions: bool = True) -> tomlkit.items.Table:
+    """
+    Create a TOML representation of a publishable entity.
+
+    The resulting content looks like:
+        [entity]
+        can_stand_alone = true
+        key = "xblock.v1:problem:my_published_example"
+
+        [entity.draft]
+        version_num = 2
+
+        [entity.published]
+        version_num = 1
+
+        [entity.container.section]
+
+    Note: This function returns a tomlkit.items.Table, which represents
+    a string-like TOML fragment rather than a complete TOML document.
+    """
+    entity_table = tomlkit.table()
+    entity_table.add("can_stand_alone", entity.can_stand_alone)
+    # Add key since the toml filename doesn't show the real key
+    entity_table.add("key", entity.key)
+    entity_table.add("created", entity.created)
+
+    if not include_versions:
+        return entity_table
+
+    if draft_version:
+        draft_table = tomlkit.table()
+        draft_table.add("version_num", draft_version.version_num)
+        entity_table.add("draft", draft_table)
+
+    published_table = tomlkit.table()
+    if published_version:
+        published_table.add("version_num", published_version.version_num)
+    else:
+        published_table.add(tomlkit.comment("unpublished: no published_version_num"))
+    entity_table.add("published", published_table)
+
+    if hasattr(entity, "container"):
+        container_table = tomlkit.table()
+        container_types = ["section", "subsection", "unit"]
+
+        for container_type in container_types:
+            if hasattr(entity.container, container_type):
+                container_table.add(container_type, tomlkit.table())
+                break  # stop after the first match
+
+        entity_table.add("container", container_table)
+
+    return entity_table
+
+
+def toml_publishable_entity(
+        entity: PublishableEntity,
+        versions_to_write: list[PublishableEntityVersion],
+        draft_version: PublishableEntityVersion | None,
+        published_version: PublishableEntityVersion | None) -> str:
+    """
+    Create a TOML representation of a publishable entity and its versions.
+
+    The resulting content looks like:
+        [entity]
+        can_stand_alone = true
+        key = "xblock.v1:problem:my_published_example"
+
+        [entity.draft]
+        version_num = 2
+
+        [entity.published]
+        version_num = 1
+
+        [entity.container.section] (if applicable)
+
+        # ### Versions
+
+        [[version]]
+        title = "My published problem"
+        version_num = 1
+
+        [version.container] (if applicable)
+        children = []
+    """
+    # Create the TOML representation for the entity itself
+    entity_table = _get_toml_publishable_entity_table(entity, draft_version, published_version)
+    doc = tomlkit.document()
+    doc.add("entity", entity_table)
+
+    # Add versions as an array of tables (AoT)
+    doc.add(tomlkit.nl())
+    doc.add(tomlkit.comment("### Versions"))
+    for entity_version in versions_to_write:
+        version = tomlkit.aot()
+        version_table = toml_publishable_entity_version(entity_version)
+        version.append(version_table)
+        doc.add("version", version)
+
+    return tomlkit.dumps(doc)
+
+
+def toml_publishable_entity_version(version: PublishableEntityVersion) -> tomlkit.items.Table:
+    """
+    Create a TOML representation of a publishable entity version.
+
+    The resulting content looks like:
+        [[version]]
+        title = "My published problem"
+        version_num = 1
+
+        [version.container] (if applicable)
+        children = []
+
+    Note: This function returns a tomlkit.items.Table, which represents
+    a string-like TOML fragment rather than a complete TOML document.
+    """
+    version_table = tomlkit.table()
+    version_table.add("title", version.title)
+    version_table.add("version_num", version.version_num)
+
+    if hasattr(version, 'containerversion'):
+        # If the version has a container version, add its children
+        container_table = tomlkit.table()
+        children = publishing_api.get_container_children_entities_keys(version.containerversion)
+        container_table.add("children", children)
+        version_table.add("container", container_table)
+    return version_table
+
+
+def toml_collection(collection: Collection, entity_keys: list[str]) -> str:
+    """
+    Create a TOML representation of a collection.
+
+    The resulting content looks like:
+        [collection]
+        title = "Collection 1"
+        key = "COL1"
+        description = "Description of Collection 1"
+        created = 2025-09-03T22:28:53.839362Z
+        entities = [
+            "xblock.v1:problem:my_published_example",
+            "xblock.v1:html:my_draft_example",
+        ]
+    """
+    doc = tomlkit.document()
+
+    entities_array = tomlkit.array()
+    entities_array.extend(entity_keys)
+    entities_array.multiline(True)
+
+    collection_table = tomlkit.table()
+    collection_table.add("title", collection.title)
+    collection_table.add("key", collection.key)
+    collection_table.add("description", collection.description)
+    collection_table.add("created", collection.created)
+    collection_table.add("entities", entities_array)
+
+    doc.add("collection", collection_table)
+
+    return tomlkit.dumps(doc)
+
+
+def parse_learning_package_toml(content: str) -> dict:
+    """
+    Parse the learning package TOML content and return a dict of its fields.
+    """
+    lp_data: Dict[str, Any] = tomlkit.parse(content)
+    return lp_data
+
+
+def parse_publishable_entity_toml(content: str) -> dict:
+    """
+    Parse the publishable entity TOML file and return a dict of its fields.
+    """
+    pe_data: Dict[str, Any] = tomlkit.parse(content)
+    return pe_data
+
+
+def parse_collection_toml(content: str) -> dict:
+    """
+    Parse the collection TOML content and return a dict of its fields.
+    """
+    collection_data: Dict[str, Any] = tomlkit.parse(content)
+    return collection_data