Fix false positives in typing.Protocol

.github/workflows/main.yml

@@ -30,7 +30,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install --upgrade build coveralls setuptools tox==4.0.2 wheel
+        python -m pip install --upgrade build coveralls setuptools tox==4.0.2 wheel ast-scope==0.3.1
 
     - name: Build Vulture wheel
       run: python -m build

CHANGELOG.md

@@ -1,5 +1,6 @@
 * Add `UnicodeEncodeError` exception handling to `core.py` (milanbalazs, #299).
 * Add whitelist for `Enum` attributes `_name_` and `_value_` (Eugene Toder, #305).
+* Add scoping info to handle false positives with `typing.Protocol` (pm3512, #309).
 
 # 2.7 (2023-01-08)
 

setup.py

@@ -47,7 +47,7 @@ def find_version(*parts):
         "Programming Language :: Python :: Implementation :: PyPy",
         "Topic :: Software Development :: Quality Assurance",
     ],
-    install_requires=["toml"],
+    install_requires=["toml", "ast_scope"],
     entry_points={"console_scripts": ["vulture = vulture.core:main"]},
     python_requires=">=3.6",
     packages=setuptools.find_packages(exclude=["tests"]),

tests/test_scavenging.py

@@ -899,3 +899,28 @@ class Color(Enum):
 
     check(v.unused_classes, [])
     check(v.unused_vars, ["BLUE"])
+
+
+def test_protocol(v):
+    v.scan(
+        """\
+from typing import Protocol, Mapping
+
+class LoggerProtocol(Protocol):
+    def log(
+        self,
+        level: int,
+        msg: str,
+        *args,
+        extra: Mapping[str, object] | None = None
+    ) -> None:
+        ...
+
+    def foo(self) -> None:
+        ...
+"""
+    )
+
+    check(v.unused_vars, [])
+    check(v.unused_funcs, [])
+    check(v.unused_classes, ["LoggerProtocol"])

vulture/core.py

@@ -11,6 +11,8 @@
 from vulture import utils
 from vulture.config import make_config
 
+import ast_scope
+
 
 DEFAULT_CONFIDENCE = 60
 
@@ -253,6 +255,11 @@ def handle_syntax_error(e):
             )
             self.found_dead_code_or_error = True
         else:
+            # ast_scope doesn't always parse, so need to handle errors.
+            try:
+                self.scope_info = ast_scope.annotate(node)
+            except Exception:
+                self.scope_info = None
             # When parsing type comments, visiting can throw SyntaxError.
             try:
                 self.visit(node)
@@ -505,6 +512,15 @@ def _define_variable(self, name, node, confidence=DEFAULT_CONFIDENCE):
     def visit_arg(self, node):
         """Function argument"""
         self._define_variable(node.arg, node, confidence=100)
+        if self.scope_info and node in self.scope_info:
+            scope = self.scope_info[node]
+            if isinstance(scope, ast_scope.scope.FunctionScope) and isinstance(
+                scope.parent, ast_scope.scope.ClassScope
+            ):
+                method_class = scope.parent.class_node
+                is_protocol = self._is_subclass(method_class, "Protocol")
+                if is_protocol:
+                    self.used_names.add(node.arg)
 
     def visit_AsyncFunctionDef(self, node):
         return self.visit_FunctionDef(node)
@@ -581,6 +597,20 @@ def _is_locals_call(node):
             and not node.keywords
         )
 
+    @staticmethod
+    def _is_subclass(node, class_name):
+        """Return True if the node is a subclass of the given class."""
+        assert isinstance(node, ast.ClassDef)
+        for superclass in node.bases:
+            if (
+                isinstance(superclass, ast.Name)
+                and superclass.id == class_name
+                or isinstance(superclass, ast.Attribute)
+                and superclass.attr == class_name
+            ):
+                return True
+        return False
+
     def visit_ClassDef(self, node):
         for decorator in node.decorator_list:
             if _match(
@@ -624,6 +654,12 @@ def visit_FunctionDef(self, node):
             self._define(
                 self.defined_methods, node.name, node, ignore=_ignore_method
             )
+            if self.scope_info and node in self.scope_info:
+                scope = self.scope_info[node]
+                if isinstance(scope, ast_scope.scope.ClassScope):
+                    method_class = scope.class_node
+                    if self._is_subclass(method_class, "Protocol"):
+                        self.used_names.add(node.name)
         else:
             self._define(
                 self.defined_funcs, node.name, node, ignore=_ignore_function