strapi-kit 0.0.1__py3-none-any.whl

strapi_kit/export/media_handler.py

@@ -0,0 +1,322 @@
+"""Media file handling for export and import operations.
+
+This module handles downloading media files during export and
+uploading them during import.
+"""
+
+import logging
+import re
+import unicodedata
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from strapi_kit.models.export_format import ExportedMediaFile
+from strapi_kit.models.response.media import MediaFile
+
+if TYPE_CHECKING:
+    from strapi_kit.client.sync_client import SyncClient
+
+logger = logging.getLogger(__name__)
+
+
+class MediaHandler:
+    """Handles media file operations for export/import.
+
+    This class provides utilities for:
+    - Extracting media references from entity data
+    - Downloading media files during export
+    - Uploading media files during import
+    - Updating entity references with new media IDs
+    """
+
+    @staticmethod
+    def _is_media(item: dict[str, Any]) -> bool:
+        """Check if item is media (v4 or v5 format).
+
+        v4 format: {"id": 1, "attributes": {"mime": "image/jpeg", ...}}
+        v5 format: {"id": 1, "mime": "image/jpeg", ...}
+
+        Args:
+            item: Dictionary to check
+
+        Returns:
+            True if item is a media object
+        """
+        # v5 format: mime at top level
+        if "mime" in item:
+            return True
+        # v4 format: mime nested in attributes
+        if "attributes" in item and isinstance(item["attributes"], dict):
+            return "mime" in item["attributes"]
+        return False
+
+    @staticmethod
+    def _get_media_id(item: dict[str, Any]) -> int | None:
+        """Extract ID from media item (v4 or v5 format).
+
+        Args:
+            item: Media dictionary
+
+        Returns:
+            Media ID or None if not found
+        """
+        return item.get("id")
+
+    @staticmethod
+    def _sanitize_filename(name: str, max_length: int = 200) -> str:
+        """Sanitize filename to prevent path traversal and other issues.
+
+        Removes or replaces dangerous characters and path components that
+        could be used for path traversal attacks.
+
+        Args:
+            name: Original filename from media
+            max_length: Maximum length for the filename
+
+        Returns:
+            Sanitized filename safe for filesystem use
+
+        Examples:
+            >>> MediaHandler._sanitize_filename("../../../etc/passwd")
+            '______etc_passwd'
+            >>> MediaHandler._sanitize_filename("image<script>.jpg")
+            'image_script_.jpg'
+            >>> MediaHandler._sanitize_filename("")
+            'unnamed'
+        """
+        if not name or not name.strip():
+            return "unnamed"
+
+        # Normalize unicode characters
+        name = unicodedata.normalize("NFKC", name)
+
+        # Remove null bytes
+        name = name.replace("\x00", "")
+
+        # Replace path traversal sequences first
+        name = name.replace("..", "_")
+
+        # Replace dangerous characters: / \ : * ? " < > |
+        name = re.sub(r'[/\\:*?"<>|]', "_", name)
+
+        # Remove leading/trailing dots and spaces (problematic on Windows)
+        name = name.strip(". ")
+
+        # Handle empty result after stripping
+        if not name:
+            return "unnamed"
+
+        # Truncate while preserving extension
+        if len(name) > max_length:
+            parts = name.rsplit(".", 1)
+            if len(parts) == 2 and len(parts[1]) <= 10:
+                # Has reasonable extension, preserve it
+                ext_with_dot = "." + parts[1]
+                base_max = max_length - len(ext_with_dot)
+                name = parts[0][:base_max] + ext_with_dot
+            else:
+                name = name[:max_length]
+
+        return name or "unnamed"
+
+    @staticmethod
+    def extract_media_references(data: dict[str, Any]) -> list[int]:
+        """Extract media file IDs from entity data.
+
+        Searches for media references in various Strapi formats:
+        - Single media: {"data": {"id": 1}}
+        - Multiple media: {"data": [{"id": 1}, {"id": 2}]}
+
+        Args:
+            data: Entity attributes dictionary
+
+        Returns:
+            List of media file IDs found in the data
+
+        Example:
+            >>> data = {
+            ...     "title": "Article",
+            ...     "cover": {"data": {"id": 5}},
+            ...     "gallery": {"data": [{"id": 10}, {"id": 11}]}
+            ... }
+            >>> MediaHandler.extract_media_references(data)
+            [5, 10, 11]
+        """
+        media_ids: list[int] = []
+
+        for field_value in data.values():
+            if isinstance(field_value, dict) and "data" in field_value:
+                media_data = field_value["data"]
+
+                if media_data is None:
+                    continue
+                elif isinstance(media_data, dict) and MediaHandler._is_media(media_data):
+                    # Single media file (v4 or v5 format)
+                    media_id = MediaHandler._get_media_id(media_data)
+                    if media_id is not None:
+                        media_ids.append(media_id)
+                elif isinstance(media_data, list):
+                    # Multiple media files
+                    for item in media_data:
+                        if isinstance(item, dict) and MediaHandler._is_media(item):
+                            media_id = MediaHandler._get_media_id(item)
+                            if media_id is not None:
+                                media_ids.append(media_id)
+
+        return media_ids
+
+    @staticmethod
+    def download_media_file(
+        client: "SyncClient",
+        media: MediaFile,
+        output_dir: Path,
+    ) -> Path:
+        """Download a media file to local directory.
+
+        Args:
+            client: Strapi client
+            media: Media file metadata
+            output_dir: Directory to save file to
+
+        Returns:
+            Path where file was saved
+
+        Example:
+            >>> output_dir = Path("export/media")
+            >>> local_path = MediaHandler.download_media_file(
+            ...     client, media, output_dir
+            ... )
+        """
+        # Create output directory if needed
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate safe filename with sanitization
+        safe_name = MediaHandler._sanitize_filename(media.name)
+        filename = f"{media.id}_{safe_name}"
+        output_path = output_dir / filename
+
+        # Download file
+        client.download_file(media.url, save_path=str(output_path))
+
+        logger.info(f"Downloaded media file: {filename}")
+        return output_path
+
+    @staticmethod
+    def create_media_export(media: MediaFile, local_path: Path) -> ExportedMediaFile:
+        """Create export metadata for a media file.
+
+        Args:
+            media: Media file metadata from Strapi
+            local_path: Local path where file is saved
+
+        Returns:
+            ExportedMediaFile with metadata
+        """
+        # MediaFile.size is in KB, ExportedMediaFile.size expects bytes
+        size_in_bytes = int(media.size * 1024) if media.size else 0
+        return ExportedMediaFile(
+            id=media.id,
+            url=media.url,
+            name=media.name,
+            mime=media.mime,
+            size=size_in_bytes,
+            hash=media.hash or "",
+            local_path=str(local_path.name),
+        )
+
+    @staticmethod
+    def upload_media_file(
+        client: "SyncClient",
+        file_path: Path,
+        original_metadata: ExportedMediaFile,
+    ) -> MediaFile:
+        """Upload a media file to Strapi.
+
+        Args:
+            client: Strapi client
+            file_path: Path to local file
+            original_metadata: Original media metadata from export
+
+        Returns:
+            Uploaded media file metadata with new ID
+
+        Example:
+            >>> file_path = Path("export/media/5_image.jpg")
+            >>> uploaded = MediaHandler.upload_media_file(
+            ...     client, file_path, exported_media
+            ... )
+            >>> print(f"Old ID: {exported_media.id}, New ID: {uploaded.id}")
+        """
+        # Upload file with original metadata
+        uploaded = client.upload_file(
+            str(file_path),
+            alternative_text=original_metadata.name,
+            caption=original_metadata.name,
+        )
+
+        logger.info(
+            f"Uploaded media file: {original_metadata.name} "
+            f"(old ID: {original_metadata.id}, new ID: {uploaded.id})"
+        )
+        return uploaded
+
+    @staticmethod
+    def update_media_references(
+        data: dict[str, Any],
+        media_id_mapping: dict[int, int],
+    ) -> dict[str, Any]:
+        """Update media IDs in entity data using mapping.
+
+        Args:
+            data: Entity attributes dictionary
+            media_id_mapping: Mapping of old media IDs to new IDs
+
+        Returns:
+            Updated data with new media IDs
+
+        Example:
+            >>> data = {"cover": {"data": {"id": 5}}}
+            >>> mapping = {5: 50}
+            >>> updated = MediaHandler.update_media_references(data, mapping)
+            >>> updated["cover"]["data"]["id"]
+            50
+        """
+        updated_data = {}
+
+        for field_name, field_value in data.items():
+            if isinstance(field_value, dict) and "data" in field_value:
+                media_data = field_value["data"]
+
+                if media_data is None:
+                    updated_data[field_name] = field_value
+                elif isinstance(media_data, dict) and MediaHandler._is_media(media_data):
+                    # Single media file (v4 or v5 format)
+                    old_id = MediaHandler._get_media_id(media_data)
+                    if old_id and old_id in media_id_mapping:
+                        # Update with new ID
+                        updated_media = media_data.copy()
+                        updated_media["id"] = media_id_mapping[old_id]
+                        updated_data[field_name] = {"data": updated_media}
+                    else:
+                        updated_data[field_name] = field_value
+                elif isinstance(media_data, list):
+                    # Multiple media files
+                    updated_list = []
+                    for item in media_data:
+                        if isinstance(item, dict) and MediaHandler._is_media(item):
+                            old_id = MediaHandler._get_media_id(item)
+                            if old_id and old_id in media_id_mapping:
+                                updated_item = item.copy()
+                                updated_item["id"] = media_id_mapping[old_id]
+                                updated_list.append(updated_item)
+                            else:
+                                updated_list.append(item)
+                        else:
+                            updated_list.append(item)
+                    updated_data[field_name] = {"data": updated_list}
+                else:
+                    updated_data[field_name] = field_value
+            else:
+                updated_data[field_name] = field_value
+
+        return updated_data

