如何阻止Black在`|`类型注解后添加换行？原因与解决方法

原因 #

Black的核心格式化逻辑围绕行宽限制（默认88字符）展开，当你的类型提示（list[str] | None）加上后续代码（= Query(...)）的整体长度接近或超过这个阈值时，它会自动在类型联合运算符|处拆分换行，以此保证每行代码的可读性符合它的规范。少数情况下，即使行宽没超，Black的内部类型提示格式化规则也可能触发拆分，但绝大多数场景都是行宽触发的。

阻止换行的方法 #

1. 调整行宽阈值 #

通过命令行参数--line-length设置更大的允许行宽，比如：

black --line-length 120 your_script.py

只要整行代码长度不超过你设置的新阈值，Black就会保持list[str] | None在同一行。

2. 强制跳过格式化 #

用# fmt: off和# fmt: on注释包裹目标代码段，让Black跳过该区域的格式化：

# fmt: off
operators: list[str] | None = Query(
    default=None,
    description="operators",
),
# fmt: on

3. 修改代码适配Black规则 #

• 用Optional[list[str]]替代list[str] | None（需要导入from typing import Optional），这种旧版类型联合语法的长度更短，更容易在默认行宽下保持单行；
• 精简后续Query的参数写法（不推荐，会降低可读性），比如把参数缩到一行：

  operators: list[str] | None = Query(default=None, description="operators"),
  

内容的提问来源于stack exchange，提问作者Doohan Kim