vulture

Install the Vulture static code analyzer using pip to find unused code in your Python projects.

$ pip install vulture

You can store Vulture configuration in your pyproject.toml file under the [tool.vulture] section. Command line arguments are converted by removing leading dashes and replacing remaining dashes with underscores. Options in pyproject.toml are overridden by command line arguments.

[tool.vulture]
exclude = ["*file*.py", "dir/"]
ignore_decorators = ["@app.route", "@require_*"]
ignore_names = ["visit_*", "do_*"]
make_whitelist = true
min_confidence = 80
paths = ["myscript.py", "mydir", "whitelist.py"]
sort_by_size = true
verbose = true

If Vulture reports false positives, you can generate strings to add to a whitelist file using the make_whitelist flag in report() or by calling get_whitelist_string() on an Item object.

Example output for a whitelist:

_ .my_method  # unused method (path/to/file.py:10)
my_var  # unused variable (path/to/file.py:20)
# unreachable code (path/to/file.py:30)

Vulture can be configured using a [tool.vulture] section in your pyproject.toml file. This allows you to persist settings like ignored patterns, decorators, and confidence thresholds.

Note that CLI arguments take precedence over settings defined in the TOML file.

[tool.vulture]
exclude = ["file*.py", "dir/"]
ignore_decorators = ["deco1", "deco2"]
ignore_names = ["name1", "name2"]
make_whitelist = true
min_confidence = 10
sort_by_size = true
verbose = true
paths = ["path1", "path2"]

Run Vulture on specific Python files or directories to detect unused functions, classes, imports, and unreachable code. Vulture analyzes all *.py files within a provided directory.

$ vulture myscript.py
$ vulture myscript.py mypackage/
$ vulture myscript.py --min-confidence 100

The Reachability class provides an interface for performing reachability analysis on Python Abstract Syntax Trees (AST). It identifies unreachable code blocks caused by control flow statements like break, continue, return, or raise, as well as unsatisfiable conditional logic (e.g., if statements that can never be true).

To use it, initialize the class with a report callback function. This callback is triggered whenever the analyzer detects unreachable code or unsatisfiable conditions.

The make_config function merges configuration from a TOML file and CLI arguments. It is the primary way to programmatically obtain a complete configuration object.

• argv: A list of strings representing CLI arguments (e.g., sys.argv[1:]).
• tomlfile: An IO instance containing TOML data (used primarily for testing or custom file loading).

Returns a dictionary containing the merged configuration. If no paths are provided in either the CLI or the config, it raises an InputError.

The ignore_line(noqa_lines, lineno, error_code) function determines if a specific error reported at a given line number should be suppressed.

A line is ignored if:

1. The specific error_code is explicitly listed in the # noqa comment for that line.
2. The line contains a generic # noqa comment (which maps to the all category).

The Vulture class is the primary engine for finding unused code in Python projects. You can use it to scan paths, exclude specific patterns, and retrieve or report unused items.

Key methods:

• scavenge(paths, exclude=None): Scans the provided paths for dead code, optionally excluding paths that match the provided patterns.
• get_unused_code(min_confidence=0, sort_by_size=False): Returns an ordered list of Item objects representing unused code.
• report(min_confidence=0, sort_by_size=False, make_whitelist=False): Prints the unused code report to stdout and returns an exit code.

The get_modules function resolves a list of paths into a list of Python files to be checked.

• If a path is a file: It is added to the list (unless it is a .pyc file, which causes an error).
• If a path is a directory: All .py files found recursively within that directory are added.
• If a path does not exist: The program exits with an error.

Note: .pyc files are explicitly not supported.