]> git.madduck.net Git - etc/vim.git/blob - README.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

e5a3036fb7bac35fcee8eecb091be3454c9dd3ab
[etc/vim.git] / README.md
1 ![Black Logo](https://raw.githubusercontent.com/ambv/black/master/docs/_static/logo2-readme.png)
2 <h2 align="center">The Uncompromising Code Formatter</h2>
3
4 <p align="center">
5 <a href="https://travis-ci.org/ambv/black"><img alt="Build Status" src="https://travis-ci.org/ambv/black.svg?branch=master"></a>
6 <a href="http://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="http://readthedocs.org/projects/black/badge/?version=stable"></a>
7 <a href="https://coveralls.io/github/ambv/black?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/ambv/black/badge.svg?branch=master"></a>
8 <a href="https://github.com/ambv/black/blob/master/LICENSE"><img alt="License: MIT" src="http://black.readthedocs.io/en/stable/_static/license.svg"></a>
9 <a href="https://pypi.python.org/pypi/black"><img alt="PyPI" src="http://black.readthedocs.io/en/stable/_static/pypi.svg"></a>
10 <a href="https://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
11 </p>
12
13 > “Any color you like.”
14
15
16 *Black* is the uncompromising Python code formatter.  By using it, you
17 agree to cede control over minutiae of hand-formatting.  In return,
18 *Black* gives you speed, determinism, and freedom from `pycodestyle`
19 nagging about formatting.  You will save time and mental energy for
20 more important matters.
21
22 Blackened code looks the same regardless of the project you're reading.
23 Formatting becomes transparent after a while and you can focus on the
24 content instead.
25
26 *Black* makes code review faster by producing the smallest diffs
27 possible.
28
29 ---
30
31 *Contents:* **[Installation and usage](#installation-and-usage)** |
32 **[The *Black* code style](#the-black-code-style)** |
33 **[Editor integration](#editor-integration)** |
34 **[Version control integration](#version-control-integration)** |
35 **[Ignoring unmodified files](#ignoring-unmodified-files)** |
36 **[Testimonials](#testimonials)** |
37 **[Show your style](#show-your-style)** |
38 **[License](#license)** |
39 **[Contributing](#contributing-to-black)** |
40 **[Change Log](#change-log)** |
41 **[Authors](#authors)**
42
43 ---
44
45 ## Installation and usage
46
47 ### Installation
48
49 *Black* can be installed by running `pip install black`.  It requires
50 Python 3.6.0+ to run but you can reformat Python 2 code with it, too.
51
52
53 ### Usage
54
55 To get started right away with sensible defaults:
56
57 ```
58 black {source_file_or_directory}
59 ```
60
61 ### Command line options
62
63 Black doesn't provide many options.  You can list them by running
64 `black --help`:
65
66 ```text
67 black [OPTIONS] [SRC]...
68
69 Options:
70   -l, --line-length INTEGER   Where to wrap around.  [default: 88]
71   --check                     Don't write the files back, just return the
72                               status.  Return code 0 means nothing would
73                               change.  Return code 1 means some files would be
74                               reformatted.  Return code 123 means there was an
75                               internal error.
76   --diff                      Don't write the files back, just output a diff
77                               for each file on stdout.
78   --fast / --safe             If --fast given, skip temporary sanity checks.
79                               [default: --safe]
80   -q, --quiet                 Don't emit non-error messages to stderr. Errors
81                               are still emitted, silence those with
82                               2>/dev/null.
83    --pyi                      Consider all input files typing stubs regardless
84                               of file extension (useful when piping source on
85                               standard input).
86   --py36                      Allow using Python 3.6-only syntax on all input
87                               files.  This will put trailing commas in function
88                               signatures and calls also after *args and
89                               **kwargs.  [default: per-file auto-detection]
90   --version                   Show the version and exit.
91   --help                      Show this message and exit.
92 ```
93
94 *Black* is a well-behaved Unix-style command-line tool:
95 * it does nothing if no sources are passed to it;
96 * it will read from standard input and write to standard output if `-`
97   is used as the filename;
98 * it only outputs messages to users on standard error;
99 * exits with code 0 unless an internal error occurred (or `--check` was
100   used).
101
102
103 ### NOTE: This is a beta product
104
105 *Black* is already successfully used by several projects, small and big.
106 It also sports a decent test suite.  However, it is still very new.
107 Things will probably be wonky for a while. This is made explicit by the
108 "Beta" trove classifier, as well as by the "b" in the version number.
109 What this means for you is that **until the formatter becomes stable,
110 you should expect some formatting to change in the future**.  That being
111 said, no drastic stylistic changes are planned, mostly responses to bug
112 reports.
113
114 Also, as a temporary safety measure, *Black* will check that the
115 reformatted code still produces a valid AST that is equivalent to the
116 original.  This slows it down.  If you're feeling confident, use
117 ``--fast``.
118
119
120 ## The *Black* code style
121
122 *Black* reformats entire files in place.  It is not configurable.  It
123 doesn't take previous formatting into account.  It doesn't reformat
124 blocks that start with `# fmt: off` and end with `# fmt: on`.  It also
125 recognizes [YAPF](https://github.com/google/yapf)'s block comments to
126 the same effect, as a courtesy for straddling code.
127
128
129 ### How *Black* wraps lines
130
131 *Black* ignores previous formatting and applies uniform horizontal
132 and vertical whitespace to your code.  The rules for horizontal
133 whitespace can be summarized as: do whatever makes `pycodestyle` happy.
134 The coding style used by *Black* can be viewed as a strict subset of
135 PEP 8.
136
137 As for vertical whitespace, *Black* tries to render one full expression
138 or simple statement per line.  If this fits the allotted line length,
139 great.
140 ```py3
141 # in:
142
143 l = [1,
144      2,
145      3,
146 ]
147
148 # out:
149
150 l = [1, 2, 3]
151 ```
152
153 If not, *Black* will look at the contents of the first outer matching
154 brackets and put that in a separate indented line.
155 ```py3
156 # in:
157
158 TracebackException.from_exception(exc, limit, lookup_lines, capture_locals)
159
160 # out:
161
162 TracebackException.from_exception(
163     exc, limit, lookup_lines, capture_locals
164 )
165 ```
166
167 If that still doesn't fit the bill, it will decompose the internal
168 expression further using the same rule, indenting matching brackets
169 every time.  If the contents of the matching brackets pair are
170 comma-separated (like an argument list, or a dict literal, and so on)
171 then *Black* will first try to keep them on the same line with the
172 matching brackets.  If that doesn't work, it will put all of them in
173 separate lines.
174 ```py3
175 # in:
176
177 def very_important_function(template: str, *variables, file: os.PathLike, debug: bool = False):
178     """Applies `variables` to the `template` and writes to `file`."""
179     with open(file, 'w') as f:
180         ...
181
182 # out:
183
184 def very_important_function(
185     template: str,
186     *variables,
187     file: os.PathLike,
188     debug: bool = False,
189 ):
190     """Applies `variables` to the `template` and writes to `file`."""
191     with open(file, "w") as f:
192         ...
193 ```
194
195 You might have noticed that closing brackets are always dedented and
196 that a trailing comma is always added.  Such formatting produces smaller
197 diffs; when you add or remove an element, it's always just one line.
198 Also, having the closing bracket dedented provides a clear delimiter
199 between two distinct sections of the code that otherwise share the same
200 indentation level (like the arguments list and the docstring in the
201 example above).
202
203 If a data structure literal (tuple, list, set, dict) or a line of "from"
204 imports cannot fit in the allotted length, it's always split into one
205 element per line.  This minimizes diffs as well as enables readers of
206 code to find which commit introduced a particular entry.  This also
207 makes *Black* compatible with [isort](https://pypi.org/p/isort/).
208
209 If you do wish to use *Black* alongside `isort`, you can pass the following
210 command-line arguments to ensure compatible behaviour:
211 ```
212 $ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --line-width=88 [ file.py ]
213 ```
214 Or use the equivalent directives in your isort config:
215 ```
216 multi_line_output=3
217 include_trailing_comma=True
218 force_grid_wrap=0
219 line_length=88
220 ```
221
222 ### Line length
223
224 You probably noticed the peculiar default line length.  *Black* defaults
225 to 88 characters per line, which happens to be 10% over 80.  This number
226 was found to produce significantly shorter files than sticking with 80
227 (the most popular), or even 79 (used by the standard library).  In
228 general, [90-ish seems like the wise choice](https://youtu.be/wf-BqAjZb8M?t=260).
229
230 If you're paid by the line of code you write, you can pass
231 `--line-length` with a lower number.  *Black* will try to respect that.
232 However, sometimes it won't be able to without breaking other rules.  In
233 those rare cases, auto-formatted code will exceed your allotted limit.
234
235 You can also increase it, but remember that people with sight disabilities
236 find it harder to work with line lengths exceeding 100 characters.
237 It also adversely affects side-by-side diff review  on typical screen
238 resolutions.  Long lines also make it harder to present code neatly
239 in documentation or talk slides.
240
241 If you're using Flake8, you can bump `max-line-length` to 88 and forget
242 about it.  Alternatively, use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s
243 B950 warning instead of E501 and keep the max line length at 80 which
244 you are probably already using.  You'd do it like this:
245 ```ini
246 [flake8]
247 max-line-length = 80
248 ...
249 select = C,E,F,W,B,B950
250 ignore = E501
251 ```
252
253 You'll find *Black*'s own .flake8 config file is configured like this.
254 If you're curious about the reasoning behind B950, Bugbear's documentation
255 explains it.  The tl;dr is "it's like highway speed limits, we won't
256 bother you if you overdo it by a few km/h".
257
258
259 ### Empty lines
260
261 *Black* avoids spurious vertical whitespace.  This is in the spirit of
262 PEP 8 which says that in-function vertical whitespace should only be
263 used sparingly.
264
265 *Black* will allow single empty lines inside functions, and single and
266 double empty lines on module level left by the original editors, except
267 when they're within parenthesized expressions.  Since such expressions
268 are always reformatted to fit minimal space, this whitespace is lost.
269
270 It will also insert proper spacing before and after function definitions.
271 It's one line before and after inner functions and two lines before and
272 after module-level functions.  *Black* will not put empty lines between
273 function/class definitions and standalone comments that immediately precede
274 the given function/class.
275
276
277 ### Trailing commas
278
279 *Black* will add trailing commas to expressions that are split
280 by comma where each element is on its own line.  This includes function
281 signatures.
282
283 Unnecessary trailing commas are removed if an expression fits in one
284 line.  This makes it 1% more likely that your line won't exceed the
285 allotted line length limit.  Moreover, in this scenario, if you added
286 another argument to your call, you'd probably fit it in the same line
287 anyway.  That doesn't make diffs any larger.
288
289 One exception to removing trailing commas is tuple expressions with
290 just one element.  In this case *Black* won't touch the single trailing
291 comma as this would unexpectedly change the underlying data type.  Note
292 that this is also the case when commas are used while indexing.  This is
293 a tuple in disguise: ```numpy_array[3, ]```.
294
295 One exception to adding trailing commas is function signatures
296 containing `*`, `*args`, or `**kwargs`.  In this case a trailing comma
297 is only safe to use on Python 3.6.  *Black* will detect if your file is
298 already 3.6+ only and use trailing commas in this situation.  If you
299 wonder how it knows, it looks for f-strings and existing use of trailing
300 commas in function signatures that have stars in them.  In other words,
301 if you'd like a trailing comma in this situation and *Black* didn't
302 recognize it was safe to do so, put it there manually and *Black* will
303 keep it.
304
305
306 ### Strings
307
308 *Black* prefers double quotes (`"` and `"""`) over single quotes (`'`
309 and `'''`).  It will replace the latter with the former as long as it
310 does not result in more backslash escapes than before.
311
312 *Black* also standardizes string prefixes, making them always lowercase.
313 On top of that, if your code is already Python 3.6+ only or it's using
314 the `unicode_literals` future import, *Black* will remove `u` from the
315 string prefix as it is meaningless in those scenarios.
316
317 The main reason to standardize on a single form of quotes is aesthetics.
318 Having one kind of quotes everywhere reduces reader distraction.
319 It will also enable a future version of *Black* to merge consecutive
320 string literals that ended up on the same line (see
321 [#26](https://github.com/ambv/black/issues/26) for details).
322
323 Why settle on double quotes?  They anticipate apostrophes in English
324 text.  They match the docstring standard described in PEP 257.  An
325 empty string in double quotes (`""`) is impossible to confuse with
326 a one double-quote regardless of fonts and syntax highlighting used.
327 On top of this, double quotes for strings are consistent with C which
328 Python interacts a lot with.
329
330 On certain keyboard layouts like US English, typing single quotes is
331 a bit easier than double quotes.  The latter requires use of the Shift
332 key.  My recommendation here is to keep using whatever is faster to type
333 and let *Black* handle the transformation.
334
335
336 ### Line breaks & binary operators
337
338 *Black* will break a line before a binary operator when splitting a block
339 of code over multiple lines. This is so that *Black* is compliant with the
340 recent changes in the [PEP 8](https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator)
341 style guide, which emphasizes that this approach improves readability.
342
343 This behaviour may raise ``W503 line break before binary operator`` warnings in
344 style guide enforcement tools like Flake8. Since ``W503`` is not PEP 8 compliant,
345 you should tell Flake8 to ignore these warnings.
346
347
348 ### Slices
349
350 PEP 8 [recommends](https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements)
351 to treat ``:`` in slices as a binary operator with the lowest priority, and to
352 leave an equal amount of space on either side, except if a parameter is omitted
353 (e.g. ``ham[1 + 1 :]``). It also states that for extended slices, both ``:``
354 operators have to have the same amount of spacing, except if a parameter is
355 omitted (``ham[1 + 1 ::]``). *Black* enforces these rules consistently.
356
357 This behaviour may raise ``E203 whitespace before ':'`` warnings in style guide
358 enforcement tools like Flake8. Since ``E203`` is not PEP 8 compliant, you should
359 tell Flake8 to ignore these warnings.
360
361
362 ### Parentheses
363
364 Some parentheses are optional in the Python grammar.  Any expression can
365 be wrapped in a pair of parentheses to form an atom.  There are a few
366 interesting cases:
367
368 - `if (...):`
369 - `while (...):`
370 - `for (...) in (...):`
371 - `assert (...), (...)`
372 - `from X import (...)`
373 - assignments like:
374   - `target = (...)`
375   - `target: type = (...)`
376   - `some, *un, packing = (...)`
377   - `augmented += (...)`
378
379 In those cases, parentheses are removed when the entire statement fits
380 in one line, or if the inner expression doesn't have any delimiters to
381 further split on.  If there is only a single delimiter and the expression
382 starts or ends with a bracket, the parenthesis can also be successfully
383 omitted since the existing bracket pair will organize the expression
384 neatly anyway.  Otherwise, the parentheses are added.
385
386 Please note that *Black* does not add or remove any additional nested
387 parentheses that you might want to have for clarity or further
388 code organization.  For example those parentheses are not going to be
389 removed:
390 ```py3
391 return not (this or that)
392 decision = (maybe.this() and values > 0) or (maybe.that() and values < 0)
393 ```
394
395
396 ### Call chains
397
398 Some popular APIs, like ORMs, use call chaining.  This API style is known
399 as a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface).
400 *Black* formats those by treating dots that follow a call or an indexing
401 operation like a very low priority delimiter.  It's easier to show the
402 behavior than to explain it.  Look at the example:
403 ```py3
404 def example(session):
405     result = (
406         session.query(models.Customer.id)
407         .filter(
408             models.Customer.account_id == account_id,
409             models.Customer.email == email_address,
410         )
411         .order_by(models.Customer.id.asc())
412         .all()
413     )
414 ```
415
416
417 ### Typing stub files
418
419 PEP 484 describes the syntax for type hints in Python.  One of the
420 use cases for typing is providing type annotations for modules which
421 cannot contain them directly (they might be written in C, or they might
422 be third-party, or their implementation may be overly dynamic, and so on).
423
424 To solve this, [stub files with the `.pyi` file
425 extension](https://www.python.org/dev/peps/pep-0484/#stub-files) can be
426 used to describe typing information for an external module.  Those stub
427 files omit the implementation of classes and functions they
428 describe, instead they only contain the structure of the file (listing
429 globals, functions, and classes with their members).  The recommended
430 code style for those files is more terse than PEP 8:
431
432 * prefer `...` on the same line as the class/function signature;
433 * avoid vertical whitespace between consecutive module-level functions,
434   names, or methods and fields within a single class;
435 * use a single blank line between top-level class definitions, or none
436   if the classes are very small.
437
438 *Black* enforces the above rules.  There are additional guidelines for
439 formatting `.pyi` file that are not enforced yet but might be in
440 a future version of the formatter:
441
442 * all function bodies should be empty (contain `...` instead of the body);
443 * do not use docstrings;
444 * prefer `...` over `pass`;
445 * for arguments with a default, use `...` instead of the actual default;
446 * avoid using string literals in type annotations, stub files support
447   forward references natively (like Python 3.7 code with `from __future__
448   import annotations`);
449 * use variable annotations instead of type comments, even for stubs that
450   target older versions of Python;
451 * for arguments that default to `None`, use `Optional[]` explicitly;
452 * use `float` instead of `Union[int, float]`.
453
454
455 ## Editor integration
456
457 ### Emacs
458
459 Use [proofit404/blacken](https://github.com/proofit404/blacken).
460
461
462 ### PyCharm
463
464 1. Install `black`.
465
466 ```console
467 $ pip install black
468 ```
469
470 2. Locate your `black` installation folder.
471
472   On macOS / Linux / BSD:
473
474 ```console
475 $ which black
476 /usr/local/bin/black  # possible location
477 ```
478
479   On Windows:
480
481 ```console
482 $ where black
483 %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
484 ```
485
486 3. Open External tools in PyCharm with `File -> Settings -> Tools -> External Tools`.
487
488 4. Click the + icon to add a new external tool with the following values:
489     - Name: Black
490     - Description: Black is the uncompromising Python code formatter.
491     - Program: <install_location_from_step_2>
492     - Arguments: $FilePath$
493
494 5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
495     - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap`.
496
497
498 ### Vim
499
500 Commands and shortcuts:
501
502 * `,=` or `:Black` to format the entire file (ranges not supported);
503 * `:BlackUpgrade` to upgrade *Black* inside the virtualenv;
504 * `:BlackVersion` to get the current version of *Black* inside the
505   virtualenv.
506
507 Configuration:
508 * `g:black_fast` (defaults to `0`)
509 * `g:black_linelength` (defaults to `88`)
510 * `g:black_virtualenv` (defaults to `~/.vim/black`)
511
512 To install with [vim-plug](https://github.com/junegunn/vim-plug):
513
514 ```
515 Plug 'ambv/black',
516 ```
517
518 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
519
520 ```
521 Plugin 'ambv/black'
522 ```
523
524 or you can copy the plugin from [plugin/black.vim](https://github.com/ambv/black/tree/master/plugin/black.vim).
525 Let me know if this requires any changes to work with Vim 8's builtin
526 `packadd`, or Pathogen, and so on.
527
528 This plugin **requires Vim 7.0+ built with Python 3.6+ support**.  It
529 needs Python 3.6 to be able to run *Black* inside the Vim process which
530 is much faster than calling an external command.
531
532 On first run, the plugin creates its own virtualenv using the right
533 Python version and automatically installs *Black*. You can upgrade it later
534 by calling `:BlackUpgrade` and restarting Vim.
535
536 If you need to do anything special to make your virtualenv work and
537 install *Black* (for example you want to run a version from master),
538 create a virtualenv manually and point `g:black_virtualenv` to it.
539 The plugin will use it.
540
541 To run *Black* on save, add the following line to `.vimrc` or `init.vim`:
542
543 ```
544 autocmd BufWritePost *.py execute ':Black'
545 ```
546
547 **How to get Vim with Python 3.6?**
548 On Ubuntu 17.10 Vim comes with Python 3.6 by default.
549 On macOS with Homebrew run: `brew install vim --with-python3`.
550 When building Vim from source, use:
551 `./configure --enable-python3interp=yes`. There's many guides online how
552 to do this.
553
554
555 ### Visual Studio Code
556
557 Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
558
559
560 ### SublimeText 3
561
562 Use [sublack plugin](https://github.com/jgirardet/sublack).
563
564
565 ### IPython Notebook Magic
566
567 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
568
569
570 ### Other editors
571
572 Atom/Nuclide integration is planned by the author, others will
573 require external contributions.
574
575 Patches welcome! ✨ 🍰 ✨
576
577 Any tool that can pipe code through *Black* using its stdio mode (just
578 [use `-` as the file name](http://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
579 The formatted code will be returned on stdout (unless `--check` was
580 passed).  *Black* will still emit messages on stderr but that shouldn't
581 affect your use case.
582
583 This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
584
585
586 ## Version control integration
587
588 Use [pre-commit](https://pre-commit.com/). Once you [have it
589 installed](https://pre-commit.com/#install), add this to the
590 `.pre-commit-config.yaml` in your repository:
591 ```yaml
592 repos:
593 -   repo: https://github.com/ambv/black
594     rev: stable
595     hooks:
596     - id: black
597       args: [--line-length=88, --safe]
598       python_version: python3.6
599 ```
600 Then run `pre-commit install` and you're ready to go.
601
602 `args` in the above config is optional but shows you how you can change
603 the line length if you really need to.  If you're already using Python
604 3.7, switch the `python_version` accordingly. Finally, `stable` is a tag
605 that is pinned to the latest release on PyPI.  If you'd rather run on
606 master, this is also an option.
607
608
609 ## Ignoring unmodified files
610
611 *Black* remembers files it has already formatted, unless the `--diff` flag is used or
612 code is passed via standard input. This information is stored per-user. The exact
613 location of the file depends on the black version and the system on which black
614 is run. The file is non-portable. The standard location on common operating systems
615 is:
616
617 * Windows: `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.pickle`
618 * macOS: `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.pickle`
619 * Linux: `/home/<username>/.cache/black/<version>/cache.<line-length>.pickle`
620
621
622 ## Testimonials
623
624 **Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
625
626 > Black is opinionated so you don't have to be.
627
628 **Hynek Schlawack**, [creator of `attrs`](http://www.attrs.org/), core
629 developer of Twisted and CPython:
630
631 > An auto-formatter that doesn't suck is all I want for Xmas!
632
633 **Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
634
635 > At least the name is good.
636
637 **Kenneth Reitz**, creator of [`requests`](http://python-requests.org/)
638 and [`pipenv`](https://docs.pipenv.org/):
639
640 > This vastly improves the formatting of our code. Thanks a ton!
641
642
643 ## Show your style
644
645 Use the badge in your project's README.md:
646
647 ```markdown
648 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
649 ```
650
651 Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
652
653
654 ## License
655
656 MIT
657
658
659 ## Contributing to Black
660
661 In terms of inspiration, *Black* is about as configurable as *gofmt*.
662 This is deliberate.
663
664 Bug reports and fixes are always welcome!  However, before you suggest a
665 new feature or configuration knob, ask yourself why you want it.  If it
666 enables better integration with some workflow, fixes an inconsistency,
667 speeds things up, and so on - go for it!  On the other hand, if your
668 answer is "because I don't like a particular formatting" then you're not
669 ready to embrace *Black* yet. Such changes are unlikely to get accepted.
670 You can still try but prepare to be disappointed.
671
672 More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
673
674
675 ## Change Log
676
677 ### 18.5b1 (unreleased)
678
679 * added `--pyi` (#249)
680
681 * added `--py36` (#249)
682
683 * Python grammar pickle caches are stored with the formatting caches, making
684   *Black* work in environments where site-packages is not user-writable (#192)
685
686 * fixed invalid code produced when standalone comments were present in a trailer
687   that was omitted from line splitting on a large expression (#237)
688
689 * fixed optional parentheses being removed within `# fmt: off` sections (#224)
690
691 * fixed invalid code produced when stars in very long imports were incorrectly
692   wrapped in optional parentheses (#234)
693
694 * fixed unstable formatting when inline comments were moved around in
695   a trailer that was omitted from line splitting on a large expression
696   (#238)
697
698
699 ### 18.5b0
700
701 * call chains are now formatted according to the
702   [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface)
703   style (#67)
704
705 * data structure literals (tuples, lists, dictionaries, and sets) are
706   now also always exploded like imports when they don't fit in a single
707   line (#152)
708
709 * slices are now formatted according to PEP 8 (#178)
710
711 * parentheses are now also managed automatically on the right-hand side
712   of assignments and return statements (#140)
713
714 * math operators now use their respective priorities for delimiting multiline
715   expressions (#148)
716
717 * optional parentheses are now omitted on expressions that start or end
718   with a bracket and only contain a single operator (#177)
719
720 * empty parentheses in a class definition are now removed (#145, #180)
721
722 * string prefixes are now standardized to lowercase and `u` is removed
723   on Python 3.6+ only code and Python 2.7+ code with the `unicode_literals`
724   future import (#188, #198, #199)
725
726 * typing stub files (`.pyi`) are now formatted in a style that is consistent
727   with PEP 484 (#207, #210)
728
729 * progress when reformatting many files is now reported incrementally
730
731 * fixed trailers (content with brackets) being unnecessarily exploded
732   into their own lines after a dedented closing bracket (#119)
733
734 * fixed an invalid trailing comma sometimes left in imports (#185)
735
736 * fixed non-deterministic formatting when multiple pairs of removable parentheses
737   were used (#183)
738
739 * fixed multiline strings being unnecessarily wrapped in optional
740   parentheses in long assignments (#215)
741
742 * fixed not splitting long from-imports with only a single name
743
744 * fixed Python 3.6+ file discovery by also looking at function calls with
745   unpacking. This fixed non-deterministic formatting if trailing commas
746   where used both in function signatures with stars and function calls
747   with stars but the former would be reformatted to a single line.
748
749 * fixed crash on dealing with optional parentheses (#193)
750
751 * fixed "is", "is not", "in", and "not in" not considered operators for
752   splitting purposes
753
754 * fixed crash when dead symlinks where encountered
755
756
757 ### 18.4a4
758
759 * don't populate the cache on `--check` (#175)
760
761
762 ### 18.4a3
763
764 * added a "cache"; files already reformatted that haven't changed on disk
765   won't be reformatted again (#109)
766
767 * `--check` and `--diff` are no longer mutually exclusive (#149)
768
769 * generalized star expression handling, including double stars; this
770   fixes multiplication making expressions "unsafe" for trailing commas (#132)
771
772 * Black no longer enforces putting empty lines behind control flow statements
773   (#90)
774
775 * Black now splits imports like "Mode 3 + trailing comma" of isort (#127)
776
777 * fixed comment indentation when a standalone comment closes a block (#16, #32)
778
779 * fixed standalone comments receiving extra empty lines if immediately preceding
780   a class, def, or decorator (#56, #154)
781
782 * fixed `--diff` not showing entire path (#130)
783
784 * fixed parsing of complex expressions after star and double stars in
785   function calls (#2)
786
787 * fixed invalid splitting on comma in lambda arguments (#133)
788
789 * fixed missing splits of ternary expressions (#141)
790
791
792 ### 18.4a2
793
794 * fixed parsing of unaligned standalone comments (#99, #112)
795
796 * fixed placement of dictionary unpacking inside dictionary literals (#111)
797
798 * Vim plugin now works on Windows, too
799
800 * fixed unstable formatting when encountering unnecessarily escaped quotes
801   in a string (#120)
802
803
804 ### 18.4a1
805
806 * added `--quiet` (#78)
807
808 * added automatic parentheses management (#4)
809
810 * added [pre-commit](https://pre-commit.com) integration (#103, #104)
811
812 * fixed reporting on `--check` with multiple files (#101, #102)
813
814 * fixed removing backslash escapes from raw strings (#100, #105)
815
816
817 ### 18.4a0
818
819 * added `--diff` (#87)
820
821 * add line breaks before all delimiters, except in cases like commas, to
822   better comply with PEP 8 (#73)
823
824 * standardize string literals to use double quotes (almost) everywhere
825   (#75)
826
827 * fixed handling of standalone comments within nested bracketed
828   expressions; Black will no longer produce super long lines or put all
829   standalone comments at the end of the expression (#22)
830
831 * fixed 18.3a4 regression: don't crash and burn on empty lines with
832   trailing whitespace (#80)
833
834 * fixed 18.3a4 regression: `# yapf: disable` usage as trailing comment
835   would cause Black to not emit the rest of the file (#95)
836
837 * when CTRL+C is pressed while formatting many files, Black no longer
838   freaks out with a flurry of asyncio-related exceptions
839
840 * only allow up to two empty lines on module level and only single empty
841   lines within functions (#74)
842
843
844 ### 18.3a4
845
846 * `# fmt: off` and `# fmt: on` are implemented (#5)
847
848 * automatic detection of deprecated Python 2 forms of print statements
849   and exec statements in the formatted file (#49)
850
851 * use proper spaces for complex expressions in default values of typed
852   function arguments (#60)
853
854 * only return exit code 1 when --check is used (#50)
855
856 * don't remove single trailing commas from square bracket indexing
857   (#59)
858
859 * don't omit whitespace if the previous factor leaf wasn't a math
860   operator (#55)
861
862 * omit extra space in kwarg unpacking if it's the first argument (#46)
863
864 * omit extra space in [Sphinx auto-attribute comments](http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-autoattribute)
865   (#68)
866
867
868 ### 18.3a3
869
870 * don't remove single empty lines outside of bracketed expressions
871   (#19)
872
873 * added ability to pipe formatting from stdin to stdin (#25)
874
875 * restored ability to format code with legacy usage of `async` as
876   a name (#20, #42)
877
878 * even better handling of numpy-style array indexing (#33, again)
879
880
881 ### 18.3a2
882
883 * changed positioning of binary operators to occur at beginning of lines
884   instead of at the end, following [a recent change to PEP8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)
885   (#21)
886
887 * ignore empty bracket pairs while splitting. This avoids very weirdly
888   looking formattings (#34, #35)
889
890 * remove a trailing comma if there is a single argument to a call
891
892 * if top level functions were separated by a comment, don't put four
893   empty lines after the upper function
894
895 * fixed unstable formatting of newlines with imports
896
897 * fixed unintentional folding of post scriptum standalone comments
898   into last statement if it was a simple statement (#18, #28)
899
900 * fixed missing space in numpy-style array indexing (#33)
901
902 * fixed spurious space after star-based unary expressions (#31)
903
904
905 ### 18.3a1
906
907 * added `--check`
908
909 * only put trailing commas in function signatures and calls if it's
910   safe to do so. If the file is Python 3.6+ it's always safe, otherwise
911   only safe if there are no `*args` or `**kwargs` used in the signature
912   or call. (#8)
913
914 * fixed invalid spacing of dots in relative imports (#6, #13)
915
916 * fixed invalid splitting after comma on unpacked variables in for-loops
917   (#23)
918
919 * fixed spurious space in parenthesized set expressions (#7)
920
921 * fixed spurious space after opening parentheses and in default
922   arguments (#14, #17)
923
924 * fixed spurious space after unary operators when the operand was
925   a complex expression (#15)
926
927
928 ### 18.3a0
929
930 * first published version, Happy 🍰 Day 2018!
931
932 * alpha quality
933
934 * date-versioned (see: https://calver.org/)
935
936
937 ## Authors
938
939 Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
940
941 Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
942 [Carl Meyer](mailto:carl@oddbird.net),
943 [Mika Naylor](mailto:mail@autophagy.io), and
944 [Zsolt Dollenstein](mailto:zsol.zsol@gmail.com).
945
946 Multiple contributions by:
947 * [Anthony Sottile](mailto:asottile@umich.edu)
948 * [Artem Malyshev](mailto:proofit404@gmail.com)
949 * [Christian Heimes](mailto:christian@python.org)
950 * [Daniel M. Capella](mailto:polycitizen@gmail.com)
951 * [Eli Treuherz](mailto:eli.treuherz@cgi.com)
952 * Hugo van Kemenade
953 * [Ivan Katanić](mailto:ivan.katanic@gmail.com)
954 * [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com)
955 * [Jonas Obrist](mailto:ojiidotch@gmail.com)
956 * [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
957 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
958 * [Sunil Kapil](mailto:snlkapil@gmail.com)
959 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
960
961 ---
962
963 *Contents:*
964 **[Installation and Usage](#installation-and-usage)** |
965 **[The *Black* code style](#the-black-code-style)** |
966 **[Editor integration](#editor-integration)** |
967 **[Version control integration](#version-control-integration)** |
968 **[Ignoring unmodified files](#ignoring-unmodified-files)** |
969 **[Testimonials](#testimonials)** |
970 **[Show your style](#show-your-style)** |
971 **[License](#license)** |
972 **[Contributing](#contributing-to-black)** |
973 **[Change Log](#change-log)** |
974 **[Authors](#authors)**