Improve error message for function bodies with docstrings and ... (introduce Y048) (#256)

Author: AlexWaygood

CHANGELOG.md

@@ -4,6 +4,11 @@
 
 New error codes:
 * Y046: Detect unused `Protocol`s.
+* Y048: Function bodies should contain exactly one statement.
+
+Bugfixes:
+* Improve error message for the case where a function body contains a docstring
+  and a `...` or `pass` statement.
 
 Other changes:
 * Pin required flake8 version to <5.0.0 (flake8-pyi is not currently compatible with flake8 5.0.0).

README.md

@@ -78,6 +78,7 @@ currently emitted:
 | Y044 | `from __future__ import annotations` has no effect in stub files, as forward references in stubs are enabled by default.
 | Y045 | `__iter__` methods should never return `Iterable[T]`, as they should always return some kind of iterator.
 | Y046 | A private `Protocol` should be used at least once in the file in which it is defined.
+| Y048 | Function bodies should contain exactly one statement. (Note that if a function body includes a docstring, the docstring counts as a "statement".)
 
 Many error codes enforce modern conventions, and some cannot yet be used in
 all cases:

pyi.py

@@ -1560,19 +1560,21 @@ def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
         with self.in_function.enabled():
             self.generic_visit(node)
 
-        for i, statement in enumerate(node.body):
-            if i == 0:
-                # normally, should just be "..."
-                if isinstance(statement, ast.Pass):
-                    self.error(statement, Y009)
-                    continue
-                # Ellipsis is fine. Str (docstrings) is not but we produce
-                # tailored error message for it elsewhere.
-                elif isinstance(statement, ast.Expr) and isinstance(
-                    statement.value, (ast.Ellipsis, ast.Str)
-                ):
-                    continue
-            self.error(statement, Y010)
+        body = node.body
+        if len(body) > 1:
+            self.error(body[1], Y048)
+        elif body:
+            statement = body[0]
+            # normally, should just be "..."
+            if isinstance(statement, ast.Pass):
+                self.error(statement, Y009)
+            # Ellipsis is fine. Str (docstrings) is not but we produce
+            # tailored error message for it elsewhere.
+            elif not (
+                isinstance(statement, ast.Expr)
+                and isinstance(statement.value, (ast.Ellipsis, ast.Str))
+            ):
+                self.error(statement, Y010)
 
         if self.in_class.active:
             self.check_self_typevars(node)
@@ -1745,3 +1747,4 @@ def parse_options(
 Y044 = 'Y044 "from __future__ import annotations" has no effect in stub files.'
 Y045 = 'Y045 "{iter_method}" methods should return an {good_cls}, not an {bad_cls}'
 Y046 = 'Y046 Protocol "{protocol_name}" is not used'
+Y048 = "Y048 Function body should contain exactly one statement"

tests/emptyfunctions.pyi

@@ -22,7 +22,7 @@ def returning(x: int) -> float:
 
 def multiple_ellipses(x: int) -> float:
     ...
-    ...  # Y010 Function body must contain only "..."
+    ...  # Y048 Function body should contain exactly one statement
 
 async def empty_async(x: int) -> float: ...
 
@@ -37,4 +37,4 @@ async def returning_async(x: int) -> float:
 
 async def multiple_ellipses_async(x: int) -> float:
     ...
-    ...  # Y010 Function body must contain only "..."
+    ...  # Y048 Function body should contain exactly one statement

tests/quotes.pyi

@@ -34,3 +34,22 @@ elif sys.platform == "win32":
     f: "str"  # Y020 Quoted annotations should never be used in stubs
 else:
     f: "bytes"  # Y020 Quoted annotations should never be used in stubs
+
+class Empty:
+    """Empty"""  # Y021 Docstrings should not be included in stubs
+
+def docstring_and_ellipsis() -> None:
+    """Docstring"""  # Y021 Docstrings should not be included in stubs
+    ...  # Y048 Function body should contain exactly one statement
+
+def docstring_and_pass() -> None:
+    """Docstring"""  # Y021 Docstrings should not be included in stubs
+    pass  # Y048 Function body should contain exactly one statement
+
+class DocstringAndEllipsis:
+    """Docstring"""  # Y021 Docstrings should not be included in stubs
+    ...  # Y013 Non-empty class body must not contain "..."
+
+class DocstringAndPass:
+    """Docstring"""  # Y021 Docstrings should not be included in stubs
+    pass  # Y012 Class body must not contain "pass"