strapi-kit 0.0.5__py3-none-any.whl → 0.1.0__py3-none-any.whl

strapi_kit/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.5'
-__version_tuple__ = version_tuple = (0, 0, 5)
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
 
 __commit_id__ = commit_id = None

strapi_kit/cache/schema_cache.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, Any
 
 from ..exceptions import StrapiError
 from ..models.schema import ContentTypeSchema, FieldSchema, FieldType, RelationType
+from ..utils.schema import extract_info_from_schema
 
 if TYPE_CHECKING:
     from ..client.sync_client import SyncClient
@@ -36,6 +37,7 @@ class InMemorySchemaCache:
         """
         self.client = client
         self._cache: dict[str, ContentTypeSchema] = {}
+        self._component_cache: dict[str, ContentTypeSchema] = {}
         self._fetch_count = 0
 
     def get_schema(self, content_type: str) -> ContentTypeSchema:
@@ -88,9 +90,80 @@ class InMemorySchemaCache:
     def clear_cache(self) -> None:
         """Clear all cached schemas."""
         self._cache.clear()
+        self._component_cache.clear()
         self._fetch_count = 0
         logger.debug("Schema cache cleared")
 
+    def get_component_schema(self, component_uid: str) -> ContentTypeSchema:
+        """Get component schema (cached or fetch from API).
+
+        Lazy loading: only fetches on first access.
+
+        Args:
+            component_uid: Component UID (e.g., "blog.author-bio")
+
+        Returns:
+            Component schema
+
+        Raises:
+            StrapiError: If schema fetch fails
+        """
+        # Check cache first
+        if component_uid in self._component_cache:
+            logger.debug(f"Component schema cache hit: {component_uid}")
+            return self._component_cache[component_uid]
+
+        # Cache miss - fetch from API
+        logger.debug(f"Component schema cache miss: {component_uid}")
+        schema = self._fetch_component_schema(component_uid)
+        self._component_cache[component_uid] = schema
+        self._fetch_count += 1
+        return schema
+
+    def has_component_schema(self, component_uid: str) -> bool:
+        """Check if component schema is cached.
+
+        Args:
+            component_uid: Component UID
+
+        Returns:
+            True if schema is cached, False otherwise
+        """
+        return component_uid in self._component_cache
+
+    def _fetch_component_schema(self, component_uid: str) -> ContentTypeSchema:
+        """Fetch component schema from Strapi API.
+
+        Endpoint: GET /api/content-type-builder/components/{uid}
+
+        Args:
+            component_uid: Component UID
+
+        Returns:
+            Parsed component schema
+
+        Raises:
+            StrapiError: If fetch fails
+        """
+        endpoint = f"content-type-builder/components/{component_uid}"
+
+        try:
+            response = self.client.get(endpoint)
+        except Exception as e:
+            raise StrapiError(
+                f"Failed to fetch component schema for {component_uid}",
+                details={"component_uid": component_uid, "error": str(e)},
+            ) from e
+
+        schema_data = response.get("data")
+        if not schema_data:
+            raise StrapiError(
+                f"Invalid component schema response for {component_uid}",
+                details={"response": response},
+            )
+
+        return self._parse_schema_response(component_uid, schema_data)
+
     def _fetch_schema(self, content_type: str) -> ContentTypeSchema:
         """Fetch schema from Strapi API.
 
