fastapi-fsp 0.1.0__py3-none-any.whl

fastapi_fsp/__init__.py

@@ -0,0 +1,9 @@
+"""fastapi-fsp: Filter, Sort, and Paginate utilities for FastAPI + SQLModel."""
+
+from . import models as models  # noqa: F401
+from .fsp import FSPManager  # noqa: F401
+
+__all__ = [
+    "FSPManager",
+    "models",
+]

fastapi_fsp/fsp.py

@@ -0,0 +1,269 @@
+import math
+from typing import Annotated, Any, List, Optional
+
+from fastapi import Depends, HTTPException, Query, Request, status
+from sqlalchemy import Select, func
+from sqlmodel import Session, select
+
+from fastapi_fsp.models import (
+    Filter,
+    FilterOperator,
+    Links,
+    Meta,
+    PaginatedResponse,
+    Pagination,
+    PaginationQuery,
+    SortingOrder,
+    SortingQuery,
+)
+
+
+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 not (len(fields) == len(operators) == len(values)):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Mismatched filter parameters.",
+        )
+    for field, operator, value in zip(fields, operators, values):
+        filters.append(Filter(field=field, operator=operator, value=value))
+    return filters
+
+
+def _parse_sort(
+    sort_by: Optional[str] = Query(None, alias="sort_by"),
+    order: Optional[SortingOrder] = Query(SortingOrder.ASC, alias="order"),
+):
+    if not sort_by:
+        return None
+    return SortingQuery(sort_by=sort_by, order=order)
+
+
+def _parse_pagination(
+    page: Optional[int] = Query(1, ge=1, description="Page number"),
+    per_page: Optional[int] = Query(10, ge=1, le=100, description="Items per page"),
+) -> PaginationQuery:
+    return PaginationQuery(page=page, per_page=per_page)
+
+
+class FSPManager:
+    def __init__(
+        self,
+        request: Request,
+        filters: Annotated[List[Filter], Depends(_parse_filters)],
+        sorting: Annotated[SortingQuery, Depends(_parse_sort)],
+        pagination: Annotated[PaginationQuery, Depends(_parse_pagination)],
+    ):
+        self.request = request
+        self.filters = filters
+        self.sorting = sorting
+        self.pagination = pagination
+
+    def paginate(self, query: Select, session: Session) -> Any:
+        return session.exec(
+            query.offset((self.pagination.page - 1) * self.pagination.per_page).limit(
+                self.pagination.per_page
+            )
+        ).all()
+
+    def _count_total(self, query: Select, session: Session) -> int:
+        # Count the total rows of the given query (with filters/sort applied) ignoring pagination
+        count_query = select(func.count()).select_from(query.subquery())
+        return session.exec(count_query).one()
+
+    def _apply_filters(self, query: Select) -> Select:
+        # Helper: build a map of column name -> column object from the select statement
+        try:
+            columns_map = {
+                col.key: col for col in query.selected_columns
+            }  # SQLAlchemy 1.4+ ColumnCollection is iterable
+        except Exception:
+            columns_map = {}
+
+        if not self.filters:
+            return query
+
+        def coerce_value(column, raw):
+            # Try to coerce raw (str or other) 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 or raw is None:
+                return raw
+            if isinstance(raw, pytype):
+                return raw
+            # Handle booleans represented as strings
+            if pytype is bool and isinstance(raw, str):
+                val = raw.strip().lower()
+                if val in {"true", "1", "t", "yes", "y"}:
+                    return True
+                if val in {"false", "0", "f", "no", "n"}:
+                    return False
+            # Generic cast with fallback
+            try:
+                return pytype(raw)
+            except Exception:
+                return raw
+
+        def split_values(raw):
+            if raw is None:
+                return []
+            if isinstance(raw, (list, tuple)):
+                return list(raw)
+            if isinstance(raw, str):
+                return [item.strip() for item in raw.split(",")]
+            return [raw]
+
+        def ilike_supported(col):
+            return hasattr(col, "ilike")
+
+        for f in self.filters:
+            if not f or not f.field:
+                continue
+
+            column = columns_map.get(f.field)
+            if column is None:
+                # Skip unknown fields silently
+                continue
+
+            op = str(f.operator).lower() if f.operator is not None else "eq"
+            raw_value = f.value
+
+            # Build conditions based on operator
+            if op == "eq":
+                query = query.where(column == coerce_value(column, raw_value))
+            elif op == "ne":
+                query = query.where(column != coerce_value(column, raw_value))
+            elif op == "gt":
+                query = query.where(column > coerce_value(column, raw_value))
+            elif op == "gte":
+                query = query.where(column >= coerce_value(column, raw_value))
+            elif op == "lt":
+                query = query.where(column < coerce_value(column, raw_value))
+            elif op == "lte":
+                query = query.where(column <= coerce_value(column, raw_value))
+            elif op == "like":
+                query = query.where(column.like(str(raw_value)))
+            elif op == "not_like":
+                query = query.where(~column.like(str(raw_value)))
+            elif op == "ilike":
+                pattern = str(raw_value)
+                if ilike_supported(column):
+                    query = query.where(column.ilike(pattern))
+                else:
+                    query = query.where(func.lower(column).like(pattern.lower()))
+            elif op == "not_ilike":
+                pattern = str(raw_value)
+                if ilike_supported(column):
+                    query = query.where(~column.ilike(pattern))
+                else:
+                    query = query.where(~func.lower(column).like(pattern.lower()))
+            elif op == "in":
+                vals = [coerce_value(column, v) for v in split_values(raw_value)]
+                query = query.where(column.in_(vals))
+            elif op == "not_in":
+                vals = [coerce_value(column, v) for v in split_values(raw_value)]
+                query = query.where(~column.in_(vals))
+            elif op == "between":
+                vals = split_values(raw_value)
+                if len(vals) != 2:
+                    # Ignore malformed between; alternatively raise 400
+                    continue
+                low = coerce_value(column, vals[0])
+                high = coerce_value(column, vals[1])
+                query = query.where(column.between(low, high))
+            elif op == "is_null":
+                query = query.where(column.is_(None))
+            elif op == "is_not_null":
+                query = query.where(column.is_not(None))
+            elif op == "starts_with":
+                pattern = f"{str(raw_value)}%"
+                query = query.where(column.like(pattern))
+            elif op == "ends_with":
+                pattern = f"%{str(raw_value)}"
+                query = query.where(column.like(pattern))
+            elif op == "contains":
+                pattern = f"%{str(raw_value)}%"
+                query = query.where(column.like(pattern))
+            else:
+                # Unknown operator: skip
+                continue
+
+        return query
+
+    def _apply_sort(self, query: Select) -> Select:
+        # Build a map of column name -> column object from the select statement
+        try:
+            columns_map = {col.key: col for col in query.selected_columns}
+        except Exception:
+            columns_map = {}
+
+        if not self.sorting or not self.sorting.sort_by:
+            return query
+
+        column = columns_map.get(self.sorting.sort_by)
+        if column is None:
+            # Unknown sort column; skip sorting
+            return query
+
+        order = str(self.sorting.order).lower() if self.sorting.order else "asc"
+        if order == "desc":
+            return query.order_by(column.desc())
+        else:
+            return query.order_by(column.asc())
+
+    def generate_response(self, query: Select, session: Session) -> PaginatedResponse[Any]:
+        query = self._apply_filters(query)
+
+        query = self._apply_sort(query)
+
+        total_items = self._count_total(query, session)
+        per_page = self.pagination.per_page
+        current_page = self.pagination.page
+        total_pages = max(1, math.ceil(total_items / per_page)) if total_items is not None else 1
+
+        data_page = self.paginate(query, session)
+
+        # Build links based on current URL, replacing/adding page and per_page parameters
+        url = self.request.url
+        first_url = str(url.include_query_params(page=1, per_page=per_page))
+        last_url = str(url.include_query_params(page=total_pages, per_page=per_page))
+        next_url = (
+            str(url.include_query_params(page=current_page + 1, per_page=per_page))
+            if current_page < total_pages
+            else None
+        )
+        prev_url = (
+            str(url.include_query_params(page=current_page - 1, per_page=per_page))
+            if current_page > 1
+            else None
+        )
+        self_url = str(url.include_query_params(page=current_page, per_page=per_page))
+
+        return PaginatedResponse(
+            data=data_page,
+            meta=Meta(
+                pagination=Pagination(
+                    total_items=total_items,
+                    per_page=per_page,
+                    current_page=current_page,
+                    total_pages=total_pages,
+                ),
+                filters=self.filters,
+                sort=self.sorting,
+            ),
+            links=Links(
+                self=self_url,
+                first=first_url,
+                last=last_url,
+                next=next_url,
+                prev=prev_url,
+            ),
+        )

