jendrikseipp/vulture
GitHub: jendrikseipp/vulture
Vulture 是一款基于 AST 的 Python 静态分析工具，用于快速发现项目中未使用的函数、类、变量和不可达代码，帮助开发者精简代码库并提升代码质量。
Stars: 4586 | Forks: 186
# Vulture - 查找死代码
[](https://pypi.python.org/pypi/vulture)
[](https://anaconda.org/conda-forge/vulture)
[](https://codecov.io/gh/jendrikseipp/vulture?branch=main)
Vulture 查找 Python 程序中未使用的代码。这对于清理和发现大型代码库中的错误非常有用。如果你同时在一个库及其测试套件上运行 Vulture，你可以找到未被测试覆盖的代码。
由于 Python 的动态特性，像 Vulture 这样的静态代码分析器可能会遗漏一些死代码。此外，仅被隐式调用的代码也可能会被报告为未使用。尽管如此，Vulture 仍然可以作为一个非常有用的工具，帮助提升代码质量。
## 功能
* 快速：使用静态代码分析
* 经过测试：自身测试并具有完整的测试覆盖率
* 补充 pyflakes 且具有相同的输出语法
* 使用 `--sort-by-size` 按大小对未使用的类和函数进行排序
## 安装
```
$ pip install vulture
```
## 用法
```
$ vulture myscript.py # or
$ python3 -m vulture myscript.py
$ vulture myscript.py mypackage/
$ vulture myscript.py --min-confidence 100 # Only report 100% dead code.
```
提供的参数可以是 Python 文件或目录。对于每个目录，Vulture 会分析其中包含的所有
\*.py 文件。
在你找到并删除死代码之后，再次运行 Vulture，因为它可能会发现更多的死代码。
## 未使用代码的类型
除了查找未使用的函数、类等之外，Vulture 还可以检测不可达代码。每块死代码都会被赋予一个介于 60% 到 100% 之间的*置信度值*，其中 100% 的值表示可以确定该代码不会被执行。低于 100% 的值是（基于代码块的类型）对该代码未被使用的可能性的*非常粗略*的估计。
| 代码类型 | 置信度值 |
|--------------------------------------------------------|------------------|
| 函数/方法/类参数，不可达代码 | 100% |
| 导入 | 90% |
| 属性，类，函数，方法，属性，变量 | 60% |
你可以使用 `--min-confidence` 标志来设置报告未使用代码的最低置信度。使用 `--min-confidence 100` 可以仅报告保证在分析的文件中未被使用的代码。
## 处理误报
当 Vulture 错误地将代码块报告为未使用时，你有几种选项来抑制这些误报。如果修复你的误报也能使其他用户受益，请提交问题报告。
#### 白名单
推荐的选项是将报告为未使用的已使用代码添加到一个 Python 模块中，并将其添加到扫描路径列表中。要自动获取此类白名单，请向 Vulture 传递 `--make-whitelist`：
```
$ vulture mydir --make-whitelist > whitelist.py
$ vulture mydir whitelist.py
```
请注意，生成的 `whitelist.py` 文件将包含有效的 Python 语法，但是要让 Python 能够*运行*它，通常需要进行一些修改。
我们在 `vulture/whitelists/` 中收集了常见 Python 模块和包的白名单（欢迎提交拉取请求）。
#### 忽略文件
如果你想忽略整个文件或目录，请使用 `--exclude` 参数（例如，`--exclude "*settings.py,*/docs/*.py,*/test_*.py,*/.venv/*.py"`）。排除模式是针对绝对路径进行匹配的。
#### Flake8 noqa 注释
paths` 下指定 Vulture 应该检查的所有文件（见上文）。
还有一个 [Vulture 的 GitHub Action](https://github.com/gtkacz/vulture-action)，
一个 [VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=sebastienfi.dead-code-finder)，
你也可以通过编程方式使用 Vulture。例如：
```
import vulture
v = vulture.Vulture()
v.scavenge(['.'])
unused_code = v.get_unused_code() # returns a list of `Item` objects
```
## 它是如何工作的？
Vulture 使用 `ast` 模块为所有给定的文件构建抽象语法树。在遍历所有语法树时，它会记录已定义和已使用的对象的名称。之后，它会报告那些已定义但未使用的对象。此分析会忽略作用域，仅考虑对象名称。
Vulture 还通过查找 `return`、`break`、`continue` 和 `raise` 语句之后的代码，以及搜索无法满足的 `if` 和 `while` 条件来检测不可达代码。
## 按大小排序
使用 `--sort-by-size` 选项时，Vulture 会按行数对未使用的代码进行排序。这有助于开发人员确定首先去哪里查找死代码。
## 示例
考虑以下 Python 脚本（`dead_code.py`）：
```
import os
class Greeter:
def greet(self):
print("Hi")
def hello_world():
message = "Hello, world!"
greeter = Greeter()
func_name = "greet"
greet_func = getattr(greeter, func_name)
greet_func()
if __name__ == "__main__":
hello_world()
```
调用：
```
$ vulture dead_code.py
```
会得到以下输出：
```
dead_code.py:1: unused import 'os' (90% confidence)
dead_code.py:4: unused function 'greet' (60% confidence)
dead_code.py:8: unused variable 'message' (60% confidence)
```
Vulture 正确地将 `os` 和 `message` 报告为未使用，但未能检测到 `greet` 实际上已被使用。处理此类误报的推荐方法是创建一个白名单 Python 文件。
**准备白名单**
在白名单中，我们模拟变量、属性等的使用。对于上面的程序，白名单可能如下所示：
```
# whitelist_dead_code.py
from dead_code import Greeter
Greeter.greet
```
或者，你可以向 Vulture 传递 `--make-whitelist` 以获取自动生成的白名单。
将原始程序和白名单同时传递给 Vulture
```
$ vulture dead_code.py whitelist_dead_code.py
```
会让 Vulture 忽略 `greet` 方法：
```
dead_code.py:1: unused import 'os' (90% confidence)
dead_code.py:8: unused variable 'message' (60% confidence)
```