fix(FAST003): handle Depends(Class()) instance pattern for __call__ deps

stakeswky · stakeswky · commit c90a5c7d05f2 · 2026-02-25T23:54:12.000+08:00
Rework the dependency resolution to correctly distinguish between:
- Depends(SomeClass) — class reference, FastAPI calls __init__
- Depends(SomeClass()) — instance, FastAPI calls __call__

Previously the code conflated both cases by checking __init__ OR __call__
in a single find(), which was both incorrect and misleading.

Now:
- from_dependency_name: handles Name refs, uses __init__ for classes
- from_dependency_instance: handles Call exprs, uses __call__ for classes
- class_params_from_method: shared helper for both paths

Also applies the matches!() nit from review and restores the original
'Skip self parameter' comment.
diff --git a/crates/ruff_linter/resources/test/fixtures/fastapi/FAST003.py b/crates/ruff_linter/resources/test/fixtures/fastapi/FAST003.py
@@ -303,7 +303,9 @@ async def read_thing_posonly_with_regular(query: str = "", /, x=None): ...
 
 # https://github.com/astral-sh/ruff/issues/23526
 
-# OK: callable class dependency with __call__ method
+# Error: `Depends(CallableQuery)` passes the class itself, so FastAPI uses
+# `__init__` (which has no params here), not `__call__`. The path parameter
+# `thing_id` is unused.
 class CallableQuery:
     def __call__(self, thing_id: int):
         pass
@@ -313,7 +315,14 @@ def __call__(self, thing_id: int):
 async def read_thing_callable_dep(query: Annotated[str, Depends(CallableQuery)]): ...
 
 
-# OK: class with both __init__ and __call__
+# OK: `Depends(CallableQuery())` passes an instance, so FastAPI uses `__call__`,
+# which declares `thing_id`.
+@app.get("/things/{thing_id}")
+async def read_thing_callable_dep_instance(query: Annotated[str, Depends(CallableQuery())]): ...
+
+
+# OK: class with both __init__ and __call__, passed as class reference.
+# FastAPI uses `__init__`, which declares `thing_id`.
 class InitAndCallQuery:
     def __init__(self, thing_id: int):
         pass
@@ -326,7 +335,8 @@ def __call__(self, other: str):
 async def read_thing_init_and_call_dep(query: Annotated[str, Depends(InitAndCallQuery)]): ...
 
 
-# Error: callable class dependency where path param is not in __call__
+# Error: `Depends(CallableQueryOther)` — class reference, uses `__init__` (no
+# params). `thing_id` is unused.
 class CallableQueryOther:
     def __call__(self, other: str):
         pass
@@ -336,6 +346,12 @@ def __call__(self, other: str):
 async def read_thing_callable_dep_missing(query: Annotated[str, Depends(CallableQueryOther)]): ...
 
 
+# Error: `Depends(InitAndCallQuery())` passes an instance, so FastAPI uses
+# `__call__`, which has `other` — not `thing_id`.
+@app.get("/things/{thing_id}")
+async def read_thing_init_and_call_instance(query: Annotated[str, Depends(InitAndCallQuery())]): ...
+
+
 # OK: class with no __init__ and no __call__ (unknown dependency, no diagnostic)
 class EmptyClass:
     pass
diff --git a/crates/ruff_linter/src/rules/fastapi/rules/fastapi_unused_path_parameter.rs b/crates/ruff_linter/src/rules/fastapi/rules/fastapi_unused_path_parameter.rs
@@ -307,13 +307,27 @@ impl<'a> Dependency<'a> {
     }
 
     fn from_depends_call(arguments: &'a Arguments, semantic: &SemanticModel<'a>) -> Option<Self> {
-        let Some(Expr::Name(name)) = arguments.find_argument_value("dependency", 0) else {
-            return None;
-        };
-
-        Self::from_dependency_name(name, semantic)
+        let dep_arg = arguments.find_argument_value("dependency", 0)?;
+
+        match dep_arg {
+            // `Depends(some_callable)` — a name reference (function or class).
+            Expr::Name(name) => Self::from_dependency_name(name, semantic),
+            // `Depends(SomeClass(...))` — a call expression. If the callee is a
+            // class, FastAPI will invoke `__call__` on the resulting instance.
+            Expr::Call(call) => {
+                let Expr::Name(name) = call.func.as_ref() else {
+                    return None;
+                };
+                Self::from_dependency_instance(name, semantic)
+            }
+            _ => None,
+        }
     }
 
