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

fastapi_fsp/__init__.py

@@ -1,9 +1,43 @@
 """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 .fsp import FSPManager  # noqa: F401
+from .models import (  # noqa: F401
+    Filter,
+    FilterOperator,
+    Links,
+    Meta,
+    PaginatedResponse,
+    Pagination,
+    PaginationQuery,
+    SortingOrder,
+    SortingQuery,
+)
+from .presets import CommonFilters  # noqa: F401
 
 __all__ = [
+    # Main class
     "FSPManager",
+    # 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,
+        )

fastapi_fsp/fsp.py

@@ -2,15 +2,16 @@
 
 from datetime import datetime
 from math import ceil
-from typing import Annotated, Any, List, Optional
+from typing import Annotated, Any, List, Optional, Type
 
 from dateutil.parser import parse
 from fastapi import Depends, HTTPException, Query, Request, status
 from pydantic import ValidationError
 from sqlalchemy import ColumnCollection, ColumnElement, Select, func
-from sqlmodel import Session, not_, select
+from sqlmodel import Session, SQLModel, not_, select
 from sqlmodel.ext.asyncio.session import AsyncSession
 
+from fastapi_fsp.config import FSPConfig
 from fastapi_fsp.models import (
     Filter,
     FilterOperator,
@@ -705,3 +706,106 @@ class FSPManager:
                 column.desc() if sorting.order == SortingOrder.DESC else column.asc()
             )
         return query
+
+    def apply_config(self, config: FSPConfig) -> "FSPManager":
+        """
+        Apply a configuration to this FSPManager instance.
+
+        Args:
+            config: FSPConfig instance with settings
+
+        Returns:
+            FSPManager: Self for chaining
+        """
+        self.strict_mode = config.strict_mode
+        # Validate and constrain pagination values
+        self.pagination.page = config.validate_page(self.pagination.page)
+        self.pagination.per_page = config.validate_per_page(self.pagination.per_page)
+        return self
+
+    def from_model(
+        self,
+        model: Type[SQLModel],
+        session: Session,
+    ) -> PaginatedResponse[Any]:
+        """
+        Convenience method to query directly from a model.
+
+        This simplifies the common pattern of selecting all from a model.
+
+        Args:
+            model: SQLModel class to query
+            session: Database session
+
+        Returns:
+            PaginatedResponse: Complete paginated response
+
+        Example:
+            @app.get("/heroes/")
+            def read_heroes(
+                session: Session = Depends(get_session),
+                fsp: FSPManager = Depends(FSPManager)
+            ):
+                return fsp.from_model(Hero, session)
+        """
+        query = select(model)
+        return self.generate_response(query, session)
+
+    async def from_model_async(
+        self,
+        model: Type[SQLModel],
+        session: AsyncSession,
+    ) -> PaginatedResponse[Any]:
+        """
+        Convenience method to query directly from a model (async version).
+
+        This simplifies the common pattern of selecting all from a model.
+
+        Args:
+            model: SQLModel class to query
+            session: Async database session
+
+        Returns:
+            PaginatedResponse: Complete paginated response
+
+        Example:
+            @app.get("/heroes/")
+            async def read_heroes(
+                session: AsyncSession = Depends(get_session),
+                fsp: FSPManager = Depends(FSPManager)
+            ):
+                return await fsp.from_model_async(Hero, session)
+        """
+        query = select(model)
+        return await self.generate_response_async(query, session)
+
+    def with_filters(self, filters: Optional[List[Filter]]) -> "FSPManager":
+        """
+        Set or override filters.
+
+        Args:
+            filters: List of filters to apply
+
+        Returns:
+            FSPManager: Self for chaining
+        """
+        if filters:
+            if self.filters:
+                self.filters.extend(filters)
+            else:
+                self.filters = filters
+        return self
+
+    def with_sorting(self, sorting: Optional[SortingQuery]) -> "FSPManager":
+        """
+        Set or override sorting.
+
+        Args:
+            sorting: Sorting configuration
+
+        Returns:
+            FSPManager: Self for chaining
+        """
+        if sorting:
+            self.sorting = sorting
+        return self

fastapi_fsp/presets.py

@@ -0,0 +1,267 @@
+"""Common filter presets for frequently used query patterns."""
+
+from datetime import datetime, timedelta
+from typing import List
+
+from fastapi_fsp.models import Filter, FilterOperator
+
+
+class CommonFilters:
+    """
+    Pre-defined filter presets for common query patterns.
+
+    These presets help reduce boilerplate for frequently used filter combinations.
+
+    Example usage:
+        from fastapi_fsp.presets import CommonFilters
+
+        # Get active (non-deleted) records
+        filters = CommonFilters.active()
+
+        # Get records from last 7 days
+        filters = CommonFilters.recent(days=7)
+
+        # Combine presets
+        filters = CommonFilters.active() + CommonFilters.recent(days=30)
+    """
+
+    @staticmethod
+    def active(deleted_field: str = "deleted") -> List[Filter]:
+        """
+        Filter for active (non-deleted) records.
+
+        Args:
+            deleted_field: Name of the boolean deleted field (default: "deleted")
+
+        Returns:
+            List[Filter]: Filters for non-deleted records
+        """
+        return [Filter(field=deleted_field, operator=FilterOperator.EQ, value="false")]
+
+    @staticmethod
+    def deleted(deleted_field: str = "deleted") -> List[Filter]:
+        """
+        Filter for deleted records only.
+
+        Args:
+            deleted_field: Name of the boolean deleted field (default: "deleted")
+
+        Returns:
+            List[Filter]: Filters for deleted records
+        """
+        return [Filter(field=deleted_field, operator=FilterOperator.EQ, value="true")]
+
+    @staticmethod
+    def recent(
+        date_field: str = "created_at",
+        days: int = 30,
+        reference_time: datetime = None,
+    ) -> List[Filter]:
+        """
+        Filter for records created in the last N days.
+
+        Args:
+            date_field: Name of the datetime field (default: "created_at")
+            days: Number of days to look back (default: 30)
+            reference_time: Reference time for calculation (default: now)
+
+        Returns:
+            List[Filter]: Filters for recent records
+        """
+        if reference_time is None:
+            reference_time = datetime.now()
+        cutoff = (reference_time - timedelta(days=days)).isoformat()
+        return [Filter(field=date_field, operator=FilterOperator.GTE, value=cutoff)]
+
+    @staticmethod
+    def older_than(
+        date_field: str = "created_at",
+        days: int = 30,
+        reference_time: datetime = None,
+    ) -> List[Filter]:
+        """
+        Filter for records created more than N days ago.
+
+        Args:
+            date_field: Name of the datetime field (default: "created_at")
+            days: Number of days threshold (default: 30)
+            reference_time: Reference time for calculation (default: now)
+
+        Returns:
+            List[Filter]: Filters for older records
+        """
+        if reference_time is None:
+            reference_time = datetime.now()
+        cutoff = (reference_time - timedelta(days=days)).isoformat()
+        return [Filter(field=date_field, operator=FilterOperator.LT, value=cutoff)]
+
+    @staticmethod
+    def date_range(
+        date_field: str = "created_at",
+        start: datetime = None,
+        end: datetime = None,
+    ) -> List[Filter]:
+        """
+        Filter for records within a date range.
+
+        Args:
+            date_field: Name of the datetime field (default: "created_at")
+            start: Start of date range (inclusive)
+            end: End of date range (inclusive)
+
+        Returns:
+            List[Filter]: Filters for date range
+
+        Raises:
+            ValueError: If neither start nor end is provided
+        """
+        if start is None and end is None:
+            raise ValueError("At least one of start or end must be provided")
+
+        filters = []
+        if start is not None:
+            filters.append(
+                Filter(field=date_field, operator=FilterOperator.GTE, value=start.isoformat())
+            )
+        if end is not None:
+            filters.append(
+                Filter(field=date_field, operator=FilterOperator.LTE, value=end.isoformat())
+            )
+        return filters
+
+    @staticmethod
+    def today(date_field: str = "created_at", reference_time: datetime = None) -> List[Filter]:
+        """
+        Filter for records created today.
+
+        Args:
+            date_field: Name of the datetime field (default: "created_at")
+            reference_time: Reference time for calculation (default: now)
+
+        Returns:
+            List[Filter]: Filters for today's records
+        """
+        if reference_time is None:
+            reference_time = datetime.now()
+        start_of_day = reference_time.replace(hour=0, minute=0, second=0, microsecond=0)
+        end_of_day = reference_time.replace(hour=23, minute=59, second=59, microsecond=999999)
+        return [
+            Filter(
+                field=date_field,
+                operator=FilterOperator.BETWEEN,
+                value=f"{start_of_day.isoformat()},{end_of_day.isoformat()}",
+            )
+        ]
+
+    @staticmethod
+    def not_null(field: str) -> List[Filter]:
+        """
+        Filter for records where field is not null.
+
+        Args:
+            field: Name of the field to check
+
+        Returns:
+            List[Filter]: Filter for non-null values
+        """
+        return [Filter(field=field, operator=FilterOperator.IS_NOT_NULL, value="")]
+
+    @staticmethod
+    def is_null(field: str) -> List[Filter]:
+        """
+        Filter for records where field is null.
+
+        Args:
+            field: Name of the field to check
+
+        Returns:
+            List[Filter]: Filter for null values
+        """
+        return [Filter(field=field, operator=FilterOperator.IS_NULL, value="")]
+
+    @staticmethod
+    def enabled(enabled_field: str = "enabled") -> List[Filter]:
+        """
+        Filter for enabled records.
+
+        Args:
+            enabled_field: Name of the boolean enabled field (default: "enabled")
+
+        Returns:
+            List[Filter]: Filters for enabled records
+        """
+        return [Filter(field=enabled_field, operator=FilterOperator.EQ, value="true")]
+
+    @staticmethod
+    def disabled(enabled_field: str = "enabled") -> List[Filter]:
+        """
+        Filter for disabled records.
+
+        Args:
+            enabled_field: Name of the boolean enabled field (default: "enabled")
+
+        Returns:
+            List[Filter]: Filters for disabled records
+        """
+        return [Filter(field=enabled_field, operator=FilterOperator.EQ, value="false")]
+
+    @staticmethod
+    def search(
+        field: str,
+        term: str,
+        match_type: str = "contains",
+    ) -> List[Filter]:
+        """
+        Create a search filter for text matching.
+
+        Args:
+            field: Name of the field to search
+            term: Search term
+            match_type: Type of match - "contains", "starts_with", "ends_with" (default: "contains")
+
+        Returns:
+            List[Filter]: Search filter
+
+        Raises:
+            ValueError: If match_type is invalid
+        """
+        operator_map = {
+            "contains": FilterOperator.CONTAINS,
+            "starts_with": FilterOperator.STARTS_WITH,
+            "ends_with": FilterOperator.ENDS_WITH,
+        }
+        operator = operator_map.get(match_type)
+        if operator is None:
+            valid_types = "contains, starts_with, ends_with"
+            raise ValueError(f"Invalid match_type: {match_type}. Use: {valid_types}")
+        return [Filter(field=field, operator=operator, value=term)]
+
+    @staticmethod
+    def in_values(field: str, values: List) -> List[Filter]:
+        """
+        Filter for records where field is in a list of values.
+
+        Args:
+            field: Name of the field to filter
+            values: List of values to match
+
+        Returns:
+            List[Filter]: IN filter
+        """
+        str_values = ",".join(str(v) for v in values)
+        return [Filter(field=field, operator=FilterOperator.IN, value=str_values)]
+
+    @staticmethod
+    def not_in_values(field: str, values: List) -> List[Filter]:
+        """
+        Filter for records where field is not in a list of values.
+
+        Args:
+            field: Name of the field to filter
+            values: List of values to exclude
+
+        Returns:
+            List[Filter]: NOT IN filter
+        """
+        str_values = ",".join(str(v) for v in values)
+        return [Filter(field=field, operator=FilterOperator.NOT_IN, value=str_values)]

{fastapi_fsp-0.2.3.dist-info → fastapi_fsp-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-fsp
-Version: 0.2.3
+Version: 0.3.0
 Summary: Filter, Sort, and Paginate (FSP) utilities for FastAPI + SQLModel
 Project-URL: Homepage, https://github.com/fromej-dev/fastapi-fsp
 Project-URL: Repository, https://github.com/fromej-dev/fastapi-fsp
@@ -205,6 +205,164 @@ GET /heroes/?field=full_name&operator=starts_with&value=Spider&field=age&operato
 - The field should be declared as `ClassVar[type]` in the SQLModel base class to work with Pydantic
 - Only computed fields with SQL expressions are supported; Python-only properties cannot be filtered at the database level
 
+## FilterBuilder API
+
+For programmatic filter creation, use the fluent `FilterBuilder` API:
+
+```python
+from fastapi_fsp import FilterBuilder
+
+# Instead of manually creating Filter objects:
+# filters = [
+#     Filter(field="age", operator=FilterOperator.GTE, value="30"),
+#     Filter(field="city", operator=FilterOperator.EQ, value="Chicago"),
+# ]
+
+# Use the builder pattern:
+filters = (
+    FilterBuilder()
+    .where("age").gte(30)
+    .where("city").eq("Chicago")
+    .where("active").eq(True)
+    .where("tags").in_(["python", "fastapi"])
+    .where("created_at").between("2024-01-01", "2024-12-31")
+    .build()
+)
+
+# Use with FSPManager
+@app.get("/heroes/")
+def read_heroes(session: Session = Depends(get_session), fsp: FSPManager = Depends(FSPManager)):
+    additional_filters = FilterBuilder().where("deleted").eq(False).build()
+    fsp.with_filters(additional_filters)
+    return fsp.generate_response(select(Hero), session)
+```
+
+### Available FilterBuilder Methods
+
+| Method | Description |
+|--------|-------------|
+| `.eq(value)` | Equal to |
+| `.ne(value)` | Not equal to |
+| `.gt(value)` | Greater than |
+| `.gte(value)` | Greater than or equal |
+| `.lt(value)` | Less than |
+| `.lte(value)` | Less than or equal |
+| `.like(pattern)` | Case-sensitive LIKE |
+| `.ilike(pattern)` | Case-insensitive LIKE |
+| `.in_(values)` | IN list |
+| `.not_in(values)` | NOT IN list |
+| `.between(low, high)` | BETWEEN range |
+| `.is_null()` | IS NULL |
+| `.is_not_null()` | IS NOT NULL |
+| `.starts_with(prefix)` | Starts with (case-insensitive) |
+| `.ends_with(suffix)` | Ends with (case-insensitive) |
+| `.contains(substring)` | Contains (case-insensitive) |
+
+## Common Filter Presets
+
+For frequently used filter patterns, use `CommonFilters`:
+
+```python
+from fastapi_fsp import CommonFilters
+
+# Active (non-deleted) records
+filters = CommonFilters.active()  # deleted=false
+
+# Recent records (last 7 days)
+filters = CommonFilters.recent(days=7)
+
+# Date range
+filters = CommonFilters.date_range(start=datetime(2024, 1, 1), end=datetime(2024, 12, 31))
+
+# Records created today
+filters = CommonFilters.today()
+
+# Null checks
+filters = CommonFilters.not_null("email")
+filters = CommonFilters.is_null("deleted_at")
+
+# Search
+filters = CommonFilters.search("name", "john", match_type="contains")
+
+# Combine presets
+filters = CommonFilters.active() + CommonFilters.recent(days=30)
+```
+
+## Configuration
+
+Customize FSPManager behavior with `FSPConfig`:
+
+```python
+from fastapi_fsp import FSPConfig, FSPPresets
+
+# Custom configuration
+config = FSPConfig(
+    max_per_page=50,
+    default_per_page=20,
+    strict_mode=True,  # Raise errors for unknown fields
+    max_page=100,
+    allow_deep_pagination=False,
+)
+
+# Or use presets
+config = FSPPresets.strict()  # strict_mode=True
+config = FSPPresets.limited_pagination(max_page=50)  # Limit deep pagination
+config = FSPPresets.high_volume(max_per_page=500)  # High-volume APIs
+
+# Apply configuration
+@app.get("/heroes/")
+def read_heroes(session: Session = Depends(get_session), fsp: FSPManager = Depends(FSPManager)):
+    fsp.apply_config(config)
+    return fsp.generate_response(select(Hero), session)
+```
+
+### Strict Mode
+
+When `strict_mode=True`, FSPManager raises HTTP 400 errors for unknown filter/sort fields:
+
+```python
+# With strict_mode=True, this raises HTTP 400:
+# GET /heroes/?field=unknown_field&operator=eq&value=test
+# Error: "Unknown field 'unknown_field'. Available fields: age, id, name, secret_name"
+```
+
+## Convenience Methods
+
+### from_model()
+
+Simplify common queries with `from_model()`:
+
+```python
+@app.get("/heroes/")
+def read_heroes(session: Session = Depends(get_session), fsp: FSPManager = Depends(FSPManager)):
+    # Instead of:
+    # query = select(Hero)
+    # return fsp.generate_response(query, session)
+
+    # Use:
+    return fsp.from_model(Hero, session)
+
+# Async version
+@app.get("/heroes/")
+async def read_heroes(session: AsyncSession = Depends(get_session), fsp: FSPManager = Depends(FSPManager)):
+    return await fsp.from_model_async(Hero, session)
+```
+
+### Method Chaining
+
+Chain configuration methods:
+
+```python
+@app.get("/heroes/")
+def read_heroes(session: Session = Depends(get_session), fsp: FSPManager = Depends(FSPManager)):
+    return (
+        fsp
+        .with_filters(CommonFilters.active())
+        .apply_config(FSPPresets.strict())
+        .generate_response(select(Hero), session)
+    )
+```
+
 ## Response model
 
 ```

fastapi_fsp-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastapi_fsp/__init__.py,sha256=vQtASadi_DWCs14VpPO60upWbJxqxSotA7thQ7dgYb0,925
+fastapi_fsp/builder.py,sha256=due8kTVApNXWZJGVDhqe6Ch9jCqdjnNe0rvWNUOgVMw,9660
+fastapi_fsp/config.py,sha256=GcrSyv_wOvNgLFq00fhsZznZH4Fnl0dCBJa73n2QwIs,4977
+fastapi_fsp/fsp.py,sha256=WNcarSmffEDs86VE7xerFC1-JC89mqusM_fx1k4v3P8,27022
+fastapi_fsp/models.py,sha256=1MwLBQFmUP8OwO3Gqby1u7s9ruimCR2XGfUzAqF4Tj4,2034
+fastapi_fsp/presets.py,sha256=hpfUmCaeqoCeb1PimpUoGEW5S0Ycc-yBEZQq6vJWv50,8500
+fastapi_fsp-0.3.0.dist-info/METADATA,sha256=tGLU0lGCCYPVBGV55c8I8gjf66pdLInb_wSKG9jBlq4,12610
+fastapi_fsp-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fastapi_fsp-0.3.0.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+fastapi_fsp-0.3.0.dist-info/RECORD,,

fastapi_fsp-0.2.3.dist-info/RECORD

@@ -1,7 +0,0 @@
-fastapi_fsp/__init__.py,sha256=0I_XN_ptNu1NyNRpjdyVm6nwvrilAB8FyT2EfgVF_QA,215
-fastapi_fsp/fsp.py,sha256=b6OuHgbTpWrFtxGKm7fcPpjHtD3Cdjrs22m3IYOBhp4,23986
-fastapi_fsp/models.py,sha256=1MwLBQFmUP8OwO3Gqby1u7s9ruimCR2XGfUzAqF4Tj4,2034
-fastapi_fsp-0.2.3.dist-info/METADATA,sha256=w4wfXs3hye-UI0-h2a81OjkG3yzzZWUq91n1HhmyUi4,8224
-fastapi_fsp-0.2.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-fastapi_fsp-0.2.3.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
-fastapi_fsp-0.2.3.dist-info/RECORD,,