README.md

   1 ![Black Logo](https://raw.githubusercontent.com/psf/black/master/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=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=master"></a>
  10 <a href="https://github.com/psf/black/blob/master/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 Python 2 code as well, install with
  44 `pip install black[python2]`.
  45
  46 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
  47
  48 `pip install git+git://github.com/psf/black`
  49
  50 ### Usage
  51
  52 To get started right away with sensible defaults:
  53
  54 ```sh
  55 black {source_file_or_directory}
  56 ```
  57
  58 You can run _Black_ as a package if running it as a script doesn't work:
  59
  60 ```sh
  61 python -m black {source_file_or_directory}
  62 ```
  63
  64 Further information can be found in our docs:
  65
  66 - [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
  67
  68 ### NOTE: This is a beta product
  69
  70 _Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
  71 projects, small and big. Black has a comprehensive test suite, with efficient parallel
  72 tests, and our own auto formatting and parallel Continuous Integration runner. However,
  73 _Black_ is still beta. Things will probably be wonky for a while. This is made explicit
  74 by the "Beta" trove classifier, as well as by the "b" in the version number. What this
  75 means for you is that **until the formatter becomes stable, you should expect some
  76 formatting to change in the future**. That being said, no drastic stylistic changes are
  77 planned, mostly responses to bug reports.
  78
  79 Also, as a safety measure which slows down processing, _Black_ will check that the
  80 reformatted code still produces a valid AST that is effectively equivalent to the
  81 original (see the
  82 [Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting)
  83 section for details). If you're feeling confident, use `--fast`.
  84
  85 ## The _Black_ code style
  86
  87 _Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in
  88 place. Style configuration options are deliberately limited and rarely added. It doesn't
  89 take previous formatting into account (see [Pragmatism](#pragmatism) for exceptions).
  90
  91 Our documentation covers the current _Black_ code style, but planned changes to it are
  92 also documented. They're both worth taking a look:
  93
  94 - [The _Black_ Code Style: Current style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
  95 - [The _Black_ Code Style: Future style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)
  96
  97 Please refer to this document before submitting an issue. What seems like a bug might be
  98 intended behaviour.
  99
 100 ### Pragmatism
 101
 102 Early versions of _Black_ used to be absolutist in some respects. They took after its
 103 initial author. This was fine at the time as it made the implementation simpler and
 104 there were not many users anyway. Not many edge cases were reported. As a mature tool,
 105 _Black_ does make some exceptions to rules it otherwise holds.
 106
 107 - [The _Black_ code style: Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
 108
 109 Please refer to this document before submitting an issue just like with the document
 110 above. What seems like a bug might be intended behaviour.
 111
 112 ## Configuration
 113
 114 _Black_ is able to read project-specific default values for its command line options
 115 from a `pyproject.toml` file. This is especially useful for specifying custom
 116 `--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your
 117 project.
 118
 119 You can find more details in our documentation:
 120
 121 - [The basics: Configuration via a file](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file)
 122
 123 And if you're looking for more general configuration documentation:
 124
 125 - [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
 126
 127 **Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
 128 "No". _Black_ is all about sensible defaults. Applying those defaults will have your
 129 code in compliance with many other _Black_ formatted projects.
 130
 131 ## Used by
 132
 133 The following notable open-source projects trust _Black_ with enforcing a consistent
 134 code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
 135 Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
 136 every Datadog Agent Integration, Home Assistant, Zulip.
 137
 138 The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora.
 139
 140 Are we missing anyone? Let us know.
 141
 142 ## Testimonials
 143
 144 **Dusty Phillips**,
 145 [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
 146
 147 > _Black_ is opinionated so you don't have to be.
 148
 149 **Hynek Schlawack**, [creator of `attrs`](https://www.attrs.org/), core developer of
 150 Twisted and CPython:
 151
 152 > An auto-formatter that doesn't suck is all I want for Xmas!
 153
 154 **Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
 155
 156 > At least the name is good.
 157
 158 **Kenneth Reitz**, creator of [`requests`](http://python-requests.org/) and
 159 [`pipenv`](https://readthedocs.org/projects/pipenv/):
 160
 161 > This vastly improves the formatting of our code. Thanks a ton!
 162
 163 ## Show your style
 164
 165 Use the badge in your project's README.md:
 166
 167 ```md
 168 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 169 ```
 170
 171 Using the badge in README.rst:
 172
 173 ```
 174 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
 175     :target: https://github.com/psf/black
 176 ```
 177
 178 Looks like this:
 179 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 180
 181 ## License
 182
 183 MIT
 184
 185 ## Contributing
 186
 187 Welcome! Happy to see you willing to make the project better. You can get started by
 188 reading this:
 189
 190 - [Contributing: The basics](https://black.readthedocs.io/en/latest/contributing/the_basics.html)
 191
 192 You can also take a look at the rest of the contributing docs or talk with the
 193 developers:
 194
 195 - [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html)
 196 - [IRC channel on Freenode](https://webchat.freenode.net/?channels=%23blackformatter)
 197
 198 ## Change log
 199
 200 The log has become rather long. It moved to its own file.
 201
 202 See [CHANGES](https://black.readthedocs.io/en/latest/change_log.html).
 203
 204 ## Authors
 205
 206 The author list is quite long nowadays, so it lives in its own file.
 207
 208 See [AUTHORS.md](./AUTHORS.md)
 209
 210 ## Code of Conduct
 211
 212 Everyone participating in the _Black_ project, and in particular in the issue tracker,
 213 pull requests, and social media activity, is expected to treat other people with respect
 214 and more generally to follow the guidelines articulated in the
 215 [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
 216
 217 At the same time, humor is encouraged. In fact, basic familiarity with Monty Python's
 218 Flying Circus is expected. We are not savages.
 219
 220 And if you _really_ need to slap somebody, do it with a fish while dancing.