Black是一个代码格式化器,可以在定义好的规则集之后自动调整你的Python代码。在这篇文章中,我讨论了对这样一个代码格式化器的需求,向你展示了如何将它集成到你的IDE和CI管道中。
为什么你要使用代码格式化器
当你是一个在大型项目中作为团队的一部分工作的开发者时,你可能已经意识到对于你的代码中的特定结构应该如何格式化存在着不同的意见。例如,你可能会对Python中的字符串使用单引号('
)还是双引号("
)更好产生争论(尽管它们完全可以互换)。
每个这样的争论都会占用宝贵的时间,而这些时间可以用来修复错误或建立新的功能。然而,当每个人都自己决定如何处理这样的格式化决定时,代码库就会变得混乱和不一致。因此,许多团队采用了风格指南--在维基页面上写下这样的格式化约定,供大家遵循。不幸的是,这不仅需要大量的时间,而且很少有这样的情况,即所有的开发人员都能记住该指南,并在阅读后从不违反任何规则。
Łukasz Langa开发的Black(以及类似的自动格式化工具,如Prettierfor JavaScript或gofmtfor Go)通过根据一套固定的规则自动格式化你的代码来解决这个问题。它们是有主见的,这意味着几乎没有定制的空间。他们的这一决定的比率是,和通常一样,完美不应该是好的敌人。完全不讨论这种规则并节省时间,比找到能更好地符合团队偏好的造型规则更有价值。
Black是如何工作的
Black的工作方式是,它解析Python代码,应用其格式化规则,然后验证格式化后的输出是否仍然在Python中创建了相同的内部表示。这最后一步使得Black使用起来非常安全--它永远不会应用可能导致代码本身的不同解释的改变。
Black的设置非常简单。
pip install black
由于没有(几乎)任何东西需要配置,你已经准备好格式化你的代码了。
一旦安装了black
工具,有两种操作方式。通过调用black --check file_name.py
,它将做一个干运行,只是输出它是否会对文件进行修改(对CI管道非常有用,后面会显示)。通过运行black file_name.py
,格式化的改变会自动应用。
另外,所有主要的IDE都有集成,所以你不必手动运行可执行文件。例如在VSCode中,你可以将Python格式化器设置为Black,然后运行 "Format "命令,在编辑器中自动调用Black。
在CI管道中运行Black
如果你是一个单独的开发者,我到现在为止所展示的设置可能是足够的。然而,在一个更大的团队中,总是有可能有新加入的人还不熟悉Black,并可能被诱惑去贡献没有自动格式化的代码。为了解决这个问题,你可以在你的CI管道中添加一个Black -check任务。这不会自动纠正错误,但至少可以防止未格式化的代码进入你的代码库。
下面是在GitLab中完成这种检查的最小可行模板(但其原理对任何CI管道都是一样的)。
image: python:latest
variables:
PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
stages:
- Static Analysis
cache:
paths:
- .cache/pip
- venv/
before_script:
- python --version
- pip install virtualenv
- virtualenv venv
- source venv/bin/activate
- pip install black
black:
stage: Static Analysis
script:
- black --check .
该流水线定义了一个 "静态分析 "阶段,该阶段有一个单一的任务("black"),对整个源代码目录进行black --check
。如果它检测到未格式化的文件,它将有一个非零的退出代码并导致管道失败。