| single |
[Black Logo]
The Uncompromising Code Formatter
[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.7+ to run.
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+https://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]
_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. Now that
we have become stable, you should not expect large formatting changes in
the future.
Stylistic changes will mostly be responses to bug reports and support for
new Python
syntax. For more information please refer to the
[The Black Code Style].
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`.
## The _Black_ code style
_Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats
entire files in
place. Style configuration options are deliberately limited and rarely
added. It doesn't
take previous formatting into account (see
[Pragmatism]
|