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