fastapi_fsp/models.py

@@ -0,0 +1,81 @@
+from enum import StrEnum
+from typing import Generic, List, Optional, TypeVar
+
+from pydantic import BaseModel
+
+
+class FilterOperator(StrEnum):
+    EQ = "eq"  # equals (=)
+    NE = "ne"  # not equals (!=)
+    GT = "gt"  # greater than (>)
+    GTE = "gte"  # greater than or equal (>=)
+    LT = "lt"  # less than (<)
+    LTE = "lte"  # less than or equal (<=)
+
+    LIKE = "like"  # case-sensitive LIKE
+    NOT_LIKE = "not_like"  # NOT LIKE
+    ILIKE = "ilike"  # case-insensitive LIKE (if supported by backend)
+    NOT_ILIKE = "not_ilike"  # NOT ILIKE
+
+    IN = "in"  # IN (...)
+    NOT_IN = "not_in"  # NOT IN (...)
+
+    BETWEEN = "between"  # BETWEEN x AND y
+
+    IS_NULL = "is_null"  # IS NULL
+    IS_NOT_NULL = "is_not_null"  # IS NOT NULL
+
+    STARTS_WITH = "starts_with"  # value%
+    ENDS_WITH = "ends_with"  # %value
+    CONTAINS = "contains"  # %value%
+
+
+class SortingOrder(StrEnum):
+    ASC = "asc"  # ascending order
+    DESC = "desc"  # descending order
+
+
+T = TypeVar("T")
+
+
+class Filter(BaseModel):
+    field: str
+    operator: FilterOperator
+    value: str
+
+
+class PaginationQuery(BaseModel):
+    page: int
+    per_page: int
+
+
+class SortingQuery(BaseModel):
+    sort_by: str
+    order: SortingOrder
+
+
+class Pagination(BaseModel):
+    total_items: Optional[int] = None
+    per_page: int
+    current_page: int
+    total_pages: Optional[int] = None
+
+
+class Meta(BaseModel):
+    pagination: Pagination
+    filters: Optional[List[Filter]] = None
+    sort: Optional[SortingQuery] = None
+
+
+class Links(BaseModel):
+    self: str
+    first: str
+    next: Optional[str] = None
+    prev: Optional[str] = None
+    last: Optional[str] = None
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    data: List[T]
+    meta: Meta
+    links: Links

