fastapi-fsp 0.1.0__tar.gz

fastapi_fsp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+
+jobs:
+  build-test-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Sync dependencies (with dev)
+        run: uv sync --dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        env:
+          PYTHONWARNINGS: default
+        run: uv run pytest -q
+
+      - name: Upload coverage artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-reports
+          path: |
+            coverage.xml
+            htmlcov
+
+      - name: Upload coverage to Codecov
+        if: always()
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

fastapi_fsp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Sync (no dev)
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest -q --maxfail=1
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if [ -z "$UV_PUBLISH_TOKEN" ]; then
+            echo "PYPI_API_TOKEN secret is not set." && exit 1
+          fi
+          uv publish --token "$UV_PUBLISH_TOKEN"

fastapi_fsp-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# -------- Python --------
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+.env/
+.python-version
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Unit test / coverage reports
+.coverage
+.coverage.*
+.cache/
+.pytest_cache/
+htmlcov/
+coverage.xml
+
+# Logs
+*.log
+
+# IDEs and editors
+.vscode/
+.idea/
+*.iml
+
+# OS-specific
+.DS_Store
+Thumbs.db
+
+# Databases (local dev/testing)
+*.db
+*.sqlite3
+
+# FastAPI/UVicorn
+debug.log
+
+# uv
+# Keep uv.lock tracked (do not ignore)
+# uv creates virtual envs typically under .venv which is already ignored
+
+# Misc
+.swp
+.swo

fastapi_fsp-0.1.0/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.

fastapi_fsp-0.1.0/PKG-INFO

@@ -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/PROJECT.md

@@ -0,0 +1,124 @@
+# FastAPI Filtering, Sorting and Pagination
+
+## pypi package name
+fastapi-fsp
+
+## pypi package version
+0.1.0
+
+## pypi package description
+Package to implement filtering, sorting and pagination in FastAPI endpoints
+using SQLModel
+
+Endpoint Depends class that parses query parameters for filtering,
+sorting and pagination. It performs all necessary checks.
+Filtering is with query params: field, operator, value (support multiple)
+Sorting is with query params: sort, order.
+Pagination is with query params: page, per_page.
+
+a request with query params:
+http://localhost:8000/items?field=name&operator=eq&value=Deadpond&sort=name&order=asc&page=1&per_page=10
+
+A response with data:
+
+data: list of objects
+meta: pagination info, filters, sort, etc.
+links: pagination links
+
+Example response:
+```
+{
+  "data": [
+    {
+      "id": 1,
+      "name": "Deadpond",
+      "secret_name": "Dive Wilson",
+      "age": 28
+    },
+  ],
+  "meta": {
+    "pagination": {
+      "total_items": 1,
+      "per_page": 10,
+      "current_page": 1,
+      "total_pages": 1
+    },
+    "filters": [
+      {
+        "field": "name",
+        "operator": "eq",
+        "value": "Deadpond"
+      }
+    ],
+    "sort": {
+      "sort": "name",
+      "order": "asc"
+    } 
+  },
+  "links": {
+    "self": "http://127.0.0.1:8000/heroes/?field=age&operator=gt&value=20&page=1&limit=2",
+    "first": "http://127.0.0.1:8000/heroes/?field=age&operator=gt&value=20&page=1&limit=2",
+    "next": "http://127.0.0.1:8000/heroes/?field=age&operator=gt&value=20&page=2&limit=2",
+    "prev": null
+  }
+}
+```
+
+
+Example usage in endpoint:
+
+class Item(SQLModel, table=True):
+    id: int = Field(default=None, primary_key=True)
+    name: str
+    secret_name: str | None = None
+    age: int | None = None
+
+@app.get("/items/", response_model=FSPResponse[Item])
+def read_items(
+    fsp: Depends(FSPManager(Item)),
+):
+    query = Item.select()
+    return fsp.make_response(query)
+
+also support async endpoints:
+
+@app.get("/items/", response_model=FSPResponse[Item])
+async def read_items(
+    fsp: Depends(FSPManager(Item)),
+):
+    query = Item.select()
+    return await fsp.make_response(query)
+
+## pypi package dependencies
+use the following dependencies:
+- uv as package manager
+
+
+- black as code formatter
+- isort as import formatter
+- flake8 as linter
+- pytest as test runner
+- pytest-cov as test coverage runner
+- pytest-asyncio as async test runner
+- pytest-mock as mock runner
+- FastAPI
+- SQLModel
+- pydantic
+
+
+## pypi package keywords
+fastapi, SQLModel, orm, filtering, sorting, pagination
+
+## open source on github
+Add a license file
+
+## Documentations
+Add a README.md file with documentation
+Add mkdocs documentation with mkdocs material theme
+Add an implementation example
+
+## full test coverage
+Implement unit tests using pytest
+
+## workflow to deploy to run all tests and package and publish to pypi
+Github Actions workflow file to deploy to run all tests and package and publish to pypi

fastapi_fsp-0.1.0/README.md

@@ -0,0 +1,178 @@
+# 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/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",
+]