fix(extensions): drop filter-provider modules from mypyc to restore deepcopy (0.48.2) (#481)

## Summary

- Drops `sqlspec/extensions/litestar/providers.py` and
`sqlspec/extensions/fastapi/providers.py` from the mypyc compile set so
route-handler deepcopy stops crashing in Litestar's
`Controller.get_route_handlers()`.
- Adds discovery-based deepcopy + pickle unit tests for every
`_*FilterProvider` class in both extension modules.
- Adds integration tests reproducing the user's
`Controller.get_route_handlers()` stack trace plus the pre-registration
`copy.deepcopy(handler)` path.
- Bumps version to **0.48.2** for patch release.

## The bug

Starting in 0.48.1, `sqlspec/extensions/{litestar,fastapi}/providers.py`
shipped as mypyc-compiled `.so` extensions. Every `_*FilterProvider`
runtime context class in those modules has an `__init__` with required
positional args. Litestar's `Controller.get_route_handlers()` performs
`copy.deepcopy(self_handler)` per route at registration time, and
`copy`'s default reconstruction calls `cls.__new__(cls)`. Under mypyc,
`__new__` chains into `__init__()` (with no args) — which raises:

```
TypeError: __init__() missing required argument 'default_page_size' (pos 1)
```

Every Litestar Controller wiring `create_filter_dependencies(...)` trips
this. DMA's `make js-api-update` (the original reporter) crashes during
OpenAPI schema generation.

## Why the in-place fix was abandoned

The first attempt followed PR #480's pattern (`__reduce__` +
`_reconstruction_args`). The second attempt (Option G — default-arg
`__init__` relying on mypyc's auto-generated `__getstate__` /
`__setstate__` over `__mypyc_attrs__`) failed because:

