]> git.madduck.net Git - etc/vim.git/blob - docs/usage_and_configuration/black_as_a_server.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Draft for Black 2023 stable style (#3418)
[etc/vim.git] / 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-Source-First-Line`: corresponds to the `--skip-source-first-line` command line
54   flag. If present and its value is not an empty string, the first line of the source
55   code will be ignored.
56 - `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization`
57   command line flag. If present and its value is not the empty string, no string
58   normalization will be performed.
59 - `X-Skip-Magic-Trailing-Comma`: corresponds to the `--skip-magic-trailing-comma`
60   command line flag. If present and its value is not an empty string, trailing commas
61   will not be used as a reason to split lines.
62 - `X-Preview`: corresponds to the `--preview` command line flag. If present and its
63   value is not an empty string, experimental and potentially disruptive style changes
64   will be used.
65 - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as _Black_ does when passed the
66   `--fast` command line flag.
67 - `X-Python-Variant`: if set to `pyi`, `blackd` will act as _Black_ does when passed the
68   `--pyi` command line flag. Otherwise, its value must correspond to a Python version or
69   a set of comma-separated Python versions, optionally prefixed with `py`. For example,
70   to request code that is compatible with Python 3.5 and 3.6, set the header to
71   `py3.5,py3.6`.
72 - `X-Diff`: corresponds to the `--diff` command line flag. If present, a diff of the
73   formats will be output.
74
75 If any of these headers are set to invalid values, `blackd` returns a `HTTP 400` error
76 response, mentioning the name of the problematic header in the message body.
77
78 Apart from the above, `blackd` can produce the following response codes:
79
80 - `HTTP 204`: If the input is already well-formatted. The response body is empty.
81 - `HTTP 200`: If formatting was needed on the input. The response body contains the
82   blackened Python code, and the `Content-Type` header is set accordingly.
83 - `HTTP 400`: If the input contains a syntax error. Details of the error are returned in
84   the response body.
85 - `HTTP 500`: If there was any other kind of error while trying to format the input. The
86   response body contains a textual representation of the error.
87
88 The response headers include a `X-Black-Version` header containing the version of
89 _Black_.