openedx-core 0.34.0__py2.py3-none-any.whl

openedx_content/admin.py

@@ -0,0 +1,13 @@
+"""
+This module aggregates all applet Django Admin modules.
+"""
+# pylint: disable=wildcard-import
+
+from .applets.backup_restore.admin import *
+from .applets.collections.admin import *
+from .applets.components.admin import *
+from .applets.contents.admin import *
+from .applets.publishing.admin import *
+from .applets.sections.admin import *
+from .applets.subsections.admin import *
+from .applets.units.admin import *

openedx_content/api.py

@@ -0,0 +1,20 @@
+"""
+This is the public API for content authoring in the Open edX Core.
+
+This is the single ``api`` module that code outside of the
+``openedx_content.*`` package should import from. It will
+re-export the public functions from all api.py modules of its applets.
+It may also implement its own convenience APIs that wrap calls to multiple app
+APIs.
+"""
+
+# These wildcard imports are okay because these api modules declare __all__.
+# pylint: disable=wildcard-import
+from .applets.backup_restore.api import *
+from .applets.collections.api import *
+from .applets.components.api import *
+from .applets.contents.api import *
+from .applets.publishing.api import *
+from .applets.sections.api import *
+from .applets.subsections.api import *
+from .applets.units.api import *

openedx_content/applets/backup_restore/admin.py

@@ -0,0 +1,3 @@
+"""
+Django Admin pages for Backup Restore models (WIP)
+"""

openedx_content/applets/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 ..publishing.api import get_learning_package_by_key
+from .zipper import LearningPackageUnzipper, LearningPackageZipper
+
+
+def create_zip_file(lp_key: str, path: str, user: UserType | None = None, origin_server: str | 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, origin_server).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_content/applets/backup_restore/models.py

@@ -0,0 +1,3 @@
+"""
+Core models for Backup Restore (WIP)
+"""

openedx_content/applets/backup_restore/serializers.py

@@ -0,0 +1,165 @@
+"""
+The serializers module for restoration of authoring data.
+"""
+from datetime import timezone
+
+from rest_framework import serializers
+
+from ..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)
+
+
+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)
+    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)
+    entities = serializers.ListField(
+        child=serializers.CharField(),
+        required=True,
+        allow_empty=True,
+    )

openedx_content/applets/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 ..collections.models import Collection
+from ..publishing import api as publishing_api
+from ..publishing.models import PublishableEntity, PublishableEntityVersion
+from ..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