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

fastapi_fsp/fsp.py

@@ -195,6 +195,7 @@ class FSPManager:
         filters: Annotated[Optional[List[Filter]], Depends(_parse_filters)],
         sorting: Annotated[Optional[SortingQuery], Depends(_parse_sort)],
         pagination: Annotated[PaginationQuery, Depends(_parse_pagination)],
+        strict_mode: bool = False,
     ):
         """
         Initialize FSPManager.
@@ -204,11 +205,76 @@ class FSPManager:
             filters: Parsed filters
             sorting: Sorting configuration
             pagination: Pagination configuration
+            strict_mode: If True, raise errors for unknown fields instead of silently skipping
         """
         self.request = request
         self.filters = filters
         self.sorting = sorting
         self.pagination = pagination
+        self.strict_mode = strict_mode
+        self._type_cache: dict[int, Optional[type]] = {}
+
+    def _get_column_type(self, column: ColumnElement[Any]) -> Optional[type]:
+        """
+        Get the Python type of a column with caching.
+
+        Args:
+            column: SQLAlchemy column element
+
+        Returns:
+            Optional[type]: Python type of the column or None
+        """
+        col_id = id(column)
+        if col_id not in self._type_cache:
+            try:
+                self._type_cache[col_id] = getattr(column.type, "python_type", None)
+            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:
         """
@@ -257,8 +323,8 @@ class FSPManager:
             PaginatedResponse: Complete paginated response
         """
         columns_map = query.selected_columns
-        query = FSPManager._apply_filters(query, columns_map, self.filters)
-        query = FSPManager._apply_sort(query, columns_map, self.sorting)
+        query = self._apply_filters(query, columns_map, self.filters)
+        query = self._apply_sort(query, columns_map, self.sorting)
 
         total_items = self._count_total(query, session)
         data_page = self.paginate(query, session)
@@ -278,8 +344,8 @@ class FSPManager:
             PaginatedResponse: Complete paginated response
         """
         columns_map = query.selected_columns
-        query = FSPManager._apply_filters(query, columns_map, self.filters)
-        query = FSPManager._apply_sort(query, columns_map, self.sorting)
+        query = self._apply_filters(query, columns_map, self.filters)
+        query = self._apply_sort(query, columns_map, self.sorting)
 
         total_items = await self._count_total_async(query, session)
         data_page = await self.paginate_async(query, session)
@@ -338,22 +404,24 @@ class FSPManager:
         )
 
     @staticmethod
-    def _coerce_value(column: ColumnElement[Any], raw: str) -> Any:
+    def _coerce_value(column: ColumnElement[Any], raw: str, pytype: Optional[type] = None) -> Any:
         """
         Coerce raw string value to column's Python type.
 
         Args:
             column: SQLAlchemy column element
             raw: Raw string value
+            pytype: Optional pre-fetched python type (for performance)
 
         Returns:
             Any: Coerced value
         """
         # Try to coerce raw (str) to the column's python type for proper comparisons
-        try:
-            pytype = getattr(column.type, "python_type", None)
-        except Exception:
-            pytype = None
+        if pytype is None:
+            try:
+                pytype = getattr(column.type, "python_type", None)
+            except Exception:
+                pytype = None
         if pytype is None or isinstance(raw, pytype):
             return raw
         # Handle booleans represented as strings
@@ -373,12 +441,17 @@ class FSPManager:
                     return int(float(raw))
                 except ValueError:
                     return raw
-        # Handle dates represented as strings
+        # Handle dates represented as strings - optimized with fast path for ISO 8601
         if pytype is datetime:
             try:
-                return parse(raw)
-            except ValueError:
-                return raw
+                # Fast path for ISO 8601 format (most common)
+                return datetime.fromisoformat(raw)
+            except (ValueError, AttributeError):
+                # Fallback to flexible dateutil parser for other formats
+                try:
+                    return parse(raw)
+                except ValueError:
+                    return raw
         # Generic cast with fallback
         try:
             return pytype(raw)
@@ -412,91 +485,96 @@ class FSPManager:
         return hasattr(col, "ilike")
 
     @staticmethod
-    def _apply_filter(query: Select, column: ColumnElement[Any], f: Filter):
+    def _build_filter_condition(
+        column: ColumnElement[Any], f: Filter, pytype: Optional[type] = None
+    ) -> Optional[Any]:
         """
-        Apply a single filter to a query.
+        Build a filter condition for a query.
 
         Args:
-            query: Base SQLAlchemy Select query
             column: Column to apply filter to
             f: Filter to apply
+            pytype: Optional pre-fetched python type (for performance)
 
         Returns:
-            Select: Query with filter applied
+            Optional[Any]: SQLAlchemy condition or None if invalid
         """
         op = f.operator  # type: FilterOperator
         raw_value = f.value  # type: str
 
         # Build conditions based on operator
         if op == FilterOperator.EQ:
-            query = query.where(column == FSPManager._coerce_value(column, raw_value))
+            return column == FSPManager._coerce_value(column, raw_value, pytype)
         elif op == FilterOperator.NE:
-            query = query.where(column != FSPManager._coerce_value(column, raw_value))
+            return column != FSPManager._coerce_value(column, raw_value, pytype)
         elif op == FilterOperator.GT:
-            query = query.where(column > FSPManager._coerce_value(column, raw_value))
+            return column > FSPManager._coerce_value(column, raw_value, pytype)
         elif op == FilterOperator.GTE:
-            query = query.where(column >= FSPManager._coerce_value(column, raw_value))
+            return column >= FSPManager._coerce_value(column, raw_value, pytype)
         elif op == FilterOperator.LT:
-            query = query.where(column < FSPManager._coerce_value(column, raw_value))
+            return column < FSPManager._coerce_value(column, raw_value, pytype)
         elif op == FilterOperator.LTE:
-            query = query.where(column <= FSPManager._coerce_value(column, raw_value))
+            return column <= FSPManager._coerce_value(column, raw_value, pytype)
         elif op == FilterOperator.LIKE:
-            query = query.where(column.like(raw_value))
+            return column.like(raw_value)
         elif op == FilterOperator.NOT_LIKE:
-            query = query.where(not_(column.like(raw_value)))
+            return not_(column.like(raw_value))
         elif op == FilterOperator.ILIKE:
             pattern = raw_value
             if FSPManager._ilike_supported(column):
-                query = query.where(column.ilike(pattern))
+                return column.ilike(pattern)
             else:
-                query = query.where(func.lower(column).like(pattern.lower()))
+                return func.lower(column).like(pattern.lower())
         elif op == FilterOperator.NOT_ILIKE:
             pattern = raw_value
             if FSPManager._ilike_supported(column):
-                query = query.where(not_(column.ilike(pattern)))
+                return not_(column.ilike(pattern))
             else:
-                query = query.where(not_(func.lower(column).like(pattern.lower())))
+                return not_(func.lower(column).like(pattern.lower()))
         elif op == FilterOperator.IN:
             vals = [
-                FSPManager._coerce_value(column, v) for v in FSPManager._split_values(raw_value)
+                FSPManager._coerce_value(column, v, pytype)
+                for v in FSPManager._split_values(raw_value)
             ]
-            query = query.where(column.in_(vals))
+            return column.in_(vals)
         elif op == FilterOperator.NOT_IN:
             vals = [
-                FSPManager._coerce_value(column, v) for v in FSPManager._split_values(raw_value)
+                FSPManager._coerce_value(column, v, pytype)
+                for v in FSPManager._split_values(raw_value)
             ]
-            query = query.where(not_(column.in_(vals)))
+            return not_(column.in_(vals))
         elif op == FilterOperator.BETWEEN:
             vals = FSPManager._split_values(raw_value)
             if len(vals) == 2:
-                # Ignore malformed between; alternatively raise 400
-                low = FSPManager._coerce_value(column, vals[0])
-                high = FSPManager._coerce_value(column, vals[1])
-                query = query.where(column.between(low, high))
+                low = FSPManager._coerce_value(column, vals[0], pytype)
+                high = FSPManager._coerce_value(column, vals[1], pytype)
+                return column.between(low, high)
+            # Ignore malformed between
+            return None
         elif op == FilterOperator.IS_NULL:
-            query = query.where(column.is_(None))
+            return column.is_(None)
         elif op == FilterOperator.IS_NOT_NULL:
-            query = query.where(column.is_not(None))
+            return column.is_not(None)
         elif op == FilterOperator.STARTS_WITH:
             pattern = f"{raw_value}%"
             if FSPManager._ilike_supported(column):
-                query = query.where(column.ilike(pattern))
+                return column.ilike(pattern)
             else:
-                query = query.where(func.lower(column).like(pattern.lower()))
+                return func.lower(column).like(pattern.lower())
         elif op == FilterOperator.ENDS_WITH:
             pattern = f"%{raw_value}"
             if FSPManager._ilike_supported(column):
-                query = query.where(column.ilike(pattern))
+                return column.ilike(pattern)
             else:
-                query = query.where(func.lower(column).like(pattern.lower()))
+                return func.lower(column).like(pattern.lower())
         elif op == FilterOperator.CONTAINS:
             pattern = f"%{raw_value}%"
             if FSPManager._ilike_supported(column):
-                query = query.where(column.ilike(pattern))
+                return column.ilike(pattern)
             else:
-                query = query.where(func.lower(column).like(pattern.lower()))
-        # Unknown operator: skip
-        return query
+                return func.lower(column).like(pattern.lower())
+        # Unknown operator
+        return None
 
     @staticmethod
     def _count_total(query: Select, session: Session) -> int:
@@ -530,8 +608,8 @@ class FSPManager:
         result = await session.exec(count_query)
         return result.one()
 
-    @staticmethod
     def _apply_filters(
+        self,
         query: Select,
         columns_map: ColumnCollection[str, ColumnElement[Any]],
         filters: Optional[List[Filter]],
@@ -546,19 +624,46 @@ class FSPManager:
 
         Returns:
             Select: Query with filters applied
+
+        Raises:
+            HTTPException: If strict_mode is True and unknown field is encountered
         """
