Milestone 1: Full Modernization: Toolchain, Dependencies, Type System, and API

[mcode-app-dev]

View Milestone

Table of Contents

• Status
• Feature Overview
• Testing
• Acceptance Criteria
• Architecture
• Suggested Order of Review

---

Status

Milestone successfully completed. All seven improvements specified in the Milestone Plan were implemented:

1. Python minimum raised to 3.12 (3.10/3.11 dropped from CI matrix and classifiers)
2. SQLAlchemy constraint broadened to >=2.0.0,<3.0.0; greenlet replaced by SQLAlchemy[asyncio] extra
3. Annotated[Filter, Query()] pattern introduced in examples, docstrings, and tests; FilterDepends retained for nested filters
4. Package manager migrated from Poetry to uv; poetry.lock deleted, uv.lock committed
5. Type annotations modernized: PEP 695 type alias, UNION_TYPES constant removed, _FilterWrapper callable class replaces __new__ override
6. MongoEngine blocking-driver warning added to module docstring and documentation
7. Test infrastructure refreshed: deprecated sqlalchemy.future import replaced, new parametrized test_api_native_pattern tests added for both SQLAlchemy and Beanie backends

No deviations from the Milestone Plan. The nox sqlalchemy parametrization currently covers 2.0.51 only; 2.1.0 is withheld pending its final PyPI release, consistent with the plan's guidance.

---

Feature Overview

This milestone delivers a full in-place modernization of the fastapi-filter library. Users of the library benefit in the following ways:

• Faster installs and lock resolution: uv sync --all-extras replaces poetry install --extras all, typically 10–100× faster.
• Broader SQLAlchemy compatibility: projects pinned to SQLAlchemy 2.0.x patch releases (up to 2.0.51) and the forthcoming 2.1.x series are no longer blocked by the old <2.1.0 upper bound.
• Simpler non-nested filter wiring: for flat filter classes (no nested with_prefix fields), the idiomatic FastAPI 0.115+ pattern Annotated[UserFilter, Query()] can now be used directly without FilterDepends. Both patterns are demonstrated side-by-side in the examples and covered by dedicated tests.
• Cleaner FilterDepends internals: the FilterWrapper.__new__ hack is replaced by _FilterWrapper, a plain callable class that copies GeneratedFilter.__signature__ so FastAPI introspects query parameters correctly without model-inheritance side effects.
• Explicit MongoEngine async warning: users who attempt to use the MongoEngine backend in async def routes now encounter a clear module-level docstring warning about event-loop blocking, with a pointer to the Beanie backend.

---

Testing

Automated Testing

The existing three-backend parametrized test suite (279 tests in the origin baseline) serves as the acceptance suite. Key test locations:

• tests/test_sqlalchemy/test_filter.py — all filter operators (neq, gt, gte, lt, lte, in, not_in, isnull, like, ilike, search) plus ordering scenarios
• tests/test_beanie/test_filter.py — equivalent coverage for the Beanie backend
• tests/test_mongoengine/test_filter.py — equivalent coverage for the MongoEngine backend
• tests/test_sqlalchemy/test_filter.py::test_api_native_pattern — new parametrized test covering the Annotated[FlatUserFilter, Query()] /users-native route with the same filter-operator cases as FilterDepends
• tests/test_beanie/test_filter.py::test_api_native_pattern — same new test for the Beanie backend

Run the full test suite (SQLAlchemy backend only; no MongoDB required):

cd $WORKSPACE_DIR/fastapi-filter
uv sync --all-extras
uv run pytest tests/test_sqlalchemy/ -v

Run via nox (parametrizes SQLAlchemy version):

uv run nox -- tests --cov-report=xml

Manual Testing

Verify the SQLAlchemy example starts cleanly and both routes are functional:

cd $WORKSPACE_DIR/fastapi-filter
uv sync --all-extras
uv run python examples/fastapi_filter_sqlalchemy.py

Then navigate to http://localhost:8000/docs and confirm:

• GET /users — filter route using FilterDepends(UserFilter) appears with full filter parameters
• GET /users-native — filter route using Annotated[FlatUserFilter, Query()] appears with the flat filter parameters

Example curl requests:

# FilterDepends route — filter by name
curl "http://localhost:8000/users?name=John"

# Native pattern route — filter by name
curl "http://localhost:8000/users-native?name=John"

# Native pattern route — filter with list field
curl "http://localhost:8000/users-native?name__in=John,Jane"

Both endpoints should return identical results for equivalent filter queries.

---

Acceptance Criteria

AC	Verdict	Origin	Target
format_issues_max	fail	format_issues: 0	format_issues: 1 (≤ 0)
line_coverage_min	pass	line_coverage_pct: 100	line_coverage_pct: 100 (≥ 100%)
lint_violations_max	pass	lint_violations: 0	lint_violations: 0 (≤ 0)
security_issues_max	pass	security_high_severity: 0 security_medium_severity: 0	security_high_severity: 0 (≤ 0) security_medium_severity: 0 (≤ 0)
type_errors_max	pass	type_errors: 0	type_errors: 0 (≤ 0)

