README.md

   1 ![Black Logo](https://raw.githubusercontent.com/psf/black/main/docs/_static/logo2-readme.png)
   2
   3 <h2 align="center">The Uncompromising Code Formatter</h2>
   4
   5 <p align="center">
   6 <a href="https://github.com/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Test/badge.svg"></a>
   7 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
   8 <a href="https://coveralls.io/github/psf/black?branch=main"><img alt="Coverage Status" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=main"></a>
   9 <a href="https://github.com/psf/black/blob/main/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
  10 <a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://img.shields.io/pypi/v/black"></a>
  11 <a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></a>
  12 <a href="https://anaconda.org/conda-forge/black/"><img alt="conda-forge" src="https://img.shields.io/conda/dn/conda-forge/black.svg?label=conda-forge"></a>
  13 <a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
  14 </p>
  15
  16 > “Any color you like.”
  17
  18 _Black_ is the uncompromising Python code formatter. By using it, you agree to cede
  19 control over minutiae of hand-formatting. In return, _Black_ gives you speed,
  20 determinism, and freedom from `pycodestyle` nagging about formatting. You will save time
  21 and mental energy for more important matters.
  22
  23 Blackened code looks the same regardless of the project you're reading. Formatting
  24 becomes transparent after a while and you can focus on the content instead.
  25
  26 _Black_ makes code review faster by producing the smallest diffs possible.
  27
  28 Try it out now using the [Black Playground](https://black.vercel.app). Watch the
  29 [PyCon 2019 talk](https://youtu.be/esZLCuWs_2Y) to learn more.
  30
  31 ---
  32
  33 **[Read the documentation on ReadTheDocs!](https://black.readthedocs.io/en/stable)**
  34
  35 ---
  36
  37 ## Installation and usage
  38
  39 ### Installation
  40
  41 _Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
  42 run. If you want to format Jupyter Notebooks, install with `pip install black[jupyter]`.
  43
  44 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
  45
  46 `pip install git+https://github.com/psf/black`
  47
  48 ### Usage
  49
  50 To get started right away with sensible defaults:
  51
  52 ```sh
  53 black {source_file_or_directory}
  54 ```
  55
  56 You can run _Black_ as a package if running it as a script doesn't work:
  57
  58 ```sh
  59 python -m black {source_file_or_directory}
  60 ```
  61
  62 Further information can be found in our docs:
  63
  64 - [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
  65
  66 _Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
  67 projects, small and big. _Black_ has a comprehensive test suite, with efficient parallel
  68 tests, and our own auto formatting and parallel Continuous Integration runner. Now that
  69 we have become stable, you should not expect large formatting to changes in the future.
  70 Stylistic changes will mostly be responses to bug reports and support for new Python
  71 syntax. For more information please refer to the
  72 [The Black Code Style](docs/the_black_code_style/index.rst).
  73
  74 Also, as a safety measure which slows down processing, _Black_ will check that the
  75 reformatted code still produces a valid AST that is effectively equivalent to the
  76 original (see the
  77 [Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting)
  78 section for details). If you're feeling confident, use `--fast`.
  79
  80 ## The _Black_ code style
  81
  82 _Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in
  83 place. Style configuration options are deliberately limited and rarely added. It doesn't
  84 take previous formatting into account (see [Pragmatism](#pragmatism) for exceptions).
  85
  86 Our documentation covers the current _Black_ code style, but planned changes to it are
  87 also documented. They're both worth taking a look:
  88
  89 - [The _Black_ Code Style: Current style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
  90 - [The _Black_ Code Style: Future style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)
  91
  92 Please refer to this document before submitting an issue. What seems like a bug might be
  93 intended behaviour.
  94
  95 ### Pragmatism
  96
  97 Early versions of _Black_ used to be absolutist in some respects. They took after its
  98 initial author. This was fine at the time as it made the implementation simpler and
  99 there were not many users anyway. Not many edge cases were reported. As a mature tool,
 100 _Black_ does make some exceptions to rules it otherwise holds.
 101
 102 - [The _Black_ code style: Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
 103
 104 Please refer to this document before submitting an issue just like with the document
 105 above. What seems like a bug might be intended behaviour.
 106
 107 ## Configuration
 108
 109 _Black_ is able to read project-specific default values for its command line options
 110 from a `pyproject.toml` file. This is especially useful for specifying custom
 111 `--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your
 112 project.
 113
 114 You can find more details in our documentation:
 115
 116 - [The basics: Configuration via a file](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file)
 117
 118 And if you're looking for more general configuration documentation:
 119
 120 - [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
 121
 122 **Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
 123 "No". _Black_ is all about sensible defaults. Applying those defaults will have your
 124 code in compliance with many other _Black_ formatted projects.
 125
 126 ## Used by
 127
 128 The following notable open-source projects trust _Black_ with enforcing a consistent
 129 code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
 130 Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
 131 Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro,
 132 OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
 133
 134 The following organizations use _Black_: Facebook, Dropbox, KeepTruckin, Mozilla, Quora,
 135 Duolingo, QuantumBlack, Tesla.
 136
 137 Are we missing anyone? Let us know.
 138
 139 ## Testimonials
 140
 141 **Mike Bayer**, [author of `SQLAlchemy`](https://www.sqlalchemy.org/):
 142
 143 > I can't think of any single tool in my entire programming career that has given me a
 144 > bigger productivity increase by its introduction. I can now do refactorings in about
 145 > 1% of the keystrokes that it would have taken me previously when we had no way for
 146 > code to format itself.
 147
 148 **Dusty Phillips**,
 149 [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
 150
 151 > _Black_ is opinionated so you don't have to be.
 152
 153 **Hynek Schlawack**, [creator of `attrs`](https://www.attrs.org/), core developer of
 154 Twisted and CPython:
 155
 156 > An auto-formatter that doesn't suck is all I want for Xmas!
 157
 158 **Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
 159
 160 > At least the name is good.
 161
 162 **Kenneth Reitz**, creator of [`requests`](http://python-requests.org/) and
 163 [`pipenv`](https://readthedocs.org/projects/pipenv/):
 164
 165 > This vastly improves the formatting of our code. Thanks a ton!
 166
 167 ## Show your style
 168
 169 Use the badge in your project's README.md:
 170
 171 ```md
 172 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 173 ```
 174
 175 Using the badge in README.rst:
 176
 177 ```
 178 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
 179     :target: https://github.com/psf/black
 180 ```
 181
 182 Looks like this:
 183 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 184
 185 ## License
 186
 187 MIT
 188
 189 ## Contributing
 190
 191 Welcome! Happy to see you willing to make the project better. You can get started by
 192 reading this:
 193
 194 - [Contributing: The basics](https://black.readthedocs.io/en/latest/contributing/the_basics.html)
 195
 196 You can also take a look at the rest of the contributing docs or talk with the
 197 developers:
 198
 199 - [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html)
 200 - [Chat on Discord](https://discord.gg/RtVdv86PrH)
 201
 202 ## Change log
 203
 204 The log has become rather long. It moved to its own file.
 205
 206 See [CHANGES](https://black.readthedocs.io/en/latest/change_log.html).
 207
 208 ## Authors
 209
 210 The author list is quite long nowadays, so it lives in its own file.
 211
 212 See [AUTHORS.md](./AUTHORS.md)
 213
 214 ## Code of Conduct
 215
 216 Everyone participating in the _Black_ project, and in particular in the issue tracker,
 217 pull requests, and social media activity, is expected to treat other people with respect
 218 and more generally to follow the guidelines articulated in the
 219 [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
 220
 221 At the same time, humor is encouraged. In fact, basic familiarity with Monty Python's
 222 Flying Circus is expected. We are not savages.
 223
 224 And if you _really_ need to slap somebody, do it with a fish while dancing.