Implement PYI045

crates/ruff/resources/test/fixtures/flake8_pyi/PYI045.py

@@ -0,0 +1,77 @@
+import collections.abc
+import typing
+from collections.abc import Iterator, Iterable
+
+# All OK for PYI045 because this isn't a stub.
+
+
+class NoReturn:
+    def __iter__(self):
+        ...
+
+
+class TypingIterableTReturn:
+    def __iter__(self) -> typing.Iterable[int]:
+        ...
+
+    def not_iter(self) -> typing.Iterable[int]:
+        ...
+
+
+class TypingIterableReturn:
+    def __iter__(self) -> typing.Iterable:
+        ...
+
+    def not_iter(self) -> typing.Iterable:
+        ...
+
+
+class CollectionsIterableTReturn:
+    def __iter__(self) -> collections.abc.Iterable[int]:
+        ...
+
+    def not_iter(self) -> collections.abc.Iterable[int]:
+        ...
+
+
+class CollectionsIterableReturn:
+    def __iter__(self) -> collections.abc.Iterable:
+        ...
+
+    def not_iter(self) -> collections.abc.Iterable:
+        ...
+
+
+class IterableReturn:
+    def __iter__(self) -> Iterable:
+        ...
+
+
+class IteratorReturn:
+    def __iter__(self) -> Iterator:
+        ...
+
+
+class IteratorTReturn:
+    def __iter__(self) -> Iterator[int]:
+        ...
+
+
+class TypingIteratorReturn:
+    def __iter__(self) -> typing.Iterator:
+        ...
+
+
+class TypingIteratorTReturn:
+    def __iter__(self) -> typing.Iterator[int]:
+        ...
+
+
+class CollectionsIteratorReturn:
+    def __iter__(self) -> collections.abc.Iterator:
+        ...
+
+
+class CollectionsIteratorTReturn:
+    def __iter__(self) -> collections.abc.Iterator[int]:
+        ...

crates/ruff/resources/test/fixtures/flake8_pyi/PYI045.pyi

@@ -0,0 +1,43 @@
+import collections.abc
+import typing
+from collections.abc import Iterator, Iterable
+
+class NoReturn:
+    def __iter__(self): ...
+
+class TypingIterableTReturn:
+    def __iter__(self) -> typing.Iterable[int]: ...  # Error: PYI045
+    def not_iter(self) -> typing.Iterable[int]: ...
+
+class TypingIterableReturn:
+    def __iter__(self) -> typing.Iterable: ...  # Error: PYI045
+    def not_iter(self) -> typing.Iterable: ...
+
+class CollectionsIterableTReturn:
+    def __iter__(self) -> collections.abc.Iterable[int]: ...  # Error: PYI045
+    def not_iter(self) -> collections.abc.Iterable[int]: ...
+
+class CollectionsIterableReturn:
+    def __iter__(self) -> collections.abc.Iterable: ...  # Error: PYI045
+    def not_iter(self) -> collections.abc.Iterable: ...
+
+class IterableReturn:
+    def __iter__(self) -> Iterable: ...  # Error: PYI045
+
+class IteratorReturn:
+    def __iter__(self) -> Iterator: ...
+
+class IteratorTReturn:
+    def __iter__(self) -> Iterator[int]: ...
+
+class TypingIteratorReturn:
+    def __iter__(self) -> typing.Iterator: ...
+
+class TypingIteratorTReturn:
+    def __iter__(self) -> typing.Iterator[int]: ...
+
+class CollectionsIteratorReturn:
+    def __iter__(self) -> collections.abc.Iterator: ...
+
+class CollectionsIteratorTReturn:
+    def __iter__(self) -> collections.abc.Iterator[int]: ...

crates/ruff/src/checkers/ast/mod.rs

@@ -5321,7 +5321,8 @@ impl<'a> Checker<'a> {
             Rule::MissingReturnTypeClassMethod,
             Rule::AnyType,
         ]);
