vulture-dead-code

Vulture 和 deadcode - 死代码检测

用于查找未使用的 Python 代码，包括函数、类、变量、导入项和属性。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用其他工具……
检测未使用的函数、类和变量	仅查找未使用的导入项（使用 ruff --select F401）
清理代码库中的死代码	检查类型正确性（使用 basedpyright）
在 CI 中强制执行代码规范	格式化代码（使用 ruff format）
为误报生成白名单	运行常规 lint 检查（使用 ruff check）

概述

Vulture（成熟，基于置信度）和 deadcode（较新，基于 AST）都能检测未使用的代码，但采用的方法不同：

特性	Vulture	deadcode
方法	静态分析 + 置信度分数	基于 AST 的检测
准确性	置信度分数（60-100%）	准确性高，误报较少
速度	快	非常快
配置	白名单文件	TOML 配置
成熟度	成熟（2012 年）	较新（2023 年及以后）
最适合	大型代码库、逐步清理	新项目、严格执行

安装

# Install vulture
uv add --dev vulture

# Install deadcode (newer alternative)
uv add --dev deadcode

# Install both for comparison
uv add --dev vulture deadcode

Vulture - 基于置信度的检测

基本用法

# Check entire project
vulture .

# Check specific files/directories
vulture src/ tests/

# Minimum confidence threshold (60-100%)
vulture --min-confidence 80 .

# Exclude patterns
vulture . --exclude "**/migrations/*,**/tests/*"

# Sort by confidence
vulture --sort-by-size .

# Generate whitelist of current issues
vulture . --make-whitelist > vulture_whitelist.py

配置（pyproject.toml）

[tool.vulture]
min_confidence = 80
paths = ["src", "tests"]
exclude = [
    "**/migrations/*",
    "**/__pycache__/*",
    ".venv/*"
]
ignore_decorators = [
    "@app.route",
    "@pytest.fixture",
    "@property",
    "@staticmethod",
    "@classmethod"
]
ignore_names = [
    "test_*",
    "setUp*",
    "tearDown*",
]

deadcode - 基于 AST 的检测

基本用法

# Check entire project
deadcode .

# Check specific files/directories
deadcode src/

# Verbose output
deadcode --verbose .

# Dry run (show what would be removed)
deadcode --dry-run .

# Show unreachable code
deadcode --show-unreachable .

# Generate configuration
deadcode --init

配置（pyproject.toml）

[tool.deadcode]
paths = ["src"]
exclude = [
    "tests/*",
    "**/__pycache__/*",
    "**/migrations/*",
]
ignore_names = [
    "test_*",
    "setUp",
    "tearDown",
    "main",
]
ignore_decorators = [
    "app.route",
    "pytest.fixture",
    "property",
    "staticmethod",
    "classmethod",
    "abstractmethod"
]
show_unreachable = false

如何选择工具

在以下情况下选择 Vulture……	在以下情况下选择 deadcode……
大型、成熟的代码库	新项目
需要基于置信度进行筛选	希望减少误报
需要采用白名单文件的方式	更倾向于使用 TOML 配置
动态代码（getattr、exec）	需要检测不可达代码

混合使用

# Run both for comprehensive detection
vulture --min-confidence 80 .
deadcode .

Agentic 优化

场景	命令
快速检查 vulture	vulture --min-confidence 90 .
快速检查 deadcode	deadcode .
生成白名单	vulture . --make-whitelist > vulture_whitelist.py
在 CI 中强制执行	vulture --min-confidence 80 . vulture_whitelist.py
不可达代码	deadcode --show-unreachable .
组合检查	vulture --min-confidence 80 . && deadcode .

快速参考

Vulture 标志

标志	说明
--min-confidence N	最低置信度（60-100%）
--exclude PATTERN	排除 glob 模式
--sort-by-size	按大小对结果排序
--make-whitelist	生成白名单文件

deadcode 标志

标志	说明
--verbose	详细输出
--dry-run	显示但不修改
--show-unreachable	检测不可达代码
--init	生成配置
--strict	严格执行模式

如需查看详细示例、高级模式和最佳实践，请参阅 REFERENCE.md。