strapi-kit 0.0.1__py3-none-any.whl

strapi_kit/models/request/pagination.py

@@ -0,0 +1,168 @@
+"""Pagination configuration for Strapi API queries.
+
+Strapi supports two pagination strategies:
+1. Page-based: Use page number and page size
+2. Offset-based: Use start offset and limit
+
+IMPORTANT: Cannot mix pagination strategies in the same query.
+
+Examples:
+    Page-based pagination:
+        >>> pagination = PagePagination(page=1, page_size=25)
+        >>> pagination.to_query_dict()
+        {'pagination[page]': 1, 'pagination[pageSize]': 25, 'pagination[withCount]': True}
+
+    Offset-based pagination:
+        >>> pagination = OffsetPagination(start=0, limit=25)
+        >>> pagination.to_query_dict()
+        {'pagination[start]': 0, 'pagination[limit]': 25, 'pagination[withCount]': True}
+
+    Disable count (performance optimization):
+        >>> pagination = PagePagination(page=1, page_size=100, with_count=False)
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class PagePagination(BaseModel):
+    """Page-based pagination configuration.
+
+    Uses page number and page size for pagination. This is the most
+    user-friendly approach for displaying results across multiple pages.
+
+    Attributes:
+        page: Page number (1-indexed, must be >= 1)
+        page_size: Number of items per page (must be between 1 and 100)
+        with_count: Include total count in response (default: True)
+    """
+
+    page: int = Field(default=1, ge=1, description="Page number (1-indexed)")
+    page_size: int = Field(default=25, ge=1, le=100, description="Items per page")
+    with_count: bool = Field(default=True, description="Include total count in response metadata")
+
+    @field_validator("page")
+    @classmethod
+    def validate_page(cls, v: int) -> int:
+        """Validate page number is positive.
+
+        Args:
+            v: Page number to validate
+
+        Returns:
+            Validated page number
+
+        Raises:
+            ValueError: If page number is less than 1
+        """
+        if v < 1:
+            raise ValueError("Page number must be >= 1")
+        return v
+
+    @field_validator("page_size")
+    @classmethod
+    def validate_page_size(cls, v: int) -> int:
+        """Validate page size is within allowed range.
+
+        Args:
+            v: Page size to validate
+
+        Returns:
+            Validated page size
+
+        Raises:
+            ValueError: If page size is out of range [1, 100]
+        """
+        if v < 1 or v > 100:
+            raise ValueError("Page size must be between 1 and 100")
+        return v
+
+    def to_query_dict(self) -> dict[str, Any]:
+        """Convert to query parameters dictionary.
+
+        Returns:
+            Dictionary with pagination parameters in Strapi format
+
+        Examples:
+            >>> PagePagination(page=2, page_size=50).to_query_dict()
+            {'pagination[page]': 2, 'pagination[pageSize]': 50, 'pagination[withCount]': True}
+        """
+        return {
+            "pagination[page]": self.page,
+            "pagination[pageSize]": self.page_size,
+            "pagination[withCount]": self.with_count,
+        }
+
+
+class OffsetPagination(BaseModel):
+    """Offset-based pagination configuration.
+
+    Uses start offset and limit for pagination. This approach is more
+    flexible but requires manual calculation of offsets.
+
+    Attributes:
+        start: Starting offset (0-indexed, must be >= 0)
+        limit: Maximum number of items to return (must be between 1 and 100)
+        with_count: Include total count in response (default: True)
+    """
+
+    start: int = Field(default=0, ge=0, description="Starting offset (0-indexed)")
+    limit: int = Field(default=25, ge=1, le=100, description="Maximum items to return")
+    with_count: bool = Field(default=True, description="Include total count in response metadata")
+
+    @field_validator("start")
+    @classmethod
+    def validate_start(cls, v: int) -> int:
+        """Validate start offset is non-negative.
+
+        Args:
+            v: Start offset to validate
+
+        Returns:
+            Validated start offset
+
+        Raises:
+            ValueError: If start is negative
+        """
+        if v < 0:
+            raise ValueError("Start offset must be >= 0")
+        return v
+
+    @field_validator("limit")
+    @classmethod
+    def validate_limit(cls, v: int) -> int:
+        """Validate limit is within allowed range.
+
+        Args:
+            v: Limit to validate
+
+        Returns:
+            Validated limit
+
+        Raises:
+            ValueError: If limit is out of range [1, 100]
+        """
+        if v < 1 or v > 100:
+            raise ValueError("Limit must be between 1 and 100")
+        return v
+
+    def to_query_dict(self) -> dict[str, Any]:
+        """Convert to query parameters dictionary.
+
+        Returns:
+            Dictionary with pagination parameters in Strapi format
+
+        Examples:
+            >>> OffsetPagination(start=50, limit=25).to_query_dict()
+            {'pagination[start]': 50, 'pagination[limit]': 25, 'pagination[withCount]': True}
+        """
+        return {
+            "pagination[start]": self.start,
+            "pagination[limit]": self.limit,
+            "pagination[withCount]": self.with_count,
+        }
+
+
+# Type alias for either pagination strategy
+Pagination = PagePagination | OffsetPagination

strapi_kit/models/request/populate.py

@@ -0,0 +1,281 @@
+"""Population (relation expansion) for Strapi API queries.
+
+Strapi supports populating (expanding) relations, components, and dynamic zones.
+This module provides a fluent API for building complex population configurations.
+
+Examples:
+    Simple population:
+        >>> populate = Populate().fields_list(["author", "category"])
+        >>> populate.to_query_dict()
+        {'populate': ['author', 'category']}
+
+    Populate all relations:
+        >>> populate = Populate().all()
+        >>> populate.to_query_dict()
+        {'populate': '*'}
+
+    Nested population with filtering:
+        >>> from strapi_kit.models.request.filters import FilterBuilder
+        >>> populate = Populate().add_field(
+        ...     "author",
+        ...     fields=["name", "email"],
+        ...     filters=FilterBuilder().eq("active", True)
+        ... )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from strapi_kit.models.request.filters import FilterBuilder
+from strapi_kit.models.request.sort import Sort
+
+
+class PopulateField(BaseModel):
+    """Configuration for populating a single field.
+
+    Attributes:
+        field: Field name to populate
+        nested: Nested population configuration
+        filters: Filter conditions for the populated data
+        fields: Specific fields to select from the relation
+        sort: Sort configuration for the populated data
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    field: str = Field(..., min_length=1, description="Field name to populate")
+    nested: Populate | None = Field(None, description="Nested population")
+    filters: FilterBuilder | None = Field(None, description="Filter populated data")
+    fields: list[str] | None = Field(None, description="Fields to select")
+    sort: Sort | None = Field(None, description="Sort configuration")
+
+    def to_dict(self, _depth: int = 0, _max_depth: int = 10) -> dict[str, Any]:
+        """Convert to dictionary format for query parameters.
+
+        Args:
+            _depth: Current recursion depth (internal use)
+            _max_depth: Maximum allowed recursion depth (default: 10)
+
+        Returns:
+            Dictionary with field name as key and configuration as value
+
+        Raises:
+            RecursionError: If nesting exceeds max_depth
+
+        Examples:
+            >>> # Simple populate
+            >>> pf = PopulateField(field="author")
+            >>> pf.to_dict()
+            {'author': {'populate': '*'}}
+
+            >>> # With field selection
+            >>> pf = PopulateField(field="author", fields=["name", "email"])
+            >>> pf.to_dict()
+            {'author': {'fields': ['name', 'email'], 'populate': '*'}}
+        """
+        if _depth > _max_depth:
+            raise RecursionError(
+                f"Populate nesting exceeded maximum depth of {_max_depth}. "
+                "This may indicate circular references in your populate configuration."
+            )
+
+        config: dict[str, Any] = {}
+
+        # Add field selection
+        if self.fields:
+            config["fields"] = self.fields
+
+        # Add filters
+        if self.filters:
+            filter_dict = self.filters.to_query_dict()
+            if filter_dict:
+                config["filters"] = filter_dict
+
+        # Add sort
+        if self.sort:
+            sort_list = self.sort.to_query_list()
+            if sort_list:
+                config["sort"] = sort_list
+
+        # Add nested population
+        if self.nested:
+            nested_dict = self.nested.to_query_dict(_depth=_depth + 1, _max_depth=_max_depth)
+            if "populate" in nested_dict:
+                config["populate"] = nested_dict["populate"]
+        else:
+            # Default: populate all fields of this relation
+            config["populate"] = "*"
+
+        return {self.field: config}
+
+
+class Populate:
+    """Fluent API for building population configurations.
+
+    Strapi population allows expanding relations, components, and dynamic zones.
+    This class provides methods to configure simple and complex population scenarios.
+
+    Examples:
+        >>> # Populate all relations
+        >>> populate = Populate().all()
+
+        >>> # Populate specific fields
+        >>> populate = Populate().fields_list(["author", "category"])
+
+        >>> # Populate with nested relations
+        >>> populate = (Populate()
+        ...     .add_field("author")
+        ...     .add_field("posts", nested=Populate().add_field("comments")))
+
+        >>> # Populate with filtering
+        >>> populate = Populate().add_field(
+        ...     "author",
+        ...     filters=FilterBuilder().eq("active", True),
+        ...     fields=["name", "email"]
+        ... )
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty populate configuration."""
+        self._populate_all: bool = False
+        self._fields: list[PopulateField] = []
+
+    def all(self) -> Populate:
+        """Populate all first-level relations.
+
+        Returns:
+            Self for method chaining
+
+        Examples:
+            >>> populate = Populate().all()
+            >>> populate.to_query_dict()
+            {'populate': '*'}
+        """
+        self._populate_all = True
+        return self
+
+    def fields_list(self, fields: list[str]) -> Populate:
+        """Populate specific fields (simple list).
+
+        Args:
+            fields: List of field names to populate
+
+        Returns:
+            Self for method chaining
+
+        Examples:
+            >>> populate = Populate().fields_list(["author", "category", "tags"])
+            >>> populate.to_query_dict()
+            {'populate': ['author', 'category', 'tags']}
+        """
+        # Convert simple field names to PopulateField objects
+        for field_name in fields:
+            self._fields.append(
+                PopulateField(field=field_name, nested=None, filters=None, fields=None, sort=None)
+            )
+        return self
+
+    def add_field(
+        self,
+        field: str,
+        nested: Populate | None = None,
+        filters: FilterBuilder | None = None,
+        fields: list[str] | None = None,
+        sort: Sort | None = None,
+    ) -> Populate:
+        """Add a field to populate with advanced configuration.
+
+        Args:
+            field: Field name to populate
+            nested: Nested population configuration
+            filters: Filter conditions for the populated data
+            fields: Specific fields to select from the relation
+            sort: Sort configuration for the populated data
+
+        Returns:
+            Self for method chaining
+
+        Examples:
+            >>> # Simple field
+            >>> populate = Populate().add_field("author")
+
+            >>> # With field selection
+            >>> populate = Populate().add_field("author", fields=["name", "email"])
+
+            >>> # With filtering
+            >>> populate = Populate().add_field(
+            ...     "comments",
+            ...     filters=FilterBuilder().eq("approved", True),
+            ...     sort=Sort().by_field("createdAt", SortDirection.DESC)
+            ... )
+
+            >>> # Nested population
+            >>> populate = Populate().add_field(
+            ...     "author",
+            ...     nested=Populate().add_field("profile")
+            ... )
+        """
+        self._fields.append(
+            PopulateField(field=field, nested=nested, filters=filters, fields=fields, sort=sort)
+        )
+        return self
+
+    def to_query_dict(self, _depth: int = 0, _max_depth: int = 10) -> dict[str, Any]:
+        """Convert to dictionary format for query parameters.
+
+        Args:
+            _depth: Current recursion depth (internal use)
+            _max_depth: Maximum allowed recursion depth (default: 10)
+
+        Returns:
+            Dictionary with 'populate' key
+
+        Raises:
+            RecursionError: If nesting exceeds max_depth
+
+        Examples:
+            >>> # Populate all
+            >>> Populate().all().to_query_dict()
+            {'populate': '*'}
+
+            >>> # Simple list
+            >>> Populate().fields_list(["author", "category"]).to_query_dict()
+            {'populate': ['author', 'category']}
+
+            >>> # Complex with configuration
+            >>> populate = Populate().add_field("author", fields=["name"])
+            >>> # Returns nested structure
+        """
+        # Check depth limit at Populate level
+        if _depth > _max_depth:
+            raise RecursionError(
+                f"Populate nesting exceeded maximum depth of {_max_depth}. "
+                "This may indicate circular references in your populate configuration."
+            )
+
+        if not self._populate_all and not self._fields:
+            return {}
+
+        # Populate all
+        if self._populate_all:
+            return {"populate": "*"}
+
+        # Check if all fields are simple (no config)
+        all_simple = all(
+            not f.nested and not f.filters and not f.fields and not f.sort for f in self._fields
+        )
+
+        if all_simple:
+            # Simple array format
+            return {"populate": [f.field for f in self._fields]}
+
+        # Complex object format
+        result: dict[str, Any] = {}
+        for field_config in self._fields:
+            field_dict = field_config.to_dict(_depth=_depth, _max_depth=_max_depth)
+            result.update(field_dict)
+
+        return {"populate": result}