---

Architecture

Overview

flowchart TD
    Route["User's FastAPI Route"]:::modified
    Init["fastapi_filter/__init__.py"]:::modified
    Base["base/filter.py\n(BaseFilterModel, FilterDepends,\n_FilterWrapper, with_prefix)"]:::modified
    SA["contrib/sqlalchemy/filter.py\n(SQLAlchemy async Filter)"]:::modified
    BN["contrib/beanie/filter.py\n(Beanie ODM Filter)"]:::unchanged
    ME["contrib/mongoengine/filter.py\n(MongoEngine sync Filter)"]:::modified
    PY["pyproject.toml + uv.lock\n(uv toolchain, Python 3.12+)"]:::modified
    CI[".github/workflows\n(test.yml, publish.yml)"]:::modified

    Route --> Init
    Init --> Base
    Base --> SA
    Base --> BN
    Base --> ME
    PY -.->|"toolchain"| Route
    CI -.->|"CI matrix"| PY

    classDef modified fill:#FFD700,stroke:#b8860b,color:#000
    classDef unchanged fill:#fff,stroke:#999,color:#000

    subgraph Legend
        L1["Modified"]:::modified
        L2["Unchanged"]:::unchanged
    end

Loading

Changes

pyproject.toml + uv.lock (Toolchain Migration)

pyproject.toml was converted from [tool.poetry]/[tool.poetry.dependencies] to standard PEP 621 [project] and [project.optional-dependencies] tables. Key changes:

• requires-python = ">=3.12" (was >=3.10)
• [project.optional-dependencies] carries sqlalchemy, beanie, mongoengine, and all extras; all uses self-referencing fastapi-filter[sqlalchemy,beanie,mongoengine] syntax
• SQLAlchemy[asyncio]>=2.0.0,<3.0.0 replaces SQLAlchemy>=2.0.0,<2.1.0; greenlet removed from dev dependencies (now a transitive dependency of SQLAlchemy[asyncio])
• Build backend switched from poetry-core to hatchling
• poetry.lock deleted; uv.lock committed (1 996 lines)
• ruff target-version updated to py312
• .python-version updated to 3.12
• runtime.txt updated from 3.8 to 3.12

.github/workflows (CI Matrix)

test.yml and publish.yml updated:

• snok/install-poetry@v1 removed; astral-sh/setup-uv@v6 added
• poetry install --extras all → uv sync --all-extras
• poetry run -- nox -- tests → uv run nox -- tests
• Python matrix: ["3.10", "3.11", "3.12", "3.13", "3.14"] → ["3.12", "3.13", "3.14"]
• publish.yml: poetry publish → uv build && uv publish

noxfile.py updated: session.run("poetry", "run", "pytest", ...) → session.run("uv", "run", "pytest", ...) with external=True; SQLAlchemy parametrization updated to ["2.0.51"].

base/filter.py (Core Filter Logic)

Three related changes:

1. _FilterWrapper callable class: the FilterWrapper(GeneratedFilter) Pydantic subclass with its __new__ override was replaced by a plain class _FilterWrapper with __init__ and __call__. __init__ copies inspect.signature(generated_filter) onto self.__signature__ so FastAPI's dependency injection introspects the correct query parameter names. __call__(**kwargs) instantiates GeneratedFilter, dumps validated data, and constructs the real Filter (handling prefix-stripping for nested filters). RequestValidationError is raised on ValidationError, preserving prior behavior.

2. UNION_TYPES removal: the module-level UNION_TYPES: list = [Union, UnionType] constant was deleted. Its usage in _list_to_str_fields was replaced with the inline check get_origin(annotation) is Union or isinstance(annotation, types.UnionType). import types and import inspect were added at module top; from types import UnionType import was removed.

3. PEP 695 type alias: type FilterField = tuple[object | type, FieldInfo | None] declared at module level; used in the return annotation of _list_to_str_fields and the ret dict annotation inside it.

4. split_str validator fix: a behavioral fix was applied to handle the Annotated[Filter, Query()] path, where FastAPI delivers ?age__in=1,2,3 as the single-element list ["1,2,3"] rather than the bare string "1,2,3" that the FilterDepends path produces. The validator now detects this single-element comma-containing list and splits it, ensuring parity between both dependency patterns.

5. FilterDepends docstring: a note added stating that for non-nested filters the native Annotated[Filter, Query()] pattern from FastAPI 0.115+ can be used directly; references the examples for side-by-side comparison.

contrib/sqlalchemy/filter.py

• _orm_operator_transformer dict annotated with explicit type dict[str, Callable[[Any], tuple[str, Any]]]
• Direction enum changed to StrEnum (available in Python 3.11+; now valid given 3.12 minimum)

contrib/mongoengine/filter.py

