strapi-kit 0.0.1__py3-none-any.whl

strapi_kit/models/config.py

@@ -0,0 +1,174 @@
+"""Configuration models for strapi-kit.
+
+This module defines the configuration structure using Pydantic for
+type safety and validation with support for environment variables.
+"""
+
+from typing import Literal
+from urllib.parse import urlsplit
+
+from pydantic import Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class RetryConfig(BaseSettings):
+    """Configuration for retry behavior.
+
+    Controls how the client handles failed requests with exponential backoff.
+    """
+
+    model_config = SettingsConfigDict(env_prefix="STRAPI_RETRY_")
+
+    max_attempts: int = Field(
+        default=3,
+        ge=1,
+        le=10,
+        description="Maximum number of retry attempts for failed requests",
+    )
+
+    initial_wait: float = Field(
+        default=1.0,
+        ge=0.1,
+        le=60.0,
+        description="Initial wait time in seconds before first retry",
+    )
+
+    max_wait: float = Field(
+        default=60.0,
+        ge=1.0,
+        le=300.0,
+        description="Maximum wait time in seconds between retries",
+    )
+
+    exponential_base: float = Field(
+        default=2.0,
+        ge=1.1,
+        le=10.0,
+        description="Exponential backoff multiplier",
+    )
+
+    retry_on_status: set[int] = Field(
+        default_factory=lambda: {500, 502, 503, 504},
+        description="HTTP status codes that should trigger a retry",
+    )
+
+
+class StrapiConfig(BaseSettings):
+    """Main configuration for the Strapi client.
+
+    This configuration can be loaded from environment variables with
+    the STRAPI_ prefix or passed directly as arguments.
+
+    Example:
+        ```python
+        # From environment variables
+        config = StrapiConfig()
+
+        # From arguments
+        config = StrapiConfig(
+            base_url="http://localhost:1337",
+            api_token="your-token-here"
+        )
+        ```
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="STRAPI_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+    )
+
+    base_url: str = Field(
+        ...,
+        description="Base URL of the Strapi instance (e.g., http://localhost:1337)",
+    )
+
+    api_token: SecretStr = Field(
+        ...,
+        description="API token for authentication",
+    )
+
+    api_version: Literal["v4", "v5", "auto"] = Field(
+        default="auto",
+        description="Strapi API version to use (v4, v5, or auto-detect)",
+    )
+
+    timeout: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=300.0,
+        description="Request timeout in seconds",
+    )
+
+    max_connections: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Maximum number of concurrent connections",
+    )
+
+    retry: RetryConfig = Field(
+        default_factory=RetryConfig,
+        description="Retry configuration",
+    )
+
+    rate_limit_per_second: float | None = Field(
+        default=None,
+        ge=0.1,
+        description="Maximum requests per second (None for unlimited)",
+    )
+
+    verify_ssl: bool = Field(
+        default=True,
+        description="Whether to verify SSL certificates",
+    )
+
+    @field_validator("base_url", mode="before")
+    @classmethod
+    def validate_base_url(cls, v: str) -> str:
+        """Validate URL format and ensure no trailing slash.
+
+        Args:
+            v: URL string to validate
+
+        Returns:
+            Validated URL without trailing slash
+
+        Raises:
+            ValueError: If URL is not a valid HTTP(S) URL
+        """
+        if not isinstance(v, str):
+            raise ValueError("base_url must be a string")
+
+        url_str = v.strip().rstrip("/")
+
+        # Validate URL format
+        if not url_str:
+            raise ValueError("base_url cannot be empty")
+
+        if not url_str.startswith(("http://", "https://")):
+            raise ValueError(f"base_url must start with http:// or https://, got: {url_str[:50]}")
+
+        # Use urlsplit for robust URL validation
+        parsed = urlsplit(url_str)
+        if not parsed.scheme or not parsed.netloc:
+            raise ValueError(f"Invalid URL format (missing host): {url_str[:50]}")
+
+        return url_str
+
+    def get_api_token(self) -> str:
+        """Get the API token as a plain string.
+
+        Returns:
+            The API token value
+        """
+        return self.api_token.get_secret_value()
+
+    def get_base_url(self) -> str:
+        """Get the base URL as a plain string.
+
+        Returns:
+            The base URL value
+        """
+        return self.base_url

strapi_kit/models/enums.py

@@ -0,0 +1,97 @@
+"""Enumerations for Strapi API parameters and types.
+
+This module defines core enums used throughout the models package:
+- FilterOperator: 24 operators for query filtering
+- SortDirection: Ascending/descending sort
+- PublicationState: Draft, published, preview content states
+"""
+
+from enum import Enum
+from typing import Literal
+
+# Type aliases for common Strapi types
+StrapiVersion = Literal["v4", "v5", "auto"]
+LocaleCode = str  # ISO 639-1 language codes (e.g., "en", "fr", "de")
+
+
+class FilterOperator(str, Enum):
+    """Filter operators supported by Strapi REST API.
+
+    Strapi supports 24 filter operators for querying content.
+    All operators work with both v4 and v5 APIs.
+
+    Examples:
+        >>> FilterOperator.EQ.value
+        '$eq'
+        >>> FilterOperator.CONTAINS.value
+        '$contains'
+    """
+
+    # Equality operators
+    EQ = "$eq"  # Equal
+    EQI = "$eqi"  # Equal (case-insensitive)
+    NE = "$ne"  # Not equal
+    NEI = "$nei"  # Not equal (case-insensitive)
+
+    # Comparison operators
+    LT = "$lt"  # Less than
+    LTE = "$lte"  # Less than or equal
+    GT = "$gt"  # Greater than
+    GTE = "$gte"  # Greater than or equal
+
+    # String matching operators
+    CONTAINS = "$contains"  # Contains substring
+    NOT_CONTAINS = "$notContains"  # Does not contain substring
+    CONTAINSI = "$containsi"  # Contains substring (case-insensitive)
+    NOT_CONTAINSI = "$notContainsi"  # Does not contain substring (case-insensitive)
+    STARTS_WITH = "$startsWith"  # Starts with string
+    STARTS_WITHI = "$startsWithi"  # Starts with string (case-insensitive)
+    ENDS_WITH = "$endsWith"  # Ends with string
+    ENDS_WITHI = "$endsWithi"  # Ends with string (case-insensitive)
+
+    # Array operators
+    IN = "$in"  # Value is in array
+    NOT_IN = "$notIn"  # Value is not in array
+
+    # Null operators
+    NULL = "$null"  # Value is null
+    NOT_NULL = "$notNull"  # Value is not null
+
+    # Date/time range operators
+    BETWEEN = "$between"  # Value is between two values (inclusive)
+
+    # Logical operators (used at filter group level)
+    AND = "$and"  # Logical AND
+    OR = "$or"  # Logical OR
+    NOT = "$not"  # Logical NOT
+
+
+class SortDirection(str, Enum):
+    """Sort direction for query results.
+
+    Examples:
+        >>> SortDirection.ASC.value
+        'asc'
+        >>> SortDirection.DESC.value
+        'desc'
+    """
+
+    ASC = "asc"  # Ascending order (A-Z, 0-9, oldest-newest)
+    DESC = "desc"  # Descending order (Z-A, 9-0, newest-oldest)
+
+
+class PublicationState(str, Enum):
+    """Content publication state filter.
+
+    Only applicable to content types with draft & publish enabled.
+    Used to filter between draft and published versions.
+
+    Examples:
+        >>> PublicationState.LIVE.value
+        'live'
+        >>> PublicationState.PREVIEW.value
+        'preview'
+    """
+
+    LIVE = "live"  # Only published content
+    PREVIEW = "preview"  # Both draft and published content

strapi_kit/models/export_format.py

@@ -0,0 +1,166 @@
+"""Models for export file format.
+
+Defines the structure of exported Strapi data for portability
+and version compatibility.
+"""
+
+from datetime import UTC, datetime
+from pathlib import PureWindowsPath
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from .schema import ContentTypeSchema
+
+
+class ExportMetadata(BaseModel):
+    """Metadata about the export.
+
+    Attributes:
+        version: Export format version (semver)
+        strapi_version: Strapi API version (v4 or v5)
+        exported_at: ISO timestamp of export
+        source_url: Base URL of source Strapi instance
+        content_types: List of exported content type UIDs
+        total_entities: Total number of entities exported
+        total_media: Total number of media files exported
+    """
+
+    version: str = Field(
+        default="1.0.0",
+        description="Export format version (semver)",
+    )
+    strapi_version: str = Field(
+        ...,
+        description="Strapi API version (v4 or v5)",
+    )
+    exported_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="ISO timestamp of export",
+    )
+    source_url: str = Field(
+        ...,
+        description="Base URL of source Strapi instance",
+    )
+    content_types: list[str] = Field(
+        default_factory=list,
+        description="List of exported content type UIDs",
+    )
+    total_entities: int = Field(
+        default=0,
+        description="Total number of entities exported",
+    )
+    total_media: int = Field(
+        default=0,
+        description="Total number of media files exported",
+    )
+    schemas: dict[str, ContentTypeSchema] = Field(
+        default_factory=dict,
+        description="Content type schemas (for relation resolution)",
+    )
+
+
+class ExportedEntity(BaseModel):
+    """A single exported entity with metadata.
+
+    Attributes:
+        id: Original entity ID
+        document_id: Document ID (v5 only)
+        content_type: Content type UID
+        data: Entity data (attributes)
+        relations: Relation field mapping
+    """
+
+    id: int = Field(..., description="Original entity ID")
+    document_id: str | None = Field(None, description="Document ID (v5 only)")
+    content_type: str = Field(..., description="Content type UID")
+    data: dict[str, Any] = Field(..., description="Entity data (attributes)")
+    relations: dict[str, list[int | str]] = Field(
+        default_factory=dict,
+        description="Relation field mapping (field -> [ids])",
+    )
+
+
+class ExportedMediaFile(BaseModel):
+    """A media file reference in the export.
+
+    Attributes:
+        id: Original media file ID
+        url: Original URL (may be relative or absolute)
+        name: File name
+        mime: MIME type
+        size: File size in bytes
+        hash: File hash (for deduplication)
+        local_path: Path in export archive (relative)
+    """
+
+    id: int = Field(..., description="Original media file ID")
+    url: str = Field(..., description="Original URL")
+    name: str = Field(..., description="File name")
+    mime: str = Field(..., description="MIME type")
+    size: int = Field(..., description="File size in bytes")
+    hash: str = Field(..., description="File hash")
+    local_path: str = Field(..., description="Path in export archive (relative)")
+
+    @field_validator("local_path")
+    @classmethod
+    def validate_local_path(cls, v: str) -> str:
+        """Validate local_path doesn't contain path traversal sequences.
+
+        Prevents malicious exports from reading arbitrary files via
+        path traversal attacks (e.g., "../../../etc/passwd").
+
+        Args:
+            v: The local_path value to validate
+
+        Returns:
+            The validated path
+
+        Raises:
+            ValueError: If path contains traversal sequences or is absolute
+        """
+        if ".." in v or v.startswith("/") or v.startswith("\\"):
+            raise ValueError("local_path must be relative without path traversal")
+        # Block Windows drive-letter absolute paths (e.g., C:\, D:/)
+        if PureWindowsPath(v).is_absolute():
+            raise ValueError("local_path must be relative without path traversal")
+        return v
+
+
+class ExportData(BaseModel):
+    """Complete export data structure.
+
+    This is the root model for exported data, containing metadata,
+    entities, and media references.
+
+    Attributes:
+        metadata: Export metadata
+        entities: Exported entities grouped by content type
+        media: Media file references
+    """
+
+    metadata: ExportMetadata = Field(..., description="Export metadata")
+    entities: dict[str, list[ExportedEntity]] = Field(
+        default_factory=dict,
+        description="Entities grouped by content type UID",
+    )
+    media: list[ExportedMediaFile] = Field(
+        default_factory=list,
+        description="Media file references",
+    )
+
+    def get_entity_count(self) -> int:
+        """Get total number of exported entities.
+
+        Returns:
+            Total entity count across all content types
+        """
+        return sum(len(entities) for entities in self.entities.values())
+
+    def get_media_count(self) -> int:
+        """Get total number of exported media files.
+
+        Returns:
+            Total media file count
+        """
+        return len(self.media)

strapi_kit/models/import_options.py

@@ -0,0 +1,142 @@
+"""Models for import configuration and options.
+
+Defines how imported data should be processed and validated.
+"""
+
+from collections.abc import Callable
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class ConflictResolution(str, Enum):
+    """Strategy for handling conflicts during import.
+
+    Attributes:
+        SKIP: Skip entities that already exist
+        UPDATE: Update existing entities with imported data
+        FAIL: Fail import if conflicts are detected
+    """
+
+    SKIP = "skip"
+    UPDATE = "update"
+    FAIL = "fail"
+
+
+class ImportOptions(BaseModel):
+    """Configuration for import operations.
+
+    Attributes:
+        dry_run: Validate without actually importing
+        conflict_resolution: How to handle existing entities
+        import_media: Whether to import media files
+        overwrite_media: Overwrite existing media files
+        content_types: Specific content types to import (None = all)
+        skip_relations: Skip importing relations (for initial pass)
+        validate_relations: Validate relation targets exist
+        batch_size: Batch size for bulk operations
+        progress_callback: Optional progress callback(current, total, message)
+    """
+
+    dry_run: bool = Field(
+        default=False,
+        description="Validate without actually importing",
+    )
+    conflict_resolution: ConflictResolution = Field(
+        default=ConflictResolution.SKIP,
+        description="How to handle existing entities",
+    )
+    import_media: bool = Field(
+        default=True,
+        description="Whether to import media files",
+    )
+    overwrite_media: bool = Field(
+        default=False,
+        description="Overwrite existing media files",
+    )
+    content_types: list[str] | None = Field(
+        default=None,
+        description="Specific content types to import (None = all)",
+    )
+    skip_relations: bool = Field(
+        default=False,
+        description="Skip importing relations (for initial pass)",
+    )
+    validate_relations: bool = Field(
+        default=True,
+        description="Validate relation targets exist",
+    )
+    batch_size: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Batch size for bulk operations",
+    )
+    progress_callback: Callable[[int, int, str], None] | None = Field(
+        default=None,
+        description="Optional progress callback(current, total, message)",
+    )
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class ImportResult(BaseModel):
+    """Result of an import operation.
+
+    Attributes:
+        success: Whether import succeeded
+        dry_run: Whether this was a dry run
+        entities_imported: Number of entities imported
+        entities_skipped: Number of entities skipped
+        entities_updated: Number of entities updated
+        entities_failed: Number of entities that failed
+        media_imported: Number of media files imported
+        media_skipped: Number of media files skipped
+        errors: List of error messages
+        warnings: List of warning messages
+        id_mapping: Mapping of old IDs to new IDs (content_type -> {old_id: new_id})
+    """
+
+    success: bool = Field(..., description="Whether import succeeded")
+    dry_run: bool = Field(..., description="Whether this was a dry run")
+    entities_imported: int = Field(default=0, description="Entities imported")
+    entities_skipped: int = Field(default=0, description="Entities skipped")
+    entities_updated: int = Field(default=0, description="Entities updated")
+    entities_failed: int = Field(default=0, description="Entities failed")
+    media_imported: int = Field(default=0, description="Media files imported")
+    media_skipped: int = Field(default=0, description="Media files skipped")
+    errors: list[str] = Field(default_factory=list, description="Error messages")
+    warnings: list[str] = Field(default_factory=list, description="Warning messages")
+    id_mapping: dict[str, dict[int, int]] = Field(
+        default_factory=dict,
+        description="Mapping of old IDs to new IDs per content type",
+    )
+
+    def add_error(self, error: str) -> None:
+        """Add an error message.
+
+        Args:
+            error: Error message to add
+        """
+        self.errors.append(error)
+
+    def add_warning(self, warning: str) -> None:
+        """Add a warning message.
+
+        Args:
+            warning: Warning message to add
+        """
+        self.warnings.append(warning)
+
+    def get_total_processed(self) -> int:
+        """Get total number of entities processed.
+
+        Returns:
+            Sum of imported, skipped, updated, and failed
+        """
+        return (
+            self.entities_imported
+            + self.entities_skipped
+            + self.entities_updated
+            + self.entities_failed
+        )

strapi_kit/models/request/__init__.py

@@ -0,0 +1 @@
+"""Request models for building Strapi API queries."""

strapi_kit/models/request/fields.py

@@ -0,0 +1,65 @@
+"""Field selection for Strapi API queries.
+
+Allows selecting specific fields to return in the response, reducing
+payload size and improving performance.
+
+Examples:
+    Select specific fields:
+        >>> fields = FieldSelection(fields=["title", "description", "publishedAt"])
+        >>> fields.to_query_dict()
+        {'fields': ['title', 'description', 'publishedAt']}
+
+    Select all fields (default):
+        >>> fields = FieldSelection()  # Returns all fields
+        >>> fields.to_query_dict()
+        {}
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FieldSelection(BaseModel):
+    """Field selection configuration.
+
+    Specifies which fields to include in the response. If no fields are
+    specified, all fields are returned by default.
+
+    Attributes:
+        fields: List of field names to return (empty = all fields)
+    """
+
+    fields: list[str] = Field(
+        default_factory=list,
+        description="List of field names to include in response (empty = all)",
+    )
+
+    def to_query_dict(self) -> dict[str, Any]:
+        """Convert to query parameters dictionary.
+
+        Returns:
+            Dictionary with fields parameter, or empty if no fields specified
+
+        Examples:
+            >>> FieldSelection(fields=["title", "description"]).to_query_dict()
+            {'fields': ['title', 'description']}
+
+            >>> FieldSelection().to_query_dict()
+            {}
+        """
+        if not self.fields:
+            return {}
+        return {"fields": self.fields}
+
+    def to_query_list(self) -> list[str]:
+        """Get list of field names.
+
+        Returns:
+            List of field names
+
+        Examples:
+            >>> FieldSelection(fields=["title", "description"]).to_query_list()
+            ['title', 'description']
+        """
+        return self.fields