每日一模块：black

一、简介

Black是一个自动化Python代码格式化工具，能够按照PEP 8风格指南以及Black自身的一些风格选择来统一格式化代码，使代码更加整洁和易读。除了格式化单个文件或目录，我们还可以将Black集成到版本控制系统中，以确保每次提交的代码都符合统一的风格。

二、安装Black

使用pip安装Black：

pip install black

三、基本使用

1. 格式化单个文件

black my_script.py

2.格式化整个目录

black my_project_directory/

3.检查代码风格而不进行格式化

black --check my_script.py

四、高级使用与选项

除了基本使用，Black还提供了许多高级选项，允许你更细致地控制代码格式。

1.指定行宽

black --line-length 120 my_script.py

2. 排除文件或目录

black --exclude='/(venv|migrations|build)/' my_project_directory/

3.格式化并输出到文件

black --diff my_script.py

或者将格式化后的代码输出到另一个文件：

black my_script.py > formatted_script.py

4. 配置Black

你可以在项目的根目录下创建一个pyproject.toml文件来配置Black。以下是一个包含多个选项的配置示例：

[tool.black]

line-length = 100  # 每行的最大字符数，默认为 88

target-version = ['py37']  # 目标 Python 版本

include = '\.pyi?$'   # 要包含的文件模式，默认为 '\.pyi?$'

exclude = '''

/(

\.git

| \.venv

| _build

| buck-out

| dist

| docs/source/conf\.py

| my_special_directory

)/

'''

在这个配置中：

•line-length设置了每行的最大字符数。

•target-version指定了目标Python版本，Black会基于这个版本生成兼容的代码。

•include是一个正则表达式，用于匹配需要格式化的文件。

•exclude是一个正则表达式，用于排除不需要格式化的文件或目录。

五、集成到版本控制系统

将Black集成到版本控制系统中（如Git），可以确保每次提交的代码都经过格式化检查。以下是如何在Git中使用pre-commit钩子来集成Black的示例。

1.安装pre-commit

首先，你需要安装pre-commit这个工具，它可以帮助你管理Git钩子。

pip install pre-commit

2. 在项目中初始化pre-commit

进入你的项目目录，并运行以下命令来初始化pre-commit配置：

pre-commit init

这将在项目根目录下创建一个.pre-commit-config.yaml文件。

3.配置Black为pre-commit钩子

编辑.pre-commit-config.yaml文件，添加Black作为pre-commit钩子：

repos:

-   repo: https://github.com/psf/black

rev: stable  # 或者你可以指定一个具体的版本号，如 21.12b0

hooks:

-   id: black

language_version: python3  # 指定Python版本

exclude: ^(docs|migrations|venv)/  # 排除的目录或文件模式

在上面的配置中，我们指定了Black的仓库地址、版本以及要排除的目录或文件模式。你可以根据需要调整这些配置。

4. 安装钩子

运行以下命令来安装配置好的钩子：

pre-commit install

现在，每次你尝试提交代码时，pre-commit都会自动运行Black来格式化你的代码。如果代码不符合Black的规范，提交将被阻止，并显示哪些文件需要格式化。

六、集成到编辑器或IDE

许多流行的编辑器（如 VS Code、PyCharm、Sublime Text 等）都支持black的集成。你可以在编辑器的插件或扩展市场中搜索black，并安装相应的插件。这样，你就可以在保存文件时自动格式化代码，或者在编辑器中直接调用black来格式化选定的代码块。

七、注意事项

•black是自动的、不可配置的。这意味着它不会给你很多选项来自定义格式化方式。它的目标是减少开发者在格式化代码上的分歧，使代码风格保持一致。如果你需要更多的配置选项，可以考虑使用其他格式化工具，如autopep8或yapf。

•black会修改你的代码。在运行black之前，最好先备份你的代码，以防万一出现不可预见的问题。

• 虽然black可以自动格式化代码，但它并不能保证代码的正确性或逻辑清晰性。你仍然需要仔细审查和测试你的代码以确保其质量和正确性。

八、总结

Black是一个强大的代码格式化工具，可以大大提高代码的一致性和可读性。通过学习和掌握Black的使用方法，你可以更有效地管理项目的代码风格，并与团队成员保持一致的编码规范。通过集成Black到版本控制系统中，你可以确保团队的代码风格保持一致，并减少由于风格不一致而引起的合并冲突。结合编辑器或IDE的集成，你可以更高效地管理和维护项目的代码风格。