@@ -134,8 +207,14 @@ class InMemorySchemaCache:
         Returns:
             Parsed content type schema
         """
-        info = schema_data.get("info", {})
-        attributes = schema_data.get("attributes", {})
+        # Handle v5 nested schema format (Issue #28)
+        if "schema" in schema_data and isinstance(schema_data["schema"], dict):
+            schema = schema_data["schema"]
+        else:
+            schema = schema_data
+
+        info = extract_info_from_schema(schema)
+        attributes = schema.get("attributes", {})
 
         fields: dict[str, FieldSchema] = {}
         for field_name, field_data in attributes.items():
@@ -147,7 +226,7 @@ class InMemorySchemaCache:
         return ContentTypeSchema(
             uid=uid,
             display_name=info.get("displayName", uid),
-            kind=schema_data.get("kind", "collectionType"),
+            kind=schema.get("kind", "collectionType"),
             singular_name=info.get("singularName"),
             plural_name=info.get("pluralName"),
             fields=fields,
@@ -190,6 +269,15 @@ class InMemorySchemaCache:
             schema.mapped_by = field_data.get("mappedBy")
             schema.inversed_by = field_data.get("inversedBy")
 
+        # Component-specific
+        if field_type == FieldType.COMPONENT:
+            schema.component = field_data.get("component")
+            schema.repeatable = field_data.get("repeatable", False)
+
+        # Dynamic zone-specific
+        if field_type == FieldType.DYNAMIC_ZONE:
+            schema.components = field_data.get("components", [])
+
         return schema
 
     @property

strapi_kit/client/async_client.py

@@ -585,7 +585,7 @@ class AsyncClient(BaseClient):
         self,
         media_url: str,
         save_path: str | Path | None = None,
-    ) -> bytes:
+    ) -> bytes | Path:
         """Download a media file from Strapi.
 
         Args:
@@ -593,7 +593,7 @@ class AsyncClient(BaseClient):
             save_path: Optional path to save file (if None, returns bytes only)
 
         Returns:
-            File content as bytes
+            File content as bytes when save_path is None, or Path when save_path is provided
 
         Raises:
             MediaError: On download failure
@@ -604,11 +604,13 @@ class AsyncClient(BaseClient):
             >>> len(content)
             102400
 
