X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/62bfbd6a63dcac2f6f31eb014f69397c9eb967d2..6debce63bc2429b1680f8838592f2e56e3df6b27:/README.md
diff --git a/README.md b/README.md
index ceccbb7..624d4d7 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,12 @@
-
+
The Uncompromising Code Formatter
-
-
-
+
+
@@ -40,12 +39,12 @@ Try it out now using the [Black Playground](https://black.vercel.app). Watch the
### Installation
_Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
-run. If you want to format Python 2 code as well, install with
-`pip install black[python2]`.
+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+git://github.com/psf/black`
+`pip install git+https://github.com/psf/black`
### Usage
@@ -65,16 +64,13 @@ Further information can be found in our docs:
- [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
-### NOTE: This is a beta product
-
_Black_ is already [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, and our own auto formatting and parallel Continuous Integration runner. However,
-_Black_ is still beta. Things will probably be wonky for a while. This is made explicit
-by the "Beta" trove classifier, as well as by the "b" in the version number. What this
-means for you is that **until the formatter becomes stable, you should expect some
-formatting to change in the future**. That being said, no drastic stylistic changes are
-planned, mostly responses to bug reports.
+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 to 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](https://black.readthedocs.io/en/stable/the_black_code_style/index.html).
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
@@ -86,7 +82,9 @@ section for details). If you're feeling confident, use `--fast`.
_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](#pragmatism) for exceptions).
+take previous formatting into account (see
+[Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
+for exceptions).
Our documentation covers the current _Black_ code style, but planned changes to it are
also documented. They're both worth taking a look:
@@ -94,6 +92,10 @@ also documented. They're both worth taking a look:
- [The _Black_ Code Style: Current style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
- [The _Black_ Code Style: Future style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)
+Changes to the _Black_ code style are bound by the Stability Policy:
+
+- [The _Black_ Code Style: Stability Policy](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy)
+
Please refer to this document before submitting an issue. What seems like a bug might be
intended behaviour.
@@ -131,16 +133,25 @@ code in compliance with many other _Black_ formatted projects.
## Used by
The following notable open-source projects trust _Black_ with enforcing a consistent
-code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
-Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
-every Datadog Agent Integration, Home Assistant, Zulip.
+code style: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs,
+SQLAlchemy, Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv),
+pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assistant,
+Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
-The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora.
+The following organizations use _Black_: Facebook, Dropbox, KeepTruckin, Mozilla, Quora,
+Duolingo, QuantumBlack, Tesla.
Are we missing anyone? Let us know.
## 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):
@@ -155,8 +166,8 @@ Twisted and CPython:
> At least the name is good.
-**Kenneth Reitz**, creator of [`requests`](http://python-requests.org/) and
-[`pipenv`](https://readthedocs.org/projects/pipenv/):
+**Kenneth Reitz**, creator of [`requests`](https://requests.readthedocs.io/en/latest/)
+and [`pipenv`](https://readthedocs.org/projects/pipenv/):
> This vastly improves the formatting of our code. Thanks a ton!
@@ -193,7 +204,7 @@ You can also take a look at the rest of the contributing docs or talk with the
developers:
- [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html)
-- [IRC channel on Freenode](https://webchat.freenode.net/?channels=%23blackformatter)
+- [Chat on Discord](https://discord.gg/RtVdv86PrH)
## Change log