strapi-kit 0.0.1__py3-none-any.whl

strapi_kit/models/response/component.py

@@ -0,0 +1,67 @@
+"""Component and dynamic zone models for Strapi responses.
+
+Models for handling components and dynamic zones which have special structure.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Component(BaseModel):
+    """Strapi component.
+
+    Components are reusable data structures that can be used across content types.
+    They have a special '__component' field identifying their type.
+
+    Attributes:
+        id: Component instance ID
+        document_id: Document ID (v5 only)
+        component_type: Component type identifier (from __component field)
+        Additional fields are allowed based on component schema.
+
+    Examples:
+        >>> component = Component(
+        ...     id=1,
+        ...     component_type="shared.seo",
+        ...     title="SEO Title",
+        ...     description="SEO Description"
+        ... )
+        >>> component.component_type
+        'shared.seo'
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: int | None = Field(None, description="Component instance ID")
+    document_id: str | None = Field(None, alias="documentId", description="Document ID (v5)")
+    component_type: str = Field(..., alias="__component", description="Component type")
+
+
+class DynamicZoneBlock(BaseModel):
+    """Dynamic zone block.
+
+    Dynamic zones are arrays of components of different types.
+    Each block has a '__component' field identifying its type.
+
+    Attributes:
+        id: Block instance ID
+        document_id: Document ID (v5 only)
+        component_type: Block type identifier (from __component field)
+        Additional fields are allowed based on block schema.
+
+    Examples:
+        >>> block = DynamicZoneBlock(
+        ...     id=1,
+        ...     component_type="content.rich-text",
+        ...     body="<p>Rich text content</p>"
+        ... )
+        >>> block.component_type
+        'content.rich-text'
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: int | None = Field(None, description="Block instance ID")
+    document_id: str | None = Field(None, alias="documentId", description="Document ID (v5)")
+    component_type: str = Field(..., alias="__component", description="Block type")

strapi_kit/models/response/media.py

@@ -0,0 +1,91 @@
+"""Media file models for Strapi file uploads.
+
+Models for parsing media/file fields with multiple formats.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MediaFormat(BaseModel):
+    """A specific format/size of a media file.
+
+    Strapi generates multiple formats for images (thumbnail, small, medium, large).
+
+    Attributes:
+        name: Format name (e.g., "thumbnail", "small", "medium", "large")
+        hash: File hash
+        ext: File extension
+        mime: MIME type
+        width: Image width in pixels
+        height: Image height in pixels
+        size: File size in KB
+        path: File path (if applicable)
+        url: URL to access the file
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str = Field(..., description="Format name")
+    hash: str = Field(..., description="File hash")
+    ext: str = Field(..., description="File extension")
+    mime: str = Field(..., description="MIME type")
+    width: int | None = Field(None, description="Image width")
+    height: int | None = Field(None, description="Image height")
+    size: float = Field(..., description="File size in KB")
+    path: str | None = Field(None, description="File path")
+    url: str = Field(..., description="File URL")
+
+
+class MediaFile(BaseModel):
+    """Media file entity from Strapi.
+
+    Represents uploaded files with multiple format variations.
+
+    Attributes:
+        id: Numeric file ID
+        document_id: Document ID (v5 only)
+        name: Original filename
+        alternative_text: Alt text for accessibility
+        caption: Image caption
+        width: Original width
+        height: Original height
+        formats: Available formats (thumbnail, small, medium, large)
+        hash: File hash
+        ext: File extension
+        mime: MIME type
+        size: File size in KB
+        url: URL to original file
+        preview_url: Preview URL
+        provider: Storage provider (local, s3, etc.)
+        provider_metadata: Provider-specific metadata
+        created_at: Upload timestamp
+        updated_at: Last update timestamp
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: int = Field(..., description="Numeric file ID")
+    document_id: str | None = Field(None, alias="documentId", description="Document ID (v5)")
+    name: str = Field(..., description="Original filename")
+    alternative_text: str | None = Field(None, alias="alternativeText")
+    caption: str | None = Field(None, description="Image caption")
+    width: int | None = Field(None, description="Image width")
+    height: int | None = Field(None, description="Image height")
+    formats: dict[str, MediaFormat] | None = Field(None, description="Available formats")
+    hash: str = Field(..., description="File hash")
+    ext: str = Field(..., description="File extension")
+    mime: str = Field(..., description="MIME type")
+    size: float = Field(..., description="File size in KB")
+    url: str = Field(..., description="File URL")
+    preview_url: str | None = Field(None, alias="previewUrl")
+    provider: str = Field(..., description="Storage provider")
+    provider_metadata: dict[str, Any] | None = Field(
+        None, alias="providerMetadata", description="Provider metadata"
+    )
+    created_at: datetime | None = Field(None, alias="createdAt")
+    updated_at: datetime | None = Field(None, alias="updatedAt")