1. mypyc strict-typing rejected the tuple default for the `SortField`
parameter on `_OrderByProvider` (the union doesn't include tuple).
2. A separate `cannot pickle 'module' object` issue surfaced further
down the handler chain, requiring additional workarounds for an issue
unrelated to providers.

These provider classes precompute `inspect.Signature` once per
`FilterConfig` and are cached by `dep_cache` for the life of the process
— the mypyc win is amortized to app boot only. Net-cost of the
source-side workarounds exceeded the perf benefit, so we opted out
instead.

## Tests

- `tests/unit/extensions/test_litestar/test_providers_deepcopy.py` and
`tests/unit/extensions/test_fastapi/test_providers_deepcopy.py` —
discovery-based parametrized deepcopy + pickle round-trips. New
`_*FilterProvider` classes auto-join coverage via
`inspect.getmembers`-style filtering.
- `tests/unit/extensions/test_litestar/test_controller_deepcopy.py` —
integration tests covering: (a) `copy.deepcopy(handler)` on a `@get(...,
dependencies=create_filter_dependencies(...))` decorated handler, (b)
idempotent re-deepcopy, (c) the user's exact
`Controller.get_route_handlers()` stack-trace path via a
`_ProbeController` instance.

All tests reproduce the documented `TypeError` against the buggy build
and pass after the fix.

## Trade-off

Standing project rule "never reduce the mypyc compile set" overridden
for these two specific modules after empirical evaluation. The remaining
~80 modules continue to be mypyc-compiled. Rationale captured in the bd
epic notes (`sqlspec-nzkc`) and the archived Flow spec.

Author: cofin

pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.48.1"
+version = "0.48.2"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -193,7 +193,6 @@ packages = ["sqlspec"]
 packages = []
 
 
-
 [tool.hatch.build.targets.wheel.hooks.mypyc]
 dependencies = ["hatch-mypyc", "hatch-cython", "mypy>=2.0.0"]
 enable-by-default = false
@@ -242,8 +241,6 @@ include = [
   "sqlspec/storage/pipeline.py",                   # Storage bridge orchestration with Arrow boundary split out
   "sqlspec/storage/backends/base.py",              # Storage backend runtime base classes
   "sqlspec/data_dictionary/**/*.py",               # Data dictionary registry, loader, and dialect helpers
-  "sqlspec/extensions/fastapi/providers.py",       # FastAPI filter providers avoid nested dependency functions
-  "sqlspec/extensions/litestar/providers.py",      # Litestar filter providers precompute dynamic signatures
   "sqlspec/extensions/events/_hints.py",           # Adapter event runtime defaults
   "sqlspec/extensions/events/_payload.py",         # Event JSON payload codec helpers
   "sqlspec/extensions/adk/_types.py",              # ADK session/event record types
@@ -293,7 +290,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.48.1"
+current_version = "0.48.2"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

tests/unit/extensions/test_fastapi/test_providers_deepcopy.py

@@ -0,0 +1,88 @@
+"""Round-trip tests for copy.deepcopy and pickle on mypyc-compiled FastAPI filter providers."""
+
+# Safe: pickle round-trips here serialize objects produced inside the test and
+# immediately deserialize them in the same process. No untrusted input crosses
+# the pickle boundary.
+import copy
+import inspect
+import pickle
+from typing import Any
+
+import pytest
+
+from sqlspec.extensions.fastapi import providers as fastapi_providers
+from sqlspec.extensions.fastapi.providers import FieldNameType
+
+_FACTORIES: "dict[str, Any]" = {
+    "_LimitOffsetFilterProvider": lambda cls: cls(20),
+    "_IdFilterProvider": lambda cls: cls("id", int),
+    "_BeforeAfterFilterProvider": lambda cls: cls("created_at", "createdBefore", "createdAfter"),
+    "_SearchFilterProvider": lambda cls: cls({"name", "email"}, False),
+    "_OrderByProvider": lambda cls: cls("id", {"sort_field": "id"}),
+    "_CollectionFilterProvider": lambda cls: cls(FieldNameType("status", str), negated=False),
+    "_NullFilterProvider": lambda cls: cls("deleted_at", negated=False),
+}
+
+
+def _discover_provider_classes() -> "list[type[Any]]":
+    classes: list[type[Any]] = []
+    for name, cls in inspect.getmembers(fastapi_providers, inspect.isclass):
+        if not name.startswith("_") or name.startswith("__"):
+            continue
+        if not name.endswith("Provider"):
+            continue
+        if cls.__module__ != fastapi_providers.__name__:
+            continue
+        classes.append(cls)
+    return classes
+
+
+def _state_attrs(inst: Any) -> "tuple[str, ...]":
+    mypyc_attrs = getattr(type(inst), "__mypyc_attrs__", None)
+    if mypyc_attrs is not None:
+        return tuple(mypyc_attrs)
+    return tuple(k for k in vars(inst) if not k.startswith("__"))
+
+
+def _build(cls: "type[Any]") -> Any:
+    factory = _FACTORIES.get(cls.__name__)
+    if factory is None:
+        msg = f"No factory registered for {cls.__name__}. Add an entry to _FACTORIES at the top of this test module."
+        raise AssertionError(msg)
+    return factory(cls)
+
+
+def _assert_state_equal(left: Any, right: Any) -> None:
+    for attr in _state_attrs(left):
+        left_value = getattr(left, attr)
+        right_value = getattr(right, attr)
+        assert left_value == right_value, (
+            f"{type(left).__name__}.{attr} diverged after round-trip: {left_value!r} != {right_value!r}"
+        )
+
+
+@pytest.mark.parametrize("cls", _discover_provider_classes(), ids=lambda c: c.__name__)
+def test_provider_deepcopy_roundtrip(cls: "type[Any]") -> None:
+    inst = _build(cls)
+    out = copy.deepcopy(inst)
+    assert out is not inst
+    assert type(out) is type(inst)
+    _assert_state_equal(inst, out)
+
+
+@pytest.mark.parametrize("cls", _discover_provider_classes(), ids=lambda c: c.__name__)
+def test_provider_pickle_roundtrip(cls: "type[Any]") -> None:
+    inst = _build(cls)
+    out = pickle.loads(pickle.dumps(inst))
+    assert out is not inst
+    assert type(out) is type(inst)
+    _assert_state_equal(inst, out)
+
+
+def test_factory_registry_covers_all_discovered_classes() -> None:
+    discovered = {cls.__name__ for cls in _discover_provider_classes()}
+    registered = set(_FACTORIES)
+    missing = discovered - registered
+    extra = registered - discovered
+    assert not missing, f"_FACTORIES missing entries for newly added provider classes: {missing}"
+    assert not extra, f"_FACTORIES has stale entries for removed/renamed classes: {extra}"

tests/unit/extensions/test_litestar/test_controller_deepcopy.py

@@ -0,0 +1,118 @@
+"""Integration test for the route-handler-deepcopy crash reported against 0.48.1.
+
+Litestar's `Controller.get_route_handlers()` performs `copy.deepcopy(self_handler)`
+at controller registration time -- *before* the app attaches the `.app` / `.owner`
+back-pointer to the handler. Pre-fix, that deepcopy walked into
+`handler.dependencies` -> `Provide` -> `functools.partial(provide_fn, _*Provider)`
+and crashed on the mypyc-compiled provider's `__new__` -> `__init__()` chain
+with `TypeError: __init__() missing required argument`.
+
+These tests exercise that same pre-registration deepcopy via the public Litestar
+API: `@get(..., dependencies=...)` returns a `BaseRouteHandler` whose
+`dependencies` dict already contains the filter `Provide` objects, and
+`copy.deepcopy(handler)` reproduces the user's exact stack trace path.
+"""
+
+import copy
+from typing import Any
+
+import pytest
+from litestar import Controller, get
+from litestar.router import Router
+
+from sqlspec.extensions.litestar.providers import FieldNameType, create_filter_dependencies, dep_cache
+from sqlspec.typing import LITESTAR_INSTALLED
+
+if not LITESTAR_INSTALLED:
+    pytest.skip("Litestar not installed", allow_module_level=True)
+
+
+@pytest.fixture(autouse=True)
+def _clear_dependency_cache() -> Any:
+    dep_cache.dependencies.clear()
+    yield
+    dep_cache.dependencies.clear()
+
+
+def _dep_keys(handler: Any) -> "set[str]":
+    return set(getattr(handler, "dependencies", None) or ())
+
+
+def test_handler_deepcopy_with_limit_offset_filter() -> None:
+    """Minimum repro: a handler with a single LimitOffsetFilter dep must deepcopy."""
+    deps = create_filter_dependencies({"pagination_type": "limit_offset", "pagination_size": 10})
+
+    @get("/probe", dependencies=deps)
+    async def probe() -> "list[Any]":
+        return []
+
+    out = copy.deepcopy(probe)
+    assert out is not probe
+    assert _dep_keys(out) == _dep_keys(probe)
+
+
+def test_handler_deepcopy_with_full_filter_set() -> None:
+    """Every supported filter type wired in. Each filter `Provide` must survive deepcopy."""
+    deps = create_filter_dependencies({
+        "id_filter": int,
+        "id_field": "id",
+        "pagination_type": "limit_offset",
+        "pagination_size": 25,
+        "search": "name",
+        "search_ignore_case": False,
+        "sort_field": "id",
+        "created_at": True,
+        "updated_at": True,
+        "in_fields": [FieldNameType("name", str)],
+        "not_in_fields": [FieldNameType("name", str)],
+        "null_fields": "deleted_at",
+        "not_null_fields": "created_at",
+    })
+
+    @get("/probe", dependencies=deps)
+    async def probe() -> "list[Any]":
+        return []
+
+    out = copy.deepcopy(probe)
+    assert out is not probe
+    assert _dep_keys(out) == _dep_keys(probe)
+
+
+def test_handler_repeated_deepcopy_is_idempotent() -> None:
+    """A deepcopied handler must itself deepcopy."""
+    deps = create_filter_dependencies({"pagination_type": "limit_offset"})
+
+    @get("/probe", dependencies=deps)
+    async def probe() -> "list[Any]":
+        return []
+
+    first = copy.deepcopy(probe)
+    second = copy.deepcopy(first)
+    assert second is not first
+    assert _dep_keys(second) == _dep_keys(first)
+
+
+def test_controller_get_route_handlers_with_filter_dependencies() -> None:
+    """Reproduce the user's exact Controller.get_route_handlers() stack trace path.
+
+    `Controller.get_route_handlers()` is what crashed in the user's report. It
+    calls `copy.deepcopy(self_handler)` on each handler attribute of the
+    Controller class. To force the controller's handlers to carry the filter
+    `Provide` objects at the point of that deepcopy, we attach `dependencies` to
+    the `@get` decorator (Litestar 2.22's Controller-level `dependencies` are
+    merged at request time, not at `get_route_handlers` time).
+    """
+    deps = create_filter_dependencies({"pagination_type": "limit_offset", "search": "name", "sort_field": "id"})
+
+    class _ProbeController(Controller):
+        path = "/probe"
+
+        @get("/", dependencies=deps)
+        async def list_items(self) -> "list[Any]":
+            return []
+
+    owner = Router(path="/api", route_handlers=[])
+    handlers = list(_ProbeController(owner=owner).get_route_handlers())
+
+    assert len(handlers) == 1
+    assert _dep_keys(handlers[0]) == set(deps)

tests/unit/extensions/test_litestar/test_providers_deepcopy.py

@@ -0,0 +1,93 @@
+"""Round-trip tests for copy.deepcopy and pickle on mypyc-compiled filter providers."""
+
+# Safe: pickle round-trips here serialize objects produced inside the test and
+# immediately deserialize them in the same process. No untrusted input crosses
+# the pickle boundary.
+import copy
+import inspect
+import pickle
+from typing import Any
+
+import pytest
+
+from sqlspec.extensions.litestar import providers as litestar_providers
+from sqlspec.extensions.litestar.providers import FieldNameType
+from sqlspec.typing import LITESTAR_INSTALLED
+
+if not LITESTAR_INSTALLED:
+    pytest.skip("Litestar not installed", allow_module_level=True)
+
+
+_FACTORIES: "dict[str, Any]" = {
+    "_LimitOffsetFilterProvider": lambda cls: cls(20),
+    "_IdFilterProvider": lambda cls: cls("id", int),
+    "_BeforeAfterFilterProvider": lambda cls: cls("created_at", "createdBefore", "createdAfter"),
+    "_SearchFilterProvider": lambda cls: cls({"name", "email"}, False),
+    "_OrderByProvider": lambda cls: cls("id", {"sort_field": "id"}),
+    "_CollectionFilterProvider": lambda cls: cls(FieldNameType("status", str), negated=False),
+    "_NullFilterProvider": lambda cls: cls("deleted_at", negated=False),
+}
+
+
+def _discover_provider_classes() -> "list[type[Any]]":
+    classes: list[type[Any]] = []
+    for name, cls in inspect.getmembers(litestar_providers, inspect.isclass):
+        if not name.startswith("_") or name.startswith("__"):
+            continue
+        if not name.endswith("Provider"):
+            continue
+        if cls.__module__ != litestar_providers.__name__:
+            continue
+        classes.append(cls)
+    return classes
+
+
+def _state_attrs(inst: Any) -> "tuple[str, ...]":
+    mypyc_attrs = getattr(type(inst), "__mypyc_attrs__", None)
+    if mypyc_attrs is not None:
+        return tuple(mypyc_attrs)
+    return tuple(k for k in vars(inst) if not k.startswith("__"))
+
+
+def _build(cls: "type[Any]") -> Any:
+    factory = _FACTORIES.get(cls.__name__)
+    if factory is None:
+        msg = f"No factory registered for {cls.__name__}. Add an entry to _FACTORIES at the top of this test module."
+        raise AssertionError(msg)
+    return factory(cls)
+
+
+def _assert_state_equal(left: Any, right: Any) -> None:
+    for attr in _state_attrs(left):
+        left_value = getattr(left, attr)
+        right_value = getattr(right, attr)
+        assert left_value == right_value, (
+            f"{type(left).__name__}.{attr} diverged after round-trip: {left_value!r} != {right_value!r}"
+        )
+
+
+@pytest.mark.parametrize("cls", _discover_provider_classes(), ids=lambda c: c.__name__)
+def test_provider_deepcopy_roundtrip(cls: "type[Any]") -> None:
+    inst = _build(cls)
+    out = copy.deepcopy(inst)
+    assert out is not inst
+    assert type(out) is type(inst)
+    _assert_state_equal(inst, out)
+
+
+@pytest.mark.parametrize("cls", _discover_provider_classes(), ids=lambda c: c.__name__)
+def test_provider_pickle_roundtrip(cls: "type[Any]") -> None:
+    inst = _build(cls)
+    out = pickle.loads(pickle.dumps(inst))
+    assert out is not inst
+    assert type(out) is type(inst)
+    _assert_state_equal(inst, out)
+
+
+def test_factory_registry_covers_all_discovered_classes() -> None:
+    discovered = {cls.__name__ for cls in _discover_provider_classes()}
+    registered = set(_FACTORIES)
+    missing = discovered - registered
+    extra = registered - discovered
+    assert not missing, f"_FACTORIES missing entries for newly added provider classes: {missing}"
+    assert not extra, f"_FACTORIES has stale entries for removed/renamed classes: {extra}"

tests/unit/utils/test_mypyc_inventory.py

@@ -141,8 +141,8 @@ def test_inventory_records_rest_of_mypyc_boundary_decisions() -> None:
     assert "sqlspec/extensions/events/_models.py" in payload["interpreted_modules"]
     assert "sqlspec/extensions/events/_queue.py" in payload["interpreted_modules"]
     assert "sqlspec/extensions/adk/converters.py" in payload["interpreted_modules"]
-    assert "sqlspec/extensions/fastapi/providers.py" in payload["compiled_modules"]
-    assert "sqlspec/extensions/litestar/providers.py" in payload["compiled_modules"]
+    assert "sqlspec/extensions/fastapi/providers.py" in payload["interpreted_modules"]
+    assert "sqlspec/extensions/litestar/providers.py" in payload["interpreted_modules"]
     assert "sqlspec/storage/_arrow_payload.py" in payload["interpreted_modules"]
     assert "sqlspec/observability/_formatting.py" in payload["interpreted_modules"]
     assert "sqlspec/extensions/events/_models.py" in payload["preserved_exclusions"]

tools/scripts/mypyc_inventory.py

@@ -173,12 +173,12 @@
         "reason": "Imports Google ADK models at module import time and keeps Pydantic model reconstruction interpreted.",
     },
     "sqlspec/extensions/fastapi/providers.py": {
-        "classification": "compile_now",
-        "reason": "Framework provider surface now uses module-level callable providers with precomputed dynamic signatures.",
+        "classification": "keep_interpreted",
+        "reason": "Compiled providers crash on copy.deepcopy via mypyc native cls.__new__ -> __init__() chain; providers precompute signatures once per FilterConfig and are cached in dep_cache, so the mypyc win is boot-only.",
     },
     "sqlspec/extensions/litestar/providers.py": {
-        "classification": "compile_now",
-        "reason": "Framework provider surface now uses module-level callable providers with precomputed dynamic signatures.",
+        "classification": "keep_interpreted",
+        "reason": "Compiled providers crash on copy.deepcopy via mypyc native cls.__new__ -> __init__() chain; providers precompute signatures once per FilterConfig and are cached in dep_cache, so the mypyc win is boot-only.",
     },
     "sqlspec/migrations/commands.py": {
         "classification": "keep_interpreted",