strapi_kit/export/relation_resolver.py

@@ -0,0 +1,172 @@
+"""Relation resolution for import operations.
+
+This module handles extracting relations from entities during export
+and resolving them during import using ID mappings.
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class RelationResolver:
+    """Handles relation extraction and resolution for export/import.
+
+    During export: Extracts relation IDs from entity attributes
+    During import: Resolves old IDs to new IDs using mapping
+    """
+
+    @staticmethod
+    def extract_relations(data: dict[str, Any]) -> dict[str, list[int | str]]:
+        """Extract relation field IDs from entity data.
+
+        Args:
+            data: Entity attributes dictionary
+
+        Returns:
+            Dictionary mapping relation field names to lists of IDs
+
+        Example:
+            >>> data = {
+            ...     "title": "Article",
+            ...     "author": {"data": {"id": 5}},
+            ...     "categories": {"data": [{"id": 1}, {"id": 2}]}
+            ... }
+            >>> RelationResolver.extract_relations(data)
+            {'author': [5], 'categories': [1, 2]}
+        """
+        relations: dict[str, list[int | str]] = {}
+
+        for field_name, field_value in data.items():
+            if isinstance(field_value, dict) and "data" in field_value:
+                # This looks like a relation field
+                relation_data = field_value["data"]
+
+                if relation_data is None:
+                    # Null relation
+                    relations[field_name] = []
+                elif isinstance(relation_data, dict):
+                    # Single relation
+                    if "id" in relation_data:
+                        relations[field_name] = [relation_data["id"]]
+                elif isinstance(relation_data, list):
+                    # Multiple relations
+                    ids = [item["id"] for item in relation_data if "id" in item]
+                    if ids:
+                        relations[field_name] = ids
+
+        return relations
+
+    @staticmethod
+    def strip_relations(data: dict[str, Any]) -> dict[str, Any]:
+        """Remove relation fields from entity data.
+
+        Useful for importing entities without relations first,
+        then adding relations in a second pass.
+
+        Args:
+            data: Entity attributes dictionary
+
+        Returns:
+            Copy of data with relation fields removed
+
+        Example:
+            >>> data = {"title": "Article", "author": {"data": {"id": 5}}}
+            >>> RelationResolver.strip_relations(data)
+            {'title': 'Article'}
+        """
+        cleaned_data = {}
+
+        for field_name, field_value in data.items():
+            # Skip fields that look like relations
+            if isinstance(field_value, dict) and "data" in field_value:
+                continue
+
+            cleaned_data[field_name] = field_value
+
+        return cleaned_data
+
+    @staticmethod
+    def resolve_relations(
+        relations: dict[str, list[int | str]],
+        id_mapping: dict[str, dict[int, int]],
+        content_type: str,
+    ) -> dict[str, list[int]]:
+        """Resolve old relation IDs to new IDs using mapping.
+
+        Args:
+            relations: Relation field mapping (field -> [old_ids])
+            id_mapping: ID mapping (content_type -> {old_id: new_id})
+            content_type: Content type of the related entities
+
+        Returns:
+            Resolved relations with new IDs
+
+        Example:
+            >>> relations = {"categories": [1, 2]}
+            >>> id_mapping = {
+            ...     "api::category.category": {1: 10, 2: 11}
+            ... }
+            >>> RelationResolver.resolve_relations(
+            ...     relations,
+            ...     id_mapping,
+            ...     "api::category.category"
+            ... )
+            {'categories': [10, 11]}
+        """
+        resolved: dict[str, list[int]] = {}
+
+        type_mapping = id_mapping.get(content_type, {})
+
+        for field_name, old_ids in relations.items():
+            new_ids = []
+            for old_id in old_ids:
+                if isinstance(old_id, int) and old_id in type_mapping:
+                    new_ids.append(type_mapping[old_id])
+                else:
+                    logger.warning(
+                        f"Could not resolve {content_type} ID {old_id} for field {field_name}"
+                    )
+
+            if new_ids:
+                resolved[field_name] = new_ids
+
+        return resolved
+
+    @staticmethod
+    def build_relation_payload(
+        relations: dict[str, list[int]],
+    ) -> dict[str, Any]:
+        """Build Strapi relation payload format.
+
+        Args:
+            relations: Resolved relations (field -> [new_ids])
+
+        Returns:
+            Payload in Strapi format for updating relations
+
+        Example:
+            >>> relations = {"author": [10], "categories": [11, 12]}
+            >>> RelationResolver.build_relation_payload(relations)
+            {'author': 10, 'categories': [11, 12]}
+
+            >>> # Empty list clears the relation
+            >>> relations = {"author": []}
+            >>> RelationResolver.build_relation_payload(relations)
+            {'author': []}
+        """
+        payload: dict[str, Any] = {}
+
+        for field_name, ids in relations.items():
+            if len(ids) == 0:
+                # Empty list - explicit clear of relation
+                payload[field_name] = []
+            elif len(ids) == 1:
+                # Single relation - use single ID
+                payload[field_name] = ids[0]
+            else:
+                # Multiple relations - use array
+                payload[field_name] = ids
+
+        return payload

strapi_kit/models/__init__.py

@@ -0,0 +1,104 @@
+"""Data models for strapi-kit.
+
+Includes configuration models and request/response models for Strapi API interactions.
+"""
+
+from .bulk import BulkOperationFailure, BulkOperationResult
+from .config import RetryConfig, StrapiConfig
+from .enums import FilterOperator, PublicationState, SortDirection
+from .export_format import ExportData, ExportedEntity, ExportedMediaFile, ExportMetadata
+from .import_options import ConflictResolution, ImportOptions, ImportResult
+from .request.fields import FieldSelection
+from .request.filters import FilterBuilder, FilterCondition, FilterGroup
+from .request.pagination import OffsetPagination, PagePagination, Pagination
+from .request.populate import Populate, PopulateField
+from .request.query import StrapiQuery
+from .request.sort import Sort, SortField
+from .response.base import (
+    BaseStrapiResponse,
+    StrapiCollectionResponse,
+    StrapiSingleResponse,
+)
+from .response.component import Component, DynamicZoneBlock
+from .response.media import MediaFile, MediaFormat
+from .response.meta import PaginationMeta, ResponseMeta
+from .response.normalized import (
+    NormalizedCollectionResponse,
+    NormalizedEntity,
+    NormalizedSingleResponse,
+)
+from .response.relation import RelationData
+from .response.v4 import V4Attributes, V4CollectionResponse, V4Entity, V4SingleResponse
+from .response.v5 import V5CollectionResponse, V5Entity, V5SingleResponse
+from .schema import ContentTypeSchema, FieldSchema, FieldType, RelationType
+
+__all__ = [
+    # Configuration
+    "StrapiConfig",
+    "RetryConfig",
+    # Bulk Operations
+    "BulkOperationResult",
+    "BulkOperationFailure",
+    # Export/Import
+    "ExportData",
+    "ExportMetadata",
+    "ExportedEntity",
+    "ExportedMediaFile",
+    "ImportOptions",
+    "ImportResult",
+    "ConflictResolution",
+    # Enums
+    "FilterOperator",
+    "SortDirection",
+    "PublicationState",
+    # Request models - Filters
+    "FilterBuilder",
+    "FilterCondition",
+    "FilterGroup",
+    # Request models - Sort
+    "Sort",
+    "SortField",
+    # Request models - Pagination
+    "PagePagination",
+    "OffsetPagination",
+    "Pagination",
+    # Request models - Fields
+    "FieldSelection",
+    # Request models - Populate
+    "Populate",
+    "PopulateField",
+    # Request models - Query (Main API)
+    "StrapiQuery",
+    # Response models - Base
+    "BaseStrapiResponse",
+    "StrapiSingleResponse",
+    "StrapiCollectionResponse",
+    # Response models - Meta
+    "PaginationMeta",
+    "ResponseMeta",
+    # Response models - V4
+    "V4Attributes",
+    "V4Entity",
+    "V4SingleResponse",
+    "V4CollectionResponse",
+    # Response models - V5
+    "V5Entity",
+    "V5SingleResponse",
+    "V5CollectionResponse",
+    # Response models - Normalized
+    "NormalizedEntity",
+    "NormalizedSingleResponse",
+    "NormalizedCollectionResponse",
+    # Response models - Media
+    "MediaFile",
+    "MediaFormat",
+    # Response models - Relations & Components
+    "RelationData",
+    "Component",
+    "DynamicZoneBlock",
+    # Schema models
+    "ContentTypeSchema",
+    "FieldSchema",
+    "FieldType",
+    "RelationType",
+]

strapi_kit/models/bulk.py

@@ -0,0 +1,69 @@
+"""Models for bulk operation results.
+
+This module provides models for tracking results of bulk operations
+like bulk_create, bulk_update, and bulk_delete.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .response.normalized import NormalizedEntity
+
+
+class BulkOperationFailure(BaseModel):
+    """Represents a failed item in a bulk operation.
+
+    Attributes:
+        index: Position in original list
+        item: Original item data
+        error: Error message
+        exception: Original exception (if available)
+    """
+
+    index: int = Field(..., description="Index in original list")
+    item: dict[str, Any] = Field(..., description="Original item data")
+    error: str = Field(..., description="Error message")
+    exception: Exception | None = Field(None, description="Original exception")
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class BulkOperationResult(BaseModel):
+    """Result of a bulk operation.
+
+    Attributes:
+        successes: Successfully processed entities
+        failures: Failed items with error details
+        total: Total items attempted
+        succeeded: Count of successful items
+        failed: Count of failed items
+    """
+
+    successes: list[NormalizedEntity] = Field(
+        default_factory=list, description="Successfully processed entities"
+    )
+    failures: list[BulkOperationFailure] = Field(
+        default_factory=list, description="Failed items with errors"
+    )
+    total: int = Field(..., description="Total items")
+    succeeded: int = Field(..., description="Successful count")
+    failed: int = Field(..., description="Failed count")
+
+    def is_complete_success(self) -> bool:
+        """Check if all items succeeded.
+
+        Returns:
+            True if all items succeeded, False otherwise
+        """
+        return self.failed == 0
+
+    def success_rate(self) -> float:
+        """Calculate success rate (0.0 to 1.0).
+
+        Returns:
+            Success rate as a float between 0.0 and 1.0
+        """
+        if self.total == 0:
+            return 0.0
+        return self.succeeded / self.total