strapi_kit/models/response/meta.py

@@ -0,0 +1,44 @@
+"""Metadata models for Strapi API responses.
+
+Contains pagination metadata and response metadata structures.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PaginationMeta(BaseModel):
+    """Pagination metadata from Strapi responses.
+
+    Attributes:
+        page: Current page number (1-indexed)
+        page_size: Number of items per page
+        page_count: Total number of pages
+        total: Total number of items across all pages
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    page: int | None = Field(None, description="Current page number")
+    page_size: int | None = Field(None, alias="pageSize", description="Items per page")
+    page_count: int | None = Field(None, alias="pageCount", description="Total pages")
+    total: int | None = Field(None, description="Total items")
+
+
+class ResponseMeta(BaseModel):
+    """Response metadata from Strapi.
+
+    Contains pagination information and other metadata like available locales.
+
+    Attributes:
+        pagination: Pagination metadata (if pagination was used)
+        available_locales: Available locale codes (if i18n is enabled)
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    pagination: PaginationMeta | None = Field(None, description="Pagination metadata")
+    available_locales: list[str] | None = Field(
+        None, alias="availableLocales", description="Available locales"
+    )

strapi_kit/models/response/normalized.py

@@ -0,0 +1,168 @@
+"""Normalized response models providing version-agnostic interface.
+
+The normalization layer abstracts the differences between Strapi v4 and v5,
+providing a consistent interface for working with entities regardless of version.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from strapi_kit.models.response.base import StrapiCollectionResponse, StrapiSingleResponse
+from strapi_kit.models.response.v4 import V4Entity
+from strapi_kit.models.response.v5 import V5Entity
+
+
+class NormalizedEntity(BaseModel):
+    """Version-agnostic entity representation.
+
+    Provides a consistent interface abstracting v4/v5 differences:
+    - V4: nested attributes → flattened in NormalizedEntity
+    - V5: already flat → preserved in NormalizedEntity
+    - Document ID: v5 only, None for v4
+    - Timestamps: extracted to top level
+    - Custom fields: grouped in 'attributes' dict
+
+    Attributes:
+        id: Numeric entity ID (present in both v4 and v5)
+        document_id: String document ID (v5 only, None for v4)
+        created_at: Creation timestamp
+        updated_at: Last update timestamp
+        published_at: Publication timestamp
+        locale: Locale code
+        attributes: All custom fields (non-timestamp, non-system fields)
+
+    Examples:
+        >>> # From v4
+        >>> v4_entity = V4Entity(
+        ...     id=1,
+        ...     attributes=V4Attributes(
+        ...         createdAt=datetime.now(),
+        ...         title="Test",
+        ...         content="Body"
+        ...     )
+        ... )
+        >>> normalized = NormalizedEntity.from_v4(v4_entity)
+        >>> normalized.attributes["title"]
+        'Test'
+        >>> normalized.document_id  # None for v4
+        None
+
+        >>> # From v5
+        >>> v5_entity = V5Entity(
+        ...     id=1,
+        ...     documentId="abc123",
+        ...     createdAt=datetime.now(),
+        ...     title="Test",
+        ...     content="Body"
+        ... )
+        >>> normalized = NormalizedEntity.from_v5(v5_entity)
+        >>> normalized.document_id
+        'abc123'
+        >>> normalized.attributes["title"]
+        'Test'
+    """
+
+    id: int = Field(..., description="Numeric entity ID")
+    document_id: str | None = Field(None, description="Document ID (v5 only)")
+    created_at: datetime | None = Field(None, description="Creation timestamp")
+    updated_at: datetime | None = Field(None, description="Last update timestamp")
+    published_at: datetime | None = Field(None, description="Publication timestamp")
+    locale: str | None = Field(None, description="Locale code")
+    attributes: dict[str, Any] = Field(default_factory=dict, description="All custom entity fields")
+
+    @classmethod
+    def from_v4(cls, entity: V4Entity) -> NormalizedEntity:
+        """Create normalized entity from v4 entity.
+
+        Extracts attributes from the nested 'attributes' object and
+        promotes timestamps to top level.
+
+        Args:
+            entity: V4 entity to normalize
+
+        Returns:
+            Normalized entity with flattened structure
+
+        Examples:
+            >>> v4 = V4Entity(
+            ...     id=1,
+            ...     attributes=V4Attributes(title="Test", content="Body")
+            ... )
+            >>> normalized = NormalizedEntity.from_v4(v4)
+            >>> normalized.id
+            1
+        """
+        # Get all attributes as dict
+        attrs_dict = entity.attributes.model_dump(by_alias=False, exclude_none=False)
+
+        # Extract system fields
+        created_at = attrs_dict.pop("created_at", None)
+        updated_at = attrs_dict.pop("updated_at", None)
+        published_at = attrs_dict.pop("published_at", None)
+        locale = attrs_dict.pop("locale", None)
+
+        # Remaining fields are custom attributes
+        return cls(
+            id=entity.id,
+            document_id=None,  # v4 doesn't have document_id
+            created_at=created_at,
+            updated_at=updated_at,
+            published_at=published_at,
+            locale=locale,
+            attributes=attrs_dict,
+        )
+
+    @classmethod
+    def from_v5(cls, entity: V5Entity) -> NormalizedEntity:
+        """Create normalized entity from v5 entity.
+
+        Extracts timestamps and system fields, grouping remaining fields
+        as custom attributes.
+
+        Args:
+            entity: V5 entity to normalize
+
+        Returns:
+            Normalized entity
+
+        Examples:
+            >>> v5 = V5Entity(
+            ...     id=1,
+            ...     documentId="abc123",
+            ...     title="Test",
+            ...     content="Body"
+            ... )
+            >>> normalized = NormalizedEntity.from_v5(v5)
+            >>> normalized.document_id
+            'abc123'
+        """
+        # Get all fields as dict
+        entity_dict = entity.model_dump(by_alias=False, exclude_none=False)
+
+        # Extract system fields
+        entity_id = entity_dict.pop("id")
+        document_id = entity_dict.pop("document_id")
+        created_at = entity_dict.pop("created_at", None)
+        updated_at = entity_dict.pop("updated_at", None)
+        published_at = entity_dict.pop("published_at", None)
+        locale = entity_dict.pop("locale", None)
+
+        # Remaining fields are custom attributes
+        return cls(
+            id=entity_id,
+            document_id=document_id,
+            created_at=created_at,
+            updated_at=updated_at,
+            published_at=published_at,
+            locale=locale,
+            attributes=entity_dict,
+        )
+
+
+# Type aliases for normalized responses
+NormalizedSingleResponse = StrapiSingleResponse[NormalizedEntity]
+NormalizedCollectionResponse = StrapiCollectionResponse[NormalizedEntity]

