fastapi-viewsets 1.4.0__tar.gz → 1.5.0__tar.gz

{fastapi_viewsets-1.4.0 → fastapi_viewsets-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi_viewsets
-Version: 1.4.0
+Version: 1.5.0
 Summary: DRF-style viewsets for FastAPI with SQLAlchemy/Tortoise/Peewee adapters and Pydantic v2 support.
 Author: Alexander Valenchits
 License: MIT
@@ -76,7 +76,7 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 - **ORM-agnostic core** — pluggable adapters for SQLAlchemy (sync/async), Tortoise ORM, and Peewee (`ORM_TYPE` / optional extras).
 - **Typed, Pydantic-first responses** with OpenAPI tags and schemas generated from your `response_model`.
 - **Declarative eager loading** (`select_related` / `prefetch_related`) via an inner `RelatedConfig` class on Pydantic schemas — eliminates N+1 without touching the viewset.
-- **Built-in list pagination** (`limit` / `offset`), optional OAuth2 on selected operations, and room to grow for search and richer filters (see Roadmap).
+- **Built-in list pagination** (`limit` / `offset`), **server-side search**, **declarative ordering** and **advanced filters** (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`) driven by an inner `ListConfig` class on Pydantic schemas, plus optional OAuth2 on selected operations.
 
 ## Feature matrix
 
@@ -86,8 +86,8 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 | `limit` / `offset` on LIST | Supported | Supported | Supported | Supported |
 | OAuth2 on selected methods (`register`) | Supported | Supported | Supported | Supported |
 | Declarative eager loading (`select_related` / `prefetch_related`) | Supported | Supported | Supported (`prefetch_related`) | Supported (`select_related`) |
-| `search` query on LIST (server-side) | **Roadmap** | **Roadmap** | **Roadmap** | **Roadmap** |
-| Declarative ordering / advanced filters | **Roadmap** | **Roadmap** | **Roadmap** | **Roadmap** |
+| `search` query on LIST (server-side) | Supported | Supported | Supported | Supported |
+| Declarative ordering / advanced filters | Supported | Supported | Supported | Supported |
 
 ## Installation
 
@@ -680,26 +680,25 @@ def pagination_hint() -> str:
     return "limit and offset are parsed by `BaseViewset.list`"
 ```
 
-**Filtering** — `list` accepts `search`, but ORM adapters ignore it today; server-side search is on the Roadmap. Subclass `BaseViewset` and override `list()` with your own query until then.
+**Search, ordering and filters** — declare a `ListConfig` inner class on the response schema and the LIST endpoint gains `?search=`, `?ordering=` and whitelisted `?<field>` / `?<field>__<op>` query parameters, applied server-side by every ORM adapter:
 
 ```python
-from fastapi_viewsets import BaseViewset
-
-def filtering_hint() -> str:
-    """Explain that `search` is reserved; override `list` for real filters today."""
-    return "search parameter is not yet applied in adapters"
-```
+from pydantic import BaseModel
 
-**Ordering** — there is no shared `order_by` helper yet; override `list()` with an ordered query or wait for the Roadmap.
-
-```python
-from fastapi_viewsets import BaseViewset
+class ItemSchema(BaseModel):
+    id: int
+    name: str
+    status: str
 
-def ordering_hint() -> str:
-    """Note the absence of a built-in ordering helper on LIST endpoints."""
-    return "override list or wait for roadmap ordering helpers"
+    class ListConfig:
+        search_fields = ["name"]
+        ordering_fields = ["name", "id"]
+        ordering = ["-id"]
+        filters = ["status"]
 ```
 
+`GET /items?search=foo&ordering=name&status=active` then works out of the box. Operators: `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in` (e.g. `?status__in=active,pending`). Fields outside the whitelist are ignored; ordering by an unknown field returns `400`. Without a `ListConfig`, LIST behaves exactly as before.
+
 ## Permissions and custom routes
 
 There is no `get_queryset` hook; scope queries by subclassing `BaseViewset` and overriding `list()`, `get_element()`, or related handlers. The class subclasses `APIRouter`, so attach extra endpoints with `add_api_route` **before** `register()` if paths must win over `/{id}`:
@@ -755,16 +754,17 @@ Details: [RELEASE_NOTES.md](RELEASE_NOTES.md), [RELEASE_1.2.0.md](RELEASE_1.2.0.
 
 | Item | Target | Status |
 | --- | --- | --- |
-| Wire `search` on LIST to real database queries | v1.4 | Planned |
-| Transaction helpers (`begin` / `atomic`) across adapters | v1.4 | Planned |
-| Declarative ordering (`order_by`) on LIST endpoints | v1.4 | Planned |
-| Advanced filters (`__gt`, `__lt`, `__in`) via query params | v1.5 | Planned |
+| Transaction helpers (`begin` / `atomic`) across adapters | future | Planned |
+| Range filters on dates (`date__range`) and null checks (`field__isnull`) | future | Planned |
+| Cross-relation search (searching through `select_related` fields) | future | Planned |
+
+Released: server-side `search` (v1.5.0), declarative ordering and advanced filters (v1.5.0).
 
 ## Comparison with alternatives
 
 | Approach | Developer experience | ORM support | Permissions | Filtering |
 | --- | --- | --- | --- | --- |
-| fastapi-viewsets | One `BaseViewset` registers CRUD routes | SQLAlchemy sync/async, Tortoise, Peewee via adapters | OAuth2 per logical method via `register` | `limit`/`offset` today; `search` and advanced filters on Roadmap |
+| fastapi-viewsets | One `BaseViewset` registers CRUD routes | SQLAlchemy sync/async, Tortoise, Peewee via adapters | OAuth2 per logical method via `register` | `limit`/`offset`, `search`, `ordering` and operator filters via `ListConfig` |
 | fastapi-crudrouter | CRUD-focused generators, less ViewSet-shaped | Primarily SQLAlchemy | Custom middleware/deps | Often extended manually |
 | Hand-rolled FastAPI | Full control, most boilerplate | Any ORM you integrate | Fully custom | Fully custom |
 

{fastapi_viewsets-1.4.0 → fastapi_viewsets-1.5.0}/README.md

@@ -21,7 +21,7 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 - **ORM-agnostic core** — pluggable adapters for SQLAlchemy (sync/async), Tortoise ORM, and Peewee (`ORM_TYPE` / optional extras).
 - **Typed, Pydantic-first responses** with OpenAPI tags and schemas generated from your `response_model`.
 - **Declarative eager loading** (`select_related` / `prefetch_related`) via an inner `RelatedConfig` class on Pydantic schemas — eliminates N+1 without touching the viewset.
-- **Built-in list pagination** (`limit` / `offset`), optional OAuth2 on selected operations, and room to grow for search and richer filters (see Roadmap).
+- **Built-in list pagination** (`limit` / `offset`), **server-side search**, **declarative ordering** and **advanced filters** (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`) driven by an inner `ListConfig` class on Pydantic schemas, plus optional OAuth2 on selected operations.
 
 ## Feature matrix
 
@@ -31,8 +31,8 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 | `limit` / `offset` on LIST | Supported | Supported | Supported | Supported |
 | OAuth2 on selected methods (`register`) | Supported | Supported | Supported | Supported |
 | Declarative eager loading (`select_related` / `prefetch_related`) | Supported | Supported | Supported (`prefetch_related`) | Supported (`select_related`) |
-| `search` query on LIST (server-side) | **Roadmap** | **Roadmap** | **Roadmap** | **Roadmap** |
-| Declarative ordering / advanced filters | **Roadmap** | **Roadmap** | **Roadmap** | **Roadmap** |
+| `search` query on LIST (server-side) | Supported | Supported | Supported | Supported |
+| Declarative ordering / advanced filters | Supported | Supported | Supported | Supported |
 
 ## Installation
 
@@ -625,26 +625,25 @@ def pagination_hint() -> str:
     return "limit and offset are parsed by `BaseViewset.list`"
 ```
 
-**Filtering** — `list` accepts `search`, but ORM adapters ignore it today; server-side search is on the Roadmap. Subclass `BaseViewset` and override `list()` with your own query until then.
+**Search, ordering and filters** — declare a `ListConfig` inner class on the response schema and the LIST endpoint gains `?search=`, `?ordering=` and whitelisted `?<field>` / `?<field>__<op>` query parameters, applied server-side by every ORM adapter:
 
 ```python
-from fastapi_viewsets import BaseViewset
-
-def filtering_hint() -> str:
-    """Explain that `search` is reserved; override `list` for real filters today."""
-    return "search parameter is not yet applied in adapters"
-```
+from pydantic import BaseModel
 
-**Ordering** — there is no shared `order_by` helper yet; override `list()` with an ordered query or wait for the Roadmap.
-
-```python
-from fastapi_viewsets import BaseViewset
+class ItemSchema(BaseModel):
+    id: int
+    name: str
+    status: str
 
-def ordering_hint() -> str:
-    """Note the absence of a built-in ordering helper on LIST endpoints."""
-    return "override list or wait for roadmap ordering helpers"
+    class ListConfig:
+        search_fields = ["name"]
+        ordering_fields = ["name", "id"]
+        ordering = ["-id"]
+        filters = ["status"]
 ```
 
+`GET /items?search=foo&ordering=name&status=active` then works out of the box. Operators: `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in` (e.g. `?status__in=active,pending`). Fields outside the whitelist are ignored; ordering by an unknown field returns `400`. Without a `ListConfig`, LIST behaves exactly as before.
+
 ## Permissions and custom routes
 
 There is no `get_queryset` hook; scope queries by subclassing `BaseViewset` and overriding `list()`, `get_element()`, or related handlers. The class subclasses `APIRouter`, so attach extra endpoints with `add_api_route` **before** `register()` if paths must win over `/{id}`:
@@ -700,16 +699,17 @@ Details: [RELEASE_NOTES.md](RELEASE_NOTES.md), [RELEASE_1.2.0.md](RELEASE_1.2.0.
 
 | Item | Target | Status |
 | --- | --- | --- |
-| Wire `search` on LIST to real database queries | v1.4 | Planned |
-| Transaction helpers (`begin` / `atomic`) across adapters | v1.4 | Planned |
-| Declarative ordering (`order_by`) on LIST endpoints | v1.4 | Planned |
-| Advanced filters (`__gt`, `__lt`, `__in`) via query params | v1.5 | Planned |
+| Transaction helpers (`begin` / `atomic`) across adapters | future | Planned |
+| Range filters on dates (`date__range`) and null checks (`field__isnull`) | future | Planned |
+| Cross-relation search (searching through `select_related` fields) | future | Planned |
+
+Released: server-side `search` (v1.5.0), declarative ordering and advanced filters (v1.5.0).
 
 ## Comparison with alternatives
 
 | Approach | Developer experience | ORM support | Permissions | Filtering |
 | --- | --- | --- | --- | --- |
-| fastapi-viewsets | One `BaseViewset` registers CRUD routes | SQLAlchemy sync/async, Tortoise, Peewee via adapters | OAuth2 per logical method via `register` | `limit`/`offset` today; `search` and advanced filters on Roadmap |
+| fastapi-viewsets | One `BaseViewset` registers CRUD routes | SQLAlchemy sync/async, Tortoise, Peewee via adapters | OAuth2 per logical method via `register` | `limit`/`offset`, `search`, `ordering` and operator filters via `ListConfig` |
 | fastapi-crudrouter | CRUD-focused generators, less ViewSet-shaped | Primarily SQLAlchemy | Custom middleware/deps | Often extended manually |
 | Hand-rolled FastAPI | Full control, most boilerplate | Any ORM you integrate | Fully custom | Fully custom |
 

{fastapi_viewsets-1.4.0 → fastapi_viewsets-1.5.0}/fastapi_viewsets/__init__.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 from typing import Any, Callable, Dict, List, Optional, Type, TypeVar, Union
 
-from fastapi import APIRouter, Body, Depends
+from fastapi import APIRouter, Body, Depends, Request
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
@@ -94,9 +94,30 @@ class BaseViewset(_RegisterMixin, APIRouter):
         limit: Optional[int] = 10,
         offset: Optional[int] = 0,
         search: Optional[str] = None,
+        ordering: Optional[str] = None,
+        request: Request = None,
         token: str = Depends(_noop_dependency),
     ) -> List[ResponseModelType]:
-        """List items with ``limit``/``offset`` pagination."""
+        """List items with pagination, search, ordering and filters.
+
+        Query parameters (behaviour is driven by the response schema's
+        ``ListConfig`` — see :mod:`fastapi_viewsets.filtering`):
+
+        * ``limit`` / ``offset`` — pagination.
+        * ``search`` — case-insensitive substring match across
+          ``ListConfig.search_fields``.
+        * ``ordering`` — comma-separated fields, ``-`` prefix for
+          descending, validated against ``ListConfig.ordering_fields``.
+        * ``<field>`` / ``<field>__<op>`` — exact and comparison filters
+          on ``ListConfig.filters`` fields.
+        """
+        from fastapi_viewsets.filtering import (
+            get_list_config,
+            parse_filters,
+            parse_ordering_param,
+        )
+
+        config = get_list_config(self.response_model)
         return get_list_queryset(
             self.model,
             db_session=self.db_session,
@@ -104,6 +125,13 @@ class BaseViewset(_RegisterMixin, APIRouter):
             offset=offset,
             orm_adapter=self.orm_adapter,
             response_model=self.response_model,
+            search=search,
+            ordering=parse_ordering_param(
+                ordering, config.ordering_fields, config.ordering
+            ),
+            filters=parse_filters(request.query_params, config.filters)
+            if request is not None
+            else None,
         )
 
     def get_element(

{fastapi_viewsets-1.4.0 → fastapi_viewsets-1.5.0}/fastapi_viewsets/async_base.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Any, Callable, Dict, List, Optional, Type, TypeVar, Union
 
-from fastapi import APIRouter, Body, Depends
+from fastapi import APIRouter, Body, Depends, Request
 from pydantic import BaseModel
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -85,9 +85,30 @@ class AsyncBaseViewset(_RegisterMixin, APIRouter):
         limit: Optional[int] = 10,
         offset: Optional[int] = 0,
         search: Optional[str] = None,
+        ordering: Optional[str] = None,
+        request: Request = None,
         token: str = Depends(_noop_dependency),
     ) -> List[ResponseModelType]:
-        """List items with ``limit``/``offset`` pagination (async)."""
+        """List items with pagination, search, ordering and filters (async).
+
+        Query parameters (behaviour is driven by the response schema's
+        ``ListConfig`` — see :mod:`fastapi_viewsets.filtering`):
+
+        * ``limit`` / ``offset`` — pagination.
+        * ``search`` — case-insensitive substring match across
+          ``ListConfig.search_fields``.
+        * ``ordering`` — comma-separated fields, ``-`` prefix for
+          descending, validated against ``ListConfig.ordering_fields``.
+        * ``<field>`` / ``<field>__<op>`` — exact and comparison filters
+          on ``ListConfig.filters`` fields.
+        """
+        from fastapi_viewsets.filtering import (
+            get_list_config,
+            parse_filters,
+            parse_ordering_param,
+        )
+
+        config = get_list_config(self.response_model)
         return await get_list_queryset(
             self.model,
             db_session=self.db_session,
@@ -95,6 +116,13 @@ class AsyncBaseViewset(_RegisterMixin, APIRouter):
             offset=offset,
             orm_adapter=self.orm_adapter,
             response_model=self.response_model,
+            search=search,
+            ordering=parse_ordering_param(
+                ordering, config.ordering_fields, config.ordering
+            ),
+            filters=parse_filters(request.query_params, config.filters)
+            if request is not None
+            else None,
         )
 
     async def get_element(

{fastapi_viewsets-1.4.0 → fastapi_viewsets-1.5.0}/fastapi_viewsets/async_utils.py

@@ -7,11 +7,49 @@ from pydantic import BaseModel
 from fastapi_viewsets.orm.base import BaseORMAdapter
 from fastapi_viewsets.db_conf import get_orm_adapter
 from fastapi_viewsets.serializer_utils import get_select_related, get_prefetch_related
+from fastapi_viewsets.filtering import get_list_config
 
 # Type variable for ORM models
 ModelType = TypeVar('ModelType')
 
 
+def _resolve_list_options(
+    response_model: Optional[Type[BaseModel]],
+    search: Optional[str],
+    search_fields: Optional[List[str]],
+    ordering: Optional[List[str]],
+):
+    """Fill in declarative ``ListConfig`` defaults for search/ordering."""
+    if search_fields is None and search:
+        search_fields = get_list_config(response_model).search_fields
+    if ordering is None:
+        ordering = get_list_config(response_model).ordering or None
+    return search_fields, ordering
+
+
+def _list_extra_kwargs(
+    search: Optional[str],
+    search_fields: Optional[List[str]],
+    ordering: Optional[List[str]],
+    filters: Optional[Dict[str, Any]],
+) -> Dict[str, Any]:
+    """Build adapter kwargs for search/ordering/filters.
+
+    Only non-empty values are included so custom ORM adapters that do
+    not (yet) accept the new keyword arguments keep working.
+    """
+    extra: Dict[str, Any] = {}
+    if search:
+        extra["search"] = search
+    if search_fields:
+        extra["search_fields"] = search_fields
+    if ordering:
+        extra["ordering"] = ordering
+    if filters:
+        extra["filters"] = filters
+    return extra
+
+
 async def get_list_queryset(
     model: Type[ModelType],
     db_session: Callable[[], Any],
@@ -21,6 +59,10 @@ async def get_list_queryset(
     response_model: Optional[Type[BaseModel]] = None,
     select_related: Optional[List[str]] = None,
     prefetch_related: Optional[List[str]] = None,
+    search: Optional[str] = None,
+    search_fields: Optional[List[str]] = None,
+    ordering: Optional[List[str]] = None,
+    filters: Optional[Dict[str, Any]] = None,
 ) -> List[ModelType]:
     """Get list of elements from database with pagination support (async).
     
@@ -31,8 +73,16 @@ async def get_list_queryset(
         offset: Number of items to skip
         orm_adapter: ORM adapter instance (optional, uses default if not provided)
         response_model: Pydantic schema that may define ``RelatedConfig``
+            and ``ListConfig``
         select_related: Explicit list of FK relations to join (overrides schema config)
         prefetch_related: Explicit list of collection relations to prefetch (overrides schema config)
+        search: Search term for case-insensitive substring matching
+        search_fields: Fields to search across (defaults to
+            ``ListConfig.search_fields`` from the response schema)
+        ordering: Ordering tokens like ``["-name"]`` (defaults to the
+            declarative ``ListConfig.ordering`` from the response schema)
+        filters: Parsed filter constraints, mapping field name to
+            ``(operator, value)`` (see :mod:`fastapi_viewsets.filtering`)
         
     Returns:
         List of model instances
@@ -44,11 +94,15 @@ async def get_list_queryset(
         select_related = get_select_related(response_model)
     if prefetch_related is None and response_model is not None:
         prefetch_related = get_prefetch_related(response_model)
+    search_fields, ordering = _resolve_list_options(
+        response_model, search, search_fields, ordering
+    )
     
     return await orm_adapter.get_list_queryset_async(
         model, db_session, limit, offset,
         select_related=select_related or None,
         prefetch_related=prefetch_related or None,
+        **_list_extra_kwargs(search, search_fields, ordering, filters),
     )
 
 

fastapi_viewsets-1.5.0/fastapi_viewsets/filtering.py

@@ -0,0 +1,197 @@
+"""Server-side search, ordering and filtering for LIST endpoints.
+
+Configuration is declarative: a Pydantic response schema may declare an
+inner ``ListConfig`` class::
+
+    class UserSchema(BaseModel):
+        class RelatedConfig:
+            select_related = ["company"]
+
+        class ListConfig:
+            search_fields = ["name", "email"]
+            ordering_fields = ["name", "created_at"]
+            ordering = ["-created_at"]
+            filters = ["status", "age", "company_id"]
+
+The viewset ``list`` handler then automatically supports:
+
+* ``?search=term`` — case-insensitive substring match, OR-ed across
+  ``search_fields``.
+* ``?ordering=-name,created_at`` — ordering validated against
+  ``ordering_fields``; a leading ``-`` means descending. When the query
+  parameter is omitted (or ordering is not enabled), the declarative
+  default ``ordering`` applies.
+* ``?<field>=value`` and ``?<field>__<op>=value`` — exact-match and
+  comparison filtering, restricted to the fields listed in ``filters``.
+  Supported operators: ``ne``, ``gt``, ``gte``, ``lt``, ``lte``,
+  ``contains`` (case-insensitive substring) and ``in``
+  (comma-separated values).
+
+All configuration is optional; without a ``ListConfig`` the LIST
+endpoint behaves exactly as before (backward compatible).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field as dc_field
+from typing import Any, Dict, List, Mapping, Optional, Tuple, Type
+
+from fastapi import HTTPException
+from pydantic import BaseModel
+from starlette import status
+
+# Operators accepted after a field name in query params: ?age__gte=18
+FILTER_OPS = ("ne", "gt", "gte", "lt", "lte", "contains", "in")
+
+
+@dataclass(frozen=True)
+class ListConfig:
+    """Declarative LIST configuration read from a schema's ``ListConfig``."""
+
+    search_fields: List[str] = dc_field(default_factory=list)
+    ordering_fields: List[str] = dc_field(default_factory=list)
+    ordering: List[str] = dc_field(default_factory=list)
+    filters: List[str] = dc_field(default_factory=list)
+
+
+def get_list_config(response_model: Optional[Type[BaseModel]]) -> ListConfig:
+    """Read ``ListConfig`` from a Pydantic schema (if present).
+
+    Args:
+        response_model: Pydantic BaseModel subclass that may define an
+            inner ``ListConfig`` class.
+
+    Returns:
+        A :class:`ListConfig` with whatever attributes were declared;
+        an all-empty config when the schema declares nothing.
+    """
+    if response_model is None:
+        return ListConfig()
+    cfg = getattr(response_model, "ListConfig", None)
+    if cfg is None:
+        return ListConfig()
+    return ListConfig(
+        search_fields=list(getattr(cfg, "search_fields", []) or []),
+        ordering_fields=list(getattr(cfg, "ordering_fields", []) or []),
+        ordering=list(getattr(cfg, "ordering", []) or []),
+        filters=list(getattr(cfg, "filters", []) or []),
+    )
+
+
+def coerce_value(raw: str) -> Any:
+    """Coerce a raw query-param string to int/float/bool when possible.
+
+    Args:
+        raw: Raw string value from a query parameter.
+
+    Returns:
+        ``int``, ``float`` or ``bool`` when the string parses as one,
+        otherwise the original string.
+    """
+    if raw is None:
+        return None
+    text = str(raw).strip()
+    lowered = text.lower()
+    if lowered in ("true", "false"):
+        return lowered == "true"
+    try:
+        return int(text)
+    except ValueError:
+        pass
+    try:
+        return float(text)
+    except ValueError:
+        pass
+    return text
+
+
+def parse_ordering_param(
+    ordering: Optional[str],
+    ordering_fields: Optional[List[str]] = None,
+    default: Optional[List[str]] = None,
+) -> Optional[List[str]]:
+    """Parse the ``ordering`` query parameter into ordering tokens.
+
+    Args:
+        ordering: Raw ``?ordering=`` value, e.g. ``"-name,created_at"``.
+        ordering_fields: Whitelist of fields that may be used. When
+            empty/None the whitelist is not enforced.
+        default: Declarative default ordering used when ``ordering`` is
+            empty or None.
+
+    Returns:
+        List of tokens such as ``["-name", "created_at"]``, or None when
+        neither the parameter nor a default is provided.
+
+    Raises:
+        HTTPException: 400 when the parameter references a field outside
+            ``ordering_fields``.
+    """
+    if ordering is None or not ordering.strip():
+        return list(default) if default else None
+
+    allowed = set(ordering_fields or [])
+    if not allowed:
+        # Ordering is not enabled for this schema; ignore the parameter
+        # so arbitrary field names never reach the ORM.
+        return list(default) if default else None
+
+    tokens = [token.strip() for token in ordering.split(",") if token.strip()]
+    for token in tokens:
+        field_name = token.lstrip("-").strip()
+        if allowed and field_name not in allowed:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=(
+                    f"Invalid ordering field: '{field_name}'. "
+                    f"Allowed fields: {sorted(allowed)}"
+                ),
+            )
+    return tokens or (list(default) if default else None)
+
+
+def parse_filters(
+    query_params: Mapping[str, Any],
+    allowed_fields: Optional[List[str]] = None,
+) -> Dict[str, Tuple[str, Any]]:
+    """Extract filter constraints from request query parameters.
+
+    Only fields listed in ``allowed_fields`` are extracted; everything
+    else (including ``limit``, ``offset``, ``search`` and ``ordering``)
+    is ignored.
+
+    Args:
+        query_params: Query parameters mapping (e.g.
+            ``request.query_params``).
+        allowed_fields: Whitelist of filterable field names.
+
+    Returns:
+        Mapping ``field -> (operator, value)`` where operator is one of
+        ``"eq"``, ``"ne"``, ``"gt"``, ``"gte"``, ``"lt"``, ``"lte"``,
+        ``"contains"``, ``"in"``. For ``"in"`` the value is a list.
+    """
+    allowed = set(allowed_fields or [])
+    if not allowed:
+        return {}
+
+    filters: Dict[str, Tuple[str, Any]] = {}
+    for key, raw in query_params.items():
+        if key in ("limit", "offset", "search", "ordering", "token"):
+            continue
+        if key not in allowed:
+            # Maybe an operator suffix: field__op
+            if "__" in key:
+                base, op = key.rsplit("__", 1)
+                if base in allowed and op in FILTER_OPS:
+                    value: Any = (
+                        [coerce_value(part) for part in str(raw).split(",")]
+                        if op == "in"
+                        else coerce_value(raw)
+                    )
+                    filters[base] = (op, value)
+            continue
+        if raw is None or str(raw) == "":
+            continue
+        filters[key] = ("eq", coerce_value(raw))
+    return filters

{fastapi_viewsets-1.4.0 → fastapi_viewsets-1.5.0}/fastapi_viewsets/orm/base.py

@@ -1,7 +1,7 @@
 """Base abstract class for ORM adapters."""
 
 from abc import ABC, abstractmethod
-from typing import Optional, Dict, Any, Union, Type, TypeVar, List, Callable
+from typing import Optional, Dict, Any, Tuple, Union, Type, TypeVar, List, Callable
 
 # Type variable for ORM models
 ModelType = TypeVar('ModelType')
@@ -54,6 +54,10 @@ class BaseORMAdapter(ABC):
         offset: Optional[int] = None,
         select_related: Optional[List[str]] = None,
         prefetch_related: Optional[List[str]] = None,
+        search: Optional[str] = None,
+        search_fields: Optional[List[str]] = None,
+        ordering: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Tuple[str, Any]]] = None,
     ) -> List[ModelType]:
         """Get list of elements from database with pagination support (synchronous).
         
@@ -62,6 +66,12 @@ class BaseORMAdapter(ABC):
             db_session: Database session factory function
             limit: Maximum number of items to return
             offset: Number of items to skip
+            select_related: FK relations to join
+            prefetch_related: Collection relations to prefetch
+            search: Search term (case-insensitive substring match)
+            search_fields: Fields to search across
+            ordering: Ordering tokens, e.g. ["-name", "created_at"]
+            filters: Mapping field -> (operator, value) for filtering
             
         Returns:
             List of model instances
@@ -77,6 +87,10 @@ class BaseORMAdapter(ABC):
         offset: Optional[int] = None,
         select_related: Optional[List[str]] = None,
         prefetch_related: Optional[List[str]] = None,
+        search: Optional[str] = None,
+        search_fields: Optional[List[str]] = None,
+        ordering: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Tuple[str, Any]]] = None,
     ) -> List[ModelType]:
         """Get list of elements from database with pagination support (asynchronous).
         
@@ -85,6 +99,12 @@ class BaseORMAdapter(ABC):
             db_session: Async database session factory function
             limit: Maximum number of items to return
             offset: Number of items to skip
+            select_related: FK relations to join
+            prefetch_related: Collection relations to prefetch
+            search: Search term (case-insensitive substring match)
+            search_fields: Fields to search across
+            ordering: Ordering tokens, e.g. ["-name", "created_at"]
+            filters: Mapping field -> (operator, value) for filtering
             
         Returns:
             List of model instances