Black 代码风格自动格式化器教程

Black 代码风格自动格式化器教程

black项目地址:https://gitcode.com/gh_mirrors/bla/black

1. 项目目录结构及介绍

Black 是一个 Python 代码自动格式化工具，其项目目录结构如下：

black/
├── bin/                # 包含可执行脚本
├── docs/               # 文档资料
├── tests/              # 单元测试
├── black.py            # 主入口文件
├── setup.py            # 安装脚本
└── pyproject.toml      # 项目配置文件

• bin/: 存放命令行工具 black 的可执行文件。
• docs/: 包含项目的文档源码和构建材料。
• tests/: 测试套件，用于验证 Black 的功能。
• black.py: 主要的 Python 模块，实现了代码格式化的逻辑。
• setup.py: setuptools 脚本，用于安装和打包 Black。
• pyproject.toml: 使用 TOML 格式定义项目的配置，包括 Black 的自定义设置。

2. 项目的启动文件介绍

Black 的主要入口点是 black.py 文件。这个文件包含了处理命令行参数并调用格式化逻辑的主要函数。用户通常通过在终端运行 black <source_file> 或 black .（格式化整个项目）来使用它。

例如，以下是如何从命令行启动 Black 格式化工具：

python -m black your_code.py

这将会根据 Black 的默认规则对 your_code.py 进行格式化。

3. 项目的配置文件介绍

Black 支持使用 pyproject.toml 配置文件来自定义格式化行为。以下是配置文件的基本结构示例：

[tool.black]
line-length = 88        # 设置每行的最大长度
target-version = ['py36']   # 指定兼容的 Python 版本
include = '\.pyi?$'     # 匹配要格式化的文件类型
exclude = '_*\.py'     # 排除不格式化的文件模式
skip-string-normalization = true  # 禁止字符串正常化

在这个例子中，line-length 设定了最大行宽，target-version 控制了格式化的语法兼容性，include 和 exclude 分别指定了要处理和忽略的文件模式。skip-string-normalization 是一个布尔值，如果为真，则不会转换单引号双引号。

要应用这些配置，确保在项目根目录下创建 pyproject.toml 文件，并将上述设置添加进去。然后运行 Black 时，它会读取并遵守这些配置。

现在你已经了解了 Black 的基本结构、启动方式以及如何进行个性化配置。为了获得更详细的使用指南，请查阅项目的官方文档。

black项目地址:https://gitcode.com/gh_mirrors/bla/black