Fix how multiple __init__() are recognized (#273)

Author: jsh9

CHANGELOG.md

@@ -1,10 +1,16 @@
 # Change Log
 
-## [Unpublished]
+## [0.8.2] - 2025-11-21
 
 - Added
   - Ability to partially match violation codes in inline `noqa` in the native
     mode (which _flake8_ already supports)
+- Fixed
+  - A bug: when there are more than one `__init__()` in a class (overloaded),
+    the first `__init__()` is incorrectly recognized as the "right" one. (The
+    last `__init__()` should be considered the right one.)
+- Full diff
+  - https://github.com/jsh9/pydoclint/compare/0.8.1...0.8.2
 
 ## [0.8.1] - 2025-11-03
 

pydoclint/utils/generic.py

@@ -109,6 +109,36 @@ def getDocstring(node: ClassOrFunctionDef) -> str:
     return '' if docstring_ is None else docstring_
 
 
+def isLastConstructor(
+        node: FuncOrAsyncFuncDef,
+        parentClass: ast.ClassDef,
+) -> bool:
+    """
+    Return True if the given __init__() is the last constructor in the class.
+
+    Overload stubs typically appear before the real implementation; by
+    detecting whether another constructor follows, we can ignore those stubs so
+    only the final body gets linted.
+    """
+    hasSeenNode = False
+    for child in parentClass.body:
+        if child is node:
+            hasSeenNode = True
+            continue
+
+        if not hasSeenNode:
+            continue
+
+        isConstructor = (
+            isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef))
+            and child.name == '__init__'
+        )
+        if isConstructor:
+            return False
+
+    return True
+
+
 def generateClassMsgPrefix(node: ast.ClassDef, *, appendColon: bool) -> str:
     """
     Generate violation message prefix for classes.

pydoclint/visitor.py

@@ -21,6 +21,7 @@
     generateClassMsgPrefix,
     generateFuncMsgPrefix,
     getDocstring,
+    isLastConstructor,
 )
 from pydoclint.utils.method_type import MethodType
 from pydoclint.utils.parse_docstring import (
@@ -172,6 +173,18 @@ def visit_FunctionDef(self, node: FuncOrAsyncFuncDef) -> None:  # noqa: D102, PL
             parent_, ast.ClassDef
         )
 
+        if (
+            isClassConstructor
+            and isinstance(parent_, ast.ClassDef)
+            and not isLastConstructor(node=node, parentClass=parent_)
+        ):
+            # Multiple __init__ definitions can exist when using overload stubs
+            # but only the last implementation represents the real constructor
+            # body, so earlier ones are skipped to avoid reporting bogus
+            # violations.
+            self.parent = parent_  # restore
+            return
+
         docstring: str = getDocstring(node)
 
         self.isAbstractMethod = checkIsAbstractMethod(node)

pyproject.toml

@@ -4,7 +4,7 @@ requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2", "wheel"]
 
 [project]
 name = "pydoclint"
-version = "0.8.1"
+version = "0.8.2"
 dependencies = [
   "click>=8.1.0",
   "docstring_parser_fork>=0.0.12",

tests/test_data/edge_cases/32_multiple_init/allow_init_docstring/google.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import overload
+
+
+class Example:
+    """Example class docstring."""
+
+    @overload
+    def __init__(self, value: str) -> None:
+        """Incorrect docstring that should be ignored.
+
+        Args:
+            wrong (int): This argument does not exist in the signature.
+        """
+
+    def __init__(self, value: str, size: int) -> None:
+        """Actual implementation docstring.
+
+        Args:
+            value (str): Primary value.
+            size (int): Size of something important.
+        """

tests/test_data/edge_cases/32_multiple_init/allow_init_docstring/numpy.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import overload
+
+
+class Example:
+    """Example class docstring."""
+
+    @overload
+    def __init__(self, value: str) -> None:
+        """Incorrect docstring that should be ignored.
+
+        Parameters
+        ----------
+        wrong : int
+            This argument does not exist in the signature.
+        """
+
+    def __init__(self, value: str, size: int) -> None:
+        """Actual implementation docstring.
+
+        Parameters
+        ----------
+        value : str
+            Primary value.
+        size : int
+            Size of something important.
+        """

tests/test_data/edge_cases/32_multiple_init/allow_init_docstring/sphinx.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import overload
+
+
+class Example:
+    """Example class docstring."""
+
+    @overload
+    def __init__(self, value: str) -> None:
+        """Incorrect docstring that should be ignored.
+
+        :param wrong: This argument does not exist in the signature.
+        :type wrong: int
+        """
+
+    def __init__(self, value: str, size: int) -> None:
+        """Actual implementation docstring.
+
+        :param value: Primary value.
+        :param size: Size of something important.
+        :type value: str
+        :type size: int
+        """

tests/test_data/edge_cases/32_multiple_init/doesnt_allow_init_docstring/google.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import overload
+
+# This case comes from: https://github.com/jsh9/pydoclint/issues/255
+class FooWrite(SomeObject):
+    """
+    The Foo write class.
+
+    Args:
+        bar (str | None): Description of bar.
+        baz (int | None): Description of baz.
+
+    Raises:
+        ValueError: If both bar and baz are None.
+    """
+
+    @overload
+    def __init__(self, bar: None, baz: None) -> NoReturn: ...
+
+    @overload
+    def __init__(self, bar: str | None, baz: int | None) -> None: ...
+
+    def __init__(self, bar: str | None, baz: int | None) -> None:
+        if bar is None and baz is None:
+            raise ValueError

tests/test_data/edge_cases/32_multiple_init/doesnt_allow_init_docstring/numpy.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import overload
+
+# This case comes from: https://github.com/jsh9/pydoclint/issues/255
+class FooWrite(SomeObject):
+    """
+    The Foo write class.
+
+    Parameters
+    ----------
+    bar : str | None
+        Description of bar.
+    baz : int | None
+        Description of baz.
+    
+    Raises
+    ------
+    ValueError
+        If both bar and baz are None.
+    """
+
+    @overload
+    def __init__(self, bar: None, baz: None) -> NoReturn: ...
+
+    @overload
+    def __init__(self, bar: str | None, baz: int | None) -> None: ...
+
+    def __init__(self, bar: str | None, baz: int | None) -> None:
+        if bar is None and baz is None:
+            raise ValueError

tests/test_data/edge_cases/32_multiple_init/doesnt_allow_init_docstring/sphinx.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import overload
+
+# This case comes from: https://github.com/jsh9/pydoclint/issues/255
+class FooWrite(SomeObject):
+    """
+    The Foo write class.
+
+    :param bar: Description of bar.
+    :param baz: Description of baz.
+    :type bar: str | None
+    :type baz: int | None
+    :raises ValueError: If both bar and baz are None.
+    """
+
+    @overload
+    def __init__(self, bar: None, baz: None) -> NoReturn: ...
+
+    @overload
+    def __init__(self, bar: str | None, baz: int | None) -> None: ...
+
+    def __init__(self, bar: str | None, baz: int | None) -> None:
+        if bar is None and baz is None:
+            raise ValueError