-_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`. `# fmt: on/off` have to be on the same level of
-indentation. It also recognizes [YAPF](https://github.com/google/yapf)'s block comments
-to the same effect, as a courtesy for straddling code.
-
-### How _Black_ wraps lines
-
-_Black_ ignores previous formatting and applies uniform horizontal and vertical
-whitespace to your code. The rules for horizontal whitespace can be summarized as: do
-whatever makes `pycodestyle` happy. The coding style used by _Black_ can be viewed as a
-strict subset of PEP 8.
-
-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:
-
-j = [1,
- 2,
- 3
-]
-
-# out:
-
-j = [1, 2, 3]
-```
-
-If not, _Black_ will look at the contents of the first outer matching brackets and put
-that in a separate indented line.
-
-```py3
-# in:
-
-ImportantClass.important_method(exc, limit, lookup_lines, capture_locals, extra_argument)
-
-# out:
-
-ImportantClass.important_method(
- exc, limit, lookup_lines, capture_locals, extra_argument
-)
-```
-
-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, engine: str, header: bool = True, 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,
- engine: str,
- header: bool = True,
- debug: bool = False,
-):
- """Applies `variables` to the `template` and writes to `file`."""
- with open(file, "w") as f:
- ...
-```
-
-_Black_ prefers parentheses over backslashes, and will remove backslashes if found.
-
-```py3
-# in:
-
-if some_short_rule1 \
- and some_short_rule2:
- ...
-
-# out:
-
-if some_short_rule1 and some_short_rule2:
- ...
-
-
-# in:
-
-if some_long_rule1 \
- and some_long_rule2:
- ...
-
-# out:
-
-if (
- some_long_rule1
- and some_long_rule2
-):
- ...
-
-```
-
-Backslashes and multiline strings are one of the two places in the Python grammar that
-break significant indentation. You never need backslashes, they are used to force the
-grammar to accept breaks that would otherwise be parse errors. That makes them confusing
-to look at and brittle to modify. This is why _Black_ always gets rid of them.
-
-If you're reaching for backslashes, that's a clear signal that you can do better if you
-slightly refactor your code. I hope some of the examples above show you that there are
-many ways in which you can do it.
-
-However there is one exception: `with` statements using multiple context managers.
-Python's grammar does not allow organizing parentheses around the series of context
-managers.
-
-We don't want formatting like:
-
-```py3
-with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
- ... # nothing to split on - line too long
-```
-
-So _Black_ will now format it like this:
-
-```py3
-with \
- make_context_manager(1) as cm1, \
- make_context_manager(2) as cm2, \
- make_context_manager(3) as cm3, \
- make_context_manager(4) as cm4 \
-:
- ... # backslashes and an ugly stranded colon
-```
-
-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).
-
-If a data structure literal (tuple, list, set, dict) or a line of "from" imports cannot
-fit in the allotted length, it's always split into one element per line. This minimizes
-diffs as well as enables readers of code to find which commit introduced a particular
-entry. This also makes _Black_ compatible with [isort](https://pypi.org/p/isort/) with
-the following configuration.
-
-<details>
-<summary>A compatible `.isort.cfg`</summary>
-
-```
-[settings]
-multi_line_output=3
-include_trailing_comma=True
-force_grid_wrap=0
-use_parentheses=True
-line_length=88
-```
-
-The equivalent command line is:
-
-```
-$ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --use-parentheses --line-width=88 [ file.py ]
-```
-
-</details>
-
-### 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 = E203, E501, W503
-```
-
-You'll find _Black_'s own .flake8 config file is configured like this. Explanation of
-why W503 and E203 are disabled can be found further in this documentation. And if you're
-curious about the reasoning behind B950,
-[Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings)
-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".
-
-**If you're looking for a minimal, black-compatible flake8 configuration:**
-
-```ini
-[flake8]
-max-line-length = 88
-extend-ignore = E203
-```
-
-### Empty lines
-
-_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.
-
-_Black_ will allow single empty lines inside functions, and single and double empty
-lines on module level left by the original editors, except when they're within
-parenthesized expressions. Since such expressions are always reformatted to fit minimal
-space, this whitespace is lost.
projects / etc / vim.git / blobdiff