Python Django项目如何配置格式化工具实现参数与可迭代对象自动拆行

一、已尝试工具的可调整配置 #

1. Black 配置 #

你当前遇到的参数挤行问题，可直接利用Black内置规则解决：

• Black 会自动识别参数列表末尾的尾随逗号，强制将所有参数拆分为每行一个、括号独立占行。触发示例：
  输入带尾随逗号的代码：

  def test_user_can_filter_all_communities(
      self, filter_field: str, filter_value: JSONSerializable, include_results: list,
  ):
  

  执行Black格式化后直接输出目标格式：

  def test_user_can_filter_all_communities(
      self,
      filter_field: str,
      filter_value: JSONSerializable,
      include_results: list,
  ):
  

• 如需自动补全尾随逗号，可配合Ruff的comma-style lint规则，无需手动添加。

2. yapf 配置 #

修改项目根目录下.style.yapf配置文件，替换为以下内容即可解决首行括号对齐续行的问题：

[style]
based_on_style = django
# 关闭首行括号对齐的续行缩进
align_closing_brackets = false
# 闭合括号独立占行
dedent_closing_brackets = true
# 强制参数拆行后每行仅放置一个
split_before_first_argument = true
split_last_argument = true
# 行宽按需调整，示例为120
column_limit = 120

二、零手动干预的自动化方案 #

如果需要完全不需要手动加尾随逗号，自动实现「函数签名超行宽即拆分为每行一个参数、括号独立」的规则，推荐使用Ruff，兼容Python 3.8、Django 3.1.4运行环境。
在项目根目录pyproject.toml中添加以下配置：

[tool.ruff]
line-length = 120
target-version = "py38"

[tool.ruff.format]
# 强制可迭代对象括号独立占行
parent-format = "preserve"
# 函数签名超行宽时强制每行放置一个参数
force-split-arguments = true
indent-style = "space"

执行ruff format .即可一次性完成所有规范的自动调整，覆盖：

• 字典、元组等可迭代对象的独立括号分行格式
• 函数签名的拆行规则

补充说明 #

• pylint为纯代码校验工具，无自动格式化能力，仅能输出不符合规范的提示，无法直接调整代码格式，这也是此前使用pylint无法达到效果的原因。
• 配置完成后可对接pre-commit钩子，在代码提交阶段自动执行格式化，消除手动调整的额外开销。

内容的提问来源于stack exchange，提问作者Gabriela Valle