+    /// Resolve a dependency that is a name reference (e.g. `Depends(Query)`).
+    ///
+    /// For classes, FastAPI calls the class constructor, so the parameters come
+    /// from `__init__`.
     fn from_dependency_name(name: &'a ast::ExprName, semantic: &SemanticModel<'a>) -> Option<Self> {
         let Some(binding) = semantic.only_binding(name).map(|id| semantic.binding(id)) else {
             return Some(Self::Unknown);
@@ -334,55 +348,75 @@ impl<'a> Dependency<'a> {
                 Some(Self::Function(parameter_names))
             }
             BindingKind::ClassDefinition(scope_id) => {
-                let scope = &semantic.scopes[scope_id];
-
-                let ScopeKind::Class(class_def) = scope.kind else {
-                    return Some(Self::Unknown);
-                };
+                Self::class_params_from_method(semantic, scope_id, "__init__")
+            }
+            _ => Some(Self::Unknown),
+        }
+    }
 
-                let parameter_names = if class_def
-                    .bases()
-                    .iter()
-                    .any(|expr| is_pydantic_base_model(expr, semantic))
-                {
-                    class_def
-                        .body
-                        .iter()
-                        .filter_map(|stmt| {
-                            stmt.as_ann_assign_stmt()
-                                .and_then(|ann_assign| ann_assign.target.as_name_expr())
-                                .map(|name| name.id.as_str())
-                        })
-                        .collect()
-                } else if let Some(method_def) = class_def
-                    .body
-                    .iter()
-                    .filter_map(|stmt| stmt.as_function_def_stmt())
-                    .find(|func_def| {
-                        func_def.name.as_str() == "__init__"
-                            || func_def.name.as_str() == "__call__"
-                    })
-                {
-                    // Skip `self` parameter.
-                    //
-                    // For classes used as FastAPI dependencies, the parameters
-                    // can come from either `__init__` (when the class itself is
-                    // passed to `Depends`) or `__call__` (when an instance of
-                    // the class is passed to `Depends`). We check `__init__`
-                    // first, falling back to `__call__`.
-                    non_posonly_non_variadic_parameters(method_def)
-                        .skip(1)
-                        .map(|param| param.name().as_str())
-                        .collect()
-                } else {
-                    return Some(Self::Unknown);
-                };
+    /// Resolve a dependency that is a class instance (e.g. `Depends(Query())`).
+    ///
+    /// FastAPI calls the instance, so the parameters come from `__call__`.
+    fn from_dependency_instance(
+        name: &'a ast::ExprName,
+        semantic: &SemanticModel<'a>,
+    ) -> Option<Self> {
+        let Some(binding) = semantic.only_binding(name).map(|id| semantic.binding(id)) else {
+            return Some(Self::Unknown);
+        };
 
-                Some(Self::Class(parameter_names))
+        match binding.kind {
+            BindingKind::ClassDefinition(scope_id) => {
+                Self::class_params_from_method(semantic, scope_id, "__call__")
             }
             _ => Some(Self::Unknown),
         }
     }
+
+    /// Extract parameters from a specific method (`__init__` or `__call__`) of a class.
+    fn class_params_from_method(
+        semantic: &SemanticModel<'a>,
+        scope_id: ruff_python_semantic::ScopeId,
+        method_name: &str,
+    ) -> Option<Self> {
+        let scope = &semantic.scopes[scope_id];
+
+        let ScopeKind::Class(class_def) = scope.kind else {
+            return Some(Self::Unknown);
+        };
+
+        let parameter_names = if class_def
+            .bases()
+            .iter()
+            .any(|expr| is_pydantic_base_model(expr, semantic))
+        {
+            class_def
+                .body
+                .iter()
+                .filter_map(|stmt| {
+                    stmt.as_ann_assign_stmt()
+                        .and_then(|ann_assign| ann_assign.target.as_name_expr())
+                        .map(|name| name.id.as_str())
+                })
+                .collect()
+        } else if let Some(method_def) = class_def
+            .body
+            .iter()
+            .filter_map(|stmt| stmt.as_function_def_stmt())
+            .find(|func_def| func_def.name.as_str() == method_name)
+        {
+            // Skip `self` parameter
+            non_posonly_non_variadic_parameters(method_def)
+                .skip(1)
+                .map(|param| param.name().as_str())
+                .collect()
+        } else {
+            // No matching method found — treat as unknown to suppress false positives.
+            return Some(Self::Unknown);
+        };
+
+        Some(Self::Class(parameter_names))
+    }
 }
 
 fn depends_arguments<'a>(expr: &'a Expr, semantic: &SemanticModel) -> Option<&'a Arguments> {
