fastapi-fsp 0.2.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

fastapi_fsp/__init__.py

@@ -1,9 +1,52 @@
 """fastapi-fsp: Filter, Sort, and Paginate utilities for FastAPI + SQLModel."""
 
 from . import models as models  # noqa: F401
+from .builder import FieldBuilder, FilterBuilder  # noqa: F401
+from .config import FSPConfig, FSPPresets  # noqa: F401
+from .filters import FILTER_STRATEGIES, FilterEngine  # noqa: F401
 from .fsp import FSPManager  # noqa: F401
+from .models import (  # noqa: F401
+    Filter,
+    FilterOperator,
+    Links,
+    Meta,
+    PaginatedResponse,
+    Pagination,
+    PaginationQuery,
+    SortingOrder,
+    SortingQuery,
+)
+from .pagination import PaginationEngine  # noqa: F401
+from .presets import CommonFilters  # noqa: F401
+from .sorting import SortEngine  # noqa: F401
 
 __all__ = [
+    # Main class
     "FSPManager",
+    # Engines
+    "FilterEngine",
+    "SortEngine",
+    "PaginationEngine",
+    # Strategy registry
+    "FILTER_STRATEGIES",
+    # Builder
+    "FilterBuilder",
+    "FieldBuilder",
+    # Configuration
+    "FSPConfig",
+    "FSPPresets",
+    # Presets
+    "CommonFilters",
+    # Models
+    "Filter",
+    "FilterOperator",
+    "SortingOrder",
+    "SortingQuery",
+    "PaginationQuery",
+    "Pagination",
+    "Meta",
+    "Links",
+    "PaginatedResponse",
+    # Module
     "models",
 ]

fastapi_fsp/builder.py

