X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/db2715441a391f218863493aa20027f802ab0c7b..411ed778d53244a9d0b9c1913266fd03aee89123:/README.md diff --git a/README.md b/README.md index 2adf60a..624d4d7 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,6 @@

Actions Status -Actions Status Documentation Status Coverage Status License: MIT @@ -40,13 +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]`. If you want to format Jupyter Notebooks, install with -`pip install black[jupyter]`. +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 @@ -66,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 @@ -87,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: @@ -95,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. @@ -132,10 +133,10 @@ 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, -Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro, and -many more. +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, KeepTruckin, Mozilla, Quora, Duolingo, QuantumBlack, Tesla. @@ -165,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!