single |
![Black Logo]
The Uncompromising Code Formatter
[image]
[image]
[image]
[image]
[image]
[image]
[image]
[image]
[image]
> “Any color you like.”
_Black_ is the uncompromising Python code formatter. By using it, you agree
to cede
control over minutiae of hand-formatting. In return, _Black_ gives you
speed,
determinism, and freedom from `pycodestyle` nagging about formatting. You
will save time
and mental energy for more important matters.
Blackened code looks the same regardless of the project you're reading.
Formatting
becomes transparent after a while and you can focus on the content instead.
_Black_ makes code review faster by producing the smallest diffs possible.
Try it out now using the [Black Playground]. Watch the
[PyCon 2019 talk] to learn more.
---
**[Read the documentation on ReadTheDocs!]**
---
## Installation and usage
### Installation
_Black_ can be installed by running `pip install black`. It requires Python
3.6.2+ to
run. If you want to format Python 2 code as well, install with
`pip install black[python2]`. If you want to format Jupyter Notebooks,
install with
`pip install black[jupyter]`.
If you can't wait for the latest _hotness_ and want to install from GitHub,
use:
`pip install git+git://github.com/psf/black`
### Usage
To get started right away with sensible defaults:
```sh
black {source_file_or_directory}
```
You can run _Black_ as a package if running it as a script doesn't work:
```sh
python -m black {source_file_or_directory}
```
Further information can be found in our docs:
- [Usage and Configuration]
### NOTE: This is a beta product
_Black_ is already [successfully used] by many
projects, small and big. Black has a comprehensive test suite, with
efficient parallel
tests, and our own auto formatting and parallel Continuous Integration
runner. However,
_Black_ is still beta. Things will probably be wonky for a while. This is
made explicit
by the "Beta" trove classifier, as well as by the "b" in the version
number. What this
means for you is that **until the formatter becomes stable, you should
expect some
formatting to change in the future**. That being said, no drastic stylistic
changes are
planned, mostly responses to bug reports.
Also, as a safety measure which slows down processing, _Black_ will check
that the
reformatted code still produces a valid AST that is effectively equivalent
to the
original (see the
[Pragmatism]
section for details). If you're feeling confident, use `--fast`.
|