fastapi-fsp 0.1.1__tar.gz → 0.1.3__tar.gz

{fastapi_fsp-0.1.1 → fastapi_fsp-0.1.3}/.github/workflows/ci.yml

@@ -8,6 +8,9 @@ on:
 jobs:
   build-test-lint:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13', '3.14']
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -15,7 +18,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: ${{ matrix.python-version }}
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v4
@@ -38,7 +41,7 @@ jobs:
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: coverage-reports
+          name: coverage-reports-${{ matrix.python-version }}
           path: |
             coverage.xml
             htmlcov

{fastapi_fsp-0.1.1 → fastapi_fsp-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-fsp
-Version: 0.1.1
+Version: 0.1.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
@@ -16,11 +16,13 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
-Requires-Dist: fastapi>=0.111
-Requires-Dist: sqlmodel>=0.0.24
+Requires-Dist: fastapi>=0.121.1
+Requires-Dist: sqlmodel>=0.0.27
 Description-Content-Type: text/markdown
 
 # fastapi-fsp
@@ -109,7 +111,9 @@ Sorting:
 - sort_by: the field name, e.g., `name`
 - order: `asc` or `desc`
 
-Filtering (repeatable sets; arrays are supported by sending multiple parameters):
+Filtering (two supported formats):
+
+1) Simple (triplets repeated in the query string):
 - field: the field/column name, e.g., `name`
 - operator: one of
   - eq, ne
@@ -122,17 +126,25 @@ Filtering (repeatable sets; arrays are supported by sending multiple parameters)
   - contains, starts_with, ends_with (translated to LIKE patterns)
 - value: raw string value (or list-like comma-separated depending on operator)
 
-Examples:
+Examples (simple format):
 - `?field=name&operator=eq&value=Deadpond`
 - `?field=age&operator=between&value=18,30`
 - `?field=name&operator=in&value=Deadpond,Rusty-Man`
 - `?field=name&operator=contains&value=man`
+- Chain multiple filters by repeating the triplet: `?field=age&operator=gte&value=18&field=name&operator=ilike&value=rust`
+
+2) Indexed format (useful for clients that handle arrays of objects):
+- Use keys like `filters[0][field]`, `filters[0][operator]`, `filters[0][value]`, then increment the index for additional filters (`filters[1][...]`, etc.).
 
-You can chain multiple filters by repeating the triplet:
+Example (indexed format):
 ```
-?field=age&operator=gte&value=18&field=name&operator=ilike&value=rust
+?filters[0][field]=age&filters[0][operator]=gte&filters[0][value]=18&filters[1][field]=name&filters[1][operator]=ilike&filters[1][value]=joy
 ```
 
+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.
+
 ## Response model
 
 ```

{fastapi_fsp-0.1.1 → fastapi_fsp-0.1.3}/README.md

@@ -84,7 +84,9 @@ Sorting:
 - sort_by: the field name, e.g., `name`
 - order: `asc` or `desc`
 
-Filtering (repeatable sets; arrays are supported by sending multiple parameters):
+Filtering (two supported formats):
+
+1) Simple (triplets repeated in the query string):
 - field: the field/column name, e.g., `name`
 - operator: one of
   - eq, ne
@@ -97,17 +99,25 @@ Filtering (repeatable sets; arrays are supported by sending multiple parameters)
   - contains, starts_with, ends_with (translated to LIKE patterns)
 - value: raw string value (or list-like comma-separated depending on operator)
 
-Examples:
+Examples (simple format):
 - `?field=name&operator=eq&value=Deadpond`
 - `?field=age&operator=between&value=18,30`
 - `?field=name&operator=in&value=Deadpond,Rusty-Man`
 - `?field=name&operator=contains&value=man`
+- Chain multiple filters by repeating the triplet: `?field=age&operator=gte&value=18&field=name&operator=ilike&value=rust`
+
+2) Indexed format (useful for clients that handle arrays of objects):
+- Use keys like `filters[0][field]`, `filters[0][operator]`, `filters[0][value]`, then increment the index for additional filters (`filters[1][...]`, etc.).
 
-You can chain multiple filters by repeating the triplet:
+Example (indexed format):
 ```
-?field=age&operator=gte&value=18&field=name&operator=ilike&value=rust
+?filters[0][field]=age&filters[0][operator]=gte&filters[0][value]=18&filters[1][field]=name&filters[1][operator]=ilike&filters[1][value]=joy
 ```
 
+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.
+
 ## Response model
 
 ```

{fastapi_fsp-0.1.1 → fastapi_fsp-0.1.3}/fastapi_fsp/fsp.py

@@ -2,6 +2,7 @@ import math
 from typing import Annotated, Any, List, Optional
 
 from fastapi import Depends, HTTPException, Query, Request, status
+from pydantic import ValidationError
 from sqlalchemy import Select, func
 from sqlmodel import Session, not_, select
 from sqlmodel.ext.asyncio.session import AsyncSession
@@ -19,22 +20,90 @@ from fastapi_fsp.models import (
 )
 
 
