Fix multiline strings unnecessarily wrapped in optional parentheses

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index b7f31dc075ff7bdc2c2db08817745bdd338352cc..3eb8ee4f131bb3bd234b457071895318932bf44c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -340,7 +340,39 @@ interesting cases:
 
 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
-further split on.  Otherwise, the parentheses are always added.
+further split on.  If there is only a single delimiter and the expression
+starts or ends with a bracket, the parenthesis can also be successfully
+omitted since the existing bracket pair will organize the expression
+neatly anyway.  Otherwise, the parentheses are added.
+
+Please note that *Black* does not add or remove any additional nested
+parentheses that you might want to have for clarity or further
+code organization.  For example those parentheses are not going to be
+removed:
+```py3
+return not (this or that)
+decision = (maybe.this() and values > 0) or (maybe.that() and values < 0)
+```
+
+### Call chains
+
+Some popular APIs, like ORMs, use call chaining.  This API style is known
+as a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface).
+*Black* formats those treating dots that follow a call or an indexing
+operation like a very low priority delimiter.  It's easier to show the
+behavior than to explain it.  Look at the example::
+```py3
+def example(session):
+    result = (
+        session.query(models.Customer.id)
+        .filter(
+            models.Customer.account_id == account_id,
+            models.Customer.email == email_address,
+        )
+        .order_by(models.Customer.id.asc())
+        .all()
+    )
+```
 
 ### Typing stub files
 
@@ -589,6 +621,8 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ### 18.5a0 (unreleased)
 
+* call chains are now formatted according to the [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface) style (#67)
+
 * slices are now formatted according to PEP 8 (#178)
 
 * parentheses are now also managed automatically on the right-hand side
@@ -609,6 +643,8 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 * typing stub files (`.pyi`) are now formatted in a style that is consistent
   with PEP 484 (#207, #210)
 
+* progress when reformatting many files is now reported incrementally
+
 * fixed trailers (content with brackets) being unnecessarily exploded
   into their own lines after a dedented closing bracket (#119)
 
@@ -617,6 +653,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 * fixed non-deterministic formatting when multiple pairs of removable parentheses
   were used (#183)
 
+* fixed multiline strings being unnecessarily wrapped in optional
+  parentheses in long assignments (#215)
+
 * fixed not splitting long from-imports with only a single name
 
 * fixed Python 3.6+ file discovery by also looking at function calls with
@@ -626,6 +665,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 * fixed crash on dealing with optional parentheses (#193)
 
+* fixed "is", "is not", "in", and "not in" not considered operators for
+  splitting purposes
+
 * fixed crash when dead symlinks where encountered