c3235e6da7
Fix unintentionally swapped words in index.md I think the intent was to say "large changes in formatting", because it doesn't make sense to say "large formatting in changes".
140 lines
3.6 KiB
Markdown
140 lines
3.6 KiB
Markdown
<!--
|
|
black documentation master file, created by
|
|
sphinx-quickstart on Fri Mar 23 10:53:30 2018.
|
|
-->
|
|
|
|
# The uncompromising code formatter
|
|
|
|
> “Any color you like.”
|
|
|
|
By using _Black_, 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.
|
|
|
|
_Black_ makes code review faster by producing the smallest diffs possible. 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.
|
|
|
|
Try it out now using the [Black Playground](https://black.vercel.app).
|
|
|
|
```{admonition} Note - Black is now stable!
|
|
*Black* is [successfully used](https://github.com/psf/black#used-by) by
|
|
many projects, small and big. *Black* has a comprehensive test suite, with efficient
|
|
parallel tests, our own auto formatting and parallel Continuous Integration runner.
|
|
Now that we have become stable, you should not expect large changes to formatting in
|
|
the future. Stylistic changes will mostly be responses to bug reports and support for new Python
|
|
syntax.
|
|
|
|
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](./the_black_code_style/current_style.md#pragmatism)
|
|
section for details). If you're feeling confident, use `--fast`.
|
|
```
|
|
|
|
```{note}
|
|
{doc}`Black is licensed under the MIT license <license>`.
|
|
```
|
|
|
|
## Testimonials
|
|
|
|
**Mike Bayer**, author of [SQLAlchemy](https://www.sqlalchemy.org/):
|
|
|
|
> _I can't think of any single tool in my entire programming career that has given me a
|
|
> bigger productivity increase by its introduction. I can now do refactorings in about
|
|
> 1% of the keystrokes that it would have taken me previously when we had no way for
|
|
> code to format itself._
|
|
|
|
**Dusty Phillips**,
|
|
[writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
|
|
|
|
> _Black is opinionated so you don't have to be._
|
|
|
|
**Hynek Schlawack**, creator of [attrs](https://www.attrs.org/), core developer of
|
|
Twisted and CPython:
|
|
|
|
> _An auto-formatter that doesn't suck is all I want for Xmas!_
|
|
|
|
**Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
|
|
|
|
> _At least the name is good._
|
|
|
|
**Kenneth Reitz**, creator of [requests](http://python-requests.org/) and
|
|
[pipenv](https://docs.pipenv.org/):
|
|
|
|
> _This vastly improves the formatting of our code. Thanks a ton!_
|
|
|
|
## Show your style
|
|
|
|
Use the badge in your project's README.md:
|
|
|
|
```md
|
|
[](https://github.com/psf/black)
|
|
```
|
|
|
|
Using the badge in README.rst:
|
|
|
|
```rst
|
|
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
|
|
:target: https://github.com/psf/black
|
|
```
|
|
|
|
Looks like this:
|
|
|
|
```{image} https://img.shields.io/badge/code%20style-black-000000.svg
|
|
:target: https://github.com/psf/black
|
|
```
|
|
|
|
## Contents
|
|
|
|
```{toctree}
|
|
---
|
|
maxdepth: 3
|
|
includehidden:
|
|
---
|
|
|
|
the_black_code_style/index
|
|
```
|
|
|
|
```{toctree}
|
|
---
|
|
maxdepth: 3
|
|
includehidden:
|
|
caption: User Guide
|
|
---
|
|
|
|
getting_started
|
|
usage_and_configuration/index
|
|
integrations/index
|
|
guides/index
|
|
faq
|
|
```
|
|
|
|
```{toctree}
|
|
---
|
|
maxdepth: 2
|
|
includehidden:
|
|
caption: Development
|
|
---
|
|
|
|
contributing/index
|
|
change_log
|
|
authors
|
|
```
|
|
|
|
```{toctree}
|
|
---
|
|
hidden:
|
|
caption: Project Links
|
|
---
|
|
|
|
GitHub <https://github.com/psf/black>
|
|
PyPI <https://pypi.org/project/black>
|
|
Chat <https://discord.gg/RtVdv86PrH>
|
|
```
|
|
|
|
# Indices and tables
|
|
|
|
- {ref}`genindex`
|
|
- {ref}`search`
|