Black代码格式化工具基础使用指南

Black代码格式化工具基础使用指南

black The uncompromising Python code formatter 项目地址: https://gitcode.com/gh_mirrors/bl/black

什么是Black？

Black是一个Python代码格式化工具，它以"不妥协"的态度著称，这意味着它几乎没有配置选项，而是强制执行一种统一的代码风格。这种设计理念让开发者无需在代码风格上花费时间争论，只需专注于代码本身。

基本使用方法

安装后快速开始

安装Black后，最简单的使用方式是直接对文件或目录运行：

black {源文件或目录}

如果直接运行脚本不工作，也可以作为Python模块运行：

python -m black {源文件或目录}

忽略特定代码段

Black允许你通过特殊注释标记来跳过特定代码段的格式化：

1. 单行忽略：在行尾添加# fmt: skip

   print( '保留原样' )  # fmt: skip
   

2. 代码块忽略：使用# 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
)/
'''

配置文件查找顺序

1. 当前目录及其父目录中的pyproject.toml
2. 用户全局配置（~/.config/black或~/.black）
3. 可通过--config显式指定配置文件

实用技巧

1. 标准输入处理：可以通过管道使用Black

   echo "print( 'hello' )" | black -
   

2. 版本控制：使用--required-version确保团队使用相同版本

   black --required-version 22.12.0 .
   

3. 编辑器集成：--line-ranges选项适合编辑器"格式化选中部分"功能

输出与错误处理

Black遵循Unix惯例：

• 成功时返回0
• 需要格式化时返回1
• 内部错误时返回123

使用--quiet减少输出，或--verbose获取更多信息。

总结

Black是一个强大的代码格式化工具，通过合理的默认值和极简的配置，帮助开发者保持一致的代码风格。虽然它提供了多种选项，但大多数情况下你只需要最基本的命令就能获得理想的结果。对于团队项目，建议通过pyproject.toml文件统一配置，并使用--required-version确保一致性。

记住Black的核心哲学：代码风格不应该成为讨论的焦点，让工具处理这些细节，开发者可以更专注于代码逻辑本身。

black The uncompromising Python code formatter 项目地址: https://gitcode.com/gh_mirrors/bl/black