strapi-kit 0.0.1__py3-none-any.whl

strapi_kit/operations/media.py

@@ -0,0 +1,226 @@
+"""Media operations utilities for strapi-kit.
+
+This module provides shared utility functions for media upload, download,
+and response normalization across sync and async clients.
+"""
+
+import json
+from pathlib import Path
+from typing import IO, Any, Literal
+from urllib.parse import urljoin, urlparse
+
+from strapi_kit.models.response.media import MediaFile
+
+
+class UploadPayload:
+    """Container for upload payload with proper file handle management.
+
+    This class ensures file handles are properly closed after upload operations,
+    preventing resource leaks in batch operations or error scenarios.
+
+    Usage:
+        Use as a context manager to ensure proper cleanup:
+
+        >>> with build_upload_payload("image.jpg") as payload:
+        ...     files = {"files": payload.files_tuple}
+        ...     data = payload.data
+        ...     # Make HTTP request
+    """
+
+    def __init__(
+        self,
+        file_path: Path,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize upload payload.
+
+        Args:
+            file_path: Path to the file to upload
+            data: Optional metadata dictionary
+        """
+        self._file_path = file_path
+        self._data = data
+        self._file_handle: IO[bytes] | None = None
+
+    @property
+    def files_tuple(self) -> tuple[str, IO[bytes], None]:
+        """Get the files tuple for httpx multipart upload.
+
+        Returns:
+            Tuple of (filename, file_handle, content_type)
+            Content type is None to let httpx auto-detect MIME type.
+
+        Raises:
+            RuntimeError: If accessed outside of context manager
+        """
+        if self._file_handle is None:
+            raise RuntimeError("UploadPayload must be used as a context manager")
+        return ("file", self._file_handle, None)
+
+    @property
+    def data(self) -> dict[str, Any] | None:
+        """Get the metadata dictionary."""
+        return self._data
+
+    def __enter__(self) -> "UploadPayload":
+        """Open file handle on context entry."""
+        self._file_handle = open(self._file_path, "rb")
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Close file handle on context exit."""
+        if self._file_handle is not None:
+            self._file_handle.close()
+            self._file_handle = None
+
+
+def build_upload_payload(
+    file_path: str | Path,
+    ref: str | None = None,
+    ref_id: str | int | None = None,
+    field: str | None = None,
+    folder: str | None = None,
+    alternative_text: str | None = None,
+    caption: str | None = None,
+) -> UploadPayload:
+    """Build multipart form data payload for file upload.
+
+    Returns an UploadPayload context manager that properly handles file
+    lifecycle to prevent resource leaks.
+
+    Args:
+        file_path: Path to file to upload
+        ref: Reference model name (e.g., "api::article.article")
+        ref_id: Reference document ID (numeric or string)
+        field: Field name in reference model
+        folder: Folder ID for organization
+        alternative_text: Alt text for images
+        caption: Caption text
+
+    Returns:
+        UploadPayload context manager with file handle management
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+
+    Example:
+        >>> with build_upload_payload(
+        ...     "image.jpg",
+        ...     ref="api::article.article",
+        ...     ref_id="123",
+        ...     alternative_text="Hero image"
+        ... ) as payload:
+        ...     # Use payload.files_tuple and payload.data for upload
+        ...     pass
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    # Build metadata dict (fileInfo in Strapi API)
+    file_info: dict[str, Any] = {}
+    if alternative_text is not None:
+        file_info["alternativeText"] = alternative_text
+    if caption is not None:
+        file_info["caption"] = caption
+
+    # Build form data metadata
+    data: dict[str, Any] = {}
+    if ref is not None:
+        data["ref"] = ref
+    if ref_id is not None:
+        data["refId"] = str(ref_id)
+    if field is not None:
+        data["field"] = field
+    if folder is not None:
+        data["folder"] = folder
+    if file_info:
+        # httpx multipart requires JSON string for nested objects
+        data["fileInfo"] = json.dumps(file_info)
+
+    return UploadPayload(path, data if data else None)
+
+
+def normalize_media_response(
+    response_data: dict[str, Any],
+    api_version: Literal["v4", "v5"],
+) -> MediaFile:
+    """Normalize v4/v5 media response to MediaFile model.
+
+    Handles both nested attributes (v4) and flattened (v5) response structures.
+
+    Args:
+        response_data: Raw API response data
+        api_version: Detected API version ("v4" or "v5")
+
+    Returns:
+        Validated MediaFile instance
+
+    Example:
+        >>> # v5 response (flattened)
+        >>> v5_data = {
+        ...     "id": 1,
+        ...     "documentId": "abc123",
+        ...     "name": "image.jpg",
+        ...     "url": "/uploads/image.jpg"
+        ... }
+        >>> media = normalize_media_response(v5_data, "v5")
+
+        >>> # v4 response (nested attributes)
+        >>> v4_data = {
+        ...     "id": 1,
+        ...     "attributes": {
+        ...         "name": "image.jpg",
+        ...         "url": "/uploads/image.jpg"
+        ...     }
+        ... }
+        >>> media = normalize_media_response(v4_data, "v4")
+    """
+    if api_version == "v4":
+        # v4: nested structure with id at top level, rest in attributes
+        if "attributes" in response_data:
+            # Flatten attributes to top level
+            flattened = {"id": response_data["id"], **response_data["attributes"]}
+            return MediaFile.model_validate(flattened)
+        else:
+            # Already flattened or invalid
+            return MediaFile.model_validate(response_data)
+    else:
+        # v5: already flattened with documentId
+        return MediaFile.model_validate(response_data)
+
+
+def build_media_download_url(base_url: str, media_url: str) -> str:
+    """Construct full URL for media download.
+
+    Handles both relative paths (/uploads/...) and absolute URLs.
+
+    Args:
+        base_url: Strapi instance base URL (e.g., "http://localhost:1337")
+        media_url: Media URL from API response (relative or absolute)
+
+    Returns:
+        Full absolute URL for download
+
+    Example:
+        >>> build_media_download_url(
+        ...     "http://localhost:1337",
+        ...     "/uploads/image.jpg"
+        ... )
+        'http://localhost:1337/uploads/image.jpg'
+
+        >>> build_media_download_url(
+        ...     "http://localhost:1337",
+        ...     "https://cdn.example.com/image.jpg"
+        ... )
+        'https://cdn.example.com/image.jpg'
+    """
+    # Check if URL is already absolute
+    parsed = urlparse(media_url)
+    if parsed.scheme:  # Has http:// or https://
+        return media_url
+
+    # Relative URL - join with base_url
+    # Ensure base_url doesn't have trailing slash for proper joining
+    base = base_url.rstrip("/")
+    return urljoin(base, media_url)

strapi_kit/operations/streaming.py

@@ -0,0 +1,144 @@
+"""Streaming pagination utilities for large result sets.
+
+This module provides generators that automatically handle pagination,
+allowing memory-efficient iteration over large datasets.
+"""
+
+from collections.abc import AsyncGenerator, Generator
+from typing import TYPE_CHECKING
+
+from ..models import StrapiQuery
+from ..models.response.normalized import NormalizedEntity
+
+if TYPE_CHECKING:
+    from ..client.async_client import AsyncClient
+    from ..client.sync_client import SyncClient
+
+
+def stream_entities(
+    client: "SyncClient",
+    endpoint: str,
+    query: StrapiQuery | None = None,
+    page_size: int = 100,
+) -> Generator[NormalizedEntity, None, None]:
+    """Stream entities from endpoint with automatic pagination.
+
+    This generator automatically fetches pages as needed, yielding
+    entities one at a time without loading the entire dataset into memory.
+
+    Args:
+        client: SyncClient instance
+        endpoint: API endpoint (e.g., "articles")
+        query: Optional query (filters, sorts, populate, etc.)
+        page_size: Items per page (default: 100)
+
+    Yields:
+        NormalizedEntity objects one at a time
+
+    Raises:
+        ValueError: If page_size < 1
+
+    Example:
+        >>> with SyncClient(config) as client:
+        ...     for article in stream_entities(client, "articles", page_size=50):
+        ...         print(article.attributes["title"])
+        ...         # Process one at a time without loading all into memory
+    """
+    if page_size < 1:
+        raise ValueError("page_size must be >= 1")
+
+    current_page = 1
+
+    # Build base query - create copy to avoid mutating caller's query
+    base_query = query.copy() if query is not None else StrapiQuery()
+
+    while True:
+        # Update pagination for current page on a copy
+        page_query = base_query.copy().paginate(page=current_page, page_size=page_size)
+
+        # Fetch page
+        response = client.get_many(endpoint, query=page_query)
+
+        # Yield each entity
+        yield from response.data
+
+        # Safety check: if no data returned, stop to prevent infinite loop
+        if not response.data:
+            break
+
+        # Check if more pages exist
+        if response.meta and response.meta.pagination:
+            total_pages = response.meta.pagination.page_count
+            # Handle None or 0 page_count - stop to prevent infinite loop
+            if total_pages is None or total_pages == 0 or current_page >= total_pages:
+                break
+        else:
+            # No pagination metadata, assume single page
+            break
+
+        current_page += 1
+
+
+async def stream_entities_async(
+    client: "AsyncClient",
+    endpoint: str,
+    query: StrapiQuery | None = None,
+    page_size: int = 100,
+) -> AsyncGenerator[NormalizedEntity, None]:
+    """Async version of stream_entities.
+
+    This async generator automatically fetches pages as needed, yielding
+    entities one at a time without loading the entire dataset into memory.
+
+    Args:
+        client: AsyncClient instance
+        endpoint: API endpoint (e.g., "articles")
+        query: Optional query (filters, sorts, populate, etc.)
+        page_size: Items per page (default: 100)
+
+    Yields:
+        NormalizedEntity objects one at a time
+
+    Raises:
+        ValueError: If page_size < 1
+
+    Example:
+        >>> async with AsyncClient(config) as client:
+        ...     async for article in stream_entities_async(client, "articles"):
+        ...         print(article.attributes["title"])
+        ...         # Process asynchronously without loading all into memory
+    """
+    if page_size < 1:
+        raise ValueError("page_size must be >= 1")
+
+    current_page = 1
+
+    # Build base query - create copy to avoid mutating caller's query
+    base_query = query.copy() if query is not None else StrapiQuery()
+
+    while True:
+        # Update pagination for current page on a copy
+        page_query = base_query.copy().paginate(page=current_page, page_size=page_size)
+
+        # Fetch page
+        response = await client.get_many(endpoint, query=page_query)
+
+        # Yield each entity
+        for entity in response.data:
+            yield entity
+
+        # Safety check: if no data returned, stop to prevent infinite loop
+        if not response.data:
+            break
+
+        # Check if more pages exist
+        if response.meta and response.meta.pagination:
+            total_pages = response.meta.pagination.page_count
+            # Handle None or 0 page_count - stop to prevent infinite loop
+            if total_pages is None or total_pages == 0 or current_page >= total_pages:
+                break
+        else:
+            # No pagination metadata, assume single page
+            break
+
+        current_page += 1

strapi_kit/parsers/__init__.py

@@ -0,0 +1,5 @@
+"""Response parsers for Strapi API responses."""
+
+from .version_detecting import VersionDetectingParser
+
+__all__ = ["VersionDetectingParser"]

strapi_kit/parsers/version_detecting.py

@@ -0,0 +1,171 @@
+"""Response parser with automatic Strapi version detection.
+
+This module provides automatic detection and normalization of Strapi v4 and v5
+API responses into a consistent format.
+"""
+
+import logging
+from typing import Any, Literal
+
+from ..models.response.normalized import (
+    NormalizedCollectionResponse,
+    NormalizedEntity,
+    NormalizedSingleResponse,
+)
+from ..models.response.v4 import V4CollectionResponse, V4SingleResponse
+from ..models.response.v5 import V5CollectionResponse, V5SingleResponse
+
+logger = logging.getLogger(__name__)
+
+
+class VersionDetectingParser:
+    """Response parser with automatic v4/v5 version detection.
+
+    This parser automatically detects whether responses are from Strapi v4
+    or v5 based on their structure, then normalizes them to a consistent format.
+
+    Example:
+        ```python
+        parser = VersionDetectingParser()
+        normalized = parser.parse_single(raw_response)
+        print(normalized.data.id)
+        ```
+    """
+
+    def __init__(self, default_version: Literal["v4", "v5"] | None = None) -> None:
+        """Initialize the parser.
+
+        Args:
+            default_version: Optional version to use if detection fails
+        """
+        self._detected_version: Literal["v4", "v5"] | None = default_version
+
+    @property
+    def detected_version(self) -> Literal["v4", "v5"] | None:
+        """Get the detected API version.
+
+        Returns:
+            Detected version or None if not yet detected
+        """
+        return self._detected_version
+
+    def detect_version(self, response_data: dict[str, Any]) -> Literal["v4", "v5"]:
+        """Detect Strapi API version from response structure.
+
+        Args:
+            response_data: Raw JSON response from Strapi
+
+        Returns:
+            Detected API version ("v4" or "v5")
+
+        Note:
+            Only caches version when detection is definitive (found attributes
+            or documentId). Ambiguous responses return fallback without caching,
+            allowing re-detection on subsequent meaningful responses.
+        """
+        # If already detected, use cached version
+        if self._detected_version:
+            return self._detected_version
+
+        # V4: data.attributes structure
+        # V5: flattened data with documentId
+        if isinstance(response_data.get("data"), dict):
+            data = response_data["data"]
+            if "attributes" in data:
+                self._detected_version = "v4"
+                logger.info("Detected Strapi v4 API format")
+            elif "documentId" in data:
+                self._detected_version = "v5"
+                logger.info("Detected Strapi v5 API format")
+            else:
+                # Don't cache - return fallback without locking
+                logger.warning("Could not detect API version from object data, using v4 fallback")
+                return "v4"
+        elif isinstance(response_data.get("data"), list) and response_data["data"]:
+            # Check first item in list
+            first_item = response_data["data"][0]
+            if "attributes" in first_item:
+                self._detected_version = "v4"
+                logger.info("Detected Strapi v4 API format")
+            elif "documentId" in first_item:
+                self._detected_version = "v5"
+                logger.info("Detected Strapi v5 API format")
+            else:
+                # Don't cache - return fallback without locking
+                logger.warning("Could not detect API version from list data, using v4 fallback")
+                return "v4"
+        else:
+            # Empty/no data - don't cache, return fallback
+            return "v4"
+
+        return self._detected_version
+
+    def parse_single(self, response_data: dict[str, Any]) -> NormalizedSingleResponse:
+        """Parse a single entity response into normalized format.
+
+        Args:
+            response_data: Raw JSON response from Strapi
+
+        Returns:
+            Normalized single entity response
+
+        Examples:
+            >>> parser = VersionDetectingParser()
+            >>> response = {"data": {"id": 1, "documentId": "abc", ...}}
+            >>> normalized = parser.parse_single(response)
+            >>> normalized.data.id
+            1
+        """
+        # Detect API version from response
+        api_version = self.detect_version(response_data)
+
+        if api_version == "v4":
+            # Parse as v4 and normalize
+            v4_response = V4SingleResponse(**response_data)
+            if v4_response.data:
+                normalized_entity = NormalizedEntity.from_v4(v4_response.data)
+            else:
+                normalized_entity = None
+
+            return NormalizedSingleResponse(data=normalized_entity, meta=v4_response.meta)
+        else:
+            # Parse as v5 and normalize
+            v5_response = V5SingleResponse(**response_data)
+            if v5_response.data:
+                normalized_entity = NormalizedEntity.from_v5(v5_response.data)
+            else:
+                normalized_entity = None
+
+            return NormalizedSingleResponse(data=normalized_entity, meta=v5_response.meta)
+
+    def parse_collection(self, response_data: dict[str, Any]) -> NormalizedCollectionResponse:
+        """Parse a collection response into normalized format.
+
+        Args:
+            response_data: Raw JSON response from Strapi
+
+        Returns:
+            Normalized collection response
+
+        Examples:
+            >>> parser = VersionDetectingParser()
+            >>> response = {"data": [{"id": 1, ...}, {"id": 2, ...}]}
+            >>> normalized = parser.parse_collection(response)
+            >>> len(normalized.data)
+            2
+        """
+        # Detect API version from response
+        api_version = self.detect_version(response_data)
+
+        if api_version == "v4":
+            # Parse as v4 and normalize
+            v4_response = V4CollectionResponse(**response_data)
+            normalized_entities = [NormalizedEntity.from_v4(entity) for entity in v4_response.data]
+
+            return NormalizedCollectionResponse(data=normalized_entities, meta=v4_response.meta)
+        else:
+            # Parse as v5 and normalize
+            v5_response = V5CollectionResponse(**response_data)
+            normalized_entities = [NormalizedEntity.from_v5(entity) for entity in v5_response.data]
+
+            return NormalizedCollectionResponse(data=normalized_entities, meta=v5_response.meta)