-        let enforce_stubs = self.is_stub && self.any_enabled(&[Rule::DocstringInStub]);
+        let enforce_stubs = self.is_stub
+            && self.any_enabled(&[Rule::DocstringInStub, Rule::IterMethodReturnIterable]);
         let enforce_docstrings = self.any_enabled(&[
             Rule::UndocumentedPublicModule,
             Rule::UndocumentedPublicClass,
@@ -5425,6 +5426,9 @@ impl<'a> Checker<'a> {
                     if self.enabled(Rule::DocstringInStub) {
                         flake8_pyi::rules::docstring_in_stubs(self, docstring);
                     }
+                    if self.enabled(Rule::IterMethodReturnIterable) {
+                        flake8_pyi::rules::iter_method_return_iterable(self, definition);
+                    }
                 }
             }
 

crates/ruff/src/codes.rs

@@ -592,6 +592,7 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
         (Flake8Pyi, "033") => (RuleGroup::Unspecified, Rule::TypeCommentInStub),
         (Flake8Pyi, "042") => (RuleGroup::Unspecified, Rule::SnakeCaseTypeAlias),
         (Flake8Pyi, "043") => (RuleGroup::Unspecified, Rule::TSuffixedTypeAlias),
+        (Flake8Pyi, "045") => (RuleGroup::Unspecified, Rule::IterMethodReturnIterable),
         (Flake8Pyi, "048") => (RuleGroup::Unspecified, Rule::StubBodyMultipleStatements),
         (Flake8Pyi, "052") => (RuleGroup::Unspecified, Rule::UnannotatedAssignmentInStub),
 

crates/ruff/src/registry.rs

@@ -512,6 +512,7 @@ ruff_macros::register_rules!(
     rules::flake8_pyi::rules::AssignmentDefaultInStub,
     rules::flake8_pyi::rules::BadVersionInfoComparison,
     rules::flake8_pyi::rules::DocstringInStub,
+    rules::flake8_pyi::rules::IterMethodReturnIterable,
     rules::flake8_pyi::rules::DuplicateUnionMember,
     rules::flake8_pyi::rules::EllipsisInNonEmptyClassBody,
     rules::flake8_pyi::rules::NonEmptyStubBody,

crates/ruff/src/rules/flake8_pyi/mod.rs

@@ -24,6 +24,8 @@ mod tests {
     #[test_case(Rule::DuplicateUnionMember, Path::new("PYI016.pyi"))]
     #[test_case(Rule::EllipsisInNonEmptyClassBody, Path::new("PYI013.py"))]
     #[test_case(Rule::EllipsisInNonEmptyClassBody, Path::new("PYI013.pyi"))]
+    #[test_case(Rule::IterMethodReturnIterable, Path::new("PYI045.py"))]
+    #[test_case(Rule::IterMethodReturnIterable, Path::new("PYI045.pyi"))]
     #[test_case(Rule::NonEmptyStubBody, Path::new("PYI010.py"))]
     #[test_case(Rule::NonEmptyStubBody, Path::new("PYI010.pyi"))]
     #[test_case(Rule::PassInClassBody, Path::new("PYI012.py"))]

crates/ruff/src/rules/flake8_pyi/rules/iter_method_return_iterable.rs

@@ -0,0 +1,86 @@
+use rustpython_parser::ast;
+use rustpython_parser::ast::{Ranged, Stmt};
+
+use ruff_diagnostics::{Diagnostic, Violation};
+use ruff_macros::{derive_message_formats, violation};
+use ruff_python_ast::prelude::Expr;
+use ruff_python_semantic::definition::{Definition, Member, MemberKind};
+
+use crate::checkers::ast::Checker;
+
+/// ## What it does
+/// Checks for `__iter__` methods in stubs with the wrong return type annotation.
+///
+/// ## Why is this bad?
+/// `__iter__` should return an `Iterator`, not an `Iterable`.
+///
+/// ## Example
+/// ```python
+/// class Foo:
+///     def __iter__(self) -> collections.abc.Iterable: ...
+/// ```
+///
+/// Use instead:
+/// ```python
+/// class Foo:
+///     def __iter__(self) -> collections.abc.Iterator: ...
+/// ```
+#[violation]
+pub struct IterMethodReturnIterable;
+
+impl Violation for IterMethodReturnIterable {
+    #[derive_message_formats]
+    fn message(&self) -> String {
+        format!("__iter__ methods should never return ` Iterable[T]`, as they should always return some kind of `Iterator`.")
+    }
+}
+
+/// PYI045
+pub(crate) fn iter_method_return_iterable(checker: &mut Checker, definition: &Definition) {
+    let Definition::Member(Member {
+                               kind: MemberKind::Method,
+                               stmt,
+                               ..
+                           }) = definition else {
+        return;
+    };
+
+    let Stmt::FunctionDef(ast::StmtFunctionDef {
+                              name,
+                              returns,
+                              ..
+                          }) = stmt else {
+        return;
+    };
+
+    if name != "__iter__" {
+        return;
+    }
+
+    let Some(returns) = returns else {
+        return;
+    };
+
+    let annotation = match returns.as_ref() {
+        // e.g., Iterable[T]
+        Expr::Subscript(ast::ExprSubscript { value, .. }) => value.as_ref(),
+        // e.g., typing.Iterable, Iterable
+        ann_expr @ (Expr::Name(_) | Expr::Attribute(_)) => ann_expr,
+        _ => return,
+    };
+
+    if checker
+        .semantic_model()
+        .resolve_call_path(annotation)
+        .map_or(false, |cp| {
+            matches!(
+                cp.as_slice(),
+                &["typing", "Iterable"] | &["collections", "abc", "Iterable"]
+            )
+        })
+    {
+        checker
+            .diagnostics
+            .push(Diagnostic::new(IterMethodReturnIterable, returns.range()));
+    }
+}

crates/ruff/src/rules/flake8_pyi/rules/mod.rs

@@ -6,6 +6,9 @@ pub(crate) use duplicate_union_member::{duplicate_union_member, DuplicateUnionMe
 pub(crate) use ellipsis_in_non_empty_class_body::{
     ellipsis_in_non_empty_class_body, EllipsisInNonEmptyClassBody,
 };
+pub(crate) use iter_method_return_iterable::{
+    iter_method_return_iterable, IterMethodReturnIterable,
+};
 pub(crate) use non_empty_stub_body::{non_empty_stub_body, NonEmptyStubBody};
 pub(crate) use pass_in_class_body::{pass_in_class_body, PassInClassBody};
 pub(crate) use pass_statement_stub_body::{pass_statement_stub_body, PassStatementStubBody};
@@ -31,6 +34,7 @@ mod bad_version_info_comparison;
 mod docstring_in_stubs;
 mod duplicate_union_member;
 mod ellipsis_in_non_empty_class_body;
+mod iter_method_return_iterable;
 mod non_empty_stub_body;
 mod pass_in_class_body;
 mod pass_statement_stub_body;

crates/ruff/src/rules/flake8_pyi/snapshots/ruff__rules__flake8_pyi__tests__PYI045_PYI045.py.snap

@@ -0,0 +1,4 @@
+---
+source: crates/ruff/src/rules/flake8_pyi/mod.rs
+---
+

crates/ruff/src/rules/flake8_pyi/snapshots/ruff__rules__flake8_pyi__tests__PYI045_PYI045.pyi.snap

@@ -0,0 +1,45 @@
+---
+source: crates/ruff/src/rules/flake8_pyi/mod.rs
+---
+PYI045.pyi:9:27: PYI045 __iter__ methods should never return ` Iterable[T]`, as they should always return some kind of `Iterator`.
+   |
+ 9 | class TypingIterableTReturn:
+10 |     def __iter__(self) -> typing.Iterable[int]: ... # Error: PYI045
+   |                           ^^^^^^^^^^^^^^^^^^^^ PYI045
+11 |     def not_iter(self) -> typing.Iterable[int]: ...
+   |
+
+PYI045.pyi:13:27: PYI045 __iter__ methods should never return ` Iterable[T]`, as they should always return some kind of `Iterator`.
+   |
+13 | class TypingIterableReturn:
+14 |     def __iter__(self) -> typing.Iterable: ... # Error: PYI045
+   |                           ^^^^^^^^^^^^^^^ PYI045
+15 |     def not_iter(self) -> typing.Iterable: ...
+   |
+
+PYI045.pyi:17:27: PYI045 __iter__ methods should never return ` Iterable[T]`, as they should always return some kind of `Iterator`.
+   |
+17 | class CollectionsIterableTReturn:
+18 |     def __iter__(self) -> collections.abc.Iterable[int]: ... # Error: PYI045
+   |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PYI045
+19 |     def not_iter(self) -> collections.abc.Iterable[int]: ...
+   |
+
+PYI045.pyi:21:27: PYI045 __iter__ methods should never return ` Iterable[T]`, as they should always return some kind of `Iterator`.
+   |
+21 | class CollectionsIterableReturn:
+22 |     def __iter__(self) -> collections.abc.Iterable: ... # Error: PYI045
+   |                           ^^^^^^^^^^^^^^^^^^^^^^^^ PYI045
+23 |     def not_iter(self) -> collections.abc.Iterable: ...
+   |
+
+PYI045.pyi:25:27: PYI045 __iter__ methods should never return ` Iterable[T]`, as they should always return some kind of `Iterator`.
+   |
+25 | class IterableReturn:
+26 |     def __iter__(self) -> Iterable: ... # Error: PYI045
+   |                           ^^^^^^^^ PYI045
+27 | 
+28 | class IteratorReturn:
+   |
+
+