-            >>> # Download and save to file
-            >>> content = await client.download_file(
+            >>> # Download and save to file (returns Path, not bytes)
+            >>> path = await client.download_file(
             ...     "/uploads/image.jpg",
             ...     save_path="downloaded_image.jpg"
             ... )
+            >>> path.exists()
+            True
         """
         try:
             # Build full URL
@@ -619,19 +621,25 @@ class AsyncClient(BaseClient):
                 if not response.is_success:
                     self._handle_error_response(response)
 
-                # Read content asynchronously
-                chunks = []
-                async for chunk in response.aiter_bytes():
-                    chunks.append(chunk)
-                content = b"".join(chunks)
-
-                # Save to file if path provided
                 if save_path:
+                    # Stream directly to disk for memory efficiency
+                    # Note: Using sync file I/O here as aiofiles is not a dependency
+                    # The streaming download itself is async which is the main benefit
                     path = Path(save_path)
-                    path.write_bytes(content)
-                    logger.info(f"Downloaded {len(content)} bytes to {save_path}")
-
-                return content
+                    total_bytes = 0
+                    with open(path, "wb") as f:
+                        async for chunk in response.aiter_bytes():
+                            f.write(chunk)
+                            total_bytes += len(chunk)
+                    logger.info(f"Downloaded {total_bytes} bytes to {save_path}")
+                    # Return path instead of reading back to avoid memory overhead
+                    return path
+                else:
+                    # Buffer in memory (original behavior for in-memory use)
+                    chunks = []
+                    async for chunk in response.aiter_bytes():
+                        chunks.append(chunk)
+                    return b"".join(chunks)
 
         except StrapiError:
             raise  # Preserve specific error types (NotFoundError, etc.)
@@ -751,6 +759,11 @@ class AsyncClient(BaseClient):
         import json as json_module
 
         try:
+            # Ensure API version is detected before choosing endpoint
+            # When api_version="auto" and no prior API call, _api_version is None
+            if self._api_version is None:
+                await self.get_media(media_id)  # Triggers version detection
+
             # Build update payload
             file_info: dict[str, Any] = {}
             if alternative_text is not None:
@@ -814,8 +827,9 @@ class AsyncClient(BaseClient):
         Args:
             endpoint: API endpoint (e.g., "articles")
             items: List of entity data dicts
-            batch_size: Items per batch (default: 10, currently unused - for API compatibility)
-            max_concurrency: Max concurrent requests (default: 5)
+            batch_size: Items per batch wave (default: 10). Controls memory usage
+                by limiting how many tasks are active at once.
+            max_concurrency: Max parallel requests within each batch (default: 5)
             query: Optional query
             progress_callback: Optional callback(completed, total)
 
@@ -827,16 +841,15 @@ class AsyncClient(BaseClient):
             ...     {"title": "Article 1", "content": "..."},
             ...     {"title": "Article 2", "content": "..."},
             ... ]
-            >>> result = await client.bulk_create("articles", items, max_concurrency=10)
+            >>> result = await client.bulk_create("articles", items, batch_size=20, max_concurrency=10)
             >>> print(f"Created {result.succeeded}/{result.total}")
         """
         successes: list[NormalizedEntity] = []
         failures: list[BulkOperationFailure] = []
-        semaphore = asyncio.Semaphore(max_concurrency)
-        lock = asyncio.Lock()
         completed = 0
+        lock = asyncio.Lock()
 
-        async def create_one(idx: int, item: dict[str, Any]) -> None:
+        async def create_one(idx: int, item: dict[str, Any], semaphore: asyncio.Semaphore) -> None:
             nonlocal completed
 
             async with semaphore:
@@ -864,11 +877,16 @@ class AsyncClient(BaseClient):
                         if progress_callback:
                             progress_callback(completed, len(items))
 
-        # Create all tasks
-        tasks = [create_one(i, item) for i, item in enumerate(items)]
+        # Process items in batches to control memory usage
+        for batch_start in range(0, len(items), batch_size):
+            batch = items[batch_start : batch_start + batch_size]
+            semaphore = asyncio.Semaphore(max_concurrency)
 
-        # Execute with gather (doesn't stop on first error)
-        await asyncio.gather(*tasks, return_exceptions=False)
+            # Create tasks for this batch only
+            tasks = [create_one(batch_start + i, item, semaphore) for i, item in enumerate(batch)]
+
+            # Execute batch with gather
+            await asyncio.gather(*tasks, return_exceptions=False)
 
         return BulkOperationResult(
             successes=successes,
@@ -893,8 +911,9 @@ class AsyncClient(BaseClient):
         Args:
             endpoint: API endpoint (e.g., "articles")
             updates: List of (id, data) tuples
-            batch_size: Items per batch (default: 10, currently unused - for API compatibility)
-            max_concurrency: Max concurrent requests (default: 5)
+            batch_size: Items per batch wave (default: 10). Controls memory usage
+                by limiting how many tasks are active at once.
+            max_concurrency: Max parallel requests within each batch (default: 5)
             query: Optional query
             progress_callback: Optional callback(completed, total)
 
@@ -906,16 +925,17 @@ class AsyncClient(BaseClient):
             ...     (1, {"title": "Updated Title 1"}),
             ...     (2, {"title": "Updated Title 2"}),
             ... ]
-            >>> result = await client.bulk_update("articles", updates)
+            >>> result = await client.bulk_update("articles", updates, batch_size=20)
             >>> print(f"Updated {result.succeeded}/{result.total}")
         """
         successes: list[NormalizedEntity] = []
         failures: list[BulkOperationFailure] = []
-        semaphore = asyncio.Semaphore(max_concurrency)
-        lock = asyncio.Lock()
         completed = 0
+        lock = asyncio.Lock()
 
-        async def update_one(idx: int, entity_id: str | int, data: dict[str, Any]) -> None:
+        async def update_one(
+            idx: int, entity_id: str | int, data: dict[str, Any], semaphore: asyncio.Semaphore
+        ) -> None:
             nonlocal completed
 
             async with semaphore:
@@ -943,11 +963,19 @@ class AsyncClient(BaseClient):
                         if progress_callback:
                             progress_callback(completed, len(updates))
 
-        # Create all tasks
-        tasks = [update_one(i, entity_id, data) for i, (entity_id, data) in enumerate(updates)]
+        # Process updates in batches to control memory usage
+        for batch_start in range(0, len(updates), batch_size):
+            batch = updates[batch_start : batch_start + batch_size]
+            semaphore = asyncio.Semaphore(max_concurrency)
+
+            # Create tasks for this batch only
+            tasks = [
+                update_one(batch_start + i, entity_id, data, semaphore)
+                for i, (entity_id, data) in enumerate(batch)
+            ]
 
-        # Execute with gather
-        await asyncio.gather(*tasks, return_exceptions=False)
+            # Execute batch with gather
+            await asyncio.gather(*tasks, return_exceptions=False)
 
         return BulkOperationResult(
             successes=successes,
@@ -971,8 +999,9 @@ class AsyncClient(BaseClient):
         Args:
             endpoint: API endpoint (e.g., "articles")
             ids: List of entity IDs (numeric or documentId)
-            batch_size: Items per batch (default: 10, currently unused - for API compatibility)
-            max_concurrency: Max concurrent requests (default: 5)
+            batch_size: Items per batch wave (default: 10). Controls memory usage
+                by limiting how many tasks are active at once.
+            max_concurrency: Max parallel requests within each batch (default: 5)
             progress_callback: Optional callback(completed, total)
 
         Returns:
@@ -980,26 +1009,25 @@ class AsyncClient(BaseClient):
 
         Example:
             >>> ids = [1, 2, 3, 4, 5]
-            >>> result = await client.bulk_delete("articles", ids)
+            >>> result = await client.bulk_delete("articles", ids, batch_size=20)
             >>> print(f"Deleted {result.succeeded} articles")
         """
         successes: list[NormalizedEntity] = []
         failures: list[BulkOperationFailure] = []
-        semaphore = asyncio.Semaphore(max_concurrency)
-        lock = asyncio.Lock()
         completed = 0
         success_count = 0
+        lock = asyncio.Lock()
 
-        async def delete_one(idx: int, entity_id: str | int) -> None:
+        async def delete_one(idx: int, entity_id: str | int, semaphore: asyncio.Semaphore) -> None:
             nonlocal completed, success_count
 
             async with semaphore:
                 try:
                     response = await self.remove(f"{endpoint}/{entity_id}")
 
+                    # DELETE may return 204 No Content with no data
+                    # Count as success when no exception is raised
                     async with lock:
-                        # DELETE may return 204 No Content with no data
-                        # Count as success when no exception is raised
                         success_count += 1
                         if response.data:
                             successes.append(response.data)
@@ -1021,11 +1049,19 @@ class AsyncClient(BaseClient):
                         if progress_callback:
                             progress_callback(completed, len(ids))
 
-        # Create all tasks
-        tasks = [delete_one(i, entity_id) for i, entity_id in enumerate(ids)]
+        # Process deletes in batches to control memory usage
+        for batch_start in range(0, len(ids), batch_size):
+            batch = ids[batch_start : batch_start + batch_size]
+            semaphore = asyncio.Semaphore(max_concurrency)
+
+            # Create tasks for this batch only
+            tasks = [
+                delete_one(batch_start + i, entity_id, semaphore)
+                for i, entity_id in enumerate(batch)
+            ]
 
-        # Execute with gather
-        await asyncio.gather(*tasks, return_exceptions=False)
+            # Execute batch with gather
+            await asyncio.gather(*tasks, return_exceptions=False)
 
         return BulkOperationResult(
             successes=successes,

strapi_kit/client/base.py

@@ -44,6 +44,7 @@ from ..models.response.normalized import (
 from ..operations.media import normalize_media_response
 from ..parsers import VersionDetectingParser
 from ..protocols import AuthProvider, ConfigProvider, ResponseParser
+from ..utils.schema import extract_info_from_schema
 
 logger = logging.getLogger(__name__)
 
@@ -465,6 +466,63 @@ class BaseClient:
         # Media list follows standard collection format
         return self._parse_collection_response(response_data)
 
+    def _normalize_content_type_item(self, item: dict[str, Any]) -> dict[str, Any]:
+        """Normalize content type item - flatten v5 schema to v4 format.
+
+        Strapi v5 returns content types with a nested 'schema' structure:
+        {"uid": "...", "apiID": "...", "schema": {"kind": "...", "info": {...}, ...}}
+
+        Or with flat schema properties (actual v5 API - Issue #28):
+        {"uid": "...", "apiID": "...", "schema": {"kind": "...", "displayName": "...", ...}}
+
+        This method flattens it to v4 format:
+        {"uid": "...", "kind": "...", "info": {...}, "attributes": {...}}
+
+        Args:
+            item: Raw content type item from API response
+
+        Returns:
+            Normalized content type item in v4-compatible format
+        """
+        if "schema" in item and isinstance(item["schema"], dict):
+            schema = item["schema"]
+            return {
+                "uid": item.get("uid", ""),
+                "kind": schema.get("kind", "collectionType"),
+                "info": extract_info_from_schema(schema),
+                "attributes": schema.get("attributes", {}),
+                "pluginOptions": schema.get("pluginOptions"),
+            }
+        return item
+
+    def _normalize_component_item(self, item: dict[str, Any]) -> dict[str, Any]:
+        """Normalize component item - flatten v5 schema to v4 format.
+
+        Strapi v5 returns components with a nested 'schema' structure:
+        {"uid": "...", "category": "...", "schema": {"info": {...}, "attributes": {...}}}
+
+        Or with flat schema properties (actual v5 API - Issue #28):
+        {"uid": "...", "category": "...", "schema": {"displayName": "...", "attributes": {...}}}
+
+        This method flattens it to v4 format:
+        {"uid": "...", "category": "...", "info": {...}, "attributes": {...}}
+
+        Args:
+            item: Raw component item from API response
+
+        Returns:
+            Normalized component item in v4-compatible format
+        """
+        if "schema" in item and isinstance(item["schema"], dict):
+            schema = item["schema"]
+            return {
+                "uid": item.get("uid", ""),
+                "category": item.get("category", schema.get("category", "")),
+                "info": extract_info_from_schema(schema),
+                "attributes": schema.get("attributes", {}),
+            }
+        return item
+
     def _parse_content_types_response(
         self,
         response_data: dict[str, Any],
@@ -472,6 +530,8 @@ class BaseClient:
     ) -> list["ContentTypeListItem"]:
         """Parse content-type-builder content types response.
 
+        Automatically normalizes v5 nested schema format to v4 flat format.
+
         Args:
             response_data: Raw JSON response from content-type-builder
             include_plugins: Whether to include plugin content types
@@ -491,7 +551,8 @@ class BaseClient:
                 continue
 
             try:
-                content_type = ContentTypeListItem.model_validate(item)
+                normalized_item = self._normalize_content_type_item(item)
+                content_type = ContentTypeListItem.model_validate(normalized_item)
                 result.append(content_type)
             except PydanticValidationError as e:
                 # Skip malformed items
@@ -506,6 +567,8 @@ class BaseClient:
     ) -> list["ComponentListItem"]:
         """Parse content-type-builder components response.
 
+        Automatically normalizes v5 nested schema format to v4 flat format.
+
         Args:
             response_data: Raw JSON response from content-type-builder
 
@@ -520,7 +583,8 @@ class BaseClient:
         for item in data:
             uid = item.get("uid", "")
             try:
-                component = ComponentListItem.model_validate(item)
+                normalized_item = self._normalize_component_item(item)
+                component = ComponentListItem.model_validate(normalized_item)
                 result.append(component)
             except PydanticValidationError as e:
                 # Skip malformed items
@@ -535,6 +599,8 @@ class BaseClient:
     ) -> "CTBContentTypeSchema":
         """Parse content-type-builder single content type schema response.
 
+        Automatically normalizes v5 nested schema format to v4 flat format.
+
         Args:
             response_data: Raw JSON response from content-type-builder
 
@@ -548,7 +614,8 @@ class BaseClient:
 
         data = response_data.get("data", response_data)
         try:
-            return CTBContentTypeSchema.model_validate(data)
+            normalized_data = self._normalize_content_type_item(data)
+            return CTBContentTypeSchema.model_validate(normalized_data)
         except PydanticValidationError as e:
             raise ValidationError(
                 "Invalid content type schema response",

strapi_kit/client/sync_client.py

@@ -578,7 +578,7 @@ class SyncClient(BaseClient):
         self,
         media_url: str,
         save_path: str | Path | None = None,
-    ) -> bytes:
+    ) -> bytes | Path:
         """Download a media file from Strapi.
 
         Args:
@@ -586,7 +586,7 @@ class SyncClient(BaseClient):
             save_path: Optional path to save file (if None, returns bytes only)
 
         Returns:
-            File content as bytes
+            File content as bytes when save_path is None, or Path when save_path is provided
 
         Raises:
             MediaError: On download failure
@@ -597,11 +597,13 @@ class SyncClient(BaseClient):
             >>> len(content)
             102400
 
-            >>> # Download and save to file
-            >>> content = client.download_file(
+            >>> # Download and save to file (returns Path, not bytes)
+            >>> path = client.download_file(
             ...     "/uploads/image.jpg",
             ...     save_path="downloaded_image.jpg"
             ... )
+            >>> path.exists()
+            True
         """
         try:
             # Build full URL
@@ -612,16 +614,20 @@ class SyncClient(BaseClient):
                 if not response.is_success:
                     self._handle_error_response(response)
 
-                # Read content
-                content = b"".join(response.iter_bytes())
-
-                # Save to file if path provided
                 if save_path:
+                    # Stream directly to disk for memory efficiency
                     path = Path(save_path)
-                    path.write_bytes(content)
-                    logger.info(f"Downloaded {len(content)} bytes to {save_path}")
-
-                return content
+                    total_bytes = 0
+                    with open(path, "wb") as f:
+                        for chunk in response.iter_bytes():
+                            f.write(chunk)
+                            total_bytes += len(chunk)
+                    logger.info(f"Downloaded {total_bytes} bytes to {save_path}")
+                    # Return path instead of reading back to avoid memory overhead
+                    return path
+                else:
+                    # Buffer in memory (original behavior for in-memory use)
+                    return b"".join(response.iter_bytes())
 
         except StrapiError:
             raise  # Preserve specific error types (NotFoundError, etc.)
@@ -741,6 +747,11 @@ class SyncClient(BaseClient):
         import json as json_module
 
         try:
+            # Ensure API version is detected before choosing endpoint
+            # When api_version="auto" and no prior API call, _api_version is None
+            if self._api_version is None:
+                self.get_media(media_id)  # Triggers version detection
+
             # Build update payload
             file_info: dict[str, Any] = {}
             if alternative_text is not None:

strapi_kit/export/__init__.py

@@ -6,5 +6,7 @@ entities, and media files in a portable format.
 
 from strapi_kit.export.exporter import StrapiExporter
 from strapi_kit.export.importer import StrapiImporter
+from strapi_kit.export.jsonl_reader import JSONLImportReader
+from strapi_kit.export.jsonl_writer import JSONLExportWriter
 
-__all__ = ["StrapiExporter", "StrapiImporter"]
+__all__ = ["JSONLExportWriter", "JSONLImportReader", "StrapiExporter", "StrapiImporter"]