-        if filters:
-            for f in filters:
-                # filter of `filters` has been validated in the `_parse_filters`
-                column = columns_map.get(f.field)
-                # Skip unknown fields silently
-                if column is not None:
-                    query = FSPManager._apply_filter(query, column, f)
+        if not filters:
+            return query
+
+        conditions = []
+        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()))
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=f"Unknown field '{f.field}'. Available fields: {available}",
+                    )
+                # Skip unknown fields silently in non-strict mode
+                continue
+
+            # Get column type from cache for better performance
+            pytype = self._get_column_type(column)
+            condition = FSPManager._build_filter_condition(column, f, pytype)
+            if condition is not None:
+                conditions.append(condition)
+
+        # Apply all conditions in a single where() call for better SQL generation
+        if conditions:
+            query = query.where(*conditions)
 
         return query
 
-    @staticmethod
     def _apply_sort(
+        self,
         query: Select,
         columns_map: ColumnCollection[str, ColumnElement[Any]],
         sorting: Optional[SortingQuery],
@@ -573,17 +678,30 @@ class FSPManager:
 
         Returns:
             Select: Query with sorting applied
+
+        Raises:
+            HTTPException: If strict_mode is True and unknown sort field is encountered
         """
         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
-            # Unknown sort column; skip sorting
-            if column is not None:
-                query = query.order_by(
-                    column.desc() if sorting.order == SortingOrder.DESC else column.asc()
-                )
+                column = FSPManager._get_entity_attribute(query, sorting.sort_by)
+
+            if column is None:
+                if self.strict_mode:
+                    available = ", ".join(sorted(columns_map.keys()))
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=(
+                            f"Unknown sort field '{sorting.sort_by}'. Available fields: {available}"
+                        ),
+                    )
+                # Unknown sort column; skip sorting in non-strict mode
+                return query
+
+            query = query.order_by(
+                column.desc() if sorting.order == SortingOrder.DESC else column.asc()
+            )
         return query

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-fsp
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -146,6 +146,65 @@ Notes:
 - Both formats are equivalent; the indexed format takes precedence if present.
 - If any filter is incomplete (missing operator or value in the indexed form, or mismatched counts of simple triplets), the API responds with HTTP 400.
 
+## Filtering on Computed Fields
+
+You can filter (and sort) on SQLAlchemy `hybrid_property` fields that have a SQL expression defined. This enables filtering on calculated or derived values at the database level.
+
+### Defining a Computed Field
+
+```python
+from typing import ClassVar, Optional
+from sqlalchemy import func
+from sqlalchemy.ext.hybrid import hybrid_property
+from sqlmodel import Field, SQLModel
+
+class HeroBase(SQLModel):
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None)
+    full_name: ClassVar[str]  # Required: declare as ClassVar for Pydantic
+
+    @hybrid_property
+    def full_name(self) -> str:
+        """Python-level implementation (used on instances)."""
+        return f"{self.name}-{self.secret_name}"
+
+    @full_name.expression
+    def full_name(cls):
+        """SQL-level implementation (used in queries)."""
+        return func.concat(cls.name, "-", cls.secret_name)
+
+class Hero(HeroBase, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+
+class HeroPublic(HeroBase):
+    id: int
+    full_name: str  # Include in response model
+```
+
+### Querying Computed Fields
+
+Once defined, you can filter and sort on the computed field like any regular field:
+
+```
+# Filter by computed field
+GET /heroes/?field=full_name&operator=eq&value=Spider-Man
+GET /heroes/?field=full_name&operator=ilike&value=%man
+GET /heroes/?field=full_name&operator=contains&value=Spider
+
+# Sort by computed field
+GET /heroes/?sort_by=full_name&order=asc
+
+# Combine with other filters
+GET /heroes/?field=full_name&operator=starts_with&value=Spider&field=age&operator=gte&value=21
+```
+
+### Requirements
+
+- The `hybrid_property` must have an `.expression` decorator that returns a valid SQL expression
+- 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
+
 ## Response model
 
 ```

fastapi_fsp-0.2.3.dist-info/RECORD

@@ -0,0 +1,7 @@
+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,,

fastapi_fsp-0.2.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-fastapi_fsp/__init__.py,sha256=0I_XN_ptNu1NyNRpjdyVm6nwvrilAB8FyT2EfgVF_QA,215
-fastapi_fsp/fsp.py,sha256=p7sGNRkYbiRtFPta0OvfZ12th69BjtD6h2GzSjbPoaU,19646
-fastapi_fsp/models.py,sha256=1MwLBQFmUP8OwO3Gqby1u7s9ruimCR2XGfUzAqF4Tj4,2034
-fastapi_fsp-0.2.1.dist-info/METADATA,sha256=LcnA3C98yai-Cw54cqw1t8XfDgb8YqiPhZTc1h0V3qk,6235
-fastapi_fsp-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-fastapi_fsp-0.2.1.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
-fastapi_fsp-0.2.1.dist-info/RECORD,,