fastapi_fsp-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: fastapi-fsp
+Version: 0.1.0
+Summary: Filter, Sort, and Paginate (FSP) utilities for FastAPI + SQLModel
+Project-URL: Homepage, https://github.com/your-org/fastapi-fsp
+Project-URL: Repository, https://github.com/your-org/fastapi-fsp
+Project-URL: Issues, https://github.com/your-org/fastapi-fsp/issues
+Author-email: Evert Jan Stamhuis <ej@fromejdevelopment.nl>
+License: MIT
+License-File: LICENSE
+Keywords: api,fastapi,filtering,pagination,sorting,sqlmodel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+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
+Description-Content-Type: text/markdown
+
+# fastapi-fsp
+
+Filter, Sort, and Paginate (FSP) utilities for FastAPI + SQLModel.
+
+fastapi-fsp helps you build standardized list endpoints that support:
+- Filtering on arbitrary fields with rich operators (eq, ne, lt, lte, gt, gte, in, between, like/ilike, null checks, contains/starts_with/ends_with)
+- Sorting by field (asc/desc)
+- Pagination with page/per_page and convenient HATEOAS links
+
+It is framework-friendly: you declare it as a FastAPI dependency and feed it a SQLModel/SQLAlchemy Select query and a Session.
+
+## Installation
+
+Using uv (recommended):
+
+```
+# create & activate virtual env with uv
+uv venv
+. .venv/bin/activate
+
+# add runtime dependency
+uv add fastapi-fsp
+```
+
+Using pip:
+
+```
+pip install fastapi-fsp
+```
+
+## Quick start
+
+Below is a minimal example using FastAPI and SQLModel.
+
+```python
+from typing import Optional
+from fastapi import Depends, FastAPI
+from sqlmodel import Field, SQLModel, Session, create_engine, select
+
+from fastapi_fsp.fsp import FSPManager
+from fastapi_fsp.models import PaginatedResponse
+
+class HeroBase(SQLModel):
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+class Hero(HeroBase, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+
+class HeroPublic(HeroBase):
+    id: int
+
+engine = create_engine("sqlite:///database.db", connect_args={"check_same_thread": False})
+SQLModel.metadata.create_all(engine)
+
+app = FastAPI()
+
+def get_session():
+    with Session(engine) as session:
+        yield session
+
+@app.get("/heroes/", response_model=PaginatedResponse[HeroPublic])
+def read_heroes(*, session: Session = Depends(get_session), fsp: FSPManager = Depends(FSPManager)):
+    query = select(Hero)
+    return fsp.generate_response(query, session)
+```
+
+Run the app and query:
+
+- Pagination: `GET /heroes/?page=1&per_page=10`
+- Sorting: `GET /heroes/?sort_by=name&order=asc`
+- Filtering: `GET /heroes/?field=age&operator=gte&value=21`
+
+The response includes data, meta (pagination, filters, sorting), and links (self, first, next, prev, last).
+
+## Query parameters
+
+Pagination:
+- page: integer (>=1), default 1
+- per_page: integer (1..100), default 10
+
+Sorting:
+- sort_by: the field name, e.g., `name`
+- order: `asc` or `desc`
+
+Filtering (repeatable sets; arrays are supported by sending multiple parameters):
+- field: the field/column name, e.g., `name`
+- operator: one of
+  - eq, ne
+  - lt, lte, gt, gte
+  - in, not_in (comma-separated values)
+  - between (two comma-separated values)
+  - like, not_like
+  - ilike, not_ilike (if backend supports ILIKE)
+  - is_null, is_not_null
+  - contains, starts_with, ends_with (translated to LIKE patterns)
+- value: raw string value (or list-like comma-separated depending on operator)
+
+Examples:
+- `?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`
+
+You can chain multiple filters by repeating the triplet:
+```
+?field=age&operator=gte&value=18&field=name&operator=ilike&value=rust
+```
+
+## Response model
+
+```
+{
+  "data": [ ... ],
+  "meta": {
+    "pagination": {
+      "total_items": 42,
+      "per_page": 10,
+      "current_page": 1,
+      "total_pages": 5
+    },
+    "filters": [
+      {"field": "name", "operator": "eq", "value": "Deadpond"}
+    ],
+    "sort": {"sort_by": "name", "order": "asc"}
+  },
+  "links": {
+    "self": "/heroes/?page=1&per_page=10",
+    "first": "/heroes/?page=1&per_page=10",
+    "next": "/heroes/?page=2&per_page=10",
+    "prev": null,
+    "last": "/heroes/?page=5&per_page=10"
+  }
+}
+```
+
+## Development
+
+This project uses uv as the package manager.
+
+- Create env and sync deps:
+```
+uv venv
+. .venv/bin/activate
+uv sync --dev
+```
+
+- Run lint and format checks:
+```
+uv run ruff check .
+uv run ruff format --check .
+```
+
+- Run tests:
+```
+uv run pytest -q
+```
+
+- Build the package:
+```
+uv build
+```
+
+## CI/CD and Releases
+
+GitHub Actions workflows are included:
+- CI (lint + tests) runs on pushes and PRs.
+- Release: pushing a tag matching `v*.*.*` runs tests, builds, and publishes to PyPI using `PYPI_API_TOKEN` secret.
+
+To release:
+1. Update the version in `pyproject.toml`.
+2. Push a tag, e.g. `git tag v0.1.1 && git push origin v0.1.1`.
+3. Ensure the repository has `PYPI_API_TOKEN` secret set (an API token from PyPI).
+
+## License
+
+MIT License. See LICENSE.

fastapi_fsp-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+fastapi_fsp/__init__.py,sha256=0I_XN_ptNu1NyNRpjdyVm6nwvrilAB8FyT2EfgVF_QA,215
+fastapi_fsp/fsp.py,sha256=lC9CV0T4Zjf4MRaVdtq2HZlpRusxuR-na_AQnZa1w6A,10033
+fastapi_fsp/models.py,sha256=_P72r_kgVh_ZvoKQqU359vnbJTxeWnvnT6yV5_M558Q,1740
+fastapi_fsp-0.1.0.dist-info/METADATA,sha256=qxwzS_WR_pCfJTPSktw-5LDSm6UyU1WulD4UTTIR-T8,5430
+fastapi_fsp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fastapi_fsp-0.1.0.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+fastapi_fsp-0.1.0.dist-info/RECORD,,

fastapi_fsp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_fsp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.