strapi_kit/models/response/relation.py

@@ -0,0 +1,48 @@
+"""Relation data models for Strapi responses.
+
+Models for handling relation fields which are wrapped in a 'data' key.
+"""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Generic type for relation data
+T = TypeVar("T")
+
+
+class RelationData(BaseModel, Generic[T]):
+    """Wrapper for relation fields.
+
+    In Strapi, populated relations are wrapped in a 'data' key:
+    - Single relation: {"data": {...}}
+    - Multiple relations: {"data": [{...}, {...}]}
+
+    Attributes:
+        data: The actual relation data (entity or list of entities)
+
+    Examples:
+        >>> # Single relation
+        >>> from strapi_kit.models.response.v5 import V5Entity
+        >>> relation = RelationData[V5Entity](
+        ...     data=V5Entity(id=1, documentId="abc", title="Related")
+        ... )
+        >>> relation.data.title
+        'Related'
+
+        >>> # Multiple relations
+        >>> relation = RelationData[list[V5Entity]](
+        ...     data=[
+        ...         V5Entity(id=1, documentId="abc", title="First"),
+        ...         V5Entity(id=2, documentId="def", title="Second")
+        ...     ]
+        ... )
+        >>> len(relation.data)
+        2
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    data: T | None = Field(None, description="Relation data")

strapi_kit/models/response/v4.py

@@ -0,0 +1,70 @@
+"""Strapi v4 response models.
+
+Models for parsing Strapi v4 API responses with nested attributes structure.
+
+V4 Structure:
+{
+  "data": {
+    "id": 1,
+    "attributes": {
+      "title": "Hello",
+      "createdAt": "2024-01-01T00:00:00.000Z",
+      "updatedAt": "2024-01-01T00:00:00.000Z",
+      "publishedAt": "2024-01-01T00:00:00.000Z",
+      "locale": "en",
+      ...custom fields
+    }
+  }
+}
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from strapi_kit.models.response.base import StrapiCollectionResponse, StrapiSingleResponse
+
+
+class V4Attributes(BaseModel):
+    """Attributes container for v4 entities.
+
+    In v4, all entity data is nested under the 'attributes' key.
+    This includes timestamps, locale, and all custom fields.
+
+    Attributes:
+        created_at: Creation timestamp
+        updated_at: Last update timestamp
+        published_at: Publication timestamp (if draft & publish enabled)
+        locale: Locale code (if i18n enabled)
+        Additional fields are allowed and will be preserved.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    created_at: datetime | None = Field(None, alias="createdAt")
+    updated_at: datetime | None = Field(None, alias="updatedAt")
+    published_at: datetime | None = Field(None, alias="publishedAt")
+    locale: str | None = Field(None, description="Locale code")
+
+
+class V4Entity(BaseModel):
+    """Strapi v4 entity structure.
+
+    V4 entities have a numeric ID and nested attributes.
+
+    Attributes:
+        id: Numeric entity ID
+        attributes: All entity data (timestamps + custom fields)
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    id: int = Field(..., description="Numeric entity ID")
+    attributes: V4Attributes = Field(..., description="Entity attributes")
+
+
+# Type aliases for v4 responses
+V4SingleResponse = StrapiSingleResponse[V4Entity]
+V4CollectionResponse = StrapiCollectionResponse[V4Entity]

