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

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,
@@ -228,10 +229,54 @@ class FSPManager:
         if col_id not in self._type_cache:
             try:
                 self._type_cache[col_id] = getattr(column.type, "python_type", None)
-            except Exception:
+            except (AttributeError, NotImplementedError):
+                # For computed fields (hybrid_property, etc.), type inference may fail
                 self._type_cache[col_id] = None
         return self._type_cache[col_id]
 
+    @staticmethod
+    def _get_entity_attribute(query: Select, field: str) -> Optional[ColumnElement[Any]]:
+        """
+        Try to get a column-like attribute from the query's entity.
+
+        This enables filtering/sorting on computed fields like hybrid_property
+        that have SQL expressions defined.
+
+        Args:
+            query: SQLAlchemy Select query
+            field: Name of the field/attribute to get
+
+        Returns:
+            Optional[ColumnElement]: The SQL expression if available, None otherwise
+        """
+        try:
+            # Get the entity class from the query
+            column_descriptions = query.column_descriptions
+            if not column_descriptions:
+                return None
+
+            entity = column_descriptions[0].get("entity")
+            if entity is None:
+                return None
+
+            # Get the attribute from the entity class
+            attr = getattr(entity, field, None)
+            if attr is None:
+                return None
+
+            # Check if it's directly usable as a ColumnElement (hybrid_property with expression)
+            # When accessing a hybrid_property on the class, it returns the SQL expression
+            if isinstance(attr, ColumnElement):
+                return attr
+
+            # Some expressions may need to call __clause_element__
+            if hasattr(attr, "__clause_element__"):
+                return attr.__clause_element__()
+
+            return None
+        except Exception:
+            return None
+
     def paginate(self, query: Select, session: Session) -> Any:
         """
         Execute pagination on a query.
@@ -591,6 +636,11 @@ class FSPManager:
         for f in filters:
             # filter of `filters` has been validated in the `_parse_filters`
             column = columns_map.get(f.field)
+
+            # Fall back to computed fields (hybrid_property, etc.) if not in columns_map
+            if column is None:
+                column = FSPManager._get_entity_attribute(query, f.field)
+
             if column is None:
                 if self.strict_mode:
                     available = ", ".join(sorted(columns_map.keys()))
@@ -635,11 +685,10 @@ class FSPManager:
         """
         if sorting and sorting.sort_by:
             column = columns_map.get(sorting.sort_by)
+
+            # Fall back to computed fields (hybrid_property, etc.) if not in columns_map
             if column is None:
-                try:
-                    column = getattr(query.column_descriptions[0]["entity"], sorting.sort_by, None)
-                except Exception:
-                    pass
+                column = FSPManager._get_entity_attribute(query, sorting.sort_by)
 
             if column is None:
                 if self.strict_mode:
@@ -657,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)]