diff --git a/crates/ruff_linter/src/rules/fastapi/snapshots/ruff_linter__rules__fastapi__tests__deferred_annotations_diff_fast-api-unused-path-parameter_FAST003.py.snap b/crates/ruff_linter/src/rules/fastapi/snapshots/ruff_linter__rules__fastapi__tests__deferred_annotations_diff_fast-api-unused-path-parameter_FAST003.py.snap
@@ -1,6 +1,5 @@
 ---
 source: crates/ruff_linter/src/rules/fastapi/mod.rs
-assertion_line: 41
 ---
 --- Linter settings ---
 -linter.unresolved_target_version = 3.13
@@ -75,20 +74,22 @@ help: Add `id` to function signature
 note: This is an unsafe fix and may change runtime behavior
 
 
-FAST003 [*] Parameter `thing_id` appears in route path, but not in `read_thing_callable_dep_missing` signature
-   --> FAST003.py:335:19
+FAST003 [*] Parameter `thing_id` appears in route path, but not in `read_thing_init_and_call_instance` signature
+   --> FAST003.py:351:19
     |
-335 | @app.get("/things/{thing_id}")
+349 | # Error: `Depends(InitAndCallQuery())` passes an instance, so FastAPI uses
+350 | # `__call__`, which has `other` — not `thing_id`.
+351 | @app.get("/things/{thing_id}")
     |                   ^^^^^^^^^^
-336 | async def read_thing_callable_dep_missing(query: Annotated[str, Depends(CallableQueryOther)]): ...
+352 | async def read_thing_init_and_call_instance(query: Annotated[str, Depends(InitAndCallQuery())]): ...
     |
 help: Add `thing_id` to function signature
-333 | 
-334 | 
-335 | @app.get("/things/{thing_id}")
-    - async def read_thing_callable_dep_missing(query: Annotated[str, Depends(CallableQueryOther)]): ...
-336 + async def read_thing_callable_dep_missing(query: Annotated[str, Depends(CallableQueryOther)], thing_id): ...
-337 | 
-338 | 
-339 | # OK: class with no __init__ and no __call__ (unknown dependency, no diagnostic)
+349 | # Error: `Depends(InitAndCallQuery())` passes an instance, so FastAPI uses
+350 | # `__call__`, which has `other` — not `thing_id`.
+351 | @app.get("/things/{thing_id}")
+    - async def read_thing_init_and_call_instance(query: Annotated[str, Depends(InitAndCallQuery())]): ...
+352 + async def read_thing_init_and_call_instance(query: Annotated[str, Depends(InitAndCallQuery())], thing_id): ...
+353 | 
+354 | 
+355 | # OK: class with no __init__ and no __call__ (unknown dependency, no diagnostic)
 note: This is an unsafe fix and may change runtime behavior