Module-level docstring added with a .. warning:: RST directive stating that all filter and sort operations are synchronous (backed by PyMongo's blocking driver) and will block the asyncio event loop when called from async def FastAPI route handlers; recommends the Beanie backend for async applications.

fastapi_filter/init.py

Module-level docstring added showing the Annotated[Filter, Query()] pattern for non-nested filters alongside the FilterDepends pattern for nested filters. __all__ is unchanged (FilterDepends, with_prefix).

docs/index.md + README.md

• docs/index.md: blockquote warning added above the MongoEngine example link describing the synchronous driver limitation and recommending the Beanie backend.
• README.md: compatibility table updated to reflect Python >=3.12, SQLAlchemy >=2.0.0,<3.0.0; Poetry install examples replaced with uv equivalents.

tests/ (Test Infrastructure)

• tests/test_sqlalchemy/test_filter.py: from sqlalchemy.future import select replaced with from sqlalchemy import select
• tests/test_sqlalchemy/conftest.py: FlatUserFilter fixture (flat filter, no nested FilterDepends fields) and /users-native route added; noqa: C901 added to the intentionally complex app fixture
• tests/test_sqlalchemy/test_filter.py: test_api_native_pattern parametrized test added hitting /users-native
• tests/test_beanie/conftest.py and test_filter.py: identical additions for the Beanie backend

Design Decisions

D1 — uvx migrate-to-uv + hand-edit strategy: The auto-conversion tool was used as a first pass, then the output was hand-corrected: extras were mapped to [project.optional-dependencies], the dev group landed in [dependency-groups], and greenlet was removed in favour of the SQLAlchemy[asyncio] extras mechanism. Build backend was set to hatchling (MIT-licensed; selected by the migration tool).

D2 — _FilterWrapper as standalone callable class: Replacing FilterWrapper.__new__ with a plain callable (_FilterWrapper) avoids non-idiomatic Pydantic model subclassing. The __signature__ copy technique allows FastAPI to introspect the query parameters of GeneratedFilter through the wrapper without the wrapper itself being a Pydantic model. Approach 1 from the Milestone Plan's Design Decision 2 was followed.

D3 — Annotated[Filter, Query()] not added to __all__: Query is already a FastAPI export and Annotated is from typing; re-exporting them through fastapi_filter would couple the library more tightly to FastAPI internals for no user benefit. Documentation and examples cover the pattern without API surface expansion (Approach 1 from Design Decision 4).

D4 — split_str validator extended for native-pattern list delivery: FastAPI 0.115+ delivers ?age__in=1,2,3 as ["1,2,3"] (a single-element list) when the field is typed list[int] and the route uses the native Annotated[Filter, Query()] pattern. Rather than requiring users to write separate validators or separate filter classes for each pattern, the existing split_str validator was extended to detect and split this case, ensuring both patterns produce the same list[int] result.

D5 — nox parametrizes 2.0.51 only: SQLAlchemy 2.1.0 had not reached a final PyPI release at the time of implementation. A comment in noxfile.py marks where "2.1.0" should be added once available, consistent with the Milestone Plan's guidance on this risk.

---

Suggested Order of Review

1. pyproject.toml — establish the new PEP 621 structure, requires-python, extras, and broadened SQLAlchemy constraint; context for all subsequent changes
2. uv.lock — verify the lock file is consistent with the new pyproject.toml (scan for unexpected version pins)
3. .github/workflows/test.yml — confirm the CI matrix drops 3.10/3.11 and the Poetry steps are fully replaced with uv
4. .github/workflows/publish.yml — confirm the publish workflow uses uv build && uv publish
5. noxfile.py — verify uv run pytest and the SQLAlchemy parametrization
6. fastapi_filter/base/filter.py — core logic changes: _FilterWrapper callable class, UNION_TYPES removal, type FilterField alias, split_str fix
7. fastapi_filter/__init__.py — new module docstring documenting the two dependency patterns
8. fastapi_filter/contrib/sqlalchemy/filter.py — _orm_operator_transformer type annotation, StrEnum
9. fastapi_filter/contrib/mongoengine/filter.py — module-level blocking-driver warning
10. tests/test_sqlalchemy/conftest.py and tests/test_beanie/conftest.py — FlatUserFilter fixture and /users-native route additions
11. tests/test_sqlalchemy/test_filter.py and tests/test_beanie/test_filter.py — test_api_native_pattern new test; sqlalchemy.future import fix
12. examples/fastapi_filter_sqlalchemy.py and examples/fastapi_filter_beanie.py — side-by-side demonstration of both patterns
13. docs/index.md and README.md — MongoEngine warning and updated compatibility table
14. runtime.txt — single-line update (3.8 → 3.12)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (fa937cb) to head (04b2bd6).

Additional details and impacted files

@@             Coverage Diff              @@
##           morph-main      #654   +/-   ##
============================================
  Coverage      100.00%   100.00%           
============================================
  Files               8         4    -4     
  Lines             215       159   -56     
============================================
- Hits              215       159   -56     

Files with missing lines	Coverage Δ
fastapi_filter/__init__.py	100.00% <ø> (ø)
fastapi_filter/base/filter.py	100.00% <100.00%> (ø)
fastapi_filter/contrib/sqlalchemy/filter.py	100.00% <100.00%> (ø)

... and 4 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.