strapi_kit/models/response/v5.py

@@ -0,0 +1,57 @@
+"""Strapi v5 response models.
+
+Models for parsing Strapi v5 API responses with flattened structure.
+
+V5 Structure:
+{
+  "data": {
+    "id": 1,
+    "documentId": "abc123",
+    "title": "Hello",
+    "createdAt": "2024-01-01T00:00:00.000Z",
+    "updatedAt": "2024-01-01T00:00:00.000Z",
+    "publishedAt": "2024-01-01T00:00:00.000Z",
+    "locale": "en",
+    ...custom fields
+  }
+}
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from strapi_kit.models.response.base import StrapiCollectionResponse, StrapiSingleResponse
+
+
+class V5Entity(BaseModel):
+    """Strapi v5 entity structure.
+
+    V5 entities have a flattened structure with both numeric ID and document ID.
+    All fields (timestamps, locale, custom) are at the same level.
+
+    Attributes:
+        id: Numeric entity ID (for backward compatibility)
+        document_id: String document ID (new in v5, unique identifier)
+        created_at: Creation timestamp
+        updated_at: Last update timestamp
+        published_at: Publication timestamp (if draft & publish enabled)
+        locale: Locale code (if i18n enabled)
+        Additional fields are allowed and will be preserved.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: int = Field(..., description="Numeric entity ID")
+    document_id: str = Field(..., alias="documentId", description="Document ID (v5)")
+    created_at: datetime | None = Field(None, alias="createdAt")
+    updated_at: datetime | None = Field(None, alias="updatedAt")
+    published_at: datetime | None = Field(None, alias="publishedAt")
+    locale: str | None = Field(None, description="Locale code")
+
+
+# Type aliases for v5 responses
+V5SingleResponse = StrapiSingleResponse[V5Entity]
+V5CollectionResponse = StrapiCollectionResponse[V5Entity]

