[flake8-annotations] Don't suggest NoReturn for functions raising NotImplementedError (ANN201, ANN202, ANN205, ANN206) (#21311)

## Summary

Fix ANN201, ANN202, ANN205, and ANN206 to not automatically suggest
`NoReturn`/`Never` return type annotations for functions that raise
`NotImplementedError`. These rules will still flag missing return type
annotations but won't provide an auto-fix, allowing developers to
manually specify the actual return type that implementations should
return.

Fixes #18886

## Problem Analysis

The bug occurred because the `auto_return_type` function in
`flake8_annotations/helpers.rs` detects when all control flow paths in a
function raise an exception (`Terminal::Raise`) and automatically
suggests `NoReturn`/`Never` as the return type. However,
`NotImplementedError` is semantically different from other exceptions -
it's used to indicate abstract methods that should be implemented by
subclasses, not methods that truly never return.

When a function raises `NotImplementedError`, it's typically an abstract
method pattern where:
- The base class defines the method signature but doesn't implement it
- Subclasses are expected to override the method with a proper
implementation
- The return type should reflect what implementations will actually
return, not `NoReturn`

For example, in Django's serializer pattern:

```py
class BaseSerializer:
    def to_internal_value(self, data):
        raise NotImplementedError('`to_internal_value()` must be implemented.')
```

This method should have a return type annotation like `dict` or `Any`,
not `NoReturn`, because implementations will return actual values.

## Approach

The fix modifies the `auto_return_type` function to:

1. **Added semantic analysis capability**: Modified `auto_return_type`
to accept a `SemanticModel` parameter, enabling it to analyze exception
types in raise statements.

2. **Created detection helper**: Implemented
`only_raises_not_implemented_error()` function that:
- Traverses the function body using a custom visitor to collect all
`raise` statements
- Checks if all raises are `NotImplementedError` (or `NotImplemented`)
using semantic analysis
   - Returns `true` only if all raises are `NotImplementedError`

3. **Modified return type inference**: When `Terminal::Raise` is
detected, the function now:
   - First checks if all raises are `NotImplementedError`
- If yes, returns `None` (no auto-fix suggested, but diagnostic still
emitted)
- If no, returns `AutoPythonType::Never` as before (suggesting
`NoReturn`/`Never`)

4. **Updated all call sites**: Updated all 4 call sites in
`definition.rs` to pass `checker.semantic()`:
   - ANN201 (public functions)
   - ANN202 (private functions)  
   - ANN205 (static methods)
   - ANN206 (class methods)

The fix ensures that:
- Functions raising `NotImplementedError` still get flagged for missing
return type annotations
- But no auto-fix is suggested, allowing manual specification of the
correct return type
- Functions raising other exceptions (like `ValueError`) still correctly
get `NoReturn`/`Never` suggestions

---------

Co-authored-by: Brent Westbrook <brentrwestbrook@gmail.com>

Author: danparizher

crates/ruff_linter/resources/test/fixtures/flake8_annotations/auto_return_type.py

@@ -302,3 +302,26 @@ def func(x: int):
             return 1
         case y:
             return "foo"
+
+
+# Test cases for NotImplementedError - should not get NoReturn auto-fix
+def func():
+    raise NotImplementedError
+
+
+class Class:
+    @staticmethod
+    def func():
+        raise NotImplementedError
+
+    @classmethod
+    def method(cls):
+        raise NotImplementedError
+
+    def instance_method(self):
+        raise NotImplementedError
+
+
+# Test case: function that raises other exceptions should still get NoReturn
+def func():
+    raise ValueError

crates/ruff_linter/src/rules/flake8_annotations/helpers.rs

@@ -48,7 +48,10 @@ pub(crate) fn is_overload_impl(
 }
 
 /// Given a function, guess its return type.
