Skip to content

vulture.md

Latest commit

 

History

History
183 lines (121 loc) · 4.57 KB

vulture.md

File metadata and controls

183 lines (121 loc) · 4.57 KB
Raw

Vulture - Dead Code Detector

Vulture is a tool that finds unused code in Python programs. It helps you identify and remove dead code, which can improve maintainability, reduce complexity, and decrease the size of your codebase.

Overview

Vulture works by analyzing your Python code and identifying:

  • Unused classes and functions
  • Unused variables and imports
  • Unreachable code
  • Unused attributes and properties

By detecting and removing dead code, you can:

  • Improve code maintainability
  • Reduce cognitive load when reading code
  • Decrease the size of your codebase
  • Prevent bugs caused by outdated, unused code

Installation

Vulture is included as a development dependency:

# Install with other development dependencies
uv sync --dev

To install it directly:

uv pip install vulture

How It's Used in This Project

In this project, Vulture is used to:

  1. Identify unused code in the codebase
  2. Maintain code quality by removing dead code
  3. Run as part of the pre-commit hooks and CI/CD pipeline

Configuration in This Project

Vulture is configured in the pyproject.toml file:

[tool.vulture]
exclude = ["tests", ".venv", ".git"]
ignore_names = ["setUp", "tearDown", "test_*"]
min_confidence = 80

This configuration:

  • Excludes test directories and virtual environments from scanning
  • Ignores common test method names
  • Sets a minimum confidence threshold of 80%

Vulture is also configured as a poethepoet task:

[tool.poe.tasks]
vulture = "vulture src --min-confidence 80"

Basic Usage

Running Vulture

To run Vulture on the project:

# Run via poethepoet
uv run poe vulture

# Run directly
uv run vulture src --min-confidence 80

Common Command-Line Options

# Scan a specific file
uv run vulture path/to/file.py

# Scan a directory
uv run vulture path/to/directory

# Set minimum confidence threshold
uv run vulture src --min-confidence 90

# Exclude specific paths
uv run vulture src --exclude tests/,examples/

# Make paths absolute
uv run vulture src --make-whitelist

Understanding Vulture Results

Vulture reports unused code with a confidence percentage. The higher the percentage, the more confident Vulture is that the code is unused.

Example output:

path/to/file.py:10: unused function 'unused_function' (90% confidence)
path/to/file.py:20: unused variable 'unused_var' (60% confidence)
path/to/file.py:30: unused import 'unused_import' (90% confidence)

Handling False Positives

Vulture may report false positives for code that is actually used. There are several ways to handle this:

1. Using Whitelists

Create a whitelist file (e.g., vulture_whitelist.py) with dummy definitions for code that should be ignored:

# vulture_whitelist.py
from path.to.module import actually_used_function

# This is a false positive, it's actually used via introspection
actually_used_function = None

Then run Vulture with the whitelist:

uv run vulture src vulture_whitelist.py

2. Using Inline Comments

Add # noqa comments to lines that should be ignored:

unused_looking_but_actually_used = SomeClass()  # noqa

3. Adjusting Confidence Threshold

Lower the confidence threshold to reduce false positives:

uv run vulture src --min-confidence 70

Best Practices

  1. Run Vulture regularly: Include Vulture in your pre-commit hooks and CI/CD pipeline.
  2. Start with a high confidence threshold: Begin with a high threshold (e.g., 90%) and gradually lower it as you clean up obvious dead code.
  3. Maintain a whitelist: Keep a whitelist of false positives to avoid repeatedly flagging the same code.
  4. Verify before removing: Always verify that code is truly unused before removing it, especially for public APIs.
  5. Consider dynamic usage: Remember that code might be used dynamically (e.g., through introspection or imports in rarely-run code paths).

Troubleshooting

Common Issues

Too Many False Positives

If you're getting too many false positives:

  1. Increase the minimum confidence threshold
  2. Add more entries to your whitelist
  3. Use more specific exclude patterns

Missing Dead Code

If Vulture is missing dead code:

  1. Ensure you're scanning all relevant directories
  2. Lower the confidence threshold
  3. Check if the code is being imported or used dynamically

Resources