strapi_kit/models/schema.py

@@ -0,0 +1,93 @@
+"""Content type schema models."""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class FieldType(str, Enum):
+    """Field types in Strapi."""
+
+    STRING = "string"
+    TEXT = "text"
+    RICH_TEXT = "richtext"
+    EMAIL = "email"
+    PASSWORD = "password"  # nosec B105 - This is a field type enum, not a hardcoded password
+    INTEGER = "integer"
+    BIG_INTEGER = "biginteger"
+    FLOAT = "float"
+    DECIMAL = "decimal"
+    DATE = "date"
+    TIME = "time"
+    DATETIME = "datetime"
+    TIMESTAMP = "timestamp"
+    BOOLEAN = "boolean"
+    ENUMERATION = "enumeration"
+    JSON = "json"
+    MEDIA = "media"
+    RELATION = "relation"
+    COMPONENT = "component"
+    DYNAMIC_ZONE = "dynamiczone"
+    UID = "uid"
+
+
+class RelationType(str, Enum):
+    """Relation types in Strapi."""
+
+    ONE_TO_ONE = "oneToOne"
+    ONE_TO_MANY = "oneToMany"
+    MANY_TO_ONE = "manyToOne"
+    MANY_TO_MANY = "manyToMany"
+
+
+class FieldSchema(BaseModel):
+    """Schema for a single field."""
+
+    type: FieldType
+    required: bool = False
+    unique: bool = False
+
+    # Relation-specific
+    relation: RelationType | None = None
+    target: str | None = None  # Target content type UID
+    mapped_by: str | None = None
+    inversed_by: str | None = None
+
+
+class ContentTypeSchema(BaseModel):
+    """Complete schema for a content type."""
+
+    uid: str
+    display_name: str
+    kind: str = "collectionType"
+    singular_name: str | None = Field(None, description="Singular name from Strapi schema")
+    plural_name: str | None = Field(
+        None, description="Plural name from Strapi schema (API endpoint)"
+    )
+    fields: dict[str, FieldSchema] = Field(default_factory=dict)
+
+    def get_field_target(self, field_name: str) -> str | None:
+        """Get target content type for a relation field.
+
+        Args:
+            field_name: Name of the field to check
+
+        Returns:
+            Target content type UID if field is a relation, None otherwise
+        """
+        field = self.fields.get(field_name)
+        if field and field.type == FieldType.RELATION:
+            return field.target
+        return None
+
+    def is_relation_field(self, field_name: str) -> bool:
+        """Check if a field is a relation.
+
+        Args:
+            field_name: Name of the field to check
+
+        Returns:
+            True if field is a relation, False otherwise
+        """
+        field = self.fields.get(field_name)
+        return field is not None and field.type == FieldType.RELATION

strapi_kit/operations/__init__.py

@@ -0,0 +1,16 @@
+"""Operations module for strapi-kit.
+
+This module contains utility functions and helpers for various operations.
+"""
+
+from strapi_kit.operations.media import (
+    build_media_download_url,
+    build_upload_payload,
+    normalize_media_response,
+)
+
+__all__ = [
+    "build_media_download_url",
+    "build_upload_payload",
+    "normalize_media_response",
+]