Merge branch 'main' into ignore-self-calls.

CHANGELOG.md

@@ -1,6 +1,7 @@
 # next (unreleased)
 
 * Add an option to mark most functions only called recursively as unused (John Doknjas, #374).
+* Add type hints for `get_unused_code` and the fields of the `Item` class (John Doknjas, #361).
 
 # 2.13 (2024-10-02)
 

README.md

@@ -218,7 +218,16 @@ Then run `pre-commit install`. Finally, create a `pyproject.toml` file
 in your repository and specify all files that Vulture should check under
 `[tool.vulture] --> paths` (see above).
 
-There's also a [GitHub Action for Vulture](https://github.com/gtkacz/vulture-action).
+There's also a [GitHub Action for Vulture](https://github.com/gtkacz/vulture-action)
+and you can use Vulture programatically. For example:
+
+``` python
+import vulture
+
+v = vulture.Vulture()
+v.scavenge(['.'])
+unused_code = v.get_unused_code()  # returns a list of `Item` objects
+```
 
 ## How does it work?
 

tests/test_pytype.py

@@ -0,0 +1,11 @@
+import subprocess
+import sys
+
+import pytest
+
+
+@pytest.mark.skipif(
+    sys.version_info >= (3, 13), reason="needs Python < 3.13 for pytype"
+)
+def test_pytype():
+    assert subprocess.run(["pytype", "vulture/core.py"]).returncode == 0

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = cleanup, py{38,310,311,312,313}, style  # Skip py39 since it chokes on distutils.
+envlist = cleanup, py{38,310,311,312,313}  # Skip py39 since it chokes on distutils.
 skip_missing_interpreters = true
 
 # Erase old coverage results, then accumulate them during this tox run.
@@ -15,6 +15,7 @@ deps =
   pint  # Use latest version to catch API changes.
   pytest
   pytest-cov
+  pytype ; python_version < '3.13'
 commands =
   pytest {posargs}
 # Install package as wheel in all envs (https://hynek.me/articles/turbo-charge-tox/).

vulture/core.py

@@ -5,6 +5,7 @@
 import re
 import string
 import sys
+from typing import List
 
 from vulture import lines
 from vulture import noqa
@@ -139,13 +140,13 @@ def __init__(
         message="",
         confidence=DEFAULT_CONFIDENCE,
     ):
-        self.name = name
-        self.typ = typ
-        self.filename = filename
-        self.first_lineno = first_lineno
-        self.last_lineno = last_lineno
-        self.message = message or f"unused {typ} '{name}'"
-        self.confidence = confidence
+        self.name: str = name
+        self.typ: str = typ
+        self.filename: Path = filename
+        self.first_lineno: int = first_lineno
+        self.last_lineno: int = last_lineno
+        self.message: str = message or f"unused {typ} '{name}'"
+        self.confidence: int = confidence
 
     @property
     def size(self):
@@ -224,6 +225,7 @@ def get_list(typ):
         self.filename = Path()
         self.code = []
         self.exit_code = ExitCode.NoDeadCode
+        self.noqa_lines = {}
 
     def scan(self, code, filename=""):
         filename = Path(filename)
@@ -307,10 +309,13 @@ def exclude_path(path):
                 except OSError:
                     # Most imported modules don't have a whitelist.
                     continue
+                assert module_data is not None
                 module_string = module_data.decode("utf-8")
                 self.scan(module_string, filename=path)
 
-    def get_unused_code(self, min_confidence=0, sort_by_size=False):
+    def get_unused_code(
+        self, min_confidence=0, sort_by_size=False
+    ) -> List[Item]:
         """
         Return ordered list of unused Item objects.
         """