7403d95862
* Split code style and components documentation Splits 'the_black_code_style', 'pragmatism', 'blackd',and 'black_primer' into their own files. The exception being 'the_black_code_style' and 'pragmatism'. They have been merged into one 'the_black_code_style_and_pragmatism' file. These changes are being made because the README is becoming very long. And a README isn't great if it dissuades its reader because of its length. * Update the doc generation logic and configuration With the moving of several sections in the README and the renaming of a few files, 'conf.py' needs to be able to support custom sections. This commit introduces DocSection which can be used to specify custom sections of documentation. The information stored in DocSection will be used by the process_sections function to read, process, and write the section to CURRENT_DIR. A large change has been made to the how the docs are prepared to be built. Instead of just generating the files needed by reading the README, this has a full chain of operations so custom sections are supported. First, it reads the README and spits out a list of DocSection objects representing the sections to be generated by process_sections. This is done since most of the docs still live in README. Then along with the defined custom_sections , the process_sections will be begin to process the DocSection objects. It reads the information it needs to generate the section. Then fetches the section's contents, calls processors required by the section to process the section's contents, and finally writes the section to CURRENT_DIR. This large change is so processing of the documentation can be done just for the versions hosted on ReadTheDocs.org. An example processor using this feature is a 'replace_links' processor. It will replace documentation links that point to the docs hosted on GitHub with links that point to the version hosted on ReadTheDocs.org. (I won't be coding that ATM) This also means that files will be overwritten or created once the docs have been built. It is annoying, since you have to 'git reset --hard' and 'git clean -f -d' after each build, but there's nothing better. The old system had the same side effects, so yeah :( * Update filenames and delete unnecessary files Update the filenames since 'the_black_code_style' and 'pragmatism' were merged and 'contributing' was deleted in favor of 'contributing_to_black'. All symlinks were deleted since their home (_build/generated) is no longer used. * Fix broken links and a few redirections * Merge master into refactor_docs (manually done) * Add my and most of @hugovk suggestions Co-Authored-By: Hugo van Kemenade <hugovk@users.noreply.github.com> * Add logging and improve configurability Just some cleaning up up of the DocSection dataclass and added logging support so you know what's going on. * Rename a section and please the grammar gods of Black Thanks @hugovk for the suggestion! * Fix Markdown comments * Add myself as an author :P Seems like the right time. Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
82 lines
3.6 KiB
Markdown
82 lines
3.6 KiB
Markdown
## 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_.
|