strapi-kit 0.0.1__py3-none-any.whl

strapi_kit/__init__.py

@@ -0,0 +1,97 @@
+"""strapi-kit: A modern Python client for Strapi CMS.
+
+This package provides a comprehensive interface for interacting with
+Strapi v4 and v5 APIs, including:
+- Synchronous and asynchronous clients
+- Full CRUD operations
+- Import/export functionality
+- Type-safe data models with Pydantic
+- Automatic retry and rate limiting
+"""
+
+from .__version__ import __version__
+from .client import AsyncClient, SyncClient
+from .config_provider import (
+    ConfigFactory,
+    ConfigurationError,
+    create_config,
+    load_config,
+)
+from .exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    FormatError,
+    ImportExportError,
+    MediaError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    RelationError,
+    ServerError,
+    StrapiError,
+    ValidationError,
+)
+from .export import StrapiExporter, StrapiImporter
+from .models import (
+    BulkOperationFailure,
+    BulkOperationResult,
+    RetryConfig,
+    StrapiConfig,
+)
+from .operations.streaming import stream_entities, stream_entities_async
+from .parsers import VersionDetectingParser
+from .protocols import (
+    AsyncHTTPClient,
+    AuthProvider,
+    ConfigProvider,
+    HTTPClient,
+    ResponseParser,
+    SchemaProvider,
+)
+
+__all__ = [
+    "__version__",
+    # Clients
+    "SyncClient",
+    "AsyncClient",
+    # Configuration
+    "StrapiConfig",
+    "RetryConfig",
+    "ConfigFactory",
+    "load_config",
+    "create_config",
+    "ConfigurationError",
+    # Bulk Operations
+    "BulkOperationResult",
+    "BulkOperationFailure",
+    # Streaming
+    "stream_entities",
+    "stream_entities_async",
+    # Export/Import
+    "StrapiExporter",
+    "StrapiImporter",
+    # Protocols (for dependency injection)
+    "AuthProvider",
+    "ConfigProvider",
+    "HTTPClient",
+    "AsyncHTTPClient",
+    "ResponseParser",
+    "SchemaProvider",
+    # Parsers
+    "VersionDetectingParser",
+    # Exceptions
+    "StrapiError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "NetworkError",
+    "RateLimitError",
+    "ServerError",
+    "ImportExportError",
+    "FormatError",
+    "RelationError",
+    "MediaError",
+]

strapi_kit/__version__.py

@@ -0,0 +1,15 @@
+"""Version information for strapi-kit.
+
+This file is automatically updated by hatch-vcs during build.
+For development installs, it falls back to a placeholder version.
+"""
+
+try:
+    # Try to import version from hatch-vcs generated file
+    from strapi_kit._version import __version__
+except ImportError:
+    # Development mode - not built with hatch-vcs yet
+    # This happens when installed with pip install -e .
+    __version__ = "0.0.0.dev0+local"
+
+__all__ = ["__version__"]

strapi_kit/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

strapi_kit/auth/__init__.py

@@ -0,0 +1,7 @@
+"""Authentication modules for strapi-kit."""
+
+from .api_token import APITokenAuth
+
+__all__ = [
+    "APITokenAuth",
+]

strapi_kit/auth/api_token.py

@@ -0,0 +1,48 @@
+"""API Token authentication for Strapi.
+
+This module provides bearer token authentication for Strapi API requests.
+"""
+
+
+class APITokenAuth:
+    """API Token authentication handler.
+
+    Manages bearer token authentication for Strapi API requests.
+    Tokens can be created in Strapi admin panel under Settings > API Tokens.
+
+    Example:
+        ```python
+        auth = APITokenAuth("your-api-token")
+        headers = auth.get_headers()
+        # {"Authorization": "Bearer your-api-token"}
+        ```
+    """
+
+    def __init__(self, token: str) -> None:
+        """Initialize API token authentication.
+
+        Args:
+            token: The API token from Strapi
+        """
+        self.token = token
+
+    def get_headers(self) -> dict[str, str]:
+        """Get authentication headers for requests.
+
+        Returns:
+            Dictionary with Authorization header
+        """
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def validate_token(self) -> bool:
+        """Validate that the token is not empty.
+
+        Returns:
+            True if token is valid (non-empty), False otherwise
+        """
+        return bool(self.token and self.token.strip())
+
+    def __repr__(self) -> str:
+        """Return string representation (token masked for security)."""
+        masked = f"{self.token[:4]}...{self.token[-4:]}" if len(self.token) > 8 else "****"
+        return f"APITokenAuth(token={masked})"

strapi_kit/cache/__init__.py

@@ -0,0 +1,5 @@
+"""Cache implementations for strapi-kit."""
+
+from .schema_cache import InMemorySchemaCache
+
+__all__ = ["InMemorySchemaCache"]

strapi_kit/cache/schema_cache.py

