[//]: # (NOTE: THIS FILE WAS AUTOGENERATED FROM blackd.md) ## blackd `blackd` is a small HTTP server that exposes _Black_'s functionality over a simple protocol. The main benefit of using it is to avoid paying the cost of starting up a new _Black_ process every time you want to blacken a file. ### Usage `blackd` is not packaged alongside _Black_ by default because it has additional dependencies. You will need to do `pip install black[d]` to install it. You can start the server on the default port, binding only to the local interface by running `blackd`. You will see a single line mentioning the server's version, and the host and port it's listening on. `blackd` will then print an access log similar to most web servers on standard output, merged with any exception traces caused by invalid formatting requests. `blackd` provides even less options than _Black_. You can see them by running `blackd --help`: ```text Usage: blackd [OPTIONS] Options: --bind-host TEXT Address to bind the server to. --bind-port INTEGER Port to listen on --version Show the version and exit. -h, --help Show this message and exit. ``` There is no official blackd client tool (yet!). You can test that blackd is working using `curl`: ```sh blackd --bind-port 9090 & # or let blackd choose a port curl -s -XPOST "localhost:9090" -d "print('valid')" ``` ### Protocol `blackd` only accepts `POST` requests at the `/` path. The body of the request should contain the python source code to be formatted, encoded according to the `charset` field in the `Content-Type` request header. If no `charset` is specified, `blackd` assumes `UTF-8`. There are a few HTTP headers that control how the source is formatted. These correspond to command line flags for _Black_. There is one exception to this: `X-Protocol-Version` which if present, should have the value `1`, otherwise the request is rejected with `HTTP 501` (Not Implemented). The headers controlling how code is formatted are: - `X-Line-Length`: corresponds to the `--line-length` command line flag. - `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization` command line flag. If present and its value is not the empty string, no string normalization will be performed. - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as _Black_ does when passed the `--fast` command line flag. - `X-Python-Variant`: if set to `pyi`, `blackd` will act as _Black_ does when passed the `--pyi` command line flag. Otherwise, its value must correspond to a Python version or a set of comma-separated Python versions, optionally prefixed with `py`. For example, to request code that is compatible with Python 3.5 and 3.6, set the header to `py3.5,py3.6`. - `X-Diff`: corresponds to the `--diff` command line flag. If present, a diff of the formats will be output. If any of these headers are set to invalid values, `blackd` returns a `HTTP 400` error response, mentioning the name of the problematic header in the message body. Apart from the above, `blackd` can produce the following response codes: - `HTTP 204`: If the input is already well-formatted. The response body is empty. - `HTTP 200`: If formatting was needed on the input. The response body contains the blackened Python code, and the `Content-Type` header is set accordingly. - `HTTP 400`: If the input contains a syntax error. Details of the error are returned in the response body. - `HTTP 500`: If there was any kind of error while trying to format the input. The response body contains a textual representation of the error. The response headers include a `X-Black-Version` header containing the version of _Black_.