Black代码格式化工具基础使用指南
项目地址: https://gitcode.com/GitHub_Trending/bl/black 什么是Black？
Black是一个Python代码格式化工具，它以"不妥协"的态度著称，这意味着它几乎没有配置选项，而是强制执行一种统一的代码风格。这种设计理念让开发者无需在代码风格上花费时间争论，只需专注于代码本身。
基本使用方法
安装后快速开始
安装Black后，最简单的使用方式是直接对文件或目录运行：
black {源文件或目录}
如果直接运行脚本不工作，也可以作为Python模块运行：
python -m black {源文件或目录}
忽略特定代码段
Black允许你通过特殊注释标记来跳过特定代码段的格式化：
-
单行忽略：在行尾添加
# fmt: skipprint( '保留原样' ) # fmt: skip -
代码块忽略：使用
# fmt: off和# fmt: on包裹代码块# fmt: off def 保留原样 ( ): pass # fmt: on
这些标记必须保持相同的缩进级别，且不能跨缩进块使用。
常用命令行选项
Black提供了多种选项来调整其行为，以下是一些最常用的：
基本选项
--line-length/-l：设置每行最大长度（默认88）--target-version/-t：指定目标Python版本--check：只检查而不修改文件--diff：显示差异而不修改文件--fast/--safe：控制安全检查级别
字符串处理
--skip-string-normalization/-S：保留字符串引号原样--skip-magic-trailing-comma/-C：忽略魔法尾随逗号
高级功能
--preview：启用预览样式功能--unstable：启用实验性样式功能--line-ranges：仅格式化指定行范围
配置文件
Black支持通过pyproject.toml文件进行项目级配置：
[tool.black]
line-length = 88
target-version = ["py311"]
exclude = '''
/(
\.eggs
| \.git
| \.hg
| \.mypy_cache
| \.tox
| \.venv
| _build
| buck-out
| build
| dist
)/
'''
配置文件查找顺序
- 当前目录及其父目录中的
pyproject.toml - 用户全局配置（
~/.config/black或~/.black） - 可通过
--config显式指定配置文件
实用技巧
-
标准输入处理：可以通过管道使用Black
echo "print( 'hello' )" | black - -
版本控制：使用
--required-version确保团队使用相同版本black --required-version 22.12.0 . -
编辑器集成：
--line-ranges选项适合编辑器"格式化选中部分"功能
输出与错误处理
Black遵循Unix惯例：
- 成功时返回0
- 需要格式化时返回1
- 内部错误时返回123
使用--quiet减少输出，或--verbose获取更多信息。
总结
Black是一个强大的代码格式化工具，通过合理的默认值和极简的配置，帮助开发者保持一致的代码风格。虽然它提供了多种选项，但大多数情况下你只需要最基本的命令就能获得理想的结果。对于团队项目，建议通过pyproject.toml文件统一配置，并使用--required-version确保一致性。
记住Black的核心哲学：代码风格不应该成为讨论的焦点，让工具处理这些细节，开发者可以更专注于代码逻辑本身。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
