Black 作为服务器 (blackd)

blackd 是一个小型 HTTP 服务器，它通过一个简单的协议公开 *Black* 的功能。使用它的主要好处是避免每次你想格式化一个文件时启动一个新的 *Black* 进程的成本。

警告

blackd 不应该作为公开可访问的服务器运行，因为它没有安全措施来防止滥用。**它仅供本地使用**。

用法

blackd 默认情况下不会与 *Black* 一起打包，因为它有额外的依赖项。您需要执行 pip install 'black[d]' 来安装它。

您可以通过运行 blackd 来启动默认端口上的服务器，仅绑定到本地接口。您将看到一行关于服务器版本、主机和监听端口的信息。然后，blackd 将在标准输出上打印类似于大多数 Web 服务器的访问日志，与任何因无效格式请求而导致的异常跟踪合并。

blackd 提供的选项甚至比 *Black* 还要少。您可以通过运行 blackd --help 来查看这些选项。

Usage: blackd [OPTIONS]

Options:
  --bind-host TEXT     Address to bind the server to.  [default: localhost]
  --bind-port INTEGER  Port to listen on  [default: 45484]
  --version            Show the version and exit.
  -h, --help           Show this message and exit.

目前还没有官方的 blackd 客户端工具！您可以使用 curl 来测试 blackd 是否正常工作。

blackd --bind-port 9090 &  # or let blackd choose a port
curl -s -XPOST "localhost:9090" -d "print('valid')"

协议

blackd 仅接受 / 路径上的 POST 请求。请求主体应包含要格式化的 Python 源代码，编码方式应根据 Content-Type 请求头中的 charset 字段进行编码。如果没有指定 charset，blackd 假设为 UTF-8。

有一些 HTTP 头控制源代码的格式化方式。这些与 *Black* 的命令行标志相对应。有一个例外：X-Protocol-Version，如果存在，其值应为 1，否则请求将被拒绝，返回 HTTP 501（未实现）。

控制源代码格式的 HTTP 头包括：

  • X-Line-Length：对应于 --line-length 命令行标志。

  • X-Skip-Source-First-Line：对应于 --skip-source-first-line 命令行标志。如果存在且其值不是空字符串，则源代码的第一行将被忽略。

  • X-Skip-String-Normalization：对应于 --skip-string-normalization 命令行标志。如果存在且其值不是空字符串，则不会执行任何字符串规范化。

  • X-Skip-Magic-Trailing-Comma：对应于 --skip-magic-trailing-comma 命令行标志。如果存在且其值不是空字符串，则尾随逗号不会用作分割行的理由。

  • X-Preview：对应于 --preview 命令行标志。如果存在且其值不是空字符串，则将使用实验性和可能具有破坏性的样式更改。

  • X-Unstable：对应于 --unstable 命令行标志。如果存在且其值不是空字符串，则将使用已知存在错误的实验性样式更改。

  • X-Enable-Unstable-Feature：对应于 --enable-unstable-feature 标志。标志的内容必须是逗号分隔的要启用的不稳定功能列表。例如：X-Enable-Unstable-Feature: feature1, feature2。

  • X-Fast-Or-Safe：如果设置为 fast，blackd 将像 *Black* 在传递 --fast 命令行标志时一样工作。

  • X-Python-Variant：如果设置为 pyi，blackd 将像 *Black* 在传递 --pyi 命令行标志时一样工作。否则，其值必须对应于一个 Python 版本或一组逗号分隔的 Python 版本，可以选择用 py 为前缀。例如，要请求与 Python 3.5 和 3.6 兼容的代码，请将头设置为 py3.5,py3.6。

  • X-Diff：对应于 --diff 命令行标志。如果存在，将输出格式的差异。

如果这些头中的任何一个设置为无效值，blackd 将返回一个 HTTP 400 错误响应，并在消息主体中提及有问题的头的名称。

除了以上内容，blackd 可以产生以下响应代码：

  • HTTP 204：如果输入已经是格式良好的。响应主体为空。

  • HTTP 200：如果输入需要格式化。响应主体包含已格式化的 Python 代码，并且 Content-Type 头相应设置。

  • HTTP 400：如果输入包含语法错误。错误的详细信息将返回在响应主体中。

  • HTTP 500：如果在尝试格式化输入时发生任何其他类型的错误。响应主体包含错误的文本表示。

响应头包括一个 X-Black-Version 头，其中包含 *Black* 的版本。