X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/9d671bdbe13ab68cea1bba15001c43e90cf2c1a6..793450aeb00c8547ef5355c38dbf573ce4252bae:/README.md diff --git a/README.md b/README.md index 4663176..aca4999 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ *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. @@ -176,6 +176,14 @@ 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 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 @@ -218,10 +226,7 @@ bother you if you overdo it by a few km/h". *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 @@ -298,6 +303,19 @@ This behaviour may raise ``W503 line break before binary operator`` warnings in 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 @@ -309,6 +327,11 @@ interesting cases: - `for (...) in (...):` - `assert (...), (...)` - `from X import (...)` +- assignments like: + - `target = (...)` + - `target: type = (...)` + - `some, *un, packing = (...)` + - `augmented += (...)` In those cases, parentheses are removed when the entire statement fits in one line, or if the inner expression doesn't have any delimiters to @@ -502,8 +525,8 @@ MIT ## 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 @@ -518,7 +541,37 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log -### 18.4a3 (unreleased) +### 18.5a0 (unreleased) + +* slices are now formatted according to PEP 8 (#178) + +* parentheses are now also managed automatically on the right-hand side + of assignments and return statements (#140) + +* math operators now use their respective priorities for delimiting multiline + expressions (#148) + +* empty parentheses in a class definition are now removed (#145, #180) + +* fixed an invalid trailing comma sometimes left in imports (#185) + +* fixed non-deterministic formatting when multiple pairs of removable parentheses + were used (#183) + +* fixed not splitting long from-imports with only a single name + +* fixed Python 3.6+ file discovery by also looking at function calls with + unpacking. This fixed non-deterministic formatting if trailing commas + where used both in function signatures with stars and function calls + with stars but the former would be reformatted to a single line. + + +### 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) @@ -528,6 +581,11 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). * 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 @@ -542,6 +600,7 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). * fixed missing splits of ternary expressions (#141) + ### 18.4a2 * fixed parsing of unaligned standalone comments (#99, #112) @@ -699,10 +758,12 @@ Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com), Multiple contributions by: * [Anthony Sottile](mailto:asottile@umich.edu) * [Artem Malyshev](mailto:proofit404@gmail.com) +* [Christian Heimes](mailto:christian@python.org) * [Daniel M. Capella](mailto:polycitizen@gmail.com) * [Eli Treuherz](mailto:eli.treuherz@cgi.com) * Hugo van Kemenade * [Ivan Katanić](mailto:ivan.katanic@gmail.com) * [Jonas Obrist](mailto:ojiidotch@gmail.com) * [Osaetin Daniel](mailto:osaetindaniel@gmail.com) +* [Sunil Kapil](mailto:snlkapil@gmail.com) * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)