]> git.madduck.net Git - etc/vim.git/blobdiff - README.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Fix multiline strings unnecessarily wrapped in optional parentheses
[etc/vim.git] / README.md
index 1570348ade6060f93d6192e9185233c09cf35d74..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,14 +643,19 @@ 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)
 
 * 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