*Black* is the uncompromising Python code formatter. By using it, you
-agree to cease control over minutiae of hand-formatting. In return,
+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.
indentation level (like the arguments list and the docstring in the
example above).
+If a line of "from" imports cannot fit in the allotted length, it's always split
+into one per line. Imports tend to change often and this minimizes diffs, as well
+as enables readers of code to easily find which commit introduced a particular
+import. This exception also makes *Black* compatible with
+[isort](https://pypi.org/p/isort/). Use `multi_line_output=3`,
+`include_trailing_comma=True`, `force_grid_wrap=0`, and `line_length=88` in your
+isort config.
+
### Line length
*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.
+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
style guide enforcement tools like Flake8. Since ``W503`` is not PEP 8 compliant,
you should tell Flake8 to ignore these warnings.
+### Slices
+
+PEP 8 [recommends](https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements)
+to treat ``:`` in slices as a binary operator with the lowest priority, and to
+leave an equal amount of space on either side, except if a parameter is omitted
+(e.g. ``ham[1 + 1 :]``). It also states that for extended slices, both ``:``
+operators have to have the same amount of spacing, except if a parameter is
+omitted (``ham[1 + 1 ::]``). *Black* enforces these rules consistently.
+
+This behaviour may raise ``E203 whitespace before ':'`` warnings in style guide
+enforcement tools like Flake8. Since ``E203`` is not PEP 8 compliant, you should
+tell Flake8 to ignore these warnings.
+
### Parentheses
Some parentheses are optional in the Python grammar. Any expression can
## Contributing to Black
-In terms of inspiration, *Black* is about as configurable as *gofmt* and
-*rustfmt* are. This is deliberate.
+In terms of inspiration, *Black* is about as configurable as *gofmt*.
+This is deliberate.
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
## Change Log
-### 18.4a3 (unreleased)
+### 18.4a4
+
+* don't populate the cache on `--check` (#175)
+
+
+### 18.4a3
* added a "cache"; files already reformatted that haven't changed on disk
won't be reformatted again (#109)
* generalized star expression handling, including double stars; this
fixes multiplication making expressions "unsafe" for trailing commas (#132)
+* Black no longer enforces putting empty lines behind control flow statements
+ (#90)
+
+* Black now splits imports like "Mode 3 + trailing comma" of isort (#127)
+
* fixed comment indentation when a standalone comment closes a block (#16, #32)
* fixed standalone comments receiving extra empty lines if immediately preceding
* fixed missing splits of ternary expressions (#141)
+
### 18.4a2
* fixed parsing of unaligned standalone comments (#99, #112)
projects / etc / vim.git / blobdiff