Fix comment handling in type hints (#259)

Author: jsh9

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Change Log
 
+## [0.7.2] - 2025-09-02
+
+- Fixed
+  - A bug where false positive arg names are reported in the violation message
+- Added
+  - Support for checking class attribute default values (numpy and Google
+    styles only)
+- Full diff
+  - https://github.com/jsh9/pydoclint/compare/0.7.1...0.7.2
+
 ## [0.7.1] - 2025-09-02
 
 - Added

pydoclint/utils/arg.py

@@ -6,7 +6,11 @@
 from docstring_parser.common import DocstringAttr, DocstringParam
 
 from pydoclint.utils.edge_case_error import EdgeCaseError
-from pydoclint.utils.generic import specialEqual, stripQuotes
+from pydoclint.utils.generic import (
+    specialEqual,
+    stripCommentsFromTypeHints,
+    stripQuotes,
+)
 from pydoclint.utils.unparser_custom import unparseName
 
 
@@ -113,6 +117,24 @@ def fromAstArgWithMapping(
         # This means there is no default value, not even a "None"
         return Arg(name=astArg.arg, typeHint=typeHint)
 
+    @classmethod
+    def fromArgWithMapping(
+            cls,
+            arg: 'Arg',
+            argToDefaultMapping: dict[str, ast.expr],
+    ) -> 'Arg':
+        """Construct an Arg object from another Arg with its default value"""
+        if arg.name in argToDefaultMapping:
+            # This means there IS a default value, even if it's None
+            defaultValue = argToDefaultMapping[arg.name]
+            return Arg(
+                name=arg.name,
+                typeHint=f'{arg.typeHint}, default={unparseName(defaultValue)}',
+            )
+
+        # This means there is no default value, not even a "None"
+        return arg
+
     @classmethod
     def fromAstAnnAssign(cls, astAnnAssign: ast.AnnAssign) -> 'Arg':
         """Construct an Arg object from a Python ast.AnnAssign object"""
@@ -359,7 +381,14 @@ def findArgsWithDifferentTypeHints(self, other: 'ArgList') -> list[Arg]:
         for selfArg in self.infoList:
             selfArgTypeHint: str = selfArg.typeHint
             otherArgTypeHint: str = other.lookup[selfArg.name]
-            if not specialEqual(selfArgTypeHint, otherArgTypeHint):
+
+            # Here we use unparseName(ast.parse(...)) in order to get rid of
+            # the comments at the end of type hints,
+            # such as: `int, default=42  # noqa: E501`
+            if not specialEqual(
+                stripCommentsFromTypeHints(selfArgTypeHint),
+                stripCommentsFromTypeHints(otherArgTypeHint),
+            ):
                 result.append(selfArg)
 
         return result

pydoclint/utils/generic.py

@@ -7,6 +7,7 @@
 
 from pydoclint.utils.astTypes import ClassOrFunctionDef, FuncOrAsyncFuncDef
 from pydoclint.utils.method_type import MethodType
+from pydoclint.utils.unparser_custom import unparseName
 from pydoclint.utils.violation import Violation
 
 if TYPE_CHECKING:
@@ -272,7 +273,7 @@ def doList1ItemsStartWithList2Items(
     return True
 
 
-def buildArgToDefaultMapping(
+def buildFuncArgToDefaultMapping(
         funcDef: FuncOrAsyncFuncDef,
 ) -> dict[ast.arg, ast.expr]:
     """
@@ -315,3 +316,54 @@ def buildArgToDefaultMapping(
             argToDefaultMapping[kwOnlyArgs[i]] = kwDefaults[i]  # type: ignore[assignment]  # noqa: LN002
 
     return argToDefaultMapping
+
+
+def buildClassAttrToDefaultMapping(
+        classDef: ast.ClassDef,
+) -> dict[str, ast.expr]:
+    """
+    Build a mapping from class attribute names to their default values using
+    proper AST structure.
+
+    Parameters
+    ----------
+    classDef : ast.ClassDef
+        Class definition node
+
+    Returns
+    -------
+    dict[str, ast.expr]
+        Dictionary mapping attribute names to their default values
+    """
+    attrToDefaultMapping: dict[str, ast.expr] = {}
+
+    # Iterate through the class body to find attribute assignments
+    for node in classDef.body:
+        if isinstance(node, ast.AnnAssign) and isinstance(
+            node.target, ast.Name
+        ):
+            # This is a typed attribute assignment like: attr: int = 42
+            if node.value is not None:
+                attrToDefaultMapping[node.target.id] = node.value
+        elif isinstance(node, ast.Assign):
+            # This is a regular assignment like: attr = 42
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    attrToDefaultMapping[target.id] = node.value
+
+    return attrToDefaultMapping
+
+
+def stripCommentsFromTypeHints(typeHint: str) -> str:
+    """
+    Strip comments from type hints to enable comparison between
+    docstring type hints and actual type hints.
+    """
+    result: str
+    try:
+        parsed = unparseName(ast.parse(typeHint))
+        result = parsed if parsed is not None else typeHint
+    except SyntaxError:
+        result = typeHint
+
+    return result

pydoclint/utils/visitor_helper.py

@@ -10,6 +10,7 @@
 from pydoclint.utils.edge_case_error import EdgeCaseError
 from pydoclint.utils.generic import (
     appendArgsToCheckToV105,
+    buildClassAttrToDefaultMapping,
     getDocstring,
     specialEqual,
     stripQuotes,
@@ -42,6 +43,7 @@ def checkClassAttributesAgainstClassDocstring(
         shouldDocumentPrivateClassAttributes: bool,
         treatPropertyMethodsAsClassAttributes: bool,
         onlyAttrsWithClassVarAreTreatedAsClassAttrs: bool,
+        checkArgDefaults: bool,
 ) -> None:
     """Check class attribute list against the attribute list in docstring"""
     actualArgs: ArgList = extractClassAttributesFromNode(
@@ -53,6 +55,7 @@ def checkClassAttributesAgainstClassDocstring(
         onlyAttrsWithClassVarAreTreatedAsClassAttrs=(
             onlyAttrsWithClassVarAreTreatedAsClassAttrs
         ),
+        checkArgDefaults=checkArgDefaults,
     )
 
     classDocstring: str = getDocstring(node)
@@ -126,12 +129,13 @@ def checkClassAttributesAgainstClassDocstring(
     )
 
 
-def extractClassAttributesFromNode(
+def extractClassAttributesFromNode(  # noqa: C901
         *,
         node: ast.ClassDef,
         shouldDocumentPrivateClassAttributes: bool,
         treatPropertyMethodsAsClassAttrs: bool,
         onlyAttrsWithClassVarAreTreatedAsClassAttrs: bool,
+        checkArgDefaults: bool,
 ) -> ArgList:
     """
     Extract class attributes from an AST node.
@@ -151,6 +155,9 @@ def extractClassAttributesFromNode(
         within ``ClassVar`` (where ``ClassVar`` is imported from ``typing``)
         are treated as class attributes, and all other attributes are
         treated as instance attributes.
+    checkArgDefaults : bool
+        If True, we should extract the arguments' default values and attach
+        them to the type hints.
 
     Returns
     -------
@@ -201,7 +208,21 @@ def extractClassAttributesFromNode(
             )
         ]
 
-    return ArgList(infoList=atl)
+    astArgList = ArgList(infoList=atl)
+
+    if not checkArgDefaults:  # no need to add defaults to type hints
+        return astArgList
+
+    argToDefaultMapping: dict[str, ast.expr] = buildClassAttrToDefaultMapping(
+        node,
+    )
+
+    return ArgList(
+        [
+            Arg.fromArgWithMapping(_, argToDefaultMapping)
+            for _ in astArgList.infoList
+        ]
+    )
 
 
 def checkDocArgsLengthAgainstActualArgs(

pydoclint/visitor.py

@@ -9,7 +9,7 @@
 from pydoclint.utils.doc import Doc
 from pydoclint.utils.edge_case_error import EdgeCaseError
 from pydoclint.utils.generic import (
-    buildArgToDefaultMapping,
+    buildFuncArgToDefaultMapping,
     collectFuncArgs,
     detectMethodType,
     doList1ItemsStartWithList2Items,
@@ -153,6 +153,7 @@ def visit_ClassDef(self, node: ast.ClassDef) -> None:  # noqa: D102
                 onlyAttrsWithClassVarAreTreatedAsClassAttrs=(
                     self.onlyAttrsWithClassVarAreTreatedAsClassAttrs
                 ),
+                checkArgDefaults=self.checkArgDefaults,
             )
 
         self.generic_visit(node)
@@ -452,7 +453,7 @@ def checkArguments(  # noqa: C901
 
         if self.checkArgDefaults:
             argToDefaultMapping: dict[ast.arg, ast.expr] = (
-                buildArgToDefaultMapping(node)
+                buildFuncArgToDefaultMapping(node)
             )
 
         isMethod: bool = isinstance(parent_, ast.ClassDef)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pydoclint"
-version = "0.7.1"
+version = "0.7.2"
 description = "A Python docstring linter that checks arguments, returns, yields, and raises sections"
 readme = "README.md"
 license = {text = "MIT"}

tests/data/edge_cases/30_comments_in_type_hints/numpy.py

@@ -0,0 +1,55 @@
+"""Test case for noqa comments in class attribute type hints in numpy style docstrings."""
+
+
+def regular_function(
+        param1: str,
+        param2: int = 42,
+        param3: float = 3.14,
+        param4: str = "foo",
+) -> bool:
+    """A regular function with parameters.
+
+    Parameters
+    ----------
+    param1 : str  # noqa: E501
+        First parameter with noqa comment.
+    param2 : int, default=42#noqa:F401
+        Second parameter with no-space noqa comment.
+    param3 : float, default=3.14
+        Third parameter with no-space noqa comment.
+    param4 : str, default='foobar'  # noqa: E501
+        Fourth parameter with no-space noqa comment.
+
+    Returns
+    -------
+    bool
+        The result.
+    """
+    return True
+
+
+class TestClass:
+    """Class with attributes that have noqa comments in type hints.
+
+    Attributes
+    ----------
+    attr1 : str # noqa: E501
+        Regular noqa comment in type hint.
+    attr2 : int, default=42#noqa:E501
+        No-space noqa comment in type hint.
+    attr3 : float, default=3.14  #  NOQA  :  E501
+        Spaced and uppercase noqa comment.
+    attr4 : bool, default=True # noqa: E501,W503
+        Multiple rule codes in noqa.
+    attr5 : list, default=[] # this is not noqa
+        Regular comment that should remain.
+    attr6 : dict, default={} # noqa: F401
+        Complex type with noqa comment.
+    """
+
+    attr1: str
+    attr2: int = 42
+    attr3: float = 3.14
+    attr4: bool = True
+    attr5: list = []
+    attr6: dict = {}

tests/test_edge_cases.py

@@ -575,6 +575,19 @@
                 'section types: Generator123[typing.Any]'
             ],
         ),
+        (
+            '30_comments_in_type_hints/numpy.py',
+            {
+                'style': 'numpy',
+                'checkClassAttributes': True,
+                'checkArgDefaults': True,
+            },
+            [
+                'DOC105: Function `regular_function`: Argument names match, but type hints in '
+                'these args do not match: param4 . (Note: docstring arg defaults should look '
+                'like: `, default=XXX`)'
+            ],
+        ),
     ],
 )
 def testEdgeCases(