diff --git a/crates/ruff_linter/src/rules/fastapi/snapshots/ruff_linter__rules__fastapi__tests__deferred_annotations_diff_fast-api-unused-path-parameter_FAST003.py.snap.new b/crates/ruff_linter/src/rules/fastapi/snapshots/ruff_linter__rules__fastapi__tests__deferred_annotations_diff_fast-api-unused-path-parameter_FAST003.py.snap.new
@@ -0,0 +1,96 @@
+---
+source: crates/ruff_linter/src/rules/fastapi/mod.rs
+assertion_line: 41
+---
+--- Linter settings ---
+-linter.unresolved_target_version = 3.13
++linter.unresolved_target_version = 3.14
+
+--- Summary ---
+Removed: 4
+Added: 0
+
+--- Removed ---
+FAST003 [*] Parameter `thing_id` appears in route path, but not in `single` signature
+   --> FAST003.py:158:19
+    |
+157 | ### Errors
+158 | @app.get("/things/{thing_id}")
+    |                   ^^^^^^^^^^
+159 | async def single(other: Annotated[str, Depends(something_else)]): ...
+160 | @app.get("/things/{thing_id}")
+    |
+help: Add `thing_id` to function signature
+156 | 
+157 | ### Errors
+158 | @app.get("/things/{thing_id}")
+    - async def single(other: Annotated[str, Depends(something_else)]): ...
+159 + async def single(other: Annotated[str, Depends(something_else)], thing_id): ...
+160 | @app.get("/things/{thing_id}")
+161 | async def default(other: str = Depends(something_else)): ...
+162 | 
+note: This is an unsafe fix and may change runtime behavior
+
+
+FAST003 [*] Parameter `id` appears in route path, but not in `get_id_pydantic_full` signature
+   --> FAST003.py:197:12
+    |
+196 | # Errors
+197 | @app.get("/{id}")
+    |            ^^^^
+198 | async def get_id_pydantic_full(
+199 |     params: Annotated[PydanticParams, Depends(PydanticParams)],
+    |
+help: Add `id` to function signature
+196 | # Errors
+197 | @app.get("/{id}")
+198 | async def get_id_pydantic_full(
+    -     params: Annotated[PydanticParams, Depends(PydanticParams)],
+199 +     params: Annotated[PydanticParams, Depends(PydanticParams)], id,
+200 | ): ...
+201 | @app.get("/{id}")
+202 | async def get_id_pydantic_short(params: Annotated[PydanticParams, Depends()]): ...
+note: This is an unsafe fix and may change runtime behavior
+
+
+FAST003 [*] Parameter `id` appears in route path, but not in `get_id_pydantic_short` signature
+   --> FAST003.py:201:12
+    |
+199 |     params: Annotated[PydanticParams, Depends(PydanticParams)],
+200 | ): ...
+201 | @app.get("/{id}")
+    |            ^^^^
+202 | async def get_id_pydantic_short(params: Annotated[PydanticParams, Depends()]): ...
+203 | @app.get("/{id}")
+    |
+help: Add `id` to function signature
+199 |     params: Annotated[PydanticParams, Depends(PydanticParams)],
+200 | ): ...
+201 | @app.get("/{id}")
+    - async def get_id_pydantic_short(params: Annotated[PydanticParams, Depends()]): ...
+202 + async def get_id_pydantic_short(params: Annotated[PydanticParams, Depends()], id): ...
+203 | @app.get("/{id}")
+204 | async def get_id_init_not_annotated(params = Depends(InitParams)): ...
+205 | 
+note: This is an unsafe fix and may change runtime behavior
+
+
+FAST003 [*] Parameter `thing_id` appears in route path, but not in `read_thing_init_and_call_instance` signature
+   --> FAST003.py:353:19
+    |
+351 | # (the instance was already constructed).
+352 | # Actually this should be an error since __call__ has `other`, not `thing_id`.
+353 | @app.get("/things/{thing_id}")
+    |                   ^^^^^^^^^^
+354 | async def read_thing_init_and_call_instance(query: Annotated[str, Depends(InitAndCallQuery())]): ...
+    |
+help: Add `thing_id` to function signature
+351 | # (the instance was already constructed).
+352 | # Actually this should be an error since __call__ has `other`, not `thing_id`.
+353 | @app.get("/things/{thing_id}")
+    - async def read_thing_init_and_call_instance(query: Annotated[str, Depends(InitAndCallQuery())]): ...
+354 + async def read_thing_init_and_call_instance(query: Annotated[str, Depends(InitAndCallQuery())], thing_id): ...
+355 | 
+356 | 
+357 | # OK: class with no __init__ and no __call__ (unknown dependency, no diagnostic)
+note: This is an unsafe fix and may change runtime behavior