@@ -0,0 +1,339 @@
+"""FilterBuilder API for creating filters with a fluent interface."""
+
+from datetime import date, datetime
+from typing import List, Optional, Union
+
+from fastapi_fsp.models import Filter, FilterOperator
+
+
+class FieldBuilder:
+    """
+    Builder for a single field's filter conditions.
+
+    Provides a fluent interface for building filter conditions on a specific field.
+    """
+
+    def __init__(self, filter_builder: "FilterBuilder", field: str):
+        """
+        Initialize FieldBuilder.
+
+        Args:
+            filter_builder: Parent FilterBuilder instance
+            field: Field name to build filters for
+        """
+        self._filter_builder = filter_builder
+        self._field = field
+
+    def _add_filter(self, operator: FilterOperator, value: str) -> "FilterBuilder":
+        """Add a filter and return the parent builder."""
+        self._filter_builder._filters.append(
+            Filter(field=self._field, operator=operator, value=value)
+        )
+        return self._filter_builder
+
+    @staticmethod
+    def _to_str(value: Union[str, int, float, bool, date, datetime]) -> str:
+        """Convert a value to string representation."""
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if isinstance(value, datetime):
+            return value.isoformat()
+        if isinstance(value, date):
+            return value.isoformat()
+        return str(value)
+
+    def eq(self, value: Union[str, int, float, bool, date, datetime]) -> "FilterBuilder":
+        """
+        Equal to (=).
+
+        Args:
+            value: Value to compare against
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.EQ, self._to_str(value))
+
+    def ne(self, value: Union[str, int, float, bool, date, datetime]) -> "FilterBuilder":
+        """
+        Not equal to (!=).
+
+        Args:
+            value: Value to compare against
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.NE, self._to_str(value))
+
+    def gt(self, value: Union[str, int, float, date, datetime]) -> "FilterBuilder":
+        """
+        Greater than (>).
+
+        Args:
+            value: Value to compare against
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.GT, self._to_str(value))
+
+    def gte(self, value: Union[str, int, float, date, datetime]) -> "FilterBuilder":
+        """
+        Greater than or equal to (>=).
+
+        Args:
+            value: Value to compare against
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.GTE, self._to_str(value))
+
+    def lt(self, value: Union[str, int, float, date, datetime]) -> "FilterBuilder":
+        """
+        Less than (<).
+
+        Args:
+            value: Value to compare against
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.LT, self._to_str(value))
+
+    def lte(self, value: Union[str, int, float, date, datetime]) -> "FilterBuilder":
+        """
+        Less than or equal to (<=).
+
+        Args:
+            value: Value to compare against
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.LTE, self._to_str(value))
+
+    def like(self, pattern: str) -> "FilterBuilder":
+        """
+        Case-sensitive LIKE pattern match.
+
+        Args:
+            pattern: LIKE pattern (use % for wildcards)
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.LIKE, pattern)
+
+    def not_like(self, pattern: str) -> "FilterBuilder":
+        """
+        Case-sensitive NOT LIKE pattern match.
+
+        Args:
+            pattern: LIKE pattern (use % for wildcards)
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.NOT_LIKE, pattern)
+
+    def ilike(self, pattern: str) -> "FilterBuilder":
+        """
+        Case-insensitive LIKE pattern match.
+
+        Args:
+            pattern: LIKE pattern (use % for wildcards)
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.ILIKE, pattern)
+
+    def not_ilike(self, pattern: str) -> "FilterBuilder":
+        """
+        Case-insensitive NOT LIKE pattern match.
+
+        Args:
+            pattern: LIKE pattern (use % for wildcards)
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.NOT_ILIKE, pattern)
+
+    def in_(self, values: List[Union[str, int, float, bool, date, datetime]]) -> "FilterBuilder":
+        """
+        IN list of values.
+
+        Args:
+            values: List of values to match against
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        str_values = ",".join(self._to_str(v) for v in values)
+        return self._add_filter(FilterOperator.IN, str_values)
+
+    def not_in(self, values: List[Union[str, int, float, bool, date, datetime]]) -> "FilterBuilder":
+        """
+        NOT IN list of values.
+
+        Args:
+            values: List of values to exclude
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        str_values = ",".join(self._to_str(v) for v in values)
+        return self._add_filter(FilterOperator.NOT_IN, str_values)
+
+    def between(
+        self,
+        low: Union[str, int, float, date, datetime],
+        high: Union[str, int, float, date, datetime],
+    ) -> "FilterBuilder":
+        """
+        BETWEEN low AND high (inclusive).
+
+        Args:
+            low: Lower bound
+            high: Upper bound
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        value = f"{self._to_str(low)},{self._to_str(high)}"
+        return self._add_filter(FilterOperator.BETWEEN, value)
+
+    def is_null(self) -> "FilterBuilder":
+        """
+        IS NULL check.
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.IS_NULL, "")
+
+    def is_not_null(self) -> "FilterBuilder":
+        """
+        IS NOT NULL check.
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.IS_NOT_NULL, "")
+
+    def starts_with(self, prefix: str) -> "FilterBuilder":
+        """
+        Starts with prefix (case-insensitive).
+
+        Args:
+            prefix: String prefix to match
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.STARTS_WITH, prefix)
+
+    def ends_with(self, suffix: str) -> "FilterBuilder":
+        """
+        Ends with suffix (case-insensitive).
+
+        Args:
+            suffix: String suffix to match
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.ENDS_WITH, suffix)
+
+    def contains(self, substring: str) -> "FilterBuilder":
+        """
+        Contains substring (case-insensitive).
+
+        Args:
+            substring: String to search for
+
+        Returns:
+            FilterBuilder: Parent builder for chaining
+        """
+        return self._add_filter(FilterOperator.CONTAINS, substring)
+
+
+class FilterBuilder:
+    """
+    Fluent builder for creating filter lists.
+
+    Example usage:
+        filters = (
+            FilterBuilder()
+            .where("age").gte(30)
+            .where("city").eq("Chicago")
+            .where("deleted").eq(False)
+            .build()
+        )
+
+    This creates a list of Filter objects that can be used with FSPManager.
+    """
+
+    def __init__(self):
+        """Initialize an empty FilterBuilder."""
+        self._filters: List[Filter] = []
+
+    def where(self, field: str) -> FieldBuilder:
+        """
+        Start building a filter for a field.
+
+        Args:
+            field: Name of the field to filter on
+
+        Returns:
+            FieldBuilder: Builder for the field's filter condition
+        """
+        return FieldBuilder(self, field)
+
+    def add_filter(self, field: str, operator: FilterOperator, value: str) -> "FilterBuilder":
+        """
+        Add a filter directly.
+
+        Args:
+            field: Field name
+            operator: Filter operator
+            value: Filter value as string
+
+        Returns:
+            FilterBuilder: Self for chaining
+        """
+        self._filters.append(Filter(field=field, operator=operator, value=value))
+        return self
+
+    def add_filters(self, filters: List[Filter]) -> "FilterBuilder":
+        """
+        Add multiple filters at once.
+
+        Args:
+            filters: List of Filter objects to add
+
+        Returns:
+            FilterBuilder: Self for chaining
+        """
+        self._filters.extend(filters)
+        return self
+
+    def build(self) -> Optional[List[Filter]]:
+        """
+        Build and return the list of filters.
+
+        Returns:
+            Optional[List[Filter]]: List of filters, or None if empty
+        """
+        return self._filters if self._filters else None
+
+    def __len__(self) -> int:
+        """Return the number of filters."""
+        return len(self._filters)
+
+    def __bool__(self) -> bool:
+        """Return True if there are any filters."""
+        return bool(self._filters)

fastapi_fsp/config.py

@@ -0,0 +1,158 @@
+"""Configuration classes for fastapi-fsp."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class FSPConfig:
+    """
+    Configuration for FSP behavior.
+
+    This class centralizes all configuration options for the FSPManager,
+    making it easier to customize behavior across your application.
+
+    Attributes:
+        max_per_page: Maximum allowed items per page (default: 100)
+        default_per_page: Default items per page when not specified (default: 10)
+        default_page: Default page number when not specified (default: 1)
+        strict_mode: If True, raise errors for unknown fields (default: False)
+        allow_deep_pagination: If True, allow pagination to any page (default: True)
+        max_page: Maximum allowed page number, None for unlimited (default: None)
+        min_per_page: Minimum allowed items per page (default: 1)
+
+    Example:
+        # Create a strict configuration
+        config = FSPConfig(
+            strict_mode=True,
+            max_per_page=50,
+            default_per_page=20
+        )
+
+        # Use with FSPManager
+        def get_fsp_config():
+            return FSPConfig(strict_mode=True)
+
+        @app.get("/items/")
+        def read_items(
+            fsp: FSPManager = Depends(FSPManager),
+            config: FSPConfig = Depends(get_fsp_config)
+        ):
+            fsp.apply_config(config)
+            ...
+    """
+
+    # Pagination settings
+    max_per_page: int = 100
+    default_per_page: int = 10
+    default_page: int = 1
+    min_per_page: int = 1
+
+    # Validation settings
+    strict_mode: bool = False
+
+    # Deep pagination settings
+    allow_deep_pagination: bool = True
+    max_page: Optional[int] = None
+
+    # Reserved for future features
+    _extra: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate configuration values."""
+        if self.max_per_page < 1:
+            raise ValueError("max_per_page must be >= 1")
+        if self.default_per_page < 1:
+            raise ValueError("default_per_page must be >= 1")
+        if self.default_per_page > self.max_per_page:
+            raise ValueError("default_per_page cannot exceed max_per_page")
+        if self.min_per_page < 1:
+            raise ValueError("min_per_page must be >= 1")
+        if self.min_per_page > self.max_per_page:
+            raise ValueError("min_per_page cannot exceed max_per_page")
+        if self.default_page < 1:
+            raise ValueError("default_page must be >= 1")
+        if self.max_page is not None and self.max_page < 1:
+            raise ValueError("max_page must be >= 1 or None")
+
+    def validate_page(self, page: int) -> int:
+        """
+        Validate and constrain a page number.
+
+        Args:
+            page: Requested page number
+
+        Returns:
+            int: Valid page number
+
+        Raises:
+            ValueError: If page exceeds max_page and allow_deep_pagination is False
+        """
+        if page < 1:
+            return self.default_page
+
+        if not self.allow_deep_pagination and self.max_page is not None:
+            if page > self.max_page:
+                raise ValueError(f"Page {page} exceeds maximum allowed page {self.max_page}")
+
+        return page
+
+    def validate_per_page(self, per_page: int) -> int:
+        """
+        Validate and constrain items per page.
+
+        Args:
+            per_page: Requested items per page
+
+        Returns:
+            int: Valid per_page value, constrained to min/max bounds
+        """
+        if per_page < self.min_per_page:
+            return self.min_per_page
+        if per_page > self.max_per_page:
+            return self.max_per_page
+        return per_page
+
+
+# Pre-defined configurations for common use cases
+class FSPPresets:
+    """Pre-defined FSPConfig presets for common use cases."""
+
+    @staticmethod
+    def default() -> FSPConfig:
+        """Default configuration with sensible defaults."""
+        return FSPConfig()
+
+    @staticmethod
+    def strict() -> FSPConfig:
+        """Strict mode configuration - raises errors for unknown fields."""
+        return FSPConfig(strict_mode=True)
+
+    @staticmethod
+    def limited_pagination(max_page: int = 100, max_per_page: int = 50) -> FSPConfig:
+        """
+        Configuration that limits deep pagination.
+
+        Args:
+            max_page: Maximum allowed page number
+            max_per_page: Maximum items per page
+        """
+        return FSPConfig(
+            max_page=max_page,
+            max_per_page=max_per_page,
+            allow_deep_pagination=False,
+        )
+
+    @staticmethod
+    def high_volume(max_per_page: int = 500, default_per_page: int = 100) -> FSPConfig:
+        """
+        Configuration for high-volume APIs.
+
+        Args:
+            max_per_page: Maximum items per page
+            default_per_page: Default items per page
+        """
+        return FSPConfig(
+            max_per_page=max_per_page,
+            default_per_page=default_per_page,
+        )