actions/black
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
5773d5cd2b
black/docs/usage_and_configuration/black_as_a_server.md
Antonio Ossa-Guerra 4da0851809
Add option to skip the first line of source code (#3299) 
* Add option to skip the first line in source file

This commit adds a CLi option to skip the first line in the source
files, just like the Cpython command line allows [1]. By enabling the
flag, using `-x` or `--skip-source-first-line`, the first line is
removed temporarilly while the remaining contents are formatted. The
first line is added back before returning the formatted output.

[1]: https://docs.python.org/dev/using/cmdline.html#cmdoption-x

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Add tests for `--skip-source-first-line` option

When the flag is disabled (default), black formats the entire source
file, as in every line. In the other hand, if the flag is enabled, by
using `-x` or `--skip-source-first-line`, the first line is retained
while the rest of the source is formatted and then is added back.

These tests use an empty Python file that contains invalid syntax in
its first line (`invalid_header.py`, at `miscellaneous/`). First,
Black is invoked without enabling the flag which should result in an
exit code different than 0. When the flag is enabled, Black is
expected to return a successful exit code and the header is expected
to be retained (even if its not valid Python syntax).

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Support skip source first line option for blackd

The recently added option can be added as an acceptable header for
blackd. The arguments are passed in such a way that using the new
header will activate the skip source first line behaviour as expected

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Add skip source first line option to blackd docs

The new option can be passed to blackd as a header. This commit
updates the blackd docs to include the new header.

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Update CHANGES.md

Include the new Black option to skip the first line of source code in
the configuration section

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Update skip first line test including valid syntax

Including valid Python syntax help us make sure that the file is still
actually valid after skipping the first line of the source file (which
contains invalid Python syntax)

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Skip first source line at `format_file_in_place`

Instead of skipping the first source line at `format_file_contents`,
do it before. This allow us to find the correct newline and encoding
on the actual source code (everything that's after the header).

This change is also applied at Blackd: take the header before passing
the source to `format_file_contents` and put the header back once we
get the formatted result.

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Test output newlines when skipping first line

When skipping the first line of source code, the reference newline must
be taken from the second line of the file instead of the first one, in
case that the file mixes more than one kind of newline character

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Test that Blackd also skips first line correctly

Simliarly to the Black tests, we first compare that Blackd fails when
the first line is invalid Python syntax and then check that the result
is the expected when tha flag is activated

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Use the content encoding to decode the header

When decoding the header to put it back at the top of the contents of
the file, use the same encoding used in the content. This should be a
better "guess" that using the default value

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>
2022-10-06 15:17:32 -07:00

4.2 KiB
Raw Blame History

Black as a server (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 the cost of starting up a new Black process every time you want to blacken a file.

`blackd` should not be run as a publicly accessible server as there are no security
precautions in place to prevent abuse. **It is intended for local use only**.

Usage

blackd is not packaged alongside Black by default because it has additional dependencies. You will need to execute 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:

There is no official blackd client tool (yet!). You can test that blackd is working using curl:

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 code 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 source code is formatted are:

  • X-Line-Length: corresponds to the --line-length command line flag.
  • X-Skip-Source-First-Line: corresponds to the --skip-source-first-line command line flag. If present and its value is not an empty string, the first line of the source code will be ignored.
  • 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-Skip-Magic-Trailing-Comma: corresponds to the --skip-magic-trailing-comma command line flag. If present and its value is not an empty string, trailing commas will not be used as a reason to split lines.
  • X-Preview: corresponds to the --preview command line flag. If present and its value is not an empty string, experimental and potentially disruptive style changes will be used.
  • 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 other 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.