@@ -0,0 +1,211 @@
+"""In-memory schema cache implementation."""
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from ..exceptions import StrapiError
+from ..models.schema import ContentTypeSchema, FieldSchema, FieldType, RelationType
+
+if TYPE_CHECKING:
+    from ..client.sync_client import SyncClient
+
+logger = logging.getLogger(__name__)
+
+
+class InMemorySchemaCache:
+    """In-memory cache for content type schemas.
+
+    Temporary cache for export/import operations only.
+    NOT persistent across process restarts.
+
+    This cache stores content type schemas to enable proper relation
+    resolution during import. Schemas are fetched lazily on first access
+    and cached for subsequent lookups.
+
+    Example:
+        >>> cache = InMemorySchemaCache(client)
+        >>> schema = cache.get_schema("api::article.article")
+        >>> target = schema.get_field_target("author")  # Returns "api::author.author"
+    """
+
+    def __init__(self, client: "SyncClient") -> None:
+        """Initialize the schema cache.
+
+        Args:
+            client: Strapi client for fetching schemas
+        """
+        self.client = client
+        self._cache: dict[str, ContentTypeSchema] = {}
+        self._fetch_count = 0
+
+    def get_schema(self, content_type: str) -> ContentTypeSchema:
+        """Get schema (cached or fetch from API).
+
+        Lazy loading: only fetches on first access.
+
+        Args:
+            content_type: Content type UID (e.g., "api::article.article")
+
+        Returns:
+            Content type schema
+
+        Raises:
+            StrapiError: If schema fetch fails
+        """
+        # Check cache first (O(1) lookup)
+        if content_type in self._cache:
+            logger.debug(f"Schema cache hit: {content_type}")
+            return self._cache[content_type]
+
+        # Cache miss - fetch from API
+        logger.debug(f"Schema cache miss: {content_type}")
+        schema = self._fetch_schema(content_type)
+        self._cache[content_type] = schema
+        self._fetch_count += 1
+        return schema
+
+    def cache_schema(self, content_type: str, schema: ContentTypeSchema) -> None:
+        """Manually cache a schema.
+
+        Args:
+            content_type: Content type UID
+            schema: Schema to cache
+        """
+        self._cache[content_type] = schema
+        logger.debug(f"Manually cached schema: {content_type}")
+
+    def has_schema(self, content_type: str) -> bool:
+        """Check if schema is cached.
+
+        Args:
+            content_type: Content type UID
+
+        Returns:
+            True if schema is cached, False otherwise
+        """
+        return content_type in self._cache
+
+    def clear_cache(self) -> None:
+        """Clear all cached schemas."""
+        self._cache.clear()
+        self._fetch_count = 0
+        logger.debug("Schema cache cleared")
+
+    def _fetch_schema(self, content_type: str) -> ContentTypeSchema:
+        """Fetch schema from Strapi API.
+
+        Endpoint: GET /api/content-type-builder/content-types/{uid}
+
+        Args:
+            content_type: Content type UID
+
+        Returns:
+            Parsed content type schema
+
+        Raises:
+            StrapiError: If fetch fails
+        """
+        endpoint = f"content-type-builder/content-types/{content_type}"
+
+        try:
+            response = self.client.get(endpoint)
+        except Exception as e:
+            raise StrapiError(
+                f"Failed to fetch schema for {content_type}",
+                details={"content_type": content_type, "error": str(e)},
+            ) from e
+
+        schema_data = response.get("data")
+        if not schema_data:
+            raise StrapiError(
+                f"Invalid schema response for {content_type}",
+                details={"response": response},
+            )
+
+        return self._parse_schema_response(content_type, schema_data)
+
+    def _parse_schema_response(self, uid: str, schema_data: dict[str, Any]) -> ContentTypeSchema:
+        """Parse Strapi schema response.
+
+        Args:
+            uid: Content type UID
+            schema_data: Schema data from API response
+
+        Returns:
+            Parsed content type schema
+        """
+        info = schema_data.get("info", {})
+        attributes = schema_data.get("attributes", {})
+
+        fields: dict[str, FieldSchema] = {}
+        for field_name, field_data in attributes.items():
+            try:
+                fields[field_name] = self._parse_field_schema(field_data)
+            except Exception as e:
+                logger.warning(f"Failed to parse field {field_name}: {e}")
+
+        return ContentTypeSchema(
+            uid=uid,
+            display_name=info.get("displayName", uid),
+            kind=schema_data.get("kind", "collectionType"),
+            singular_name=info.get("singularName"),
+            plural_name=info.get("pluralName"),
+            fields=fields,
+        )
+
+    def _parse_field_schema(self, field_data: dict[str, Any]) -> FieldSchema:
+        """Parse a single field schema.
+
+        Args:
+            field_data: Field data from API response
+
+        Returns:
+            Parsed field schema
+        """
+        field_type_str = field_data.get("type", "string")
+
+        # Try to match to FieldType enum, fallback to STRING
+        try:
+            field_type = FieldType(field_type_str)
+        except ValueError:
+            logger.warning(f"Unknown field type: {field_type_str}, using STRING")
+            field_type = FieldType.STRING
+
+        schema = FieldSchema(
+            type=field_type,
+            required=field_data.get("required", False),
+            unique=field_data.get("unique", False),
+        )
+
+        # Relation-specific
+        if field_type == FieldType.RELATION:
+            relation_str = field_data.get("relation")
+            if relation_str:
+                try:
+                    schema.relation = RelationType(relation_str)
+                except ValueError:
+                    logger.warning(f"Unknown relation type: {relation_str}")
+
+            schema.target = field_data.get("target")
+            schema.mapped_by = field_data.get("mappedBy")
+            schema.inversed_by = field_data.get("inversedBy")
+
+        return schema
+
+    @property
+    def cache_size(self) -> int:
+        """Get number of cached schemas.
+
+        Returns:
+            Number of schemas in cache
+        """
+        return len(self._cache)
+
+    @property
+    def fetch_count(self) -> int:
+        """Get number of schemas fetched from API.
+
+        Returns:
+            Number of API fetches performed
+        """
+        return self._fetch_count

strapi_kit/client/__init__.py

@@ -0,0 +1,11 @@
+"""HTTP client modules for strapi-kit."""
+
+from .async_client import AsyncClient
+from .base import BaseClient
+from .sync_client import SyncClient
+
+__all__ = [
+    "BaseClient",
+    "SyncClient",
+    "AsyncClient",
+]