Black as a server (blackd)

blackdは、シンプルなプロトコルを介してBlackの機能を提供する小型のHTTPサーバーです。これを使用する主な利点は、ファイルを整形するたびに新しいBlackプロセスを起動するコストを回避できることです。

警告

blackdは、悪用を防ぐためのセキュリティ対策がないため、公開アクセス可能なサーバーとして実行しないでください。**ローカルでのみ使用することを目的としています**。

使用方法

blackdは、追加の依存関係があるため、デフォルトではBlackと共にパッケージ化されていません。pip install 'black[d]'を実行してインストールする必要があります。

ローカルインターフェースのみにバインドしてデフォルトポートでサーバーを起動するには、blackdを実行します。サーバーのバージョン、およびリスニングしているホストとポートを示す1行が表示されます。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リクエストのみを受け付けます。リクエストの本文には、Content-Typeリクエストヘッダーのcharsetフィールドに従ってエンコードされた、フォーマットするPythonソースコードを含める必要があります。charsetが指定されていない場合、blackdはUTF-8を想定します。

ソースコードのフォーマット方法を制御するHTTPヘッダーがいくつかあります。これらは、Blackのコマンドラインフラグに対応します。ただし、例外としてX-Protocol-Versionがあり、存在する場合は値を1にする必要があります。そうでない場合、リクエストはHTTP 501（未実装）で拒否されます。

ソースコードのフォーマット方法を制御するヘッダーは次のとおりです。

  • 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は--fastコマンドラインフラグが渡された場合のBlackのように動作します。

  • X-Python-Variant：pyiに設定されている場合、blackdは--pyiコマンドラインフラグが渡された場合のBlackのように動作します。それ以外の場合は、その値は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：入力をフォーマットしようとしたときに他の種類のエラーが発生した場合。応答本文には、エラーのテキスト表現が含まれます。

応答ヘッダーには、Blackのバージョンを含むX-Black-Versionヘッダーが含まれています。