一文掌握提升 Python 代码质量的最佳伴侣工具：black、isort、flake8 和 mypy

🍉 CSDN 叶庭云：https://yetingyun.blog.csdn.net/

在 Python 项目开发中，为了保持代码质量和提高开发效率，我们常需借助一些工具。今天，我将为大家介绍四个 Python 代码工程的得力助手：black、isort、flake8 和 mypy。

🚀🚀 本文的思维导图如下所示：

在这里插入图片描述

使用这四个工具的有机结合，能够编写出更为规范、整洁的 Python 代码。然而，代码的具体质量仍然取决于开发者自身，工具只是辅助手段。请牢记这一点。

一、black

什么是 Black？

Black 是一个开源的 Python 代码格式化工具，旨在提供一致的代码风格并提高代码的可读性和可维护性。它会自动将代码格式化为符合 PEP 8 规范的标准风格，因此被称为 “零妥协代码格式化工具”。

Black 24.4.2 官方文档：https://black.readthedocs.io/en/stable/getting_started.html

为什么使用 Black？

使用 Black 的主要原因如下：

一致性：通过自动格式化代码，Black 确保了整个项目中的代码风格一致，减少了代码审查过程中的争议和耗时。
简化代码审查：由于 Black 自动处理代码格式问题，开发者可以将更多精力放在代码逻辑和功能上，而非格式细节。
提高可读性：Black 强制执行标准化的格式，使代码更容易阅读和理解，尤其是在团队合作中。
节省时间：自动格式化代码可以显著减少开发者手动调整代码格式的时间，提高开发效率。

具体怎么做？

安装 Black

在命令行中使用 pip 安装 Black：

pip install black

如果需要在 Jupyter Notebook 中使用，则运行：

pip install black[jupyter]

需要注意的是，Black 需要 Python 3.8 以上的版本。

使用 Black

Black 使用非常简单，以下是一些基本用法：

格式化文件：在命令行中运行以下命令即可格式化文件：
```
black your_file.py
```
格式化目录：格式化目录中的所有 Python 文件：
```
black your_directory/
```
跳过字符串格式化：如果项目要求保留单引号，可以使用 -S 选项：
```
black -S your_file.py
```

高级用法和配置

Black 还支持一些高级配置选项，可以通过命令行参数实现：

指定行宽：使用 --line-length 选项来设置自定义代码最大行宽：
```
black --line-length 100 your_file.py
```
排除特定文件或目录：使用 --exclude 选项排除特定的文件或目录：
```
black --exclude "tests/" your_directory/
```
仅检查不修改：使用 --check 选项只检查格式而不修改文件：
```
black --check your_file.py
```

集成到 IDE 中

Black 可以集成到多种编辑器和 IDE 中，如 VS Code、PyCharm、Sublime Text 等。以 VS Code 为例，可以在扩展市场中搜索并安装 Black Formatter 扩展。

总结

Black 是一个强大的 Python 代码格式化工具，通过其自动化和一致性的特点，帮助开发者减少代码格式问题，提高代码审查效率和项目可维护性。无论是个人项目还是团队合作，Black 都能显著提升开发体验和代码质量。

二、isort

是什么？

isort 是一个 Python 实用工具库，用于自动排序和格式化 Python 文件中的导入语句。它能够将导入语句按照字母顺序排列，并自动分组成不同的部分，例如标准库、第三方库和项目内部模块（自己封装、实现的模块）。

isort 官方文档：https://pycqa.github.io/isort/

为什么？

导入语句规范化有助于提高代码的可读性和维护性，尤其在团队协作和大型项目中显得尤为重要。手动管理导入语句的顺序不仅耗时，而且容易出错。isort 自动化这一过程，确保所有导入语句都符合特定的格式和排序规则，从而减少代码审查过程中对导入顺序的讨论。

具体怎么做？

安装 isort

可以通过 pip 来安装 isort：

pip install isort

基本使用

对单个文件排序：
```
isort your_script.py
```
对整个项目中的所有 Python 文件排序：
```
isort .
```

进行配置

可以通过配置文件（如 pyproject.toml、.isort.cfg、setup.cfg 等）自定义 isort 的行为。例如，在 pyproject.toml 中：

[tool.isort]
profile = "black"
line_length = 88

上述配置指示 isort 使用与 black 代码格式化器兼容的配置，并将最大代码行长度设置为 88。

集成到编辑器或持续集成流程

编辑器插件：isort 提供了多种编辑器插件支持，包括 VSCode、PyCharm 等，方便在保存文件时自动排序导入语句。
预提交钩子（pre-commit hook）：isort 官方支持 pre-commit，确保在代码提交前自动检查和修复导入语句的顺序。

检查导入顺序是否正确

使用 -c 或 --check-only 选项可以仅检查导入顺序是否正确，而不实际修改文件：

isort -c your_script.py

如果导入顺序不正确，会输出相应的错误信息。通过使用 isort，可以显著提高代码的一致性和可读性，特别是在大型项目和团队协作中，自动化工具的使用能够大幅减少手动操作的错误和时间消耗。

