X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/de860cccf1af23bc8c4f04474fa26bdf04f6e350..4da0851809e024760d3861ff43309125de34157a:/README.md diff --git a/README.md b/README.md index 56321c7..b259302 100644 --- a/README.md +++ b/README.md @@ -1,201 +1,163 @@ -# black +[![Black Logo](https://raw.githubusercontent.com/psf/black/main/docs/_static/logo2-readme.png)](https://black.readthedocs.io/en/stable/) -[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black) +

The Uncompromising Code Formatter

-> Any color you like. +

+Actions Status +Documentation Status +Coverage Status +License: MIT +PyPI +Downloads +conda-forge +Code style: black +

+> “Any color you like.” -*Black* is the uncompromising Python code formatter. By using it, you -agree to cease control over minutiae of hand-formatting. In return, -*Black* gives you speed, determinism, and freedom from `pycodestyle` -nagging about formatting. You will save time and mental energy for -more important matters. +_Black_ is the uncompromising Python code formatter. By using it, you agree to cede +control over minutiae of hand-formatting. In return, _Black_ gives you speed, +determinism, and freedom from `pycodestyle` nagging about formatting. You will save time +and mental energy for more important matters. -Blackened code looks the same regardless of the project you're reading. -Formatting becomes transparent after a while and you can focus on the -content instead. +Blackened code looks the same regardless of the project you're reading. Formatting +becomes transparent after a while and you can focus on the content instead. -*Black* makes code review faster by producing the smallest diffs -possible. +_Black_ makes code review faster by producing the smallest diffs possible. +Try it out now using the [Black Playground](https://black.vercel.app). Watch the +[PyCon 2019 talk](https://youtu.be/esZLCuWs_2Y) to learn more. -## NOTE: This is an early pre-release +--- -*Black* can already successfully format itself and the standard library. -It also sports a decent test suite. However, it is still very new. -Things will probably be wonky for a while. This is made explicit by the -"Alpha" trove classifier, as well as by the "a" 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**. +**[Read the documentation on ReadTheDocs!](https://black.readthedocs.io/en/stable)** -Also, as a temporary safety measure, *Black* will check that the -reformatted code still produces a valid AST that is equivalent to the -original. This slows it down. If you're feeling confident, use -``--fast``. +--- +## Installation and usage -## Usage +### Installation -*Black* can be installed by running `pip install black`. +_Black_ can be installed by running `pip install black`. It requires Python 3.7+ to 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+https://github.com/psf/black` + +### Usage + +To get started right away with sensible defaults: + +```sh +black {source_file_or_directory} ``` -black [OPTIONS] [SRC]... - -Options: - -l, --line-length INTEGER Where to wrap around. [default: 88] - --fast / --safe If --fast given, skip temporary sanity checks. - [default: --safe] - --version Show the version and exit. - --help Show this message and exit. + +You can run _Black_ as a package if running it as a script doesn't work: + +```sh +python -m black {source_file_or_directory} ``` +Further information can be found in our docs: -## The philosophy behind *Black* +- [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html) -*Black* reformats entire files in place. It is not configurable. It -doesn't take previous formatting into account. It doesn't reformat -blocks that start with `# fmt: off` and end with `# fmt: on`. It also -recognizes [YAPF](https://github.com/google/yapf)'s block comments to -the same effect, as a courtesy for straddling code. +_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. 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 +original (see the +[Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting) +section for details). If you're feeling confident, use `--fast`. -### How *Black* formats files +## The _Black_ code style -*Black* ignores previous formatting and applies uniform horizontal -and vertical whitespace to your code. The rules for horizontal -whitespace are pretty obvious and can be summarized as: do whatever -makes `pycodestyle` happy. +_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](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism) +for exceptions). -As for vertical whitespace, *Black* tries to render one full expression -or simple statement per line. If this fits the allotted line length, -great. -```py3 -# in: -l = [1, - 2, - 3, -] +Our documentation covers the current _Black_ code style, but planned changes to it are +also documented. They're both worth taking a look: -# out: -l = [1, 2, 3] -``` +- [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) -If not, *Black* will look at the contents of the first outer matching -brackets and put that in a separate indented line. -```py3 -# in: -l = [[n for n in list_bosses()], [n for n in list_employees()]] +Changes to the _Black_ code style are bound by the Stability Policy: -# out: -l = [ - [n for n in list_bosses()], [n for n in list_employees()] -] -``` +- [The _Black_ Code Style: Stability Policy](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy) -If that still doesn't fit the bill, it will decompose the internal -expression further using the same rule, indenting matching brackets -every time. If the contents of the matching brackets pair are -comma-separated (like an argument list, or a dict literal, and so on) -then *Black* will first try to keep them on the same line with the -matching brackets. If that doesn't work, it will put all of them in -separate lines. -```py3 -# in: -def very_important_function(template: str, *variables, *, file: os.PathLike, debug: bool = False): - """Applies `variables` to the `template` and writes to `file`.""" - with open(file, 'w') as f: - ... - -# out: -def very_important_function( - template: str, - *variables, - *, - file: os.PathLike, - debug: bool = False, -): - """Applies `variables` to the `template` and writes to `file`.""" - with open(file, 'w') as f: - ... -``` +Please refer to this document before submitting an issue. What seems like a bug might be +intended behaviour. -You might have noticed that closing brackets are always dedented and -that a trailing comma is always added. Such formatting produces smaller -diffs; when you add or remove an element, it's always just one line. -Also, having the closing bracket dedented provides a clear delimiter -between two distinct sections of the code that otherwise share the same -indentation level (like the arguments list and the docstring in the -example above). - -Unnecessary trailing commas are removed if an expression fits in one -line. This makes it 1% more likely that your line won't exceed the -allotted line length limit. - -*Black* avoids spurious vertical whitespace. This is in the spirit of -PEP 8 which says that in-function vertical whitespace should only be -used sparingly. One exception is control flow statements: *Black* will -always emit an extra empty line after ``return``, ``raise``, ``break``, -``continue``, and ``yield``. This is to make changes in control flow -more prominent to readers of your code. - -That's it. The rest of the whitespace formatting rules follow PEP 8 and -are designed to keep `pycodestyle` quiet. - - -### Line length - -You probably noticed the peculiar default line length. *Black* defaults -to 88 characters per line, which happens to be 10% over 80. This number -was found to produce significantly shorter files than sticking with 80 -(the most popular), or even 79 (used by the standard library). In -general, [90-ish seems like the wise choice](https://youtu.be/wf-BqAjZb8M?t=260). - -If you're paid by the line of code you write, you can pass -`--line-length` with a lower number. *Black* will try to respect that. -However, sometimes it won't be able to without breaking other rules. In -those rare cases, auto-formatted code will exceed your allotted limit. - -You can also increase it, but remember that people with sight disabilities -find it harder to work with line lengths exceeding 100 characters. -It also adversely affects side-by-side diff review on typical screen -resolutions. Long lines also make it harder to present code neatly -in documentation or talk slides. - -If you're using Flake8, you can bump `max-line-length` to 88 and forget -about it. Alternatively, use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s -B950 warning instead of E501 and keep the max line length at 80 which -you are probably already using. You'd do it like this: -```ini -[flake8] -max-line-length = 80 -... -select = C,E,F,W,B,B950 -ignore = E501 -``` +### Pragmatism + +Early versions of _Black_ used to be absolutist in some respects. They took after its +initial author. This was fine at the time as it made the implementation simpler and +there were not many users anyway. Not many edge cases were reported. As a mature tool, +_Black_ does make some exceptions to rules it otherwise holds. + +- [The _Black_ code style: Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism) + +Please refer to this document before submitting an issue just like with the document +above. What seems like a bug might be intended behaviour. + +## Configuration + +_Black_ is able to read project-specific default values for its command line options +from a `pyproject.toml` file. This is especially useful for specifying custom +`--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your +project. + +You can find more details in our documentation: -You'll find *Black*'s own .flake8 config file is configured like this. -If you're curious about the reasoning behind B950, Bugbear's documentation -explains it. The tl;dr is "it's like highway speed limits, we won't -bother you if you overdo it by a few km/h". +- [The basics: Configuration via a file](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file) +And if you're looking for more general configuration documentation: -### Editor integration +- [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html) -There is currently no integration with any text editors. Vim and -Atom/Nuclide integration is planned by the author, others will require -external contributions. +**Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is +"No". _Black_ is all about sensible defaults. Applying those defaults will have your +code in compliance with many other _Black_ formatted projects. -Patches welcome! ✨ 🍰 ✨ +## Used by +The following notable open-source projects trust _Black_ with enforcing a consistent +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. + +Are we missing anyone? Let us know. ## Testimonials -**Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips): +**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): -> Black is opinionated so you don't have to be. +> _Black_ is opinionated so you don't have to be. -**Hynek Schlawack**, [creator of `attrs`](http://www.attrs.org/), core -developer of Twisted and CPython: +**Hynek Schlawack**, [creator of `attrs`](https://www.attrs.org/), core developer of +Twisted and CPython: > An auto-formatter that doesn't suck is all I want for Xmas! @@ -203,63 +165,66 @@ developer of Twisted and CPython: > At least the name is good. -**Kenneth Reitz**, creator of [`requests`](http://python-requests.org/) -and [`pipenv`](https://docs.pipenv.org/): +**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! +## Show your style -## Tests +Use the badge in your project's README.md: -Just run: - -``` -python setup.py test +```md +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) ``` -## This tool requires Python 3.6.0+ to run +Using the badge in README.rst: -But you can reformat Python 2 code with it, too. *Black* is able to parse -all of the new syntax supported on Python 3.6 but also *effectively all* -the Python 2 syntax at the same time, as long as you're not using print -statements. - -By making the code exclusively Python 3.6+, I'm able to focus on the -quality of the formatting and re-use all the nice features of the new -releases (check out [pathlib](docs.python.org/3/library/pathlib.html) or -f-strings) instead of wasting cycles on Unicode compatibility, and so on. +``` +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/psf/black +``` +Looks like this: +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) ## License MIT - ## Contributing -In terms of inspiration, *Black* is about as configurable as *gofmt* and -*rustfmt* are. This is deliberate. +Welcome! Happy to see you willing to make the project better. You can get started by +reading this: -Bug reports and fixes are always welcome! However, before you suggest a -new feature or configuration knob, ask yourself why you want it. If it -enables better integration with some workflow, fixes an inconsistency, -speeds things up, and so on - go for it! On the other hand, if your -answer is "because I don't like a particular formatting" then you're not -ready to embrace *Black* yet. Such changes are unlikely to get accepted. -You can still try but prepare to be disappointed. +- [Contributing: The basics](https://black.readthedocs.io/en/latest/contributing/the_basics.html) +You can also take a look at the rest of the contributing docs or talk with the +developers: -## Change Log +- [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html) +- [Chat on Discord](https://discord.gg/RtVdv86PrH) -### 18.3a0 +## Change log -* first published version, Happy 🍰 Day 2018! +The log has become rather long. It moved to its own file. -* alpha quality +See [CHANGES](https://black.readthedocs.io/en/latest/change_log.html). -* date-versioned (see: https://calver.org/) +## Authors +The author list is quite long nowadays, so it lives in its own file. -## Authors +See [AUTHORS.md](./AUTHORS.md) + +## Code of Conduct + +Everyone participating in the _Black_ project, and in particular in the issue tracker, +pull requests, and social media activity, is expected to treat other people with respect +and more generally to follow the guidelines articulated in the +[Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/). + +At the same time, humor is encouraged. In fact, basic familiarity with Monty Python's +Flying Circus is expected. We are not savages. -Glued together by [Łukasz Langa](mailto:lukasz@langa.pl). +And if you _really_ need to slap somebody, do it with a fish while dancing.