一文掌握提升 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 有以下几个主要原因：

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

具体怎么做？

安装 flake8

1. 打开终端（或命令行界面）。

2. 运行以下命令通过 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 风格指南 - 内容目录