slightly refactor your code. I hope some of the examples above show you that there are
many ways in which you can do it.
+(labels/line-length)=
+
### Line length
You probably noticed the peculiar default line length. _Black_ defaults to 88 characters
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 mostly forget about it.
-However, it's better if you use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s
-B950 warning instead of E501, and bump the max line length to 88 (or the `--line-length`
-you used for black), which will align more with black's _"try to respect
-`--line-length`, but don't become crazy if you can't"_. You'd do it like this:
-
-```ini
-[flake8]
-max-line-length = 88
-...
-select = C,E,F,W,B,B950
-extend-ignore = E203, E501
-```
+#### Flake8
-Explanation of why E203 is 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 use Flake8, you have a few options:
-**If you're looking for a minimal, black-compatible flake8 configuration:**
+1. Recommended is using [Bugbear](https://github.com/PyCQA/flake8-bugbear) and enabling
+ its B950 check instead of using Flake8's E501, because it aligns with Black's 10%
+ rule. Install Bugbear and use the following config:
-```ini
-[flake8]
-max-line-length = 88
-extend-ignore = E203
-```
+ ```ini
+ [flake8]
+ max-line-length = 80
+ ...
+ select = C,E,F,W,B,B950
+ extend-ignore = E203, E501
+ ```
+
+ The rationale for E950 is explained in
+ [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings).
+
+2. For a minimally compatible config:
+
+ ```ini
+ [flake8]
+ max-line-length = 88
+ extend-ignore = E203
+ ```
+
+An explanation of why E203 is disabled can be found in the [Slices section](#slices) of
+this page.
### Empty lines
_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.
+space, this whitespace is lost. The other exception is that it will remove any empty
+lines immediately following a statement that introduces a new indentation level.
+
+```python
+# in:
+
+def foo():
+
+ print("All the newlines above me should be deleted!")
+
+
+if condition:
+
+ print("No newline above me!")
+
+ print("There is a newline above me, and that's OK!")
+
+
+class Point:
+
+ x: int
+ y: int
+
+# out:
+
+def foo():
+ print("All the newlines above me should be deleted!")
+
+
+if condition:
+ print("No newline above me!")
+
+ print("There is a newline above me, and that's OK!")
+
+
+class Point:
+ x: int
+ y: int
+```
It will also insert proper spacing before and after function definitions. It's one line
before and after inner functions and two lines before and after module-level functions
_Black_ does not format comment contents, but it enforces two spaces between code and a
comment on the same line, and a space before the comment text begins. Some types of
-comments that require specific spacing rules are respected: doc comments (`#: comment`),
-section comments with long runs of hashes, and Spyder cells. Non-breaking spaces after
-hashes are also preserved. Comments may sometimes be moved because of formatting
-changes, which can break tools that assign special meaning to them. See
-[AST before and after formatting](#ast-before-and-after-formatting) for more discussion.
+comments that require specific spacing rules are respected: shebangs (`#! comment`), doc
+comments (`#: comment`), section comments with long runs of hashes, and Spyder cells.
+Non-breaking spaces after hashes are also preserved. Comments may sometimes be moved
+because of formatting changes, which can break tools that assign special meaning to
+them. See [AST before and after formatting](#ast-before-and-after-formatting) for more
+discussion.
### Trailing commas
bracket pair into one item per line. Read more about this in the
[Pragmatism](#pragmatism) section below.
+(labels/strings)=
+
### Strings
_Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It
_Black_ does make some exceptions to rules it otherwise holds. This section documents
what those exceptions are and why this is the case.
+(labels/magic-trailing-comma)=
+
### The magic trailing comma
_Black_ in general does not take existing formatting into account.
r-strings and R-strings. The former are syntax highlighted as regular expressions while
the latter are treated as true raw strings with no special semantics.
+(labels/ast-changes)=
+
### AST before and after formatting
-When run with `--safe`, _Black_ checks that the code before and after is semantically
-equivalent. This check is done by comparing the AST of the source with the AST of the
-target. There are three limited cases in which the AST does differ:
+When run with `--safe` (the default), _Black_ checks that the code before and after is
+semantically equivalent. This check is done by comparing the AST of the source with the
+AST of the target. There are three limited cases in which the AST does differ:
1. _Black_ cleans up leading and trailing whitespace of docstrings, re-indenting them if
needed. It's been one of the most popular user-reported features for the formatter to
fix whitespace issues with docstrings. While the result is technically an AST
- difference, due to the various possibilities of forming docstrings, all realtime use
- of docstrings that we're aware of sanitizes indentation and leading/trailing
+ difference, due to the various possibilities of forming docstrings, all real-world
+ uses of docstrings that we're aware of sanitize indentation and leading/trailing
whitespace anyway.
1. _Black_ manages optional parentheses for some statements. In the case of the `del`
projects / etc / vim.git / blobdiff