docs/usage_and_configuration/black_as_a_server.md

   1 # Black as a server (blackd)
   2
   3 `blackd` is a small HTTP server that exposes _Black_'s functionality over a simple
   4 protocol. The main benefit of using it is to avoid the cost of starting up a new _Black_
   5 process every time you want to blacken a file.
   6
   7 ```{warning}
   8 `blackd` should not be run as a publicly accessible server as there are no security
   9 precautions in place to prevent abuse. **It is intended for local use only**.
  10 ```
  11
  12 ## Usage
  13
  14 `blackd` is not packaged alongside _Black_ by default because it has additional
  15 dependencies. You will need to execute `pip install 'black[d]'` to install it.
  16
  17 You can start the server on the default port, binding only to the local interface by
  18 running `blackd`. You will see a single line mentioning the server's version, and the
  19 host and port it's listening on. `blackd` will then print an access log similar to most
  20 web servers on standard output, merged with any exception traces caused by invalid
  21 formatting requests.
  22
  23 `blackd` provides even less options than _Black_. You can see them by running
  24 `blackd --help`:
  25
  26 ```{program-output} blackd --help
  27
  28 ```
  29
  30 There is no official `blackd` client tool (yet!). You can test that blackd is working
  31 using `curl`:
  32
  33 ```sh
  34 blackd --bind-port 9090 &  # or let blackd choose a port
  35 curl -s -XPOST "localhost:9090" -d "print('valid')"
  36 ```
  37
  38 ## Protocol
  39
  40 `blackd` only accepts `POST` requests at the `/` path. The body of the request should
  41 contain the python source code to be formatted, encoded according to the `charset` field
  42 in the `Content-Type` request header. If no `charset` is specified, `blackd` assumes
  43 `UTF-8`.
  44
  45 There are a few HTTP headers that control how the source code is formatted. These
  46 correspond to command line flags for _Black_. There is one exception to this:
  47 `X-Protocol-Version` which if present, should have the value `1`, otherwise the request
  48 is rejected with `HTTP 501` (Not Implemented).
  49
  50 The headers controlling how source code is formatted are:
  51
  52 - `X-Line-Length`: corresponds to the `--line-length` command line flag.
  53 - `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization`
  54   command line flag. If present and its value is not the empty string, no string
  55   normalization will be performed.
  56 - `X-Skip-Magic-Trailing-Comma`: corresponds to the `--skip-magic-trailing-comma`
  57   command line flag. If present and its value is not the empty string, trailing commas
  58   will not be used as a reason to split lines.
  59 - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as _Black_ does when passed the
  60   `--fast` command line flag.
  61 - `X-Python-Variant`: if set to `pyi`, `blackd` will act as _Black_ does when passed the
  62   `--pyi` command line flag. Otherwise, its value must correspond to a Python version or
  63   a set of comma-separated Python versions, optionally prefixed with `py`. For example,
  64   to request code that is compatible with Python 3.5 and 3.6, set the header to
  65   `py3.5,py3.6`.
  66 - `X-Diff`: corresponds to the `--diff` command line flag. If present, a diff of the
  67   formats will be output.
  68
  69 If any of these headers are set to invalid values, `blackd` returns a `HTTP 400` error
  70 response, mentioning the name of the problematic header in the message body.
  71
  72 Apart from the above, `blackd` can produce the following response codes:
  73
  74 - `HTTP 204`: If the input is already well-formatted. The response body is empty.
  75 - `HTTP 200`: If formatting was needed on the input. The response body contains the
  76   blackened Python code, and the `Content-Type` header is set accordingly.
  77 - `HTTP 400`: If the input contains a syntax error. Details of the error are returned in
  78   the response body.
  79 - `HTTP 500`: If there was any other kind of error while trying to format the input. The
  80   response body contains a textual representation of the error.
  81
  82 The response headers include a `X-Black-Version` header containing the version of
  83 _Black_.