X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/5a47fd13cc4c9f43270dd12c37577244c1eabfcc..34646945e7517ce3bcd03289e7bfa4db6fefd27f:/README.md

diff --git a/README.md b/README.md
index 1570348..c88639a 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ content instead.
 possible.
 
 
-## Installation and Usage
+## Installation and usage
 
 ### Installation
 
@@ -78,14 +78,16 @@ Options:
   used).
 
 
-### NOTE: This is an early pre-release
+### NOTE: This is a beta product
 
-*Black* can already successfully format itself and the standard library.
+*Black* is already successfully used by several projects, small and big.
 It also sports a decent test suite.  However, it is still very new.
 Things will probably be wonky for a while. This is made explicit by the
-"Alpha" trove classifier, as well as by the "a" in the version number.
+"Beta" trove classifier, as well as by the "b" in the version number.
 What this means for you is that **until the formatter becomes stable,
-you should expect some formatting to change in the future**.
+you should expect some formatting to change in the future**.  That being
+said, no drastic stylistic changes are planned, mostly responses to bug
+reports.
 
 Also, as a temporary safety measure, *Black* will check that the
 reformatted code still produces a valid AST that is equivalent to the
@@ -131,13 +133,13 @@ brackets and put that in a separate indented line.
 ```py3
 # in:
 
-l = [[n for n in list_bosses()], [n for n in list_employees()]]
+TracebackException.from_exception(exc, limit, lookup_lines, capture_locals)
 
 # out:
 
-l = [
-    [n for n in list_bosses()], [n for n in list_employees()]
-]
+TracebackException.from_exception(
+    exc, limit, lookup_lines, capture_locals
+)
 ```
 
 If that still doesn't fit the bill, it will decompose the internal
@@ -176,13 +178,13 @@ 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.
+If a data structure literal (tuple, list, set, dict) or a line of "from"
+imports cannot fit in the allotted length, it's always split into one
+element per line.  This minimizes diffs as well as enables readers of
+code to find which commit introduced a particular entry.  This 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
@@ -268,6 +270,7 @@ if you'd like a trailing comma in this situation and *Black* didn't
 recognize it was safe to do so, put it there manually and *Black* will
 keep it.
 
+
 ### Strings
 
 *Black* prefers double quotes (`"` and `"""`) over single quotes (`'`
@@ -297,7 +300,8 @@ a bit easier than double quotes.  The latter requires use of the Shift
 key.  My recommendation here is to keep using whatever is faster to type
 and let *Black* handle the transformation.
 
-### Line Breaks & Binary Operators
+
+### Line breaks & binary operators
 
 *Black* will break a line before a binary operator when splitting a block
 of code over multiple lines. This is so that *Black* is compliant with the
@@ -308,6 +312,7 @@ 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)
@@ -321,6 +326,7 @@ 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
@@ -340,7 +346,41 @@ 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
 
@@ -391,19 +431,25 @@ Use [proofit404/blacken](https://github.com/proofit404/blacken).
 
 1. Install `black`.
 
-        $ pip install black
+```console
+$ pip install black
+```
 
 2. Locate your `black` installation folder.
 
-  On MacOS / Linux / BSD:
+  On macOS / Linux / BSD:
 
-        $ which black
-        /usr/local/bin/black  # possible location
+```console
+$ which black
+/usr/local/bin/black  # possible location
+```
 
   On Windows:
 
-        $ where black
-        %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
+```console
+$ where black
+%LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
+```
 
 3. Open External tools in PyCharm with `File -> Settings -> Tools -> External Tools`.
 
@@ -462,7 +508,7 @@ The plugin will use it.
 
 **How to get Vim with Python 3.6?**
 On Ubuntu 17.10 Vim comes with Python 3.6 by default.
-On macOS with HomeBrew run: `brew install vim --with-python3`.
+On macOS with Homebrew run: `brew install vim --with-python3`.
 When building Vim from source, use:
 `./configure --enable-python3interp=yes`. There's many guides online how
 to do this.
@@ -472,14 +518,17 @@ to do this.
 
 Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
 
+
 ### SublimeText 3
 
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
+
 ### IPython Notebook Magic
 
 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 
+
 ### Other editors
 
 Atom/Nuclide integration is planned by the author, others will
@@ -587,7 +636,15 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
-### 18.5a0 (unreleased)
+### 18.5b0
+
+* call chains are now formatted according to the
+  [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface)
+  style (#67)
+
+* data structure literals (tuples, lists, dictionaries, and sets) are
+  now also always exploded like imports when they don't fit in a single
+  line (#152)
 
 * slices are now formatted according to PEP 8 (#178)
 
@@ -609,14 +666,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 +688,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