Implement fluent interfaces

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index 6c99fd32a7c5053fa084d8ecf906acd55ba29d38..ed69cb835eafe07da148e13bdfe118514fab0690 100644 (file)
--- a/README.md
+++ b/README.md
@@ -342,6 +342,26 @@ 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.
 
+### 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
 
 PEP 484 describes the syntax for type hints in Python.  One of the
@@ -589,6 +609,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
@@ -597,6 +619,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 * math operators now use their respective priorities for delimiting multiline
   expressions (#148)
 
+* optional parentheses are now omitted on expressions that start or end
+  with a bracket and only contain a single operator (#177)
+
 * empty parentheses in a class definition are now removed (#145, #180)
 
 * string prefixes are now standardized to lowercase and `u` is removed
@@ -606,8 +631,10 @@ 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
+  into their own lines after a dedented closing bracket (#119)
 
 * fixed an invalid trailing comma sometimes left in imports (#185)
 
@@ -621,6 +648,11 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
   where used both in function signatures with stars and function calls
   with stars but the former would be reformatted to a single line.
 
+* 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