-pub(crate) fn auto_return_type(function: &ast::StmtFunctionDef) -> Option<AutoPythonType> {
+pub(crate) fn auto_return_type(
+    function: &ast::StmtFunctionDef,
+    semantic: &SemanticModel,
+) -> Option<AutoPythonType> {
     // Collect all the `return` statements.
     let returns = {
         let mut visitor = ReturnStatementVisitor::default();
@@ -63,9 +66,16 @@ pub(crate) fn auto_return_type(function: &ast::StmtFunctionDef) -> Option<AutoPy
     };
 
     // Determine the terminal behavior (i.e., implicit return, no return, etc.).
-    let terminal = Terminal::from_function(function);
+    let terminal = Terminal::from_function(function, semantic);
+
+    // If every control flow path raises NotImplementedError, don't suggest NoReturn
+    // since these are abstract methods that should have the actual return type.
+    if terminal == Terminal::RaiseNotImplemented {
+        return None;
+    }
 
-    // If every control flow path raises an exception, return `NoReturn`.
+    // If every control flow path raises an exception (other than NotImplementedError),
+    // suggest NoReturn.
     if terminal == Terminal::Raise {
         return Some(AutoPythonType::Never);
     }

crates/ruff_linter/src/rules/flake8_annotations/rules/definition.rs

@@ -774,7 +774,7 @@ pub(crate) fn definition(
                 let return_type = if is_stub_function(function, checker) {
                     None
                 } else {
-                    auto_return_type(function)
+                    auto_return_type(function, checker.semantic())
                         .and_then(|return_type| {
                             return_type.into_expression(checker, function.parameters.start())
                         })
@@ -801,7 +801,7 @@ pub(crate) fn definition(
                 let return_type = if is_stub_function(function, checker) {
                     None
                 } else {
-                    auto_return_type(function)
+                    auto_return_type(function, checker.semantic())
                         .and_then(|return_type| {
                             return_type.into_expression(checker, function.parameters.start())
                         })
@@ -887,7 +887,7 @@ pub(crate) fn definition(
                         let return_type = if is_stub_function(function, checker) {
                             None
                         } else {
-                            auto_return_type(function)
+                            auto_return_type(function, checker.semantic())
                                 .and_then(|return_type| {
                                     return_type
                                         .into_expression(checker, function.parameters.start())
@@ -922,7 +922,7 @@ pub(crate) fn definition(
                         let return_type = if is_stub_function(function, checker) {
                             None
                         } else {
-                            auto_return_type(function)
+                            auto_return_type(function, checker.semantic())
                                 .and_then(|return_type| {
                                     return_type
                                         .into_expression(checker, function.parameters.start())

crates/ruff_linter/src/rules/flake8_annotations/snapshots/ruff_linter__rules__flake8_annotations__tests__auto_return_type.snap

@@ -775,3 +775,71 @@ help: Add return type annotation: `str | int`
 301 |         case [1, 2, 3]:
 302 |             return 1
 note: This is an unsafe fix and may change runtime behavior
+
+ANN201 Missing return type annotation for public function `func`
+   --> auto_return_type.py:308:5
+    |
+307 | # Test cases for NotImplementedError - should not get NoReturn auto-fix
+308 | def func():
+    |     ^^^^
+309 |     raise NotImplementedError
+    |
+help: Add return type annotation
+
+ANN205 Missing return type annotation for staticmethod `func`
+   --> auto_return_type.py:314:9
+    |
+312 | class Class:
+313 |     @staticmethod
+314 |     def func():
+    |         ^^^^
+315 |         raise NotImplementedError
+    |
+help: Add return type annotation
+
+ANN206 Missing return type annotation for classmethod `method`
+   --> auto_return_type.py:318:9
+    |
+317 |     @classmethod
+318 |     def method(cls):
+    |         ^^^^^^
+319 |         raise NotImplementedError
+    |
+help: Add return type annotation
+
+ANN201 Missing return type annotation for public function `instance_method`
+   --> auto_return_type.py:321:9
+    |
+319 |         raise NotImplementedError
+320 |
+321 |     def instance_method(self):
+    |         ^^^^^^^^^^^^^^^
+322 |         raise NotImplementedError
+    |
+help: Add return type annotation
+
+ANN201 [*] Missing return type annotation for public function `func`
+   --> auto_return_type.py:326:5
+    |
+325 | # Test case: function that raises other exceptions should still get NoReturn
+326 | def func():
+    |     ^^^^
+327 |     raise ValueError
+    |
+help: Add return type annotation: `Never`
+214 |         return 1
+215 | 
+216 | 
+    - from typing import overload
+217 + from typing import overload, Never
+218 | 
+219 | 
+220 | @overload
+--------------------------------------------------------------------------------
+323 | 
+324 | 
+325 | # Test case: function that raises other exceptions should still get NoReturn
+    - def func():
+326 + def func() -> Never:
+327 |     raise ValueError
+note: This is an unsafe fix and may change runtime behavior

crates/ruff_linter/src/rules/flake8_annotations/snapshots/ruff_linter__rules__flake8_annotations__tests__auto_return_type_py38.snap

@@ -879,3 +879,71 @@ help: Add return type annotation: `Union[str, int]`
 301 |         case [1, 2, 3]:
 302 |             return 1
 note: This is an unsafe fix and may change runtime behavior
+
+ANN201 Missing return type annotation for public function `func`
+   --> auto_return_type.py:308:5
+    |
+307 | # Test cases for NotImplementedError - should not get NoReturn auto-fix
+308 | def func():
+    |     ^^^^
+309 |     raise NotImplementedError
+    |
+help: Add return type annotation
+
+ANN205 Missing return type annotation for staticmethod `func`
+   --> auto_return_type.py:314:9
+    |
+312 | class Class:
+313 |     @staticmethod
+314 |     def func():
+    |         ^^^^
+315 |         raise NotImplementedError
+    |
+help: Add return type annotation
+
+ANN206 Missing return type annotation for classmethod `method`
+   --> auto_return_type.py:318:9
+    |
+317 |     @classmethod
+318 |     def method(cls):
+    |         ^^^^^^
+319 |         raise NotImplementedError
+    |
+help: Add return type annotation
+
+ANN201 Missing return type annotation for public function `instance_method`
+   --> auto_return_type.py:321:9
+    |
+319 |         raise NotImplementedError
+320 |
+321 |     def instance_method(self):
+    |         ^^^^^^^^^^^^^^^
+322 |         raise NotImplementedError
+    |
+help: Add return type annotation
+
+ANN201 [*] Missing return type annotation for public function `func`
+   --> auto_return_type.py:326:5
+    |
+325 | # Test case: function that raises other exceptions should still get NoReturn
+326 | def func():
+    |     ^^^^
+327 |     raise ValueError
+    |
+help: Add return type annotation: `NoReturn`
+214 |         return 1
+215 | 
+216 | 
+    - from typing import overload
+217 + from typing import overload, NoReturn
+218 | 
+219 | 
+220 | @overload
+--------------------------------------------------------------------------------
+323 | 
+324 | 
+325 | # Test case: function that raises other exceptions should still get NoReturn
+    - def func():
+326 + def func() -> NoReturn:
+327 |     raise ValueError
+note: This is an unsafe fix and may change runtime behavior

crates/ruff_linter/src/rules/pylint/rules/invalid_bool_return.rs

@@ -60,10 +60,10 @@ pub(crate) fn invalid_bool_return(checker: &Checker, function_def: &ast::StmtFun
     }
 
     // Determine the terminal behavior (i.e., implicit return, no return, etc.).
-    let terminal = Terminal::from_function(function_def);
+    let terminal = Terminal::from_function(function_def, checker.semantic());
 
     // If every control flow path raises an exception, ignore the function.
-    if terminal == Terminal::Raise {
+    if terminal.is_always_raise() {
         return;
     }
 

crates/ruff_linter/src/rules/pylint/rules/invalid_bytes_return.rs

@@ -60,10 +60,10 @@ pub(crate) fn invalid_bytes_return(checker: &Checker, function_def: &ast::StmtFu
     }
 
     // Determine the terminal behavior (i.e., implicit return, no return, etc.).
-    let terminal = Terminal::from_function(function_def);
+    let terminal = Terminal::from_function(function_def, checker.semantic());
 
     // If every control flow path raises an exception, ignore the function.
-    if terminal == Terminal::Raise {
+    if terminal.is_always_raise() {
         return;
     }
 

crates/ruff_linter/src/rules/pylint/rules/invalid_hash_return.rs

@@ -64,10 +64,10 @@ pub(crate) fn invalid_hash_return(checker: &Checker, function_def: &ast::StmtFun
     }
 
     // Determine the terminal behavior (i.e., implicit return, no return, etc.).
-    let terminal = Terminal::from_function(function_def);
+    let terminal = Terminal::from_function(function_def, checker.semantic());
 
     // If every control flow path raises an exception, ignore the function.
-    if terminal == Terminal::Raise {
+    if terminal.is_always_raise() {
         return;
     }
 

crates/ruff_linter/src/rules/pylint/rules/invalid_index_return.rs

@@ -66,10 +66,10 @@ pub(crate) fn invalid_index_return(checker: &Checker, function_def: &ast::StmtFu
     }
 
     // Determine the terminal behavior (i.e., implicit return, no return, etc.).
-    let terminal = Terminal::from_function(function_def);
+    let terminal = Terminal::from_function(function_def, checker.semantic());
 
     // If every control flow path raises an exception, ignore the function.
-    if terminal == Terminal::Raise {
+    if terminal.is_always_raise() {
         return;
     }
 

crates/ruff_linter/src/rules/pylint/rules/invalid_length_return.rs

@@ -65,10 +65,10 @@ pub(crate) fn invalid_length_return(checker: &Checker, function_def: &ast::StmtF
     }
 
     // Determine the terminal behavior (i.e., implicit return, no return, etc.).
-    let terminal = Terminal::from_function(function_def);
+    let terminal = Terminal::from_function(function_def, checker.semantic());
 
     // If every control flow path raises an exception, ignore the function.
-    if terminal == Terminal::Raise {
+    if terminal.is_always_raise() {
         return;
     }