feat(5159): Add new checker invalid-field-call (#8126)

Co-authored-by: Daniël van Noord <[email protected]>
Co-authored-by: Jacob Walls <[email protected]>
Co-authored-by: Pierre Sassoulas <[email protected]>

Author: 4 people

.pyenchant_pylint_custom_dict.txt

@@ -21,6 +21,7 @@ async
 asynccontextmanager
 attr
 attrib
+attrname
 backport
 BaseChecker
 basename
@@ -72,6 +73,7 @@ CVE
 cwd
 cyclomatic
 dataclass
+dataclasses
 datetime
 debian
 deduplication

doc/data/messages/i/invalid-field-call/bad.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class C:
+    a: float
+    b: float
+    c: float
+
+    field(init=False)  # [invalid-field-call]
+
+    def __post_init__(self):
+        self.c = self.a + self.b
+
+
+print(field(init=False))  # [invalid-field-call]

doc/data/messages/i/invalid-field-call/good.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass, field, make_dataclass
+
+C = make_dataclass(
+    "C",
+    [("x", int), "y", ("z", int, field(default=5))],
+    namespace={"add_one": lambda self: self.x + 1},
+)
+
+
+@dataclass
+class C:
+    a: float
+    b: float
+    c: float = field(init=False)
+
+    def __post_init__(self):
+        self.c = self.a + self.b

doc/user_guide/checkers/features.rst

@@ -389,6 +389,19 @@ Classes checker Messages
   an unexpected reason. Please report this kind if you don't make sense of it.
 
 
+Dataclass checker
+~~~~~~~~~~~~~~~~~
+
+Verbatim name of the checker is ``dataclass``.
+
+Dataclass checker Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+:invalid-field-call (E3701): *Invalid usage of field(), %s*
+  The dataclasses.field() specifier should only be used as the value of an
+  assignment within a dataclass, or within the make_dataclass() function. This
+  message can't be emitted when using Python < 3.7.
+
+
 Design checker
 ~~~~~~~~~~~~~~
 

doc/user_guide/messages/messages_overview.rst

@@ -91,6 +91,7 @@ All messages in the error category:
    error/invalid-class-object
    error/invalid-enum-extension
    error/invalid-envvar-value
+   error/invalid-field-call
    error/invalid-format-returned
    error/invalid-getnewargs-ex-returned
    error/invalid-getnewargs-returned

doc/whatsnew/fragments/5159.new_check

@@ -0,0 +1,3 @@
+Added ``DataclassChecker`` module and ``invalid-field-call`` checker to check for invalid dataclasses.field() usage.
+
+Refs #5159

pylint/checkers/dataclass_checker.py

@@ -0,0 +1,129 @@
+# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+# For details: https://github.com/pylint-dev/pylint/blob/main/LICENSE
+# Copyright (c) https://github.com/pylint-dev/pylint/blob/main/CONTRIBUTORS.txt
+
+"""Dataclass checkers for Python code."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from astroid import nodes
+from astroid.brain.brain_dataclasses import DATACLASS_MODULES
+
+from pylint.checkers import BaseChecker, utils
+from pylint.interfaces import INFERENCE
+
+if TYPE_CHECKING:
+    from pylint.lint import PyLinter
+
+
+def _is_dataclasses_module(node: nodes.Module) -> bool:
+    """Utility function to check if node is from dataclasses_module."""
+    return node.name in DATACLASS_MODULES
+
+
+def _check_name_or_attrname_eq_to(
+    node: nodes.Name | nodes.Attribute, check_with: str
+) -> bool:
+    """Utility function to check either a Name/Attribute node's name/attrname with a
+    given string.
+    """
+    if isinstance(node, nodes.Name):
+        return str(node.name) == check_with
+    return str(node.attrname) == check_with
+
+
+class DataclassChecker(BaseChecker):
+    """Checker that detects invalid or problematic usage in dataclasses.
+
+    Checks for
+    * invalid-field-call
+    """
+
+    name = "dataclass"
+    msgs = {
+        "E3701": (
+            "Invalid usage of field(), %s",
+            "invalid-field-call",
+            "The dataclasses.field() specifier should only be used as the value of "
+            "an assignment within a dataclass, or within the make_dataclass() function.",
+        ),
+    }
+
+    @utils.only_required_for_messages("invalid-field-call")
+    def visit_call(self, node: nodes.Call) -> None:
+        self._check_invalid_field_call(node)
+
+    def _check_invalid_field_call(self, node: nodes.Call) -> None:
+        """Checks for correct usage of the dataclasses.field() specifier in
+        dataclasses or within the make_dataclass() function.
+
+        Emits message
+        when field() is detected to be used outside a class decorated with
+        @dataclass decorator and outside make_dataclass() function, or when it
+        is used improperly within a dataclass.
+        """
+        if not isinstance(node.func, (nodes.Name, nodes.Attribute)):
+            return
+        if not _check_name_or_attrname_eq_to(node.func, "field"):
+            return
+        inferred_func = utils.safe_infer(node.func)
+        if not (
+            isinstance(inferred_func, nodes.FunctionDef)
+            and _is_dataclasses_module(inferred_func.root())
+        ):
+            return
+        scope_node = node.parent
+        while scope_node and not isinstance(scope_node, (nodes.ClassDef, nodes.Call)):
+            scope_node = scope_node.parent
+
+        if isinstance(scope_node, nodes.Call):
+            self._check_invalid_field_call_within_call(node, scope_node)
+            return
+
+        if not scope_node or not scope_node.is_dataclass:
+            self.add_message(
+                "invalid-field-call",
+                node=node,
+                args=(
+                    "it should be used within a dataclass or the make_dataclass() function.",
+                ),
+                confidence=INFERENCE,
+            )
+            return
+
+        if not (isinstance(node.parent, nodes.AnnAssign) and node == node.parent.value):
+            self.add_message(
+                "invalid-field-call",
+                node=node,
+                args=("it should be the value of an assignment within a dataclass.",),
+                confidence=INFERENCE,
+            )
+
+    def _check_invalid_field_call_within_call(
+        self, node: nodes.Call, scope_node: nodes.Call
+    ) -> None:
+        """Checks for special case where calling field is valid as an argument of the
+        make_dataclass() function.
+        """
+        inferred_func = utils.safe_infer(scope_node.func)
+        if (
+            isinstance(scope_node.func, (nodes.Name, nodes.AssignName))
+            and scope_node.func.name == "make_dataclass"
+            and isinstance(inferred_func, nodes.FunctionDef)
+            and _is_dataclasses_module(inferred_func.root())
+        ):
+            return
+        self.add_message(
+            "invalid-field-call",
+            node=node,
+            args=(
+                "it should be used within a dataclass or the make_dataclass() function.",
+            ),
+            confidence=INFERENCE,
+        )
+
+
+def register(linter: PyLinter) -> None:
+    linter.register_checker(DataclassChecker(linter))

tests/functional/d/dataclass/dataclass_with_default_factory.py

@@ -1,3 +1,4 @@
+# pylint: disable=invalid-field-call
 """Various regression tests for dataclasses."""
 # See issues:
 # - https://github.com/pylint-dev/pylint/issues/2605
@@ -48,3 +49,9 @@ class Test2:
 class TEST3:
     """Test dataclass that puts call to field() in another function call"""
     attribute: int = cast(int, field(default_factory=dict))
+
+
+@dc.dataclass
+class TEST4:
+    """Absurd example to test a potential crash found during development."""
+    attribute: int = lambda this: cast(int, this)(field(default_factory=dict))

tests/functional/d/dataclass/dataclass_with_default_factory.txt

@@ -1,2 +1,2 @@
-not-an-iterable:40:9:40:23::Non-iterable value Test2.int_prop is used in an iterating context:UNDEFINED
-unsupported-assignment-operation:44:0:44:14::'Test2.int_prop' does not support item assignment:UNDEFINED
+not-an-iterable:41:9:41:23::Non-iterable value Test2.int_prop is used in an iterating context:UNDEFINED
+unsupported-assignment-operation:45:0:45:14::'Test2.int_prop' does not support item assignment:UNDEFINED

tests/functional/i/invalid/invalid_field_call.py

@@ -0,0 +1,61 @@
+"""Tests for the invalid-field-call message."""
+
+# pylint: disable=invalid-name, missing-class-docstring, missing-function-docstring, too-few-public-methods
+
+from dataclasses import dataclass, field, make_dataclass
+import dataclasses as dc
+
+class MyClass:
+    def field(self):
+        return "Not an actual dataclasses.field function"
+
+mc = MyClass()
+
+C = make_dataclass('C',
+                   [('x', int),
+                     'y',
+                    ('z', int, field(default=5))],
+                   namespace={'add_one': lambda self: self.x + 1})
+
+bad = print(field(init=False))  # [invalid-field-call]
+
+a: float = field()  # [invalid-field-call]
+
+class NotADataClass:
+    field()  # [invalid-field-call]
+    a: float = field(init=False)  # [invalid-field-call]
+    dc.field()  # [invalid-field-call]
+    b: float = dc.field(init=False)  # [invalid-field-call]
+
+@dataclass
+class DC:
+    field()  # [invalid-field-call]
+    dc.field()  # [invalid-field-call]
+    mc.field()
+    a: float = field(init=False)
+    b: float = dc.field(init=False)
+    # TODO(remove py3.9 min) pylint: disable-next=unsubscriptable-object
+    c: list[float] = [field(), field()]  # [invalid-field-call, invalid-field-call]
+
+@dc.dataclass
+class IsAlsoDC:
+    field()  # [invalid-field-call]
+    a: float = field(init=False)
+    b: float = dc.field(init=False)
+    # TODO(remove py3.9 min) pylint: disable-next=unsubscriptable-object
+    c: list[float] = [field(), field()]  # [invalid-field-call, invalid-field-call]
+
+@dc.dataclass(frozen=True)
+class FrozenDC:
+    a: float = field(init=False)
+    b: float = dc.field(init=False)
+
+def my_decorator(func):
+    def wrapper():
+        func()
+
+    return wrapper
+
+@my_decorator
+class AlsoNotADataClass:
+    a: float = field(init=False)  # [invalid-field-call]