-def _parse_filters(
-    fields: Optional[List[str]] = Query(None, alias="field"),
-    operators: Optional[List[FilterOperator]] = Query(None, alias="operator"),
-    values: Optional[List[str]] = Query(None, alias="value"),
-) -> List[Filter] | None:
-    if not fields:
-        return None
-    filters: List[Filter] = []
-    if operators is None or values is None or not (len(fields) == len(operators) == len(values)):
+def _parse_one_filter_at(i: int, field: str, operator: str, value: str) -> Filter:
+    try:
+        filter_ = Filter(field=field, operator=FilterOperator(operator), value=value)
+    except ValidationError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid filter at index {i}: {str(e)}",
+        ) from e
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid operator '{operator}' at index {i}.",
+        ) from e
+    return filter_
+
+
+def _parse_array_of_filters(
+    fields: List[str], operators: List[str], values: List[str]
+) -> List[Filter]:
+    # Validate that we have matching lengths
+    if not (len(fields) == len(operators) == len(values)):
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail="Mismatched filter parameters.",
+            detail="Mismatched filter parameters in array format.",
         )
-    for field, operator, value in zip(fields, operators, values):
-        filters.append(Filter(field=field, operator=operator, value=value))
-    return filters
+    return [
+        _parse_one_filter_at(i, field, operator, value)
+        for i, (field, operator, value) in enumerate(zip(fields, operators, values))
+    ]
+
+
+def _parse_filters(
+    request: Request,
+) -> Optional[List[Filter]]:
+    """
+    Parse filters from query parameters supporting two formats:
+    1. Indexed format:
+       ?filters[0][field]=age&filters[0][operator]=gte&filters[0][value]=18&filters[1][field]=name&filters[1][operator]=ilike&filters[1][value]=joy
+    2. Simple format:
+       ?field=age&operator=gte&value=18&field=name&operator=ilike&value=joy
+    """
+    query_params = request.query_params
+    filters = []
+
+    # Try indexed format first: filters[0][field], filters[0][operator], etc.
+    i = 0
+    while True:
+        field_key = f"filters[{i}][field]"
+        operator_key = f"filters[{i}][operator]"
+        value_key = f"filters[{i}][value]"
+
+        field = query_params.get(field_key)
+        operator = query_params.get(operator_key)
+        value = query_params.get(value_key)
+
+        # If we don't have a field at this index, break the loop
+        if field is None:
+            break
+
+        # Validate that we have all required parts
+        if operator is None or value is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Incomplete filter at index {i}. Missing operator or value.",
+            )
+
+        filters.append(_parse_one_filter_at(i, field, operator, value))
+        i += 1
+
+    # If we found indexed filters, return them
+    if filters:
+        return filters
+
+    # Fall back to simple format: field, operator, value
+    filters = _parse_array_of_filters(
+        query_params.getlist("field"),
+        query_params.getlist("operator"),
+        query_params.getlist("value"),
+    )
+    if filters:
+        return filters
+
+    # No filters found
+    return None
 
 
 def _parse_sort(

{fastapi_fsp-0.1.1 → fastapi_fsp-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi-fsp"
-version = "0.1.1"
+version = "0.1.3"
 description = "Filter, Sort, and Paginate (FSP) utilities for FastAPI + SQLModel"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -20,13 +20,15 @@ classifiers = [
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Framework :: FastAPI",
   "Topic :: Internet :: WWW/HTTP",
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "fastapi>=0.111",
-    "sqlmodel>=0.0.24",
+    "fastapi>=0.121.1",
+    "sqlmodel>=0.0.27",
 ]
 
 [project.urls]

fastapi_fsp-0.1.3/tests/test_fsp_filters_indexed_sync.py

@@ -0,0 +1,46 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session
+
+from tests.main import Hero
+
+
+def seed(session: Session):
+    session.add_all(
+        [
+            Hero(name="Deadpond", secret_name="Dive Wilson", age=None),
+            Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48),
+            Hero(name="ALPHA", secret_name="Alpha Secret", age=10),
+            Hero(name="beta", secret_name="Beta Secret", age=20),
+        ]
+    )
+    session.commit()
+
+
+def test_indexed_single_filter_eq(session: Session, client: TestClient):
+    seed(session)
+    r = client.get(
+        "/heroes/?filters[0][field]=name&filters[0][operator]=eq&filters[0][value]=Deadpond"
+    )
+    assert r.status_code == 200
+    js = r.json()
+    assert len(js["data"]) == 1
+    assert js["data"][0]["name"] == "Deadpond"
+
+
+def test_indexed_multiple_filters_combined(session: Session, client: TestClient):
+    seed(session)
+    # age >= 18 AND name ILIKE '%eta'
+    r = client.get(
+        "/heroes/?filters[0][field]=age&filters[0][operator]=gte&filters[0][value]=18"
+        "&filters[1][field]=name&filters[1][operator]=ilike&filters[1][value]=%25eta"
+    )
+    assert r.status_code == 200
+    names = [h["name"] for h in r.json()["data"]]
+    # Only 'beta' is age >= 18 and ends with 'eta'
+    assert set(names) == {"beta"}
+
+
+def test_indexed_incomplete_filter_returns_400(session: Session, client: TestClient):
+    seed(session)
+    r = client.get("/heroes/?filters[0][field]=age&filters[0][operator]=gte")
+    assert r.status_code == 400