综上所述，isort 是一个强大且高效的工具库，可以帮助 Python 开发人员自动化和标准化导入语句的管理，为代码审查和维护提供了极大的便利。

三、flake8

flake8 是什么？

flake8 是一个用于 Python 编程语言的静态代码分析工具，它结合了多个工具来检查代码质量和风格一致性。具体来说，flake8 集成了以下三种工具：

PyFlakes：用于检查代码中的错误。
pycodestyle：用于检查代码是否符合 PEP 8 编码规范。
Ned Batchelder 的 McCabe script：用于检查代码的复杂度。

flake8 官方文档：https://flake8.pycqa.org/en/latest/

为什么使用 flake8？

使用 flake8 有以下几个主要原因：

代码质量保障：自动检测代码中的错误，帮助开发者在早期发现潜在问题。
风格一致性：确保代码符合 PEP 8 标准，提升代码的可读性和一致性。
复杂度控制：分析代码的复杂度，提醒开发者避免过于复杂的代码结构。
可扩展性强：支持第三方插件，可以根据需要自定义检查规则。

具体怎么做？

安装 flake8

打开终端（或命令行界面）。
运行以下命令通过 pip 安装 flake8：
```
python -m pip install flake8
```
这条命令会自动安装 flake8 及其所有必要的依赖项。

使用 flake8

基本用法：
- 检查特定文件：
```
flake8 path/to/code/to/check.py
```
- 检查整个目录：
```
flake8 path/to/code/
```
  这将会递归检查目录下的所有文件。
选择特定的错误或警告：
- 仅查看特定警告或错误：
```
flake8 --select E123,W503 path/to/code/
```
- 忽略特定的警告或错误：
```
flake8 --ignore E24,W504 path/to/code/
```
  可以指定多个错误及警告，用逗号分隔。
配置 flake8：
- 可以通过配置文件来设置全局和项目级的 flake8 选项，例如在项目根目录下创建一个 .flake8 文件，并配置其中的选项：
```
[flake8]
max-line-length = 88
exclude = venv, tests
```
  这样可以避免在每次运行 flake8 时都重复输入相同的命令行参数。

通过以上步骤，您可以有效地使用 flake8 来帮助提升代码质量、保持风格一致性并控制复杂度。建议参考官方文档获取更多详细的用法和配置示例。

四、mypy

是什么？

mypy 是 Python 的一个静态类型检查工具。它通过在代码中添加类型注解，帮助开发者在编写代码时发现潜在的类型错误，从而提高代码质量和可读性。mypy 允许在 Python 这种动态类型语言中使用静态类型检查的优点。

mypy 官方文档：https://mypy.readthedocs.io/en/stable/

为什么？

使用 mypy 的主要原因有以下几点：

提高代码质量与可读性：通过在代码中加入类型注解，可以使代码更加易读，明确变量和函数的预期类型，从而减少理解和维护代码所需的时间。
捕获潜在错误：mypy 可以在代码运行前发现类型错误，避免运行时才发现的问题，从而减少调试时间。
文档化作用：类型注解可以作为代码的一部分，有助于自动生成文档和辅助开发者理解代码。

具体怎么做？

安装 mypy

首先，你需要安装 mypy，可以使用以下 pip 命令：

pip install mypy

添加类型注释

在代码中添加类型注释，可以使用 Python 提供的 typing 模块。例如：

from typing import List, Tuple

def add_numbers(x: int, y: int) -> int:
    return x + y

def process_data(data: List[Tuple[str, int]]) -> None:
    for name, age in data:
        print(f"Name: {name}, Age: {age}")

data_list = [("Alice", 25), ("Bob", 30), ("Charlie", 22)]
process_data(data_list)

运行 mypy

在添加了类型注释之后，可以使用 mypy 来进行类型检查。运行以下命令：

mypy your_code.py

如果代码中有类型错误，mypy 会显示错误信息。例如：

def add(x: int, y: int) -> int:
    return x + y

result = add(10, "20")  # 错误：第二个参数应该是 int 类型

运行 mypy 后，会提示类似这样的错误信息：

error: Argument 2 to "add" has incompatible type "str"; expected "int"

配置 mypy

你还可以通过配置文件来定制 mypy 的行为。创建一个 mypy 配置文件（例如 mypy.ini），内容如下：

[mypy]
python_version = 3.8
warn_return_any = True
warn_unused_ignores = True

使用配置文件运行 mypy：

mypy --config-file mypy.ini your_code.py

通过这些步骤，开发者可以逐步将 mypy 集成到现有的项目中，逐步为代码添加类型注释，提升代码的质量和可维护性。

总结

mypy 是一个强大的工具，通过在 Python 代码中引入类型注解，帮助开发者在编写代码时发现潜在的类型错误，提升代码的质量和可读性。通过简单的安装、类型注释以及运行 mypy 进行检查，可以显著提高开发效率并减少错误发生。

Python 字符串应该用双引号还是单引号？
在 VSCode 中编写 Python 代码，代码规范工具介绍与推荐
Python 中 20 个提高代码质量的测试工具
Python 工程的最佳伴侣：isort、flake8、black 和 mypy
PEP 8 – Style Guide for Python